public interface MaterialPackage extends Package
Specifies a material object that provides access to source packages and essence data.
This interface provides a number of methods that are useful for the management of tracks.
| Modifier and Type | Method and Description |
|---|---|
void |
addMaterialTrack(DataDefinition dataDefinition,
int sourceTrackID,
SourcePackage sourcePackage,
int materialTrackID,
String trackName)
Adds a track to this material package that references the specified
track in the specified
source package. |
void |
appendPhysSourceRef(Rational editrate,
int trackID,
DataDefinition essenceKind,
SourceReferenceValue ref,
long srcRefLength)
Connects this material package with the physical Source package that
describes the previous generation of essence, appending it to
existing package data.
|
MaterialPackage |
clone()
Create a cloned copy of this material package.
|
short |
countChannels(int trackID,
CriteriaType mediaCriteria,
DataDefinition mediaKind)
Returns the number of interleaved essence channels of a given
type in the essence stream referenced from the given track of this
material package.
|
EssenceAccess |
createEssence(int materialTrackID,
DataDefinition mediaKind,
AUID codecID,
Rational editRate,
Rational samplerate,
CompressEnable compressEnable,
Locator destination,
AUID fileFormat)
Creates a single channel stream of essence in the given track of this
material package.
|
EssenceAccess |
createEventEssence(int materialTrackID,
DataDefinition mediaKind,
AUID codecID,
Rational editRate,
Rational sampleRate,
CompressEnable compressEnable,
Locator destination,
AUID fileFormat)
Creates and initializes an event track in a track
of this material packages that represents a stream of events.
|
EssenceMultiAccess |
createMultiEssence(AUID codecID,
MultiCreateItem[] mediaArray,
CompressEnable enable,
Locator destination,
AUID fileFormat)
Creates a multi-channel interleaved stream of essence for this
material package.
|
EssenceAccess |
createStaticEssence(int materialTrackID,
DataDefinition mediaKind,
AUID codecID,
CompressEnable compressEnable,
Locator destination,
AUID fileFormat)
Creates and initializes static essence as a referenced track of
this material package, returning access to them.
|
EssenceAccess |
extendEssence(int materialTrackID,
DataDefinition mediaKind,
AUID codecID,
Rational editRate,
Rational sampleRate,
CompressEnable enable,
Locator destintation,
AUID fileFormat)
Extends a single stream of essence that was originally created using
createEssence(). |
EssenceMultiAccess |
extendMultiEssence(AUID codecId,
MultiCreateItem[] mediaArray,
CompressEnable compressEnable,
Locator destination,
AUID fileFormat)
Extends a multi-channel interleaved stream of essence that was
originally created using
createMultiEssence(). |
Segment |
getCriteriaSegment(int trackID,
CriteriaType criteria)
Returns the segment on the specified track of this
material package that references the source package that best meets the
specified criteria.
|
int |
getNumberOfRepresentations(int trackID)
This function returns the number of media representations
available for the specified track of this material package.
|
PackageMarker |
getPackageMarker()
Returns the package marker for this material package, which
specifies an optional sub-section that may be played as an alternative to the
full material package.
|
Segment |
getRepresentation(int trackID,
int representationIndex)
This method returns the indexed media representation for this material package,
for this given track id and index through the different representations.
|
String |
getTapeName(int materialTrackId)
Finds the tape source package associated with a track
of this material package and returns the name of the tape, which is stored in the
source package's name property.
|
void |
newPhysSourceRef(Rational editrate,
int track,
DataDefinition essenceKind,
SourceReferenceValue ref,
long srcRefLength)
Connects this Source package with the physical Source package that
describes the previous generation of essence, replacing any
existing package data.
|
EssenceAccess |
openEssence(int trackID,
CriteriaType mediaCriteria,
MediaOpenMode openMode,
CompressEnable compressEnable)
Opens a single channel of a file source package referenced from a track of this
material package.
|
EssenceMultiAccess |
openMultiEssence(int trackID,
CriteriaType mediaCriteria,
MediaOpenMode openMode,
CompressEnable compressEnable)
Opens all channels associated with a file source package referenced
from this material package.
|
void |
setPackageMarker(PackageMarker packageMarker)
Sets the package marker for this material package, which
specifies an optional sub-section that may be played as an alternative to the
full material package.
|
appendNewEventTrack, appendNewStaticTrack, appendNewTimelineTrack, appendPackageAttribute, appendPackageAttribute, appendPackageKLVData, appendPackageTrack, appendPackageUserComment, appendPackageUserComment, changeReference, clearPackageAttributes, clearPackageKLVData, clearPackageTracks, clearPackageUserComments, cloneExternal, copy, countPackageAttributes, countPackageKLVData, countPackageTracks, countPackageUserComments, getCreationTime, getPackageAttributes, getPackageID, getPackageKLVData, getPackageLastModified, getPackageName, getPackageTrackAt, getPackageTracks, getPackageUsage, getPackageUserComments, insertPackageTrackAt, lookupPackageTrack, offsetToPackageTimecode, prependPackageTrack, removePackageAttribute, removePackageKLVData, removePackageTrackAt, removePackageUserComment, setCreationTime, setPackageID, setPackageLastModified, setPackageName, setPackageUsageaddApplicationPlugin, clearApplicationPlugins, containsApplicationPlugin, containsApplicationPlugin, countApplicationPlugins, deepEquals, disableGenerationTracking, enableGenerationTracking, equals, getApplicationPlugins, getGeneration, getLinkedGenerationID, getObjectClass, isGenerationTracked, removeApplicationPlugin, removeApplicationPlugin, setLinkedGenerationID, setObjectClass, toStringgetPersistentID, setPersistentIndexgetAUID, getWeakTargetReferencePackageMarker getPackageMarker() throws PropertyNotPresentException
Returns the package marker for this material package, which specifies an optional sub-section that may be played as an alternative to the full material package. This is an optional property.
PropertyNotPresentException - The optional package marker property is not present for
this material package.void setPackageMarker(PackageMarker packageMarker)
Sets the package marker for this material package, which
specifies an optional sub-section that may be played as an alternative to the
full material package. Set this optional property to null to omit it.
packageMarker - Package marker for this material package.void addMaterialTrack(DataDefinition dataDefinition, @TrackID int sourceTrackID, SourcePackage sourcePackage, @TrackID int materialTrackID, @AAFString String trackName) throws NullPointerException, InvalidDataDefinitionException, TrackNotFoundException, TrackExistsException, IllegalArgumentException
Adds a track to this material package that references the specified
track in the specified source package. The new track in
the material package contains a source clip that specifies
the source package in its source reference properties.
dataDefinition - Essence kind of the new track. Requires an essence kind valid
for time-varying essence, such as: "Picture",
"Sound".sourceTrackID - Track id of the source track to be referenced from this
material package.sourcePackage - Source package containing the track to be referenced from this material package.materialTrackID - Track id to be assigned to the new material track.trackName - Name to assign to new track in the material package. Set this property to null
to omit the optional track name.NullPointerException - One or both of the data definition and/or source package
parameters is/are null.InvalidDataDefinitionException - The data kind of the source track
to be added to the material package does not match what is specified in
dataDefinition.TrackNotFoundException - The given source track was not found.TrackExistsException - The given material track id already identifies a track in
this material package.IllegalArgumentException - The given material track id is is negative.SourceClip,
TimelineTrack,
Package.getPackageTracks()@AAFString String getTapeName(@TrackID int materialTrackId) throws TrackNotFoundException, NotTapePackageException
Finds the tape source package associated with a track of this material package and returns the name of the tape, which is stored in the source package's name property. If the property name has not yet been set, a zero-length string will be returned.
A tape source package is a source package described by a tape descriptor.
materialTrackId - Track id of this material track to use to find the tape
name.TrackNotFoundException - The specified material track was not found.NotTapePackageException - The specified material track does not contain
a tape package.TapeDescriptor,
SourcePackage.getEssenceDescriptor()@NumTracks int getNumberOfRepresentations(@TrackID int trackID) throws TrackNotFoundException
This function returns the number of media representations
available for the specified track of this material package. Each different representation will
have a media criteria that can be used to
select it. Use getCriteriaSegment(int, CriteriaType) to handle multiple
representations.
trackID - Track id the count of the number of representations are required for.TrackNotFoundException - The material track specified by track is
was not found for this material package.Segment getRepresentation(@TrackID int trackID, @UInt32 int representationIndex) throws TrackNotFoundException, IndexOutOfBoundsException
This method returns the indexed media representation for this material package,
for this given track id and index through the different representations. This
call is designed to work with getNumberOfRepresentations(int) so that the
user can iterate through all of the choices. This method uses
an integer index, not an iterator. The method takes an index between 0 and
one less than the number of representations,
and returns the source package at that representation index.
trackID - Track id of this material package to find a representation for.representationIndex - Index of media representation in the given track.TrackNotFoundException - The material track specified by track id
was not found in this material package.IndexOutOfBoundsException - No media representation is available at
the specified index.CriteriaTypeSegment getCriteriaSegment(@TrackID int trackID, CriteriaType criteria) throws TrackNotFoundException, NullPointerException
Returns the segment on the specified track of this material package that references the source package that best meets the specified criteria. This function will return a result whether multiple media representations exist or not, as one representation not matching a criteria is considered better than no representation for any given media criteria.
trackID - Track id of a track of this material package to return a representation for.criteria - Criteria for selecting one of the segments.TrackNotFoundException - The material track specified by track id was not found.NullPointerException - One or both of the track id and/or criteria is/are null.void appendPhysSourceRef(Rational editrate, @TrackID int trackID, DataDefinition essenceKind, SourceReferenceValue ref, @LengthType long srcRefLength) throws NullPointerException
Connects this material package with the physical Source package that describes the previous generation of essence, appending it to existing package data. If a physical Source package, such as a File Source package or tape Source package, references another physical Source package as its ancestor, with no pulldown, then this function makes the connection between the two.
Functionally, this is a helper method to create a track with an
SourceClip referencing a particular piece of media. This
method takes many parameters because the components of an
SourceReferenceValue have been broken out as separate parameters.
The ancestor of a SourcePackage with an AAFFileDescriptor
is often a TapeDescriptor or null.
editrate - Edit rate of track to contain reference.trackID - Track id of track to contain reference.essenceKind - Data kind of track to contain reference.
Requires a data kind valid for a essence stream. Valid data
kinds are: "Picture", "Sound"ref - Reference to a Physical Source package.srcRefLength - Length of the Source Clip.NullPointerException - One or more of the arguments is
null.void newPhysSourceRef(Rational editrate, @TrackID int track, DataDefinition essenceKind, SourceReferenceValue ref, @LengthType long srcRefLength) throws NullPointerException
Connects this Source package with the physical Source package that describes the previous generation of essence, replacing any existing package data. If a physical Source package, such as a File Source package or tape Source package, references another physical Source package as its ancestor, with no pulldown, then this function makes the connection between the two.
Functionally, this is a helper method to create a track with a
SourceClip referencing a particular piece of media. This
function takes many parameters because the components of a
SourceReferenceValue have been broken out as separate parameters.
The ancestor of an source package with an AAFFileDescriptor
is often an TapeDescriptor or null.
editrate - track - essenceKind - ref - srcRefLength - NullPointerExceptionEssenceAccess createEssence(@TrackID int materialTrackID, DataDefinition mediaKind, AUID codecID, Rational editRate, Rational samplerate, CompressEnable compressEnable, Locator destination, AUID fileFormat) throws NullPointerException
Creates a single channel stream of essence in the given track of this
material package. Convenience functions exist to create audio or video essence, and a separate
call (createMultiEssence(AUID, MultiCreateItem[], CompressEnable, Locator, AUID))
exists to create interleaved audio and video data.
The essence handle from this call can be used with
EssenceAccess.writeSamples(int, byte[]), but
not with
EssenceMultiAccess.writeMultiSamples(MultiXferItem[]).
For video, the sample rate should be the edit rate of the file source package. For audio, the sample rate should be the actual number of samples per second.
materialTrackID - Material track id for the new essence.mediaKind - Create essence of this type.codecID - Create essence according to this codec.editRate - Create essence with this edit rate.samplerate - Create essence with this sample rate.compressEnable - Is compression enabled?destination - Create the essence at this location, or
null for the default location.fileFormat - Create essence to this file format.NullPointerException - One or more of the required arguments
is null.EssenceMultiAccess createMultiEssence(AUID codecID, MultiCreateItem[] mediaArray, CompressEnable enable, Locator destination, AUID fileFormat) throws NullPointerException
Creates a multi-channel interleaved stream of essence for this
material package. The
essence handle from this call can be used with
EssenceAccess.writeSamples(int, byte[]) or
EssenceMultiAccess.writeMultiSamples(MultiXferItem[]).
codecID - Create multi-essence using this codec.mediaArray - Create multi-essence using this array of definitions.enable - Is multi-essence compressed?destination - Create the interleaved essence file at this location,
or null for default location.fileFormat - If a file is created, use this file format as specified
by the identifier of a container definition.NullPointerException - One or more of the required arguments
is null.EssenceAccess openEssence(@TrackID int trackID, CriteriaType mediaCriteria, MediaOpenMode openMode, CompressEnable compressEnable) throws NullPointerException, TrackNotFoundException
Opens a single channel of a file source package referenced from a track of this material package. If the essence is interleaved, then it will be de-interleaved when samples are read. This routine follows the locator of the source package's essence descriptor.
The essence handle from this call can be used with
EssenceAccess.readSamples(int), but NOT with
EssenceMultiAccess.readMultiSamples(MultiXferItem[]).
trackID - Open essence on this track.mediaCriteria - Select essence using this criteria.openMode - Open essence with this mode, either read only or append.compressEnable - Should the essence be decompressed?NullPointerException - One or more of the arguments was null.TrackNotFoundException - The specified track does not exist
in the material package.EssenceMultiAccess openMultiEssence(@TrackID int trackID, CriteriaType mediaCriteria, MediaOpenMode openMode, CompressEnable compressEnable) throws NullPointerException, TrackNotFoundException
Opens all channels associated with a file source package referenced from this material package. This routine follows the locator of the essence descriptor of the source package.
The essence handle from this call can be used with
EssenceMultiAccess.writeMultiSamples(MultiXferItem[])
but not with
EssenceAccess.writeSamples(int, byte[]).
trackID - Track id of this material package referencing the essence to open.mediaCriteria - Select a kind of representation of the content in the track using this criteria.openMode - Open mode for essence access, either MediaOpenMode.ReadOnly or
MediaOpenMode.Append.compressEnable - Should the essence be decompressed?NullPointerException - One or more of the media criteria, open mode or compress enable
arguments is/are null.TrackNotFoundException - The given track does not exist in this material package.@UInt16 short countChannels(@TrackID int trackID, CriteriaType mediaCriteria, DataDefinition mediaKind) throws NullPointerException, TrackNotFoundException
Returns the number of interleaved essence channels of a given type in the essence stream referenced from the given track of this material package. This method is structured so that it can be called before essence is opened.
If the data format is not interleaved, then the answer will always be zero or one. This function correctly returns zero for essence types not handled by a given codec, and handles codecs which work with multiple essence types.
trackID - Count channels on this track of this material package.mediaCriteria - Filter channels using this media criteria.mediaKind - Count channels of this kind of essence.NullPointerException - One or both of the media criteria and/or media
kind arguments is/are null.TrackNotFoundException - The specified track does not exist
in this material package.EssenceAccess extendEssence(@TrackID int materialTrackID, DataDefinition mediaKind, AUID codecID, Rational editRate, Rational sampleRate, CompressEnable enable, Locator destintation, AUID fileFormat) throws NullPointerException
Extends a single stream of essence that was originally created using
createEssence(). Extended essence is represented by
a sequence of source clips.
The first call to this method will cause the timeline
track's source clip object to be replaced by a sequence. The initial source clip becomes the first
component of the new sequence.
materialTrackID - Track id of the essence to be extended on this material package.mediaKind - Create the extended essence with this type.codecID - Create the extended essence with this codec.editRate - Create the extended essence with this edit rate.sampleRate - Create the extended essence with this sample rage.enable - Should the extended essence by compressed?destintation - Optionally create a file of extended essence at this location.fileFormat - If a file is created, use this file format, as specified by a
the identifier of a container definition.NullPointerException - One of more of the required arguments is/are null.EssenceMultiAccess extendMultiEssence(AUID codecId, MultiCreateItem[] mediaArray, CompressEnable compressEnable, Locator destination, AUID fileFormat) throws NullPointerException
Extends a multi-channel interleaved stream of essence that was
originally created using
createMultiEssence(). Extended essence is represented by a sequence of source clips. The first call to
this method will cause the timeline track's
source clip to be replaced by a sequence.
The initial source clip becomes the first component of the new
sequence.
codecId - Extend the multi-channel essence using this codec.mediaArray - Use these media definitions to extend the essence.compressEnable - Should the extension be done with compression enabled?destination - Optionally create a file at this location.fileFormat - If the file is created, use this format, as specified by
the identifier of a container definition.NullPointerException - One or more of the required arguments is/are null.MultiCreateItem,
ContainerConstantEssenceAccess createStaticEssence(@TrackID int materialTrackID, DataDefinition mediaKind, AUID codecID, CompressEnable compressEnable, Locator destination, AUID fileFormat) throws NullPointerException
Creates and initializes static essence as a referenced track of this material package, returning access to them.
This method is broadly similar to
createEssence() except that the essence is created in a
static track in this material package.
The essence handle from this call can be used with
EssenceAccess.writeSamples(int, byte[]) but not with
EssenceMultiAccess.writeMultiSamples(MultiXferItem[]).
materialTrackID - Track of this material package in which to create static essence.mediaKind - Create essence of this type.codecID - Create essence using this codec.compressEnable - Compress the created essence?destination - Optionally create the essence file at this location.fileFormat - If the file is created, use this file format, as specified by a
container definition.NullPointerException - One or more of the required arguments is/are null.ContainerConstantEssenceAccess createEventEssence(@TrackID int materialTrackID, DataDefinition mediaKind, AUID codecID, Rational editRate, Rational sampleRate, CompressEnable compressEnable, Locator destination, AUID fileFormat) throws NullPointerException
Creates and initializes an event track in a track of this material packages that represents a stream of events.
This method is broadly similar to
createEssence() except that the essence is created in a
event track in this material package.
The essence handle from this call can be used with
EssenceAccess.writeSamples(int, byte[]) but not with
EssenceMultiAccess.writeMultiSamples(MultiXferItem[]).
materialTrackID - Track of this material package in which to create the event essence.mediaKind - Create essence of this type.codecID - Create essence with this codec.editRate - Create essence with this edit rate.sampleRate - Create essence with this sample rate.compressEnable - Compress the created essence?destination - Optionally create a the essence file at this location.fileFormat - If the file is created, use this file format, as specified
by the identifier of a container definition.NullPointerException - One or more of the required arguments is/are null.ContainerConstant,
CodecConstantMaterialPackage clone()
Create a cloned copy of this material package.
clone in interface InterchangeObjectclone in interface MediaEntityclone in interface Package(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.