Metadata-Version: 2.4
Name: ltc-reader
Version: 1.0.2
Summary: Python ltc reader.
Project-URL: Homepage, https://gitlab.ewi.tudelft.nl/capturelab/py-ltc-reader
Author-email: REIT <reit-ewi@tudelft.nl>
License-File: LICENSE
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# ltc-reader

Python ltc reader.

[[_TOC_]]


## A generic basic LTC decoder

LTC stands for Linear Timecode and is a signal used in media production to
time synchronize multiple sources of audio and video involved in same production.

LTC is an analog audio signal and because of it can be easily transmitted
among stations and added as an audio channel with other audio and video.


## Usage

The test code in LTCMapTest shows how to use this:

```
        with wave.open("tests/Audio_2.wav") as wav_file:
            metadata = wav_file.getparams()
            if metadata.nchannels != 1:
                raise ValueError("1-channel data required")  # noqa: EM101
            # frames = wav_file.readframes(metadata.nframes)
            data: bytes = wav_file.readframes(metadata.nframes)
            chan: Channel = ByteChannel(data, metadata.framerate, metadata.sampwidth, "little", None)

            map: LTCMap = LTCMap.fromChannel(chan)
            print(map)

```

Most lines are just fetching your audio from a file and extracting the data, sample rate, data width etc. You can change this with other code to read your favourite encoding (eg mp3 , aiff, flac, etc). The decoded data is then put into the Channel object and that is used to create the LTCMap. The Channel ensures the audio is 1-channel with float samples, and ensures there is a ```get``` method to get the Nth sample in the audio.

The example uses an ByteChannel, which assumes your data consists of a list of samples
and each sample is a fixed number of bytes in little or big endian form.
If your data has a different behaviour, you can implement your own Channel
to map map/adapt to the required form. Your data doesn't even have to be in memory for that.

The LTCMap processes all the Channel samples and finds all the LTCs contained.
This map can be accessed through the ```getMap``` method.
This map contains all sample positions (int) and the extracted LTCFrame data.
The sample position is the first sample of the LTC code in the channel.



NOTE
This contains hard copy of tudelft.utilities 1.1.6 from  https://gitlab.ewi.tudelft.nl/interactive-intelligence/utilities/utilitiespy


## Installation


1. Install [uv](https://docs.astral.sh/uv/):

2. Install the dependencies, including the dev dependencies

    ```bash
    uv sync
    ```
    or install only the runtime dependencies

    ```bash
    uv sync --no-dev
    ```

3. Install the prek hook.
This will set up prek to run the checks automatically on your files before you commit them.

    ```bash
    uv run prek install
    ```

  **Remember that if the prek checks fail, you can always commit by skipping the checks with `git commit --no-verify`**


## Running tests

Run your tests with

```bash
uv run pytest --cov=src ./tests
```

## Formatting and checking

The tools for formatting and linting your code for errors are all bundled with [prek](https://prek.j178.dev). Included are:
- [ruff](https://astral.sh/ruff) - linting and formatting
- [yamlfix](https://github.com/lyz-code/yamlfix) - linting and formatting for .yaml files
- various other small fixes and checks (see the [`.pre-commit-config.yaml`](.pre-commit-config.yaml) file for more information)

It's possible that prek will make changes to your files when it runs the checks, so you should add those changes to your commit before you commit your code. A typical workflow would look like this:

```bash
git add -u
git commit -m "My commit message"
# prek will run the checks here; if it makes changes, you'll need to add them to your commit
git add -u
git commit -m "My commit message"
# changes should have all been made by now and the commit should pass if there are no other issues
# if your commit fails again here, you have to fix the issues manually (not everything can be fixed automatically).
```

One thing that is worth knowing is how to lint your files outside of the context of a commit. You can run the checks manually by running the following command:

```bash
uv run prek run --all-files
```

This will run the checks on all files in your git project, regardless of whether they're staged for commit or not.

## Documentation

Generate the documentation locally with

```bash
uv run zensical serve
```

## Versions

Versions are managed automatically via [hatch-vcs](https://github.com/ofek/hatch-vcs), which follows the versioning scheme from [setuptools-scm](https://setuptools-scm.readthedocs.io/en/latest/usage/#default-versioning-scheme).

To create a new version, tag the code with `git tag <version>`, e.g. `git tag v0.1.0`, and push the tag with `git push --tags`.

You can check the version by running

```bash
uv run hatch version
```

In python you can see the version with
```python
from ltc_reader import __version__

print(f"ltc_reader version is { __version__ }")
```

## Publishing the package


If you're ready to publish your package to [PyPI](https://pypi.org/) (i.e. you want to be able to run `pip install my-package-name` from anywhere), follow the [uv instructions](https://docs.astral.sh/uv/guides/publish/).
In short, they boil down to running:

1. Build the wheel

    ```bash
    uv build
    ```

2. Upload the wheel to PyPI

    ```bash
    uv publish
    ```

If your package is private and you are using gitlab.ewi.tudelft.nl, you can publish it to it's private registry.
This will let you do `pip install ltc-reader`.
See the instructions [here](https://gitlab.ewi.tudelft.nl/reit/python-package-template/-/blob/main/GITLAB-PYPI.md).

## License
Distributed under the terms of the [GPL license](LICENSE).
