SMPTE-X SMPTE/LTC Reader Writer

The SMPTE-X Active-X control is no longer offered as a standalone Drastic SDK. Its functionality still exists within the Drastic product line and the below information is provided for reference.

SMPTEX is a time code reader and generator that uses a standard audio board to produce and read SMPTE longitudinal time code (LTC). It provides both a simple interface where the control handles the audio board and a more advanced interface where the caller deals with the audio board. The control is intended to replace the functionality of PC based time code boards (costing as much as one thousand dollars in the old days) without dedicating a slot or being obliged to work with proprietary hardware.

This document describes the programming interface for the SMPTE-X Active-X control.

The SMPTE-X control supports the following formats and interfaces:

• NTSC Non-Drop Frame
• NTSC Drop Frame
• PAL (25 frames per second)
• FILM (24 frames per second)
• User Bits (8 Bytes per frame)
• Forward and reverse direction reading
• Non play speed reading
• Automatic time code 'jam' for drop outs
• A simple read/generate interface (ISmpte)
• A buffer fill/read interface (ISmpteDirect)
• Error, jam and info flags
• Time code, User bits and Flag change events
• Current state properties
• Visual C++, Borland Power Builder, Visual Basic, Delphi and other Active X compatible development environments

Installation

The development disks include an automatic installer which is run from the SETUP.EXE program on the disk. The example code that accompanies the programs should be unzipped using the -d option into a directory of your choice. The zip includes subdirectories.

Interfaces

The basic interface is described below. It is actually two separate interfaces:
ISmpte – Simple interface (SMPTEX controls the audio board)
ISmpteDirect – Buffer interface (you control the audio board)

// Interfaces for Smpte X?
// C like overview
ISmpte

// Methods
long Read(void);
long Generate(long lTC, long lUB, long lFlags);
long Stop(void);
BSTR Wave Dev Name?(short sWaveDev)
long Wave Dev Formats?(short sWaveDev)
short Wave Dev Channels?(short sWaveDev)

// Properties
long Cur TC?;     // R / O?
long Cur UB?;     // R / O?
long Cur Flags?;     // R / O?
short Cur Wave Dev?;     // R / W? (default -1 = WAVE_MAPPER)
short Cur Wave Dev Channels?;     // R / W? (1 Left, 2 Right, ~ Auto / Both?)
short Num Wave Dev?;     // R / O?
long Last State?;     // Rdr / Gen? state flags R / O?

// Events
void Change TC?(long lTC);
void Change UB?(long lUB);
void Change Flags?(long lFlags);

ISmpteDirect

// Methods
long Setup(LONG lWaveFormat, long lFlags);

void Decode Start?(void * pBuf, long lSize);
long Decode(long * plTC, long * plUB, long * plFlags, long *lBytesProcessed);

long Encode Start?(long lTC, long lUB, long lFlags);
long Encode(void * pBuf, long lSize);

long Get Buffer Size?(long lFlags);

// Properties
long Sample Rate?     // R / O? 11, 22 or 44 kHz
BOOL f16Bit;     // R / O? If false, 8 bit
long Last State?;     // R / O? Rdr / Gen? state flags

ISmpte – Methods

long Read(void)
Begin reading SMPTE time code from the audio board. This uses method the current wave device and channel settings to try to decode incoming time code. The decoded values will be placed in the Cur TC / UB / Flags? properties and changeTC/UB/Flags events will be called as necessary. The control will continue to read until the Generate or Stop methods are called.

long Generate(long lTC, long lUB, long lFlags)
Begin generating SMPTE time code from the audio board. This method uses the current wave device and channel settings to generate SMPTE time code. The starting values are passed into the method by lTC/lUB/Flags. The generator will increment the time code based on the flags and continue generating until the Read or Stop methods are called.

long Stop(void)
Stop generating or reading time code.

BSTR Wave Dev Name?(short sWaveDev)
Return the audio board manufacturer's name for the wave device.

long Wave Dev Formats?(short sWaveDev)
Return the supported formats for the wave device.

short Wave Dev Channels?(short sWaveDev)
Return the supported channels for the wave device.

ISmpte – Properties

long Cur TC?
Contains the current time code being read or generated. This property is read only.

long Cur UB?
Contains the current user bits being read or generated. This property is read only.

long Cur Flags?
Contains the current flags being read or being used to generate. This property is read only.

