ltc-reader 1.0.2

Python ltc reader.

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:

2. Install the dependencies, including the dev dependencies

   uv sync
   

   or install only the runtime dependencies

   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.

   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

uv run pytest --cov=src ./tests

Formatting and checking

The tools for formatting and linting your code for errors are all bundled with prek. Included are:

• ruff - linting and formatting
• yamlfix - linting and formatting for .yaml files
• various other small fixes and checks (see the .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:

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:

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

uv run zensical serve

Versions

Versions are managed automatically via hatch-vcs, which follows the versioning scheme from setuptools-scm.

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

uv run hatch version

In python you can see the version with

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 (i.e. you want to be able to run pip install my-package-name from anywhere), follow the uv instructions. In short, they boil down to running:

1. Build the wheel

   uv build
   

2. Upload the wheel to PyPI

   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.

License

Distributed under the terms of the GPL license.