dmLTC(3dm) dmLTC(3dm)
dmLTCDecoderCreate, dmLTCDecoderSetParams, dmLTCDecode,
dmLTCDecoderDestroy - decode linear timecode (LTC)
#include <dmedia/dm_ltc.h>
DMstatus dmLTCDecoderCreate [Toc] [Back]
( DMLTCdecoder **decoder, int tc_type);
DMstatus dmLTCDecoderSetParams [Toc] [Back]
( DMLTCContext *decoder,
DMparams *audioparams,
int timecodeChannel);
DMstatus dmLTCDecode [Toc] [Back]
( DMLTCContext *decoder,
void **sampleBuffer,
int *sampleCount,
DMLTCcode *dmLTCcodeword);
void DMLTCDecoderDestroy
( DMLTCContext *decoder );
These routines provide a mechanism for decoding linear (or longitudinal)
time code (LTC). LTC is a mechanism for storing and transferring SMPTE
time code as an audio-like waveform. Applications may use LTC to
synchronize audio, video, or other events with external devices by
decoding an LTC signal connected to an audio input port, or they may
parse the LTC code from a previously captured audio or movie file.
To decode LTC from an external device, the LTC or time code output of the
device should be connected to an audio input channel on the workstation.
The application then opens an audio port using the audio library (see
ALintro(3dm)).
In order to decode LTC, you first create a LTC decoder using
dmLTCDecoderCreate. The tc_type parameter tells the decoder what format
and rate of timecode to expect. The possible values for tc_type, defined
in <dmedia/dm_timecode.h>, are explained in tc_type(3dm). The
dmLTCDecoderCreate routine only pays attention to the DM_TC_FORMAT and
DM_TC_RATE bits of the passed-in tc_type, since it will be able to
determine the drop-frame/non-drop-frame status from the LTC code itself.
The currently supported timecode formats are DM_TC_FORMAT_NTSC,
DM_TC_FORMAT_PAL, and DM_TC_FORMAT_FILM. The currently supported
timecode rate values are DM_TC_RATE_2997, DM_TC_RATE_30, DM_TC_RATE_24,
and DM_TC_RATE_25.
The value returned by dmLTCDecoderCreate must be passed to all of the
other LTC routines. It may be freed by calling DMLTCDecoderDestroy.
Page 1
dmLTC(3dm) dmLTC(3dm)
The audio port configuration is set with dmLTCDecoderSetParams. The
sample format, sample resolution, and number of channels is specified by
the audioparams parameter. The channel that the LTC signal is to be
received on (0, 1, 2, or 3) is specified by the timecodeChannel
parameter.
After calling ALreadsamps to read a buffer of audio (or otherwise
obtaining the LTC samples), the procedure dmLTCDecode should be called to
decode the LTC. The sampleBuffer is a pointer to pointer to a buffer
containing audio samples in the format specified by dmLTCSetConfig. The
sampleCount is a pointer to an integer containing the number of samples
contained in sampleBuffer. Upon return, dmLTCDecode advances the sample
buffer pointer pointed to by sampleBuffer past where it has decoded and
decrements *sampleCount by a like amount. If an LTC word is successfully
decoded, dmLTCDecode returns DM_SUCCESS and fills dmLTCcodeword with the
appropriate information. An application should normally repeatedly call
dmLTCDecode until *sampleCount reaches zero.
The format of the LTC time code structure is as follows:
typedef struct {
DMtimecode tc;
unsigned int dropFrame :1;
unsigned int colorLock :1;
char userType;
char userData[4];
} DMLTCcode;
The tc structure contains a SMPTE timecode structure. This includes
hours, minutes, seconds, and frame count. The dropFrame flag indicates
whether or not the time code was recorded in a sequence that takes into
account the difference between the NTSC frame rate of 30000/1001 Hz and
the nominal rate of 30hz. In drop frame mode, the SMPTE time code is
advanced by a count of three instead of one every minute, except for
minutes 0, 10, 20, 30, 40, and 50. Note that this does not mean that an
actual video frame is ever dropped. Note also that the timecode drop
frame scheme gives you a rate of exactly 29.97 timecode frames per second
over one day, but the video rate is 30000/1001, which does not equal
29.97. So even when using drop frame timecode, timecode will drift away
from real time at a rate of approximately 2.5 frames per day. See
tc_type(3dm) for more information.
The colorLock flag indicates the relationship between the timecode and
the underlying video signal's color subcarrier phase. In the
DM_TC_FORMAT_NTSC LTC, the flag is 1 if an even timecode address (that
is, a timecode whose "frame" value mod 2 is 1) identifies a "Color Frame
A" frame as described in ANSI/SMPTE 170M. In the DM_TC_FORMAT_PAL LTC,
the flag indicates that the 4-frame PAL color sequence is aligned with
the timecode sequence such that the first field of the day will be the
first field of "frame I" of the PAL color sequence as defined in ITU-R
BT. 470.
Page 2
dmLTC(3dm) dmLTC(3dm)
The userData field contains 32 additional bits used in some applications
to contain secondary time codes or other coded data. In the LTC
codeword, the user bits are divided up into 8 4-bit user groups.
userData[0]&0x01 contains the (temporally) first bit of the first 4-bit
user group (this is bit 4 of the LTC codeword, using the bit numbering
scheme found in the LTC specifications), userData[0]&0x80 contains the
last bit of the second 4-bit user group, userData[1]&0x01 contains the
first bit of the third 4-bit user group, and so on.
The userType field is currently undefined.
ANSI/SMPTE 12M (defines LTC encoding for 525/60 video applications), EBU
Tech 3097 and IEC 461: 1986 (BS 6865:1987) (for 625/50 applications),
"Time Code: A User's Guide" by Ratcliff (Oxford: Focal Press),
dmTCFromSeconds(3dm), dmTCToSeconds(3dm), dmTCFromString(3dm),
dmTCFromString(3dm), dmTCFramesPerDay(3dm), dmTCFramesBetween(3dm),
dmVITC(3dm)
PPPPaaaaggggeeee 3333 [ Back ]
|