short Cur Wave Dev?
Used to set the wave device to be used. If the control is reading or generating, this property contains the device number that control is using. This property must be set when the control is in Stop mode. Any change in Read or Generate mode will be ignored.

short Cur Wave Dev Channels?
Used to set the channel's wave device to be used. If the control is reading or generating, this property contains the channels that control is using. This property must be set when the control is in Stop mode. Any change in Read or Generate mode will be ignored.

short Num Wave Dev?
Contains the total number of audio devices found in the system. This count contains only physical audio devices. Aside from these devices the Microsoft Wave Mapper may be used (Cur Wave Dev? = -1). This property is read only.

long Last State?
Contains extended reader generator flags. Used to indicate errors in the incoming time code including drop outs and time code jamming.

ISmpte – Events

void Change TC?(long lTC)
Called whenever the time code changes. Although it is mostly used in the reader mode, it is also active in the generator mode. The current time code is passed through lTC.

void Change UB?(long lUB)
Called whenever the user bits change. This is only applicable to the reader as the user changes the bits in generator mode. The current user bits are passed through lUB.

void Change Flags?(long lFlags)
Called whenever the flags change. This is only applicable to the reader as the user changes the flags in generator mode. The current flags are passed through lFlags.

ISmpteDirect – Methods

long Setup(LONG lWaveFormat, long lFlags)
This method configures the encode and decode routines and returns the maximum buffer size required for one frame of time code based on the requested wave format (sample rate, size and channels) and the requested time code flags (NDF, DF, PAL or Film). The required size on a per frame basis is returned during the encode and decode process, but will never be larger than the size returned here.

void Decode Start?(void * pBuf, long lSize)
Once the control is set up, the captured audio buffer is to Decode Start? to decode the SMPTE time code. This method takes a pointer to the wave data in pBuf and the size of the captured buffer. Once called, the Decode method will decode and return the information for the buffer. This method is called again whenever the Decode method exhausts the buffer. Note lSize must be block aligned - see the block alignment section below.

long Decode(long * plTC, long * plUB, long * plFlags, long *lBytesProcessed)
Decode the current buffer of SMPTE wave data and return the time code, user bits and flags found. Also return the number of bytes processed to get those values. If the decode runs out of data, the STBUFFER_EXAUSTED will be returned and more data should be supplied via Decode Start?.

long Encode Start?(long lTC, long lUB, long lFlags)
Setup the time code, user bits and flags for the current encode. This method returns the number of bytes required to encode the information passed in using the flags passed in. The return value will vary slightly on a frame by frame basis. To actually encode, a buffer must be passed to the Encode method below.

long Encode(void * pBuf, long lSize)
Encode the current time code and user bits into the buffer supplied by pBuf. This method returns the number of bytes processed. Once the encode calls return zero, the encode is out of buffer. The Encode Start? method should be used to supply more buffers. Note lSize must be block aligned (see the block alignment section below). Also note the size returned from encode start is block aligned.

long Get Buffer Size?(long lFlags)
Get the maximum required buffer size required for encode. It can be used as an estimated buffer size for decode at standard play speed, however decodes can vary greatly. The actual buffer size required for an encoded frame is returned by the Encode Start? Method. This value will vary depending on the flags and video standard used.

ISmpteDirect – Methods

long Sample Rate?
Contains the current sample rate being used to encode and decode. This property is read only, and is set by the Setup method.

BOOL f16Bit
If this property is true, then a 16 bit sample size is being used. If it is false, then an 8 bit sample size is being used. This property is read only, and is set by the Setup method.

long Last State?
Contains extended reader generator flags. Used to indicate errors in the incoming time code including drop outs and time code jamming.

Constants

Flags
Used by ISmpte::Generate, ISmpte::CurFlags, ISmpte::changeFlags, ISmpteDirect::Setup, ISmpteDirect::Decode, ISmpteDirect::EncodeStart, ISmpteDirect::GetBufferSize

TC2_TCTYPE_FILM
Using Film time code at 24 frames per second.
TC2_TCTYPE_NDF
Using NTSC Non-Drop frame time code at 29.97/30 frames per second.
TC2_TCTYPE_DF
Using NTSC Drop frame time code at 29.97 frames per second.
TC2_TCTYPE_PAL
Using PAL time code at 25 frames per second.
TC2_STREXT_CF
Using the colour frame flag.

