Differences

This shows you the differences between two versions of the page.

--- blocks:app-note:ltc_timecode [2025-04-28 11:46]
fredrik [Use the timecode in Blocks]
+++ blocks:app-note:ltc_timecode [2025-05-06 10:59] (current)
mattias [Make multiple Timecode readers autostart]
@@ Line 1: / Line 1: @@
+======LTC timecode as sync source======
+This application note describes a method to receive analog timecode from an external source.  For simplicity we use a USB analog soundcard that we plug in to the blocks server. Such audio interface should be "class compliant" USB-A, that means to special driver is required for the device to operate basic functionality properly.
+{{:blocks:app-note:ltc_timecode:i_face.jpg?400|}}
+We refer to the analog input on the Blocks server in the article, the application can run on any linux computer, so if your source signal is elsewhere it may make sense to pickup the sync signal with another computer running the LTC_timecode reader software. One way of doing that is to use the blocks server image to create the computer. Disable the blocks service and then follow the instructions in this application not to make this into a LTC timecode reader device.
+There are other alternative that sometimes may be more suitable, such as the one shown here:
+https://www.youtube.com/watch?v=VY9kEkZim_k made by joananton@joananton.com. This reciever will produce serial data from the LTC timecode and can be connected to any Blocks spot with the same driver used in this article.
+====Setup the timecode reader software====
+Plug in the USB audio device to the blocks server.
+Use a second computer to play [[https://int.pixilab.se/outgoing/permanent/wiki/LTC_10mins_30fps_44100x24.wav|some sample LTC timecode]], just for testing purposes. We play the sample audio from a Windows laptops mediaplayer.
+Plug an 3.5mm audio cable between the computers audio output with the line in/mic input of the analog audio card of the Blocks server.
+===Find out the ALSA name of the sound device===
+To capture the desired device we must figure out the ALSA name of the usb-device. To do so we open the terminal as the pixi-server user and type:
+<code>arecord -L</code>
+Look for an entry like:
+<code>plughw:CARD=Device,DEV=0
+    USB PnP Sound Device, USB Audio
+    Hardware device with all software conversions
+</code>
+The ALSA name is
+<code>plughw:CARD=Device,DEV=0</code>
+If you have more than one USB audio device one can expect the next one to be named:
+<code>plughw:CARD=Device_1,DEV=0</code>
+and so on.
+===Echo test===
+To test if we get any signal one can now plug in headphones in the USB card output and make an Echo test:
+<code>arecord -D plughw:CARD=Device,DEV=0 -f cd | aplay</code>
+You should hear the incoming timecode in the headphones.
+Stop the echo test by hitting ctrl+c.
+===Test run the LTC reader software===
+Now we can dryrun also the LTC reader software by making it log the time using the -t parameter.
+Change to the directory where the software is stored, on a Blocks server image is is stored in home/blocks/native/
+<code>cd native</code>
+Run the program using the -d parameter to specify device and -t parameter to run in test mode.
+<code>./timecode-reader -d plughw:CARD=Device,DEV=0 -t</code>
+We should see the time changing as the time source progress in the console output:
+<code>New settings: i/2000/t/25/p/1633/n/1/c/0/w/150/f/2
+:57.11 signal, dbFS: -0.6
+</code>
+In test mode we may also see some error logging while reading the signal.
+<code>Non contiguos 92925 with lastAccepted 92929
+Minor error ignored. 92926 contiguous with lastReceived 92925</code>
 ====Use the timecode in Blocks====
 There are a few steps to do before we can make use of the incoming analog timesource in blocks.
@@ Line 25: / Line 81: @@
 ===Configure the driver===
-You must configure the driver for the expected timecode type. This can be done with one of the following methods:
+You must configure the driver with the expected timecode type. The driver will fporward this information to the timecode reader program  . This can be done with one of the following methods:
 A. Set the 'type' property of this Network Device to the expected type.
@@ Line 41: / Line 97: @@
 Apply any time offset as required. This timeline is now controlled by the timecode.
+====Make the Timecode reader autostart====
+To make the timecode reader autostart we must perform a few more steps. On a blocks server we have prepared whats called  a unit file used by systemd in most linux distros to manage running programs and services.
+Change to the users unit files directory:
+<code>cd /home/pixi-server/.config/systemd/user</code>
+Edit the timecode-reader.service.config file.
+<code>nano timecode-reader.service.config</code>
+Edit the TIMECODE_READER_OPTIONS= line to make the software use the wanted device name.
+In my case I set it to:
+<code>TIMECODE_READER_OPTIONS=-d plughw:CARD=Device,DEV=0</code>
+Next step is to enable the service at computer startup.
+<code>systemctl --user enable --now timecode-reader.service</code>
+====Make multiple Timecode readers autostart====
+:!: **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, {{:blocks:app-note:timecode-reader:timecode-reader-1.4.zip|download version 1.4 here}}, unpack the ZIP and replace the **timecode-reader** file in the //native// subdirectory of the home directory.
+<code>~/native/timecode-reader -h</code>
+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:
+<code>mv timecode-reader.service timecode-reader@.service</code>
+**2.** Edit the unit template.
+<code>nano timecode-reader@.service</code>
+Using this configuration:
+<code>
+[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
+</code>
+**3.** Rename the unit's configuration file:
+<code>mv timecode-reader.service.config timecode-reader.alpha.config</code>
+**4.** Make a copy of that configuration file with a new name:
+<code>cp timecode-reader.alpha.config timecode-reader.beta.config</code>
+**5.** Edit the config files, specifying different audio interfaces and different network ports in each instance.
+<code>nano timecode-reader.beta.config</code>
+The configuraition file will look something like this (but with your device name and desired port number)
+<code>
+# 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
+</code>
+**6.** Notify systemd of your changes:
+<code>
+systemctl --user daemon-reload </code>
+**7.** Finally, enable and start the two instances
+<code>
+systemctl --user enable --now timecode-reader@alpha.service
+systemctl --user enable --now timecode-reader@beta.service
+</code>