Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Browse files

update documentation and packaging.

  • Loading branch information...
1 parent 267546b commit a1b3082ef6159bdd293e25d080bdd2815b8e986e @x42 committed
1  .gitignore
@@ -2,7 +2,6 @@ cscope.*
@@ -0,0 +1,370 @@
+Installation Instructions
+Copyright (C) 1994-1996, 1999-2002, 2004-2011 Free Software Foundation,
+ Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved. This file is offered as-is,
+without warranty of any kind.
+Basic Installation
+ Briefly, the shell commands `./configure; make; make install' should
+configure, build, and install this package. The following
+more-detailed instructions are generic; see the `README' file for
+instructions specific to this package. Some packages provide this
+`INSTALL' file but do not implement all of the features documented
+below. The lack of an optional feature in a given package is not
+necessarily a bug. More recommendations for GNU packages can be found
+in *note Makefile Conventions: (standards)Makefile Conventions.
+ The `configure' shell script attempts to guess correct values for
+various system-dependent variables used during compilation. It uses
+those values to create a `Makefile' in each directory of the package.
+It may also create one or more `.h' files containing system-dependent
+definitions. Finally, it creates a shell script `config.status' that
+you can run in the future to recreate the current configuration, and a
+file `config.log' containing compiler output (useful mainly for
+debugging `configure').
+ It can also use an optional file (typically called `config.cache'
+and enabled with `--cache-file=config.cache' or simply `-C') that saves
+the results of its tests to speed up reconfiguring. Caching is
+disabled by default to prevent problems with accidental use of stale
+cache files.
+ If you need to do unusual things to compile the package, please try
+to figure out how `configure' could check whether to do them, and mail
+diffs or instructions to the address given in the `README' so they can
+be considered for the next release. If you are using the cache, and at
+some point `config.cache' contains results you don't want to keep, you
+may remove or edit it.
+ The file `' (or `') is used to create
+`configure' by a program called `autoconf'. You need `' if
+you want to change it or regenerate `configure' using a newer version
+of `autoconf'.
+ The simplest way to compile this package is:
+ 1. `cd' to the directory containing the package's source code and type
+ `./configure' to configure the package for your system.
+ Running `configure' might take a while. While running, it prints
+ some messages telling which features it is checking for.
+ 2. Type `make' to compile the package.
+ 3. Optionally, type `make check' to run any self-tests that come with
+ the package, generally using the just-built uninstalled binaries.
+ 4. Type `make install' to install the programs and any data files and
+ documentation. When installing into a prefix owned by root, it is
+ recommended that the package be configured and built as a regular
+ user, and only the `make install' phase executed with root
+ privileges.
+ 5. Optionally, type `make installcheck' to repeat any self-tests, but
+ this time using the binaries in their final installed location.
+ This target does not install anything. Running this target as a
+ regular user, particularly if the prior `make install' required
+ root privileges, verifies that the installation completed
+ correctly.
+ 6. You can remove the program binaries and object files from the
+ source code directory by typing `make clean'. To also remove the
+ files that `configure' created (so you can compile the package for
+ a different kind of computer), type `make distclean'. There is
+ also a `make maintainer-clean' target, but that is intended mainly
+ for the package's developers. If you use it, you may have to get
+ all sorts of other programs in order to regenerate files that came
+ with the distribution.
+ 7. Often, you can also type `make uninstall' to remove the installed
+ files again. In practice, not all packages have tested that
+ uninstallation works correctly, even though it is required by the
+ GNU Coding Standards.
+ 8. Some packages, particularly those that use Automake, provide `make
+ distcheck', which can by used by developers to test that all other
+ targets like `make install' and `make uninstall' work correctly.
+ This target is generally not run by end users.
+Compilers and Options
+ Some systems require unusual options for compilation or linking that
+the `configure' script does not know about. Run `./configure --help'
+for details on some of the pertinent environment variables.
+ You can give `configure' initial values for configuration parameters
+by setting variables in the command line or in the environment. Here
+is an example:
+ ./configure CC=c99 CFLAGS=-g LIBS=-lposix
+ *Note Defining Variables::, for more details.
+Compiling For Multiple Architectures
+ You can compile the package for more than one kind of computer at the
+same time, by placing the object files for each architecture in their
+own directory. To do this, you can use GNU `make'. `cd' to the
+directory where you want the object files and executables to go and run
+the `configure' script. `configure' automatically checks for the
+source code in the directory that `configure' is in and in `..'. This
+is known as a "VPATH" build.
+ With a non-GNU `make', it is safer to compile the package for one
+architecture at a time in the source code directory. After you have
+installed the package for one architecture, use `make distclean' before
+reconfiguring for another architecture.
+ On MacOS X 10.5 and later systems, you can create libraries and
+executables that work on multiple system types--known as "fat" or
+"universal" binaries--by specifying multiple `-arch' options to the
+compiler but only a single `-arch' option to the preprocessor. Like
+ ./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
+ CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \
+ CPP="gcc -E" CXXCPP="g++ -E"
+ This is not guaranteed to produce working output in all cases, you
+may have to build one architecture at a time and combine the results
+using the `lipo' tool if you have problems.
+Installation Names
+ By default, `make install' installs the package's commands under
+`/usr/local/bin', include files under `/usr/local/include', etc. You
+can specify an installation prefix other than `/usr/local' by giving
+`configure' the option `--prefix=PREFIX', where PREFIX must be an
+absolute file name.
+ You can specify separate installation prefixes for
+architecture-specific files and architecture-independent files. If you
+pass the option `--exec-prefix=PREFIX' to `configure', the package uses
+PREFIX as the prefix for installing programs and libraries.
+Documentation and other data files still use the regular prefix.
+ In addition, if you use an unusual directory layout you can give
+options like `--bindir=DIR' to specify different values for particular
+kinds of files. Run `configure --help' for a list of the directories
+you can set and what kinds of files go in them. In general, the
+default for these options is expressed in terms of `${prefix}', so that
+specifying just `--prefix' will affect all of the other directory
+specifications that were not explicitly provided.
+ The most portable way to affect installation locations is to pass the
+correct locations to `configure'; however, many packages provide one or
+both of the following shortcuts of passing variable assignments to the
+`make install' command line to change installation locations without
+having to reconfigure or recompile.
+ The first method involves providing an override variable for each
+affected directory. For example, `make install
+prefix=/alternate/directory' will choose an alternate location for all
+directory configuration variables that were expressed in terms of
+`${prefix}'. Any directories that were specified during `configure',
+but not in terms of `${prefix}', must each be overridden at install
+time for the entire installation to be relocated. The approach of
+makefile variable overrides for each directory variable is required by
+the GNU Coding Standards, and ideally causes no recompilation.
+However, some platforms have known limitations with the semantics of
+shared libraries that end up requiring recompilation when using this
+method, particularly noticeable in packages that use GNU Libtool.
+ The second method involves providing the `DESTDIR' variable. For
+example, `make install DESTDIR=/alternate/directory' will prepend
+`/alternate/directory' before all installation names. The approach of
+`DESTDIR' overrides is not required by the GNU Coding Standards, and
+does not work on platforms that have drive letters. On the other hand,
+it does better at avoiding recompilation issues, and works well even
+when some directory options were not specified in terms of `${prefix}'
+at `configure' time.
+Optional Features
+ If the package supports it, you can cause programs to be installed
+with an extra prefix or suffix on their names by giving `configure' the
+option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
+ Some packages pay attention to `--enable-FEATURE' options to
+`configure', where FEATURE indicates an optional part of the package.
+They may also pay attention to `--with-PACKAGE' options, where PACKAGE
+is something like `gnu-as' or `x' (for the X Window System). The
+`README' should mention any `--enable-' and `--with-' options that the
+package recognizes.
+ For packages that use the X Window System, `configure' can usually
+find the X include and library files automatically, but if it doesn't,
+you can use the `configure' options `--x-includes=DIR' and
+`--x-libraries=DIR' to specify their locations.
+ Some packages offer the ability to configure how verbose the
+execution of `make' will be. For these packages, running `./configure
+--enable-silent-rules' sets the default to minimal output, which can be
+overridden with `make V=1'; while running `./configure
+--disable-silent-rules' sets the default to verbose, which can be
+overridden with `make V=0'.
+Particular systems
+ On HP-UX, the default C compiler is not ANSI C compatible. If GNU
+CC is not installed, it is recommended to use the following options in
+order to use an ANSI C compiler:
+ ./configure CC="cc -Ae -D_XOPEN_SOURCE=500"
+and if that doesn't work, install pre-built binaries of GCC for HP-UX.
+ HP-UX `make' updates targets which have the same time stamps as
+their prerequisites, which makes it generally unusable when shipped
+generated files such as `configure' are involved. Use GNU `make'
+ On OSF/1 a.k.a. Tru64, some versions of the default C compiler cannot
+parse its `<wchar.h>' header file. The option `-nodtk' can be used as
+a workaround. If GNU CC is not installed, it is therefore recommended
+to try
+ ./configure CC="cc"
+and if that doesn't work, try
+ ./configure CC="cc -nodtk"
+ On Solaris, don't put `/usr/ucb' early in your `PATH'. This
+directory contains several dysfunctional programs; working variants of
+these programs are available in `/usr/bin'. So, if you need `/usr/ucb'
+in your `PATH', put it _after_ `/usr/bin'.
+ On Haiku, software installed for all users goes in `/boot/common',
+not `/usr/local'. It is recommended to use the following options:
+ ./configure --prefix=/boot/common
+Specifying the System Type
+ There may be some features `configure' cannot figure out
+automatically, but needs to determine by the type of machine the package
+will run on. Usually, assuming the package is built to be run on the
+_same_ architectures, `configure' can figure that out, but if it prints
+a message saying it cannot guess the machine type, give it the
+`--build=TYPE' option. TYPE can either be a short name for the system
+type, such as `sun4', or a canonical name which has the form:
+where SYSTEM can have one of these forms:
+ OS
+ See the file `config.sub' for the possible values of each field. If
+`config.sub' isn't included in this package, then this package doesn't
+need to know the machine type.
+ If you are _building_ compiler tools for cross-compiling, you should
+use the option `--target=TYPE' to select the type of system they will
+produce code for.
+ If you want to _use_ a cross compiler, that generates code for a
+platform different from the build platform, you should specify the
+"host" platform (i.e., that on which the generated programs will
+eventually be run) with `--host=TYPE'.
+Sharing Defaults
+ If you want to set default values for `configure' scripts to share,
+you can create a site shell script called `' that gives
+default values for variables like `CC', `cache_file', and `prefix'.
+`configure' looks for `PREFIX/share/' if it exists, then
+`PREFIX/etc/' if it exists. Or, you can set the
+`CONFIG_SITE' environment variable to the location of the site script.
+A warning: not all `configure' scripts look for a site script.
+Defining Variables
+ Variables not defined in a site shell script can be set in the
+environment passed to `configure'. However, some packages may run
+configure again during the build, and the customized values of these
+variables may be lost. In order to avoid this problem, you should set
+them in the `configure' command line, using `VAR=value'. For example:
+ ./configure CC=/usr/local2/bin/gcc
+causes the specified `gcc' to be used as the C compiler (unless it is
+overridden in the site shell script).
+Unfortunately, this technique does not work for `CONFIG_SHELL' due to
+an Autoconf bug. Until the bug is fixed you can use this workaround:
+ CONFIG_SHELL=/bin/bash /bin/bash ./configure CONFIG_SHELL=/bin/bash
+`configure' Invocation
+ `configure' recognizes the following options to control how it
+ Print a summary of all of the options to `configure', and exit.
+ Print a summary of the options unique to this package's
+ `configure', and exit. The `short' variant lists options used
+ only in the top level, while the `recursive' variant lists options
+ also present in any nested packages.
+ Print the version of Autoconf used to generate the `configure'
+ script, and exit.
+ Enable the cache: use and save the results of the tests in FILE,
+ traditionally `config.cache'. FILE defaults to `/dev/null' to
+ disable caching.
+ Alias for `--cache-file=config.cache'.
+ Do not print messages saying which checks are being made. To
+ suppress all normal output, redirect it to `/dev/null' (any error
+ messages will still be shown).
+ Look for the package's source code in directory DIR. Usually
+ `configure' can determine that directory automatically.
+ Use DIR as the installation prefix. *note Installation Names::
+ for more details, including other options available for fine-tuning
+ the installation locations.
+ Run the configure checks, but stop before creating any output
+ files.
+`configure' also accepts some other, not widely useful, options. Run
+`configure --help' for more details.
@@ -1,5 +1,9 @@
SUBDIRS = @subdirs@ testdata/smpte.raw COPYING COPYING INSTALL \
+ tests/example_encode.c \
+ tests/timecode.raw tests/timecode.txt \
+ tests/expect_48k_2sec.txt tests/expect_96k_2sec.txt
pkgconfigdir = $(libdir)/pkgconfig
pkgconfig_DATA = ltc.pc
@@ -10,4 +14,5 @@ dox: stamp-doxygen
stamp-doxygen: src/ltc.h doc/mainpage.dox Doxyfile
$(DOXYGEN) Doxyfile
+ cp doc/favicon.ico doc/html/
touch stamp-doxygen
@@ -7,3 +7,12 @@ The audio signal is commonly recorded on a VTR track or other storage media.
libltc provides functionality to encode and decode LTC audio from/to
SMPTE timecode, including SMPTE date support.
+libltc is the successor of [libltcsmpte](
+for more info, please see the FAQ in the documentaion.
BIN  doc/favicon.ico
Binary file not shown
56 doc/mainpage.dox
@@ -36,6 +36,46 @@
@section about About
libltc is the successor of libltcsmpte.
+ **Q**: How can I get help?
+ **A**: The preferred way is to use the issue-tracker at
+ You can also send a private-mail to the author.
+ **Q**: How good is the LTC-decoder? Will it decode my file?
+ **A**: It's doing pretty good, thanks. :)
+ We did extensive testing using LTC samples from various
+ sources and have not yet found one that libLTC does 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 an sample,
+ please contact us, we will look into ways to improve libLTC.
+ **Q**: does it support vari-speed LTC?
+ **A**: Yes. libltc tracks speed variations. Each LTC-frame is tagged with
+ the corresponding audio-sample number (start/end).
+ **Q**: does it support backwards played LTC - reverse tape direction
+ **A**: No, not yet.
+ **Q**: Is there free software is using libltc?
+ ltc-tools is in the making. It comprises two JACK applications to generate and
+ decode LTC from live audio-sources and includes 'ltcdump' which reads LTC from
+ audio-files. Stay tuned (ETA Sept/2012).
+ Currently there is self-test code, which can en&decode LTC from raw audio-data
+ (it reads 8 bit, mono .wav files, too. because they're basically just raw
+ audio-data, but the timestamps are off by the length of the .wav header.)
+ There are lots of tools (incl iOS applications and NLEs) using libltcsmpte.
+ We dare say that many - if not most - of them will be updated to libLTC in time.
**Q**: What is the difference between libltcsmpte and libltc?
**A**: Functionally, there is little difference, usage and work-flow are very similar, too.
@@ -72,6 +112,21 @@
**A**: yes. I could have done that.
+ **Q**: libltcsmpte can be compiled to use any kind of audio-sample (float, 16bit,..)
+ Why is libltc limited to 8bit unsigned?
+ **A**: Selecting the sample-format is a compile time option in libltcsmpte. Changing
+ it breaks the ABI (the shared-lib will only be usable for applications compiled
+ with exactly that version of libltcsmpte).
+ 8bit samples are more than sufficient to carry LTC information.
+ Changing the audio-sample type from one format to another is trivial.
+ The internal decoder has been re-factored so that it performs really
+ well also when feeding one sample at a time. So samples can be
+ converted and fed into it on the fly. - Future versions of
+ libltc may actually include wrappers that do the conversion.
@section usage Usage
Consult \ref ltc.h for a detailed reference of available functions.
The documentation is also available as Unix manual pages.
@@ -112,5 +167,6 @@ Copyright (C) 2008-2010 by Jan Weiß
\example ltcdecode.c
\example ltcencode.c
+\example example_encode.c
24 doc/man/man3/ltc.h.3
@@ -1,4 +1,4 @@
-.TH "ltc.h" 3 "Wed Aug 15 2012" "Version 0.0.1" "libltc" \" -*- nroff -*-
+.TH "ltc.h" 3 "Wed Aug 15 2012" "Version 0.5.0" "libltc" \" -*- nroff -*-
.ad l
@@ -219,7 +219,7 @@ unsigned int \fIsecs_tens:3\fP
unsigned int \fIsecs_units:4\fP
-unsigned int \fIsyncWord:16\fP
+unsigned int \fIsync_word:16\fP
unsigned int \fIuser1:4\fP
@@ -275,7 +275,7 @@ Human readable time representation, decimal values\&.
\fBExamples: \fP
.in +1c
-\fBltcdecode\&.c\fP, and \fBltcencode\&.c\fP\&.
+\fBexample_encode\&.c\fP, \fBltcdecode\&.c\fP, and \fBltcencode\&.c\fP\&.
\fBData Fields:\fP
.RS 4
@@ -466,7 +466,7 @@ moves the SMPTE to the next timecode frame\&. uses \fBltc_frame_increment()\fP i
\fBExamples: \fP
.in +1c
+\fBexample_encode\&.c\fP, and \fBltcencode\&.c\fP\&.
.SS "\fBLTCEncoder\fP* ltc_encoder_create (doublesample_rate, doublefps, intuse_date)"
Allocate and initialize LTC audio encoder\&.
@@ -485,7 +485,7 @@ Note: if fps equals to 29\&.97 or 30000\&.0/1001\&.0, the \fBLTCFrame\fP's 'dfbi
\fBExamples: \fP
.in +1c
+\fBexample_encode\&.c\fP, and \fBltcencode\&.c\fP\&.
.SS "int ltc_encoder_encode_byte (\fBLTCEncoder\fP *e, intbyte, doublespeed)"
Generate LTC audio for given byte of the LTC-frame and place it into the internal buffer\&.
@@ -511,7 +511,7 @@ LTC has 10 bytes per frame: 0 <= bytecnt < 10 use SMPTESetTime(\&.\&.) to set th
\fBExamples: \fP
.in +1c
.SS "void ltc_encoder_encode_frame (\fBLTCEncoder\fP *e)"
encode a full LTC frame at fixed speed\&. This is equivalent to calling \fBltc_encoder_encode_byte\fP 10 times for bytes 0\&.\&.9 with speed 1\&.0\&.
@@ -526,7 +526,7 @@ Note: The buffer must be empty before calling this function\&. This is usually t
\fBExamples: \fP
.in +1c
+\fBexample_encode\&.c\fP, and \fBltcencode\&.c\fP\&.
.SS "void ltc_encoder_free (\fBLTCEncoder\fP *e)"
release encoder data structure
@@ -539,7 +539,7 @@ release encoder data structure
\fBExamples: \fP
.in +1c
+\fBexample_encode\&.c\fP, and \fBltcencode\&.c\fP\&.
.SS "int ltc_encoder_get_buffer (\fBLTCEncoder\fP *e, \fBltcsnd_sample_t\fP *buf)"
copy the accumulated encoded audio to the given sample-buffer and flush the buffer\&.
@@ -559,7 +559,7 @@ the number of bytes written to the memory area pointed to by buf\&.
\fBExamples: \fP
.in +1c
.SS "size_t ltc_encoder_get_buffersize (\fBLTCEncoder\fP *e)"
query the length of the internal buffer\&. It is allocated to hold audio-frames for exactly one LTC frame for the given sample-rate and frame-rate\&. ie\&. (1 + sample-rate / fps) bytes
@@ -577,7 +577,7 @@ size of the allocated internal buffer\&.
\fBExamples: \fP
.in +1c
.SS "\fBltcsnd_sample_t\fP* ltc_encoder_get_bufptr (\fBLTCEncoder\fP *e, int *size, intflush)"
get a pointer to the accumulated encoded audio-data\&.
@@ -599,7 +599,7 @@ pointer to encoder-buffer
\fBExamples: \fP
.in +1c
+\fBexample_encode\&.c\fP, and \fBltcencode\&.c\fP\&.
.SS "void ltc_encoder_get_frame (\fBLTCEncoder\fP *e, \fBLTCFrame\fP *f)"
low-level access to the internal \fBLTCFrame\fP data
@@ -651,7 +651,7 @@ set the encoder LTC-frame from given \fBSMPTETimecode\fP\&.
\fBExamples: \fP
.in +1c
+\fBexample_encode\&.c\fP, and \fBltcencode\&.c\fP\&.
.SS "int ltc_frame_increment (\fBLTCFrame\fP *frame, intfps, intuse_date)"
increment the timecode by one SMPTE-Frame (1/framerate seconds)

0 comments on commit a1b3082

Please sign in to comment.
Something went wrong with that request. Please try again.