---

QuickTime Sample Table API

The new QuickTime sample table API in QuickTime 7 is used when you need to obtain information about samples—such as their size, location, and sample descriptions—or to set this kind of information (for example, when adding samples or blocks of samples to a media directly, without using the services of an importer or sequence grabber).

This new API introduces QTSampleTable as a logical replacement for the arrays of sample reference records used with the older functions AddMediaSampleReferences and AddMediaSampleReferences64. New functions allow you to operate on whole tables of data simultaneously.

Like many new QuickTime APIs, the QuickTime sample table API uses opaque data types whose properties can be discovered dynamically at runtime. This is analogous to the component properties API for configuring components. You use a GetPropertyInfo function to discover the size and format of a property, then allocate the necessary container or structure to get or set the actual property.

This API works with both simple media types that have a single media time for each sample and new media types such as frame reordering video that have independent decode and display times for samples.

In the QuickTime sample table API, sample numbers for audio always refer to packets. This is simpler and more consistant, but it means that a new function may not return the same value as an older, analogous function when called with reference to compressed CBR sound. For example, QTSampleTableGetNumberOfSamples may return a different sample count than GetMediaSampleCount.

All compressed audio is quantized into packets, and each packet can be decompressed into multiple PCM samples. With previous APIs, media sample numbers for CBR sound refer to PCM samples, rather than the compressed packets. When the same APIs are applied to variable-bit-rate (VBR) sound, however, the sample numbers refer to packets. This inconsistency means that code using these older APIs must handle CBR and VBR differently. In this API, by contrast, sample numbers always refer to packets.

This applies only to compressed CBR sound, however. In uncompressed sound tracks, each packet is simply an uncompressed PCM frame, so the value is the same whether the sample number refers to packets or PCM samples.

For full details of the QuickTime sample table API, see:

• QTSampleTableCreateMutable

• QTSampleTableCreateMutableCopy

• QTSampleTableAddSampleDescription

• QTSampleTableCopySampleDescription

• QTSampleTableAddSampleReferences

• AddSampleTableToMedia

• CopyMediaMutableSampleTable

• QTSampleTableReplaceRange

• QTSampleTableGetProperty

• QTSampleTableSetProperty

• QTSampleTableGetPropertyInfo

• QTSampleTableGetNumberOfSamples

• QTSampleTableGetSampleDescriptionID

• QTSampleTableGetDataSizePerSample

• QTSampleTableGetSampleFlags

• QTSampleTableGetDataOffset

• QTSampleTableGetDisplayOffset

• QTSampleTableGetTypeID

• QTSampleTableGetDecodeDuration

• QTSampleTableGetNextAttributeChange

• QTSampleTableGetTimeScale

• QTSampleTableRelease

• QTSampleTableReplaceRange

• QTSampleTableRetain

• QTSampleTableSetTimeScale

---