dmLTC(3dm) dmLTC(3dm) NAME dmLTCDecoderCreate, dmLTCDecoderSetParams, dmLTCDecode, dmLTCDecoderDestroy - decode linear timecode (LTC) SYNOPSIS #include <dmedia/dm_ltc.h> DMstatus dmLTCDecoderCreate ( DMLTCdecoder **decoder, int tc_type); DMstatus dmLTCDecoderSetParams ( DMLTCContext *decoder, DMparams *audioparams, int timecodeChannel); DMstatus dmLTCDecode ( DMLTCContext *decoder, void **sampleBuffer, int *sampleCount, DMLTCcode *dmLTCcodeword); void DMLTCDecoderDestroy ( DMLTCContext *decoder ); DESCRIPTION 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. 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. 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. SEE ALSO 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) Page 3