-
Notifications
You must be signed in to change notification settings - Fork 36
Media related functions
ISOErr ISOAddMediaDataReference( ISOMedia theMedia,
u32 *outReferenceIndex, ISOHandle urlHandle,
ISOHandle urnHandle );Use this to add a data reference to a media container. The data reference specifies a location for media samples. The outReferenceIndex parameter is updated to contain the index for the new reference. (You will need to use this index to create a sample description that will point to this new data reference.) The other parameters include:
urlHandle
UTF-8 encoded file:// URL that indicates the file containing the samples. Set this to NULL to indicate that the samples are in the movie’s file.
urnHandle
UTF-8 encoded URN. This may be used in addition to urlHandle to indicate the uniform resource name associated with this media file. If no URN is used, set urnHandle to NULL.
ISOErr ISOAddMediaSampleReference( ISOMedia media,
u64 dataOffset, u32 sampleCount,
ISOHandle durationsH, ISOHandle sizesH,
ISOHandle sampleEntryH,
ISOHandle compositionOffsetsH,
ISOHandle syncSamplesH );Use this function to add samples to a media by reference. This is usually used when the samples are already present in some file, for example when you are making reference to samples contained in an external file. There are a number of parameters:
dataOffset
The byte offset into the file containing the samples. All samples added in this function are assumed to be contiguous in the file starting at this offset.
sampleCount
The number of samples to be added in this call.
durationsH
A handle containing u32[] durations for each sample to be added. If the durations differ you must supply a duration for each sample. If the durations are constant you should only place one entry in this handle.
sizesH
A handle containing u32[] sizes (in bytes) for each sample to be added. If the sizes differ you must indicate a size for each sample. If the sizes are constant you should only place one entry in this handle.
sampleEntryH
Contains a sample entry that describes the samples to be added. For MPEG-4, this entry can be created using MP4CreateSampleDescription, or for both MJ2 and MP4 you can supply your own as long as it is formatted according to the appropriate standard. If this handle is set to NULL the previous non-null sample entry will be used.
compositionOffsetsH
If the media contains separate decoding and composition timestamps you must use this handle to indicate the offset between the composition time and the decoding time for each sample in a u32[]. Note that samples must be added in decoding order.
syncSamplesH
If all the samples added are sync samples you can set this to NULL. Otherwise, place the one-based indexes of each sync sample into this handle as a u32[]. If none of the samples you are adding is a sync sample this handle will have a size of zero.
ISOErr ISOAddMediaSamples( ISOMedia media,
ISOHandle sampleH,
u32 sampleCount,
ISOHandle durationsH,
ISOHandle sizesH,
ISOHandle sampleEntryH,
ISOHandle compositionOffsetsH,
ISOHandle syncSamplesH );Use this function to samples to the media. The sampleH parameter contains the data for all the samples. It is interpreted according to the other parameters, which work the same as described for ISOAddMediaSampleReference.
ISOErr ISOAddMediaSamplesPad( ISOMedia media,
ISOHandle sampleH,
u32 sampleCount,
ISOHandle durationsH,
ISOHandle sizesH,
ISOHandle sampleEntryH,
ISOHandle compositionOffsetsH,
ISOHandle syncSamplesH
ISOHandle padsH);
ISOErr ISOAddMediaSampleReferencePad( ISOMedia media,
u64 dataOffset, u32 sampleCount,
ISOHandle durationsH, ISOHandle sizesH,
ISOHandle sampleEntryH,
ISOHandle compositionOffsetsH,
ISOHandle syncSamplesH
ISOHandle padsH);These functions are like AddMediaSamples and ISOAddMediaSampleReference, except that it is possible to supply padding bits information for the samples (causing the insertion of a padding bits table in the output file). The parameter padsH may be NULL, indicating no pad, or may be a handle to an array of padding values (which are 8 bits each). If the array has only one value, then it is used for all the samples; otherwise, the array should be sampleCount long.
ISOErr ISOBeginMediaEdits( ISOMedia theMedia );Use this function to prepare the media before adding samples.
ISOErr ISOCheckMediaDataReferences( ISOMedia theMedia );Tests all data references in the media to ensure that the references exist and are readable.
ISOErr ISOCheckMediaDataRef ( ISOMedia theMedia, u32 dataEntryIndex );Tests a specific data reference in the media to ensure that the reference exists and is readable.
ISOErr MP4GetMediaDataRefCount( MP4Media theMedia, u32 *outCount );Returns the number of data references.
ISOErr ISOEndMediaEdits( ISOMedia theMedia );Call this function when you have finished adding samples to the media.
ISOErr ISOGetIndMediaSample( ISOMedia theMedia,
u32 sampleNumber,
ISOHandle outSample,
u32 *outSize,
u64 *outDecodingTime,
s32 *outCTSOffset,
u64 *outDuration,
u32 *outSampleFlags,
u32 *outSampleDescIndex );Returns a sample from the media, given the sample's index. Parameters include:
sampleNumber
The index of the desired sample within its Media. This index runs from one to the total number of samples in the Media.
outSample
The data for the desired sample. This is the raw access unit without any headers.
outSize
The size of the returned sample in bytes.
outDecodingTime
The decoding time for the sample using the media time scale.
outCTSOffset
The composition time offset for the sample using the media time scale.
outDuration
The sample's duration in units of media time scale.
outSampleFlags
Flags that indicate the nature of this sample. Values are combinations of MP4MediaSampleNotSync if the sample is not a sync sample and MP4MediaSampleHasCompositionOffset if the sample’s DTS differs from its CTS.
outSampleDescIndex
The index of the sample description that corresponds to this sample in the media.
ISOErr MP4GetIndMediaSampleReference( MP4Media theMedia,
u32 sampleNumber,
u32 *outOffset,
u32 *outSize,
u32 *outDuration,
u32 *outSampleFlags,
u32 *outSampleDescIndex,
MP4Handle sampleDesc);Returns a reference (offset and size) for the sample from the media, given the sample's index.
ISOErr ISOGetIndMediaSampleWithPad( ISOMedia theMedia,
u32 sampleNumber,
ISOHandle outSample,
u32 *outSize,
u64 *outDecodingTime,
s32 *outCTSOffset,
u64 *outDuration,
u32 *outSampleFlags,
u32 *outSampleDescIndex
u8 *outPad );Returns a sample from the media, given the sample's index. If the track has no recorded padding table (no padding information) then the padding value returned will be 0xF8. This is not a legal value for actual padding and should not be supplied to calls which add samples.
ISOErr ISOGetMediaDataReference( ISOMedia theMedia,
u32 index,
ISOHandle referenceURL,
ISOHandle referenceURN,
u32 *outReferenceType,
u32 *outReferenceAttributes );Use this to get information about a specific data reference to a media container. The data reference specifies a location for media samples. Note that data references to samples contained in the movie's file are treated as URL reference types with no name and a special attribute bit set. The parameters are:
index
The index of the desired data reference. This number ranges from one to the number of data references in the media.
referenceURL
Will be set to a UTF-8 encoded file:// URL that indicates the file containing the samples. If the data reference doesn't contain a URL the handle size will be set to zero. Set referenceURL to NULL if you do not want this information.
referenceURN
UTF-8 encoded URN. This may be used in addition to urlHandle to indicate the uniform resource name associated with this media file. If the data reference does not contain a URN the handle size will be set to zero. Set referenceURN to NULL if you do not want this information.
outReferenceType
This will be set to MP4URLDataReferenceType or MP4URNDataReferenceType to indicate the type of data reference.
outReferenceAttributes
Returns the attributes of the data reference as a bit set. The only bit currently defined is MP4DataRefSelfReferenceMask which will be set if the media's samples are contained in the same file as the movie.
ISOErr ISOGetMediaDuration( ISOMedia theMedia, u64 *outDuration );Use this function to get the total duration of the media, expressed in the media’s time scale.
ISOErr ISOGetMediaHandlerDescription( ISOMedia theMedia,
u32 *outType, ISOHandle *outName );This function can be used to obtain the media type. The outType parameter is set to contain the media handler. Examples are ISOVisualHandlerType and ISOAudioHandlerType. This, and the decoder config information, can be used to obtain enough information to instantiate a decoder. If you want to retrieve the name for the handler you must supply a handle for outName, otherwise set outName to NULL.
ISOErr ISOGetMediaLanguage( ISOMedia theMedia, char *outThreeCharCode );Returns the ISO 639-2/T three character language code associated with the media.
ISOErr ISOGetMediaExtendedLanguageTag( ISOMedia theMedia, char **extended_language );Returns the extended language, based on RFC 4646 (Best Common Practices – BCP – 47) industry standard. Allocates memory for extended_language string. extended_language string will be set to NULL if there is no extended language tag.
ISOErr ISOGetMediaSample( ISOMedia theMedia, ISOHandle outSample,
u32 *outSize, u64 desiredDecodingTime,
u64 *outDecodingTime, u64 *outCompositionTime,
u64 *outDuration, ISOHandle outSampleDescription,
u32 *outSampleDescriptionIndex,
u32 *outSampleFlags );Returns a closest sample from the media, given the desired decoding time. Parameters include:
outSample
The data for the desired sample. This is the raw access unit without any headers.
outSize
The size of the returned sample in bytes.
desiredDecodingTime
The decoding time of the sample to be retrieved. You must specify this value in the media’s time scale.
outDecodingTime
The decoding time for the sample using the media time scale. This time may differ from the value specified in the desiredDecodingTime parameter if that parameter's value is not at a sample time boundary.
outCompositionTime
The composition time for the sample expressed in the media time scale.
outDuration
The sample's duration in units of media time scale.
outSampleFlags
Flags that indicate the nature of this sample. Values are combinations of MP4MediaSampleNotSync if the sample is not a sync sample and MP4MediaSampleHasCompositionOffset if the sample’s DTS differs from its CTS.
outSampleDescriptionIndex
The index of the sample description that corresponds to this sample in the media.
outSampleDescription
The sample description that corresponds to this sample in the media. Set this to NULL if you do not want this information to be returned.
ISOErr ISOGetMediaSampleWithPad( ISOMedia theMedia,
ISOHandle outSample,
u32 *outSize, u64 desiredDecodingTime,
u64 *outDecodingTime, u64 *outCompositionTime,
u64 *outDuration, ISOHandle outSampleDescription,
u32 *outSampleDescriptionIndex,
u32 outSampleFlags, u8* outPad );Returns a closest sample from the media, given the desired decoding time. If the track has no recorded padding table (no padding information) then the padding value returned will be 0xF8. This is not a legal value for actual padding and should not be supplied to calls which add samples.
ISOErr ISOGetMediaSampleCount( ISOMedia theMedia, u32 *outCount );Use this to determine the total number of samples contained in the media.
ISOErr ISOGetMediaTimeScale( ISOMedia theMedia, u32 *outTimeScale );Returns the time scale associated with the media.
ISOErr ISOGetMediaTrack( ISOMedia theMedia, ISOTrack *outTrack );Returns the track that is associated with this media.
ISOErr ISOMediaTimeToSampleNum( ISOMedia theMedia,
u64 desiredTime, u32 *outSampleNum,
u64 *outSampleCompositionTime,
u64 *outSampleDecodingTime,
s32 *outSampleDuration );Use this to obtain the sample number for a sample with the given decoding time. Parameters include:
desiredTime
The decoding time of the desired sample. This is expressed in the media's time scale.
outSampleNum
The sample number index for the desired sample.
outSampleCompositionTime,
outSampleDecodingTime
The composition and decoding time for the desired sample. Note that the time may differ from the desiredTime if the desired time is not on a sample boundary.
outSampleDuration
The duration of the sample, expressed in the media time scale.
ISOErr ISOSampleNumToMediaTime( ISOMedia theMedia,
u32 sampleNum,
u64 *outSampleCompositionTime,
u64 *outSampleDecodingTime,
s32 *outSampleDuration );Use this to obtain the decoding and composition times for a particular media sample. Parameters include:
sampleNum
The sample number index for the desired sample.
outSampleCompositionTime,
outSampleDecodingTime
The composition and decoding time for the desired sample.
outSampleDuration
The duration of the sample, expressed in the media time scale.
ISOErr ISOSetMediaLanguage( ISOMedia theMedia, char *threeCharCode );Use this to indicate the ISO 639-2/T three character language code that is to be associated with the media.
ISOErr ISOSetMediaExtendedLanguageTag( ISOMedia theMedia, char *extended_language );The extended language tag box represents media language information, based on RFC 4646 (Best Common Practices – BCP – 47) industry standard.
ISOErr ISOSetSampleSizeField ( ISOMedia theMedia, u32 fieldsize );Use this to set the size of samplesize entries in the sample size table. The default value is 32, which gives the ‘old’ sample size table. Values of 4, 8, or 16 (the size in bits of the field) may be given, to request the ‘compact’ sample size table.
ISOErr MP4GetMediaDecoderConfig( ISOMedia theMedia,
u32 sampleDescIndex,
ISOHandle decoderConfigH );Use this to obtain the decoder configuration descriptor for a given sample description.
ISOErr MP4GetMediaDecoderType( ISOMedia theMedia,
u32 sampleDescIndex,
u32 *outObjectType,
u32 *outStreamType,
u32 *outBufferSize,
ISOHandle specificinfoH );Use this to obtain the decoder configuration and specific info without having to parse the decoder config descriptor. (See MP4GetMediaDecoderConfig if you need all the configuration information.) Parameters are:
sampleDescIndex
Index of the sample description you desire.
outObjectType
Will contain the object type for this decoder config.
outStreamType
Will contain the stream type for this decoder config.
outBufferSize
Will contain the decoder buffer size.
specificInfoH
Handle that will contain the specific info for this decoder config The tag and length fields are stripped from the descriptor so only the configuration data remains. Set specificInfoH to NULL if you do not want this information.
ISOErr MP4GetMediaDecoderInformation( ISOMedia theMedia,
u32 sampleDescIndex,
u32 *outObjectType,
u32 *outStreamType,
u32 *outBufferSize,
u32 *outUpstream,
u32 *outMaxBitrate,
u32 *outAvgBitrate,
ISOHandle specificinfoH );Use this to obtain the complete decoder configuration and specific info without having to parse the decoder config descriptor. Parameters are:
sampleDescIndex
Index of the sample description you desire.
outObjectType
Will contain the object type for this decoder config.
outStreamType
Will contain the stream type for this decoder config.
outBufferSize
Will contain the decoder buffer size.
outUpstream
Will contain the value of the upstream flag.
outMaxBitrate
Will contain the maximum bitrate for this decoder config.
outAvgBitrate
Will contain the average bitrate for this decoder config.
specificInfoH
Handle that will contain the specific info for this decoder config The tag and length fields are stripped from the descriptor so only the configuration data remains. Set specificInfoH to NULL if you do not want this information.
ISOErr MJ2SetMediaGraphicsMode( ISOMedia theMedia,
u32 mode,
const ISORGBColor *opColor );Sets the graphics mode for this track. The mode should be chosen from the following list. The default mode is ISOGraphicsModeSrcCopy.
ISOGraphicsModeSrcCopy
This video image will be copied over the top of the layers below it. This is the default value, and should be used for the backmost track.
ISOGraphicsModeTransparent
The color ISORGBColor in this video image will be treated as transparent, allowing layers behind to be seen.
ISOGraphicsModeAlpha
This video image includes an alpha plane to define its transparency.
ISOGraphicsModeWhiteAlpha
This video image includes an alpha plane, which has been premultiplied with white, to define its transparency.
ISOGraphicsModeBlackAlpha
This video image includes an alpha plane, which has been premultiplied with black, to define its transparency.
ISOErr MJ2GetMediaGraphicsMode( ISOMedia theMedia,
u32 *outMode,
ISORGBColor *outOpColor );Returns the currently set graphics mode.
ISOErr MJ2SetMediaSoundBalance( ISOMedia theMedia, s16 balance );Sets the left-right balance of an audio track (normally a mono track). Balance values are represented as 16-bit, fixed-point numbers that range from -1.0 to +1.0. The high-order 8 bits contain the integer portion of the value; the low-order 8 bits contain the fractional part. Negative values weight the balance toward the left speaker; positive values emphasize the right channel. Setting the balance to 0 (the default) corresponds to a neutral setting.
ISOErr MJ2GetMediaSoundBalance( ISOMedia theMedia, s16 *outBalance );Returns the currently set balance value.
ISOErr ISOAddGroupDescription(
MP4Media media,
u32 groupType,
MP4Handle description,
u32* index );Adds a Sample Group Description to the indicated media. The index of the added group is returned in the index parameter. The description is the pre-serialized (big-endian format) group description.
ISOErr ISOSetSamplestoGroupType ( MP4Media media, u32 enableCompact );Sets whether this track or fragment will use a traditional sample to group map (0, default) or the newer compact sample to group map (1). Should be called only before mapping any samples in this movie or fragment.
ISOErr ISOMapSamplestoGroup(
MP4Media media,
u32 groupType,
u32 group_index,
s32 sample_index,
u32 count );Maps a set of samples to a group of a given type, after having added the samples. The parameter groupType should be set as above, and the group_index be either 0 (to map samples to no group of this type) or an index value from the call above. The number of samples for which to set the mapping is specified by count. The first of those samples to map is indicated by sample_index; if it is zero or positive, it is the sample at that offset from the first sample in the media. If it is negative, it is at that offset from the last sample in the media. For example, a sample_index of -2 and a count of 2 sets the mapping for the last two samples. If movie fragments are in use, the sample index is relative to the current fragment (and cannot be outside it), not the whole movie.
ISOErr ISOGetSampletoGroupMap(
MP4Media media,
u32 groupType,
u32 sample_number,
u32* group_index );Returns in group_index the group index associated with the given sample number of the given group type.
ISOErr ISOGetGroupDescription(
MP4Media media,
u32 groupType,
u32 index,
MP4Handle description );Returns in the handle ‘description’ the group description associated with the given group index of the given group type.
ISOErr ISOSetSampleDependency( MP4Media media,
s32 sample_index, MP4Handle dependencies );Sets the sample dependency of a set of samples, after having added the samples. The number of samples for which to set the mapping is specified by the size of the handle. The first of those samples to map is indicated by sample_index; if it is zero or positive, it is the sample at that offset from the first sample in the media. If it is negative, it is at that offset from the last sample in the media. For example, a sample_index of -2 and a count of 2 sets the dependency for the last two samples. If movie fragments are in use, the sample index is relative to the current fragment (and cannot be outside it), not the whole movie.
The handle contains a set of one-byte values each made from OR-ing together the at most one from each pair of the following constants:
does_depend_on
does_not_depend_on
is_depended_on
is_not_depended_on
has_redundancy
has_no_redundancy
ISOErr ISOGetSampleDependency( MP4Media media, s32 sample_index, u8* dependency );Returns in dependency the sample dependency associated with the given sample number.
ISOErr ISOUseSignedCompositionTimeOffsets ( MP4Media media );Sets the version of the CompositionOffsetAtom to 1, which means that negative offsets for the composition time are enabled. Call this function before adding samples to the media. This function also adds the composition to decode atom to the sample table. Note that, before you start a new movie fragment you have to call ISOSetCompositonToDecodePropertiesForFragments to set the composition to decode fields manually, because they cannot be automatically computed for fragments.
How to use
API documentation single page
- Data Types
- Movie related functions
- Track related functions
- Media related functions
- MPEG sample auxiliary information functions
- MPEG sync-layer functions
- MPEG SLConfig functions
- General Sample Description functions
- AVC Sample Description functions
- MetaData Sample Description functions
- Meta data functions
- Track reader functions
- MPEG-4 IPMPX related functions
- ISMACrypt Support
- Utility functions