IAMTimecodeReader Interface
You can implement the IAMTimecodeReader interface to read SMPTE (Society of Motion Picture and Television Engineers) or MIDI timecode from an external device. It contains properties and methods that specify the timecode format that an external device should read, and how it is embedded in the media. It is expected that you will use this interface with the IAMExtDevice and IAMExtTransport interfaces to control an external device, such as a VCR, which can read timecode data.
SMPTE timecode is a frame addressing system that identifies video and audio sources, makes automatic track synchronization possible, and provides a container for additional data related to the source material. SMPTE timecode's main purpose is to provide a machine-readable address for video and audio. It is displayed in hh:mm:ss:ff (hours, minutes, seconds, frames) format and is thoroughly defined in ANSI/SMPTE 12-1986.
For more information on SMPTE timecode, see Control an External Device in DirectShow.
Implement this interface on an external device filter when you want to specify how an external device should read SMPTE/MIDI timecode information.
Expose the IMediaSeeking interface on your filter so that applications can convert timecode to Microsoft® DirectShow® reference time (by using the IMediaSeeking::ConvertTimeFormat method).
Your external device must be able to read timecode and send it to the computer over its control interface. If this is not the case, you must either have a timecode reader card in your computer, or you can write a software decoder that converts VITC (Vertical Interval Timecode) in captured video frames or LTC (Linear Timecode) captured as an audio signal into DirectShow timecode samples.
Use this interface when you need to read timecode information for controlling an external device, or when you want to use timecode information from an external device in applications that must refer to original program information.
Applications generally save timecode in one of two ways. It is either written to the capture file as an additional stream or as a discontinuity table stored in the extended AVI file index. It is commonly used to trigger capture or playback and to create edit decision lists that describes how source material is organized into a finished product.
If you intend to capture timecode, treat it as a separate stream that has its own media type. It can be consumed by an appropriate file-writing multiplexer filter. However, sometimes there are errors in reading the timecode off the tape because of dropouts and other mechanical tape problems. In such cases, the timecode source filter should simply drop samples and mark the next valid one with the discontinuity property.
If you intend to use timecodes to trigger capture or playback from a timecoded (or "striped") videotape, the sequence of events goes as follows:
- Build a capture graph, open a target AVI file, and pre allocate disk space if necessary. If the captured material will be appended to an existing AVI file, seek to the end of the file before writing. The capture graph is paused at this point.
- Search the VCR to the capture start point and note the timecode. You can either enter this value manually into your program, or the application can automatically read it. Automatic reading requires that the graph is running but the stream control interfaces on the file multiplexer's input pins are discarding incoming samples, effectively gating the capture.
- Cue the VCR to preroll position, usually five seconds before the target point.
- Start the VCR and the graph. When the trigger point is reached (or the trigger point minus the file writer's preroll), the stream control interfaces release the file multiplexer and it begins streaming media samples to the file writer.
- You can stop the capture process manually or by setting a duration property on the stream control interface.
You must consider discontinuous timecode, both during preroll and during the capture process; it is reasonable to demand that the timecode be continuous and monotonically increasing throughout the preroll and capture start point. This prevents a potentially ambiguous calculation of relative stream times by the IMediaSeeking::ConvertTimeFormat method. Also, the timecode need not be the only gating signal for triggered capture. Any time-stamped data stored in the vertical blanking interval, such as Intercast or closed-captioned data (XDS), can be used to start the streaming of video and audio data to disk.
See the IAMExtTransport interface for hardware requirements.
Methods in Vtable Order
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IAMTimecodeReader methods Description GetTCRMode Retrieves properties of the timecode reader. SetTCRMode Sets the timecode reader properties. put_VITCLine Specifies the vertical interval line that the timecode reader will use to read timecode. get_VITCLine Retrieves the vertical interval line that the timecode reader is using to read timecode. GetTimecode Retrieves the most recent timecode, userbits, and flag values available in the stream.
IAMTimecodeReader::GetTCRMode
Retrieves the timecode reader's properties.
Syntax
HRESULT GetTCRMode(
long Param,
long *pValue
);
Parameters
- Param
- [in] Timecode reader property to get (either ED_TCR_SOURCE or ED_TCR_NOTIFY_ENABLE).
- pValue
- [out] Pointer to the value of the requested timecode reader property. If Param is set to ED_TCR_NOTIFY_ENABLE, then this parameter will return OATRUE—meaning that notifications are enabled—or OAFALSE. If Param is set to ED_TCR_SOURCE, then this value must be one of the following:
ED_TCR_CT Control track ED_TCR_LTC Linear timecode ED_TCR_VITC Vertical interval timecode ED_TCR_LAST_VALUE Last read value
Return Value
Returns an HRESULT value that depends on the implementation of the interface.
Remarks
Linear timecode is recorded on an analog audio track as a bi-phase mark-encoded signal. Each timecode frame is one video frame time in duration.
Vertical timecode is usually stored in two lines of a video signal's vertical interval, somewhere between lines 11 and 20.
Control track is a once-per-frame signal recorded on a special track on a tape. The head and drive servo mechanisms use it to keep everything locked. It is also used to drive the counter on machines without timecode capability, and can optionally be used on machines equipped with a timecode reader.
Note that ED_TCR_LAST_VALUE is used when implementing timecode notification because the application does not want to initiate another timecode request to the external device. This method is not recommended for frame-accurate applications because of multithreading issues.
See Also
IAMTimecodeReader::GetTimecode
Retrieves the most recent timecode, userbit, and flag values available in the stream.
Syntax
HRESULT GetTimecode(
PTIMECODE_SAMPLE pTimecodeSample
);
Parameters
- pTimecodeSample
- [out] Pointer to a TIMECODE_SAMPLE timecode structure.
Return Value
Returns an HRESULT value that depends on the implementation of the interface.
Remarks
Use this method to monitor the timecode and to parse duplicates and discontinuities. The source filter supplying the timecode, or possibly a downstream filter, might want to parse for discontinuities or errors because you have to look at every sample to be able to retrieve the most recent timecode.
Applications can fill undefined bits in the timecode word to store synchronization information, or to encode original film and audio tape information. These undefined bits, or userbits, are retrieved by calling this method.
IAMTimecodeReader::get_VITCLine
Retrieves the vertical interval line that the timecode reader is using to read timecode.
Syntax
HRESULT get_VITCLine(
long *pLine );
Parameters
- pLine
- [out] Pointer to the vertical line containing timecode information (valid lines are from 11 through 20).
Return Value
Returns an HRESULT value that depends on the implementation of the interface.
Remarks
The high bit indicates that multiple lines are used and successive calls will cycle through the line numbers.
See Also
IAMTimecodeReader::put_VITCLine
Specifies the vertical interval line that the timecode reader will use to read timecode.
Syntax
HRESULT put_VITCLine(
long Line );
Parameters
- Line
- [in] Vertical line containing timecode information (valid lines are 11-20; 0 means autoselect).
Return Value
Returns an HRESULT value that depends on the implementation of the interface.
Remarks
If VITC mode is specified in the IAMTimecodeReader::SetTCRMode method, you must specify which line or lines will contain timecode information. To read VITC on specific multiple lines, the caller would make successive calls to put_VITCLine, once for each line desired.
Set the hi bit to add to the list of lines for readers that test across multiple lines.
See Also
IAMTimecodeReader::SetTCRMode
Sets the timecode reader properties.
Syntax
HRESULT SetTCRMode(
long Param,
long Value
);
Parameters
- Param
- [in] Property you want to set (use ED_TCR_SOURCE or ED_TCR_NOTIFY_ENABLE).
- Value
- [in] Value of the specified property; If Param returns ED_TCR_NOTIFY_ENABLE, then this value will return OATRUE or OAFALSE. IfParam returns ED_TCR_SOURCE, then this value must be one of the following:
ED_TCR_CT Control Track ED_TCR_LTC Linear Timecode ED_TCR_VITC Vertical Interval Timecode ED_TCR_LAST_VALUE Return last read value.
Return Value
Returns an HRESULT value that depends on the implementation of the interface.
Remarks
Linear timecode is recorded on an analog audio track as an NRZ bi-phase mark-encoded signal. Each timecode frame is one video frame time in duration.
Vertical timecode is usually stored in two lines of a video signal's vertical interval, somewhere between 10 and 20.
Control track is a once-per-frame signal recorded on a special track on a tape. The head and drive servo mechanisms use it to keep everything locked. It is also used to drive the counter on machines without timecode capability, and can optionally be used on machines equipped with a timecode reader.
Note that ED_TCR_LAST_VALUE is used when implementing timecode notification because the application does not want to initiate another timecode request to the external device. This method is not recommended for frame-accurate applications because of multithreading issues.
See Also
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.