libltc: POSIX-C Library for handling Linear/Logitudinal Time Code (LTC)

| libltc 1.3.1 Linear/Logitudinal Time Code (LTC) Library

POSIX-C Library for handling Linear/Logitudinal Time Code (LTC)

# Introduction

Linear (or Longitudinal) Timecode (LTC) is an encoding of timecode data as a Manchester-Biphase encoded audio signal. The audio signal is commonly recorded on a VTR track or other storage media.

libltc provides functionality to encode and decode LTC from/to timecode, including SMPTE date support.

libltc is the successor of libltcsmpte.

# Download

- GitHub Downloads/Releases
- GitHub Project Page
- git://github.com/x42/libltc.git

# Installation

libltc uses GNU autotools and libtool. The default auto-* workflow applies:

run `./configure` and build libltc with `make`. See the INSTALL file for further instructions.

The tar.gz package release includes the build-environment (`configure` script, etc), but if you get the source from the repository, you first need to generate the build environment with something alike: `aclocal; autoheader; libtoolize –copy; autoconf; automake –gnu –add-missing –copy`. (OSX users use `glibtoolize`).

If Doxygen is available, the documentation can be [re-]generated from the source by calling `make dox`. Self-test scenarios and example code can be compiled and executed with `make check`.

# Usage

Consult ltc.h for a detailed reference of available functions. The documentation is also available as Unix manual pages.

The self-test code lends itself as good examples on how to get started. See ltcdecode.c, ltcencode.c and example_encode.c. Other good starting point include

- ltc-tools portable commandline-tools with file-i/o via libsndfile and audio-i/o via libjack
- LtcWaveAudio, a MSVC project to generate and play LTC by Hakan Soyalp.

# Q&A

How can I get help?

  The preferred way is to use the issue-tracker at https://github.com/x42/libltc/issues . You can also send a private-mail to the authors.

How good is the LTC-decoder? Will it decode my file?

  It's doing very well, thanks. :) We did extensive testing using LTC samples from various sources and have not yet found one that libLTC can not decode. It may well be that there are edge-cases or degraded LTC waveforms that will not be reconstructed correctly. If you find such a sample, please contact us, we will look into ways to improve libLTC.

Does it support vari-speed LTC?

  Yes. libltc tracks speed variations. Each decoded LTC-frame is tagged with the corresponding audio-sample number (start/end). The LTC encoder has a 'speed' parameter that can be set for each byte.

Does libltc support decoding backwards played LTC - reverse tape direction

  Yes it does. See the documentation for LTCFrameExt

Can I use libltc in a proprietary/closed-source project?

  Yes, with some care. In a nutshell:
  Create a dynamic library (.dll, ,dylib, .so) of libltc and link your program against it. Your project remains independent. You only need to be able to convey means to re-create this library (source-code, build-scripts) to anyone who asks. The easiest way to do this is to simply not modify libltc and refer to the upstream source (keep a copy just in case).
  If you copy the library code directly into your project and statically link your application against it, your project will have to be licensed in terms of the LGPL or a compatible license. See the license text for details and consult with a person with expertise in licensing.

Is commercial licensing available?

  No, libltc is only available in terms of the GNU Lesser General Public License: LGPLv3.

Is there [free] software is using libltc?

  Yes, ltc-tools. It comprises JACK applications to generate and decode LTC from live sources and includes tools to read or write LTC from/to audio-files. xjadeo video-monitor has been updated to use libltc, and ardour3 DAW fully supports chasing and latency free [re]encoding of LTC since svn rev 13390.

  The library comes self-test code, which can en&decode LTC from raw audio-data.

  There are lots of apps (incl iOS applications, NLEs and hardware/firmware solutions) using libltcsmpte. We dare say that many - if not most - of them will be updated to libLTC in time.

  Mattijs Kneppers has written a MAX/MSP external smpte~ to encode LTC.

What is the difference between libltcsmpte and libltc?

  Functionally, there is little difference, usage and work-flow are very similar. But, the API has changed almost completely. Yet the majority of these changes are only parameter and function names.

  libltc introduces support for encoding vari-speed LTC and reverse played LTC. The internal code-path was optimized and the phase-tracking was slightly improved.

  libltc drops support for operations on timecode such as converting video-timecode to real-time (seconds, audio-frames), etc. This functionality is now part of libtimcode.

  The reasoning behind this is that libltc operates on LTC-frames. It ought to be ignorant about timecode or framerate semantics and should not make assumptions about the data, which is application dependent.

  Some related inappropriate functionality of libltcsmpte was dropped, as well. e.g. The ability to detect timecode discontinuities. This is an application specific issue and not LTC related.

  libltc still includes some timecode operations directly related to LTC, i.e. incrementing/decrementing timecode for use in the encoder and functions to map the 80 LTC bits to HH:MM:SS:FF timecode.

  In general: the API was simplified and cleaned up.

Why not continue to develop libltcsmpte?

  Mostly because of API and ABI compatibility issues. libltcsmpte was one of the first shared libraries that I have written. I've made mistakes: Naming conventions (functions, structure and variables) were chosen unwisely and can cause conflicts.

  Merging LTC date-support and making it compile-time optional was the next mistake: Versions compiled with-date do not allow using the user-bits of the LTC frame for anything else that date. Even worse is the compile-time option to change the sample-format and its encoding (signed/unsigned, 8/16bit or 32bit float). This really made the ABI incompatible between variants compiled with different options...

  Cleaning up this mess, while retaining compatibility with existing applications would probably have made things worse. libltcsmpte was the pilot system "built to be thrown away". That being said, "it works, NTL".

But you could still have called it libltcsmpte-2.0.0..

  Yes, we could have done that.

  The SMPTE part in the name was not appropriate. libltc handles EBU timecode just as well as SMPTE timecode. As mentioned above libltc is not concerned with timecode or framerates semantics per se, only the encoding/decoding of it.

libltcsmpte supports a variety of audio-sample formats/encodings (float, 16bit,..). Why is libltc limited to 8bit unsigned?

  Selecting the sample-format is a compile-time option in libltcsmpte. Changing it breaks the ABI (applications using the library will only work with the exact same variant of the libarary it has been compiled for - which makes a shared-lib useless.)

  8bit samples are more than sufficient to carry LTC information.

  Changing the audio-sample type from one encoding to another is [mostly] trivial. There is no way that libLTC could include an interface for every possible way to represent audio-data. This is application specific.

  There are however wrappers to convert common formats (16bit signed/unsigned and 32bit float) on the fly to 8 bit unsigned samples.

  Yes, libltcsmpte is/was superior in the sense that it can detect, track and filter very low signals-levels. Due to the 8bit limitation, libltc requires a minimum amplitude of -36db. This is usually a non-issue in real-world applications, but yes, if you want to analyze very low signals, possibly with DC-offset, you must implement your own amp and high-pass filter. In any case the generic signal tracker in libltc (or libltcsmpte) will likely perform worse than your application specific one.

# References

- libLTC GitHub Project Page
- libTimecode GitHub Project Page
- libLTCSMPTE Sourceforge Project Page
- Phil Rees' Article "Synchronisation and SMPTE timecode"
- Barney Wol's Timecode page
- Wikipedia Info on Linear Timecode
- Wikipedia Page on SMPTE
- Java wrapper around libltc

# License

Copyright (C) 2003 by Maarten de Boer

Copyright (C) 2006-2012 by Robin Gareus

Copyright (C) 2008-2010 by Jan Weiß

libltc is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/