/*
 * main page of the libLTC manual
 */

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

@section intro Introduction

 Linear (or Longitudinal) Timecode (LTC) is an encoding of
 <a href="http://en.wikipedia.org/wiki/SMPTE_timecode">timecode</a> data
 as a
 <a href="http://en.wikipedia.org/wiki/Manchester_Code">Manchester-Biphase</a>
 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 <a href="https://sourceforge.net/projects/ltcsmpte/">libltcsmpte</a>.

@section download Download
<ul>
 <li><a href="https://github.com/x42/libltc/releases">GitHub Downloads/Releases</a></li>
 <li><a href="https://github.com/x42/libltc/">GitHub Project Page</a></li>
 <li>git://github.com/x42/libltc.git</li>
</ul>

@section installation Installation
 libltc uses GNU autotools and libtool. The default auto-* workflow applies:

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

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

 If <a href="http://doxygen.org/">Doxygen</a> is available, the documentation can be [re-]generated from the source by calling <tt>make dox</tt>. Self-test scenarios and example code can be compiled and executed with <tt>make check</tt>.

@section usage Usage
 Consult \ref 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 \ref ltcdecode.c, \ref ltcencode.c and \ref example_encode.c.
 Another good starting point is <a href="https://github.com/x42/ltc-tools">ltc-tools</a>.

@section about Q&A

<dl>
 <dt>How can I get help?</dt>
 <dd>
  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.
 </dd>

 <dt>How good is the LTC-decoder? Will it decode my file?</dt>
 <dd>
  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.
 </dd>

 <dt>Does it support vari-speed LTC?</dt>
 <dd>
  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.
 </dd>

 <dt>Does libltc support decoding backwards played LTC - reverse tape direction</dt>

 <dd>
  Yes it does. See the documentation for \ref LTCFrameExt
 </dd>

 <dt>Is there [free] software is using libltc?</dt>
 <dd>
  yes, <a href="https://github.com/x42/ltc-tools">ltc-tools</a>.
  It comprises <a href="http://jackaudio.org">JACK</a> applications to generate
  and decode LTC from live sources and includes tools to read or write
  LTC from/to audio-files.
  <a href="http://xjadeo.sf.net">xjadeo</a> video-monitor has been updated
  to use libltc, and <a href="http://ardour.org">ardour</a>3 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 <a href="http://cycling74.com/toolbox/smpte/">smpte~</a> to encode LTC.
 </dd>

 <dt>What is the difference between libltcsmpte and libltc?</dt>
 <dd>
  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 <a href="https://github.com/x42/libtimecode/">libtimcode</a>.

  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.
 </dd>

 <dt>Why not continue to develop libltcsmpte?</dt>
 <dd>
  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".
 </dd>

 <dt>But you could still have called it libltcsmpte-2.0.0..</dt>
 <dd>
  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.
 </dd>

 <dt>libltcsmpte supports a variety of audio-sample formats/encodings (float, 16bit,..).
    Why is libltc limited to 8bit unsigned?</dt>
 <dd>
  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.
 </dd>
</dl>


@section references References
<ul>
 <li><a href="https://github.com/x42/libltc/">libLTC GitHub Project Page</a></li>
 <li><a href="https://github.com/x42/libtimecode/">libTimecode GitHub Project Page</a></li>
 <li><a href="https://sourceforge.net/projects/ltcsmpte/">libLTCSMPTE Sourceforge Project Page</a></li>
 <li><a href="http://www.philrees.co.uk/articles/timecode.htm">Phil Rees' Article "Synchronisation and SMPTE timecode"</a></li>
 <li><a href="http://www.barney-wol.net/time/timecode.html">Barney Wol's Timecode page</a></li>
 <li><a href="http://en.wikipedia.org/wiki/Linear_timecode">Wikipedia Info on Linear Timecode</a></li>
 <li><a href="http://en.wikipedia.org/wiki/SMPTE_timecode">Wikipedia Page on SMPTE</a></li>
</ul>

@section license 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/

\example ltcdecode.c
\example ltcencode.c
\example example_encode.c

*/

/* vi:set ts=2 sts=2 sw=2 et: */
