This application note describes how to receive analog timecode from an external source. A USB analog audio interface plugs in to the Blocks server. The audio interface must be "class compliant" USB-A, that means no custom driver is required for basic functionality.

A separate program is used to receive the timecode. This program is included on our Linux Server Image, and can be found in the "native" directory. It can run on most Intel-based Linux computers. If your timecode signal is far away it could make sense to pick up the signal using another small computer running the timecode reader program. Simply make another computer based on our Linux server image, disable blocks and follow the instructions below to turn this into a LTC timecode reader device, whcih then will be accessed over the network.

There are other alternative that sometimes may be more suitable, such as the one made by joananton@joananton.com you can watch here, which can be connected through a PIXILAB Player using the timecode driver (then configured as a Serial port bound to the Display Spot running PIXILAB Player software).

Connect the USB audio device to the server. Use a second computer (e.g. any laptop with an analog autio output) to play some sample LTC timecode for testing purposes. Connect a 3.5mm audio cable between the laptop's audio output and the line in/mic input of the analog audio interface connected to the server.

You must determine the the operating system's name of the USB inputdevice, as it may have more than one. To do so, open a terminal as the pixi-server user and type:

arecord -L

Look for an entry like:

plughw:CARD=Device,DEV=0
    USB PnP Sound Device, USB Audio
    Hardware device with all software conversions

The name to use then is

plughw:CARD=Device,DEV=0

If you have more than one USB audio device one can expect the next audio device to be named:

plughw:CARD=Device_1,DEV=0

and so on.

To test if the signal can be received, connect some headphones to the USB card output and make an Echo test:

arecord -D plughw:CARD=Device,DEV=0 -f cd | aplay

Make sure to use the name determined above. You should hear the incoming timecode in the headphones. Stop the echo test by hitting ctrl+c.

Test the timecode-reader program by using the -t parameter. First change to the directory where the timecode-reader program is stored:

cd native

Run the program using the -d parameter to specify device and -t parameter to run in test mode.

./timecode-reader -d plughw:CARD=Device,DEV=0 -t

We should see the time changing as the time source progress in the console output:

New settings: i/2000/t/25/p/1633/n/1/c/0/w/150/f/2
01:57.11 signal, dbFS: -0.6

In test mode we may also see some error logging while reading the signal.

Non contiguos 92925 with lastAccepted 92929
Minor error ignored. 92926 contiguous with lastReceived 92925

Adjust the signal level to minimize errors.

A few additional steps are required to make use of the timecode in blocks.

The driver to handle the timedata from the LTC-reader software is not enabled by default. To enable the driver, first must make sure the driver files exist in the script/driver directory in the PIXILAB-Blocks-root. The TimecodeLTC driver is stored in the script/driver-archive/ directory and needs to be enabled:

Change to the script directory:

 cd /home/pixi-server/PIXILAB-Blocks-root/script 

Move the following files from drivers-archive to the drivers directory (unless already there):

mv driver-archive/TimecodeLTC.ts driver/
mv driver-archive/TimecodeLTC.js driver/

Restart the blocks server to pick up the changes:

systemctl --user restart blocks

The driver is now available for use.

Under the Manage/Network page in the Blocks editor, add a new device and assign it the TimecodeLTC driver. The port is predefined in the driver to match the default configuration to the Timecode reader on the server.

Configure the driver with the expected timecode type. This can be done with either of the following methods:

A. Set the 'type' property of this Network Device to the expected type. This can be done using a Task triggered on system start-up or the 'connected' appears on the network).

B. Set options using JSON data in the "Custom Options" field of the Network Device, like this: {"type": "29.97_drop", "offset": 0.0} Supported type values: "24","25","29.97_drop","29.97_nondrop","30".

Add a Timeline block. Set it to use "External Synchronization" and select your LTCTimecode device as its sync source property.

Apply a time offset, if required. This timeline is now controlled by the timecode.

To make the timecode reader start automatically with the computer, you must perform a few more steps. The Blocks server (based on a recent Linux server image) comes with a "systemd unit" file for managing the timecode-reader program. You must edit this file to make sure it's set correctly for your audio device. Start by navigating to this directory:

cd /home/pixi-server/.config/systemd/user

Edit the timecode-reader.service.config file using the nano text editor:

nano timecode-reader.service.config

Edit the TIMECODE_READER_OPTIONS= line to make the software use the wanted device name. In my case I set it to:

TIMECODE_READER_OPTIONS=-d plughw:CARD=Device,DEV=0

Save the file using Ctrl-O then exit the nano editor using Ctrl-X.

Inform Linux that you've canged the configuration file:

systemctl --user daemon-reload

Finally, enable the service to start at computer startup.

systemctl --user enable --now timecode-reader

IMPORTANT: To use multiple timecode readers on the same computer, make sure you're running version 1.4 or later of the timecode-reader program. You can see the version number by the following command on the command line, while logged in as the pixi-server user. If your version is older than 1.4, download version 1.4 here, unpack the ZIP and replace the timecode-reader file in the native subdirectory of the home directory.

~/native/timecode-reader -h

To read more than one LTC timecode source you could duplicate and modify the unit file, thus creating a separate unit file for this purpose. However, a better solution is to modify the unit file to a unit template, as this keeps all the common stuff in one place. Follow this procudure to use that option.

1. Rename the unit file like this:

mv timecode-reader.service timecode-reader@.service

2. Edit the unit template.

nano timecode-reader@.service

Using this configuration:

[unit]
Description=LTC Timecode Reader (%i)

[Service]
EnvironmentFile=%h/.config/systemd/user/timecode-reader.%i.config
ExecStart=%h/native/timecode-reader $TIMECODE_READER_OPTIONS
TimeoutStopSec=20
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target

3. Rename the unit's configuration file:

mv timecode-reader.service.config timecode-reader.alpha.config

4. Make a copy of that configuration file with a new name:

cp timecode-reader.alpha.config timecode-reader.beta.config

5. Edit the config files, specifying different audio interfaces and different network ports in each instance.

nano timecode-reader.beta.config

The configuraition file will look something like this (but with your device name and desired port number)

# Options to pass to the timecode-reader program, e.g.,
# TIMECODE_READER_OPTIONS=-d "Alsa device name" -p "UDP port"
TIMECODE_READER_OPTIONS=-d plughw:CARD=Device_1,DEV=0 -p 1638

6. Notify systemd of your changes:

systemctl --user daemon-reload 

7. Finally, enable and start the two instances

systemctl --user enable --now timecode-reader@alpha.service
systemctl --user enable --now timecode-reader@beta.service