Wave Format?
Used by ISmpteDirect::Setup

WAVE_FORMAT_1M08    – 11 kHz, 8 Bit, Mono
WAVE_FORMAT_1M16    – 11 kHz, 16 Bit, Mono
WAVE_FORMAT_1S08    – 11 kHz, 8 Bit, Stereo (requires WAVE_FORMAT_CH_...)
WAVE_FORMAT_1S16    – 11 kHz, 16 Bit, Stereo (requires WAVE_FORMAT_CH_...)

WAVE_FORMAT_2M08    – 22 kHz, 8 Bit, Mono
WAVE_FORMAT_2M16    – 22 kHz, 16 Bit, Mono
WAVE_FORMAT_2S08    – 22 kHz, 8 Bit, Stereo (requires WAVE_FORMAT_CH_...)
WAVE_FORMAT_2S16    – 22 kHz, 16 Bit, Stereo (requires WAVE_FORMAT_CH_...)

WAVE_FORMAT_4M08    – 44 kHz, 8 Bit, Mono
WAVE_FORMAT_4M16    – 44 kHz, 16 Bit, Mono
WAVE_FORMAT_4S08    – 44 kHz, 8 Bit, Stereo (requires WAVE_FORMAT_CH_...)
WAVE_FORMAT_4S16    – 44 kHz, 16 Bit, Stereo (requires WAVE_FORMAT_CH_...)

WAVE_FORMAT_5M08    – 48 kHz, 8 Bit, Mono
WAVE_FORMAT_5M16    – 48 kHz, 16 Bit, Mono
WAVE_FORMAT_5S08    – 48 kHz, 8 Bit, Stereo (requires WAVE_FORMAT_CH_...)
WAVE_FORMAT_5S16    – 48 kHz, 16 Bit, Stereo (requires WAVE_FORMAT_CH_...)

Wave Format Channels?
Used by ISmpte::CurWaveDevChannels, ISmpteDirect::Setup

WAVE_FORMAT_CH_LEFT
Use the left channel of a stereo wave.
WAVE_FORMAT_CH_RIGHT
Use the right channel of a stereo wave.

Status Returns

STSMPTE_BUFFER_EXAUSTED
The ISmpteDirect encode or decode has run out of wave buffer. The call should supply buffers to continue encoding or decoding.

STSMPTE_TC_FOUND
A time code was successfully decoded.

STSMPTE_TC_FOUND_SKIP
More than one valid time code was found. The last time code successfully decoded has been returned.

Error Returns

ERRSMPTE_NO_ALLOC
No allocated memory available.

ERRSMPTE_NO_SYNCRO_OBJECT
Unable to create Windows synchronization object.

ERRSMPTE_NO_WAVE_DEVICE_AVAILABLE
The selected wave device is already in use, or not operating properly. May also occur if the selected wave device does not support the requested wave format.

ERRSMPTE_INVALID_WAVE_FORMAT
Either the wave device does not support the wave format, or the wave format is not recognized.

ERRSMPTE_WAVE_OUT_FAIL
A failure to open the wave output device (audio hardware problem)

ERRSMPTE_WAVE_IN_FAIL
A failure to open the wave input device (audio hardware problem)

ERRSMPTE_ILLEGAL_SAMPLE_SIZE
The sample size must be 8 or 16 bits.

ERRSMPTE_ILLEGAL_SAMPLE_RATE
Only 11025, 22050, 44100 and 48000 samples per second are supported.

ERRSMPTE_ILLEGAL_FLAGS
The control cannot understand the flags passed to it.

Notes on block alignment:
A size that requires block alignment must be a a multiple of a block size. The block size = samplesize * number of channels. For example, in the case of a 16 bit mono the sample size (16 Bits) is 2 bytes, and the number of channels is 1, yielding a block size of 2 bytes per sample. For the case of 16 bit stereo, the sample size (16 Bits) is 2 bytes, and the number of channels is 2, yielding a block size of 4 bytes per sample.

Miscellaneous

Please see the supplied examples for further information on using the Smpte X? control.

Both the examples and the Smpte X? control use the TCXlat time code translation Active X? control. This control is used to translate between frame counts and strings of time code as well as translation for user bits and strings. For more information on this control, see the TCXlat Active X? manual.

For more information on Drastic OEM Components, contact us This email address is being protected from spambots. You need JavaScript enabled to view it..