tv.amwa.maj.iface
Interface MasterMob

All Superinterfaces:

InterchangeObject, Mob

All Known Implementing Classes:

MasterMob

public interface MasterMob
extends Mob

Specifies a material object that provides access to source mobs and essence data.

This interface provides a number of methods that are useful for the management of slots.

Author:

Richard Cartwright

See Also:

makeMasterMob()

Method Summary

void	addMasterSlot(DataDefinition dataDefinition, int sourceSlotId, SourceMob sourceMob, int masterSlotId, String slotName) Adds a slot to this master mob that references the specified slot in the specified source mob.
void	appendPhysSourceRef(Rational editrate, int mobSlot, DataDefinition essenceKind, SourceReferenceValue ref, long srcRefLength) Connects this Master Mob with the physical Source Mob that describes the previous generation of essence, appending it to existing Mob data.
short	countChannels(int slotId, CriteriaType mediaCriteria, DataDefinition mediaKind) Returns the number of interleaved essence channels of a given type in the essence stream referenced from the given slot of this master mob.
EssenceAccess	createEssence(int masterSlotId, DataDefinition mediaKind, AUID codecID, Rational editRate, Rational samplerate, CompressEnable compressEnable, Locator destination, AUID fileFormat) Creates a single channel stream of essence in the given slot of this master mob.
EssenceAccess	createEventEssence(int masterSlotId, DataDefinition mediaKind, AUID codecId, Rational editRate, Rational sampleRate, CompressEnable compressEnable, Locator destination, AUID fileFormat) Creates and initializes an event mob slot in a slot of this master mobs 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 master mob.
EssenceAccess	createStaticEssence(int masterSlotId, DataDefinition mediaKind, AUID codecId, CompressEnable compressEnable, Locator destination, AUID fileFormat) Creates and initializes static essence as a referenced slot of this master mob, returning access to them.
EssenceAccess	extendEssence(int masterSlotID, 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 slotId, CriteriaType criteria) Returns the segment on the specified slot of this master mob that references the source mob that best meets the specified criteria.
int	getNumberOfRepresentations(int slotID) This function returns the number of media representations available for the specified slot of this master mob.
Segment	getRepresentation(int slotId, int representationIndex) This method returns the indexed media representation for this master mob, for this given slot id and index through the different representations.
String	getTapeName(int masterSlotId) Finds the tape source mob associated with a slot of this master mob and returns the name of the tape, which is stored in the source mob's name property.
void	newPhysSourceRef(Rational editrate, int mobSlot, DataDefinition essenceKind, SourceReferenceValue ref, long srcRefLength) Connects this Source Mob with the physical Source Mob that describes the previous generation of essence, replacing any existing Mob data.
EssenceAccess	openEssence(int slotId, CriteriaType mediaCriteria, MediaOpenMode openMode, CompressEnable compressEnable) Opens a single channel of a file source mob referenced from a slot of this master mob.
EssenceMultiAccess	openMultiEssence(int slotId, CriteriaType mediaCriteria, MediaOpenMode openMode, CompressEnable compressEnable) Opens all channels associated with a file source mob referenced from this master mob.

Methods inherited from interface tv.amwa.maj.iface.Mob

appendAttribute, appendAttribute, appendComment, appendComment, appendKLVData, appendNewEventSlot, appendNewStaticSlot, appendNewTimelineSlot, appendSlot, changeReference, cloneExternal, copy, countAttributes, countComments, countKLVData, countSlots, getAttributes, getComments, getCreateTime, getKLVData, getMobID, getModTime, getName, getSlotAt, getSlots, getUsageCode, insertSlotAt, lookupSlot, offsetToMobTimecode, prependSlot, removeAttribute, removeComment, removeKLVData, removeSlotAt, setCreateTime, setMobID, setModTime, setName, setUsageCode

Methods inherited from interface tv.amwa.maj.iface.InterchangeObject

countProperties, createOptionalPropertyValue, disableGenerationTracking, enableGenerationTracking, getDefinition, getGeneration, getGenerationAUID, getProperties, getPropertyValue, isGenerationTracked, isPropertyPresent, omitOpionalProperty, setPropertyValue

Method Detail

addMasterSlot

void addMasterSlot(DataDefinition dataDefinition,
                   @SlotID
                   int sourceSlotId,
                   SourceMob sourceMob,
                   @SlotID
                   int masterSlotId,
                   @AAFString
                   String slotName)
                   throws NullPointerException,
                          InvalidDataDefinitionException,
                          SlotNotFoundException,
                          SlotExistsException,
                          IllegalArgumentException

Adds a slot to this master mob that references the specified slot in the specified source mob. The new slot in the master mob contains a source clip that specifies the source mob in its source reference properties.

Parameters:

dataDefinition - Essence kind of the new slot. Requires an essence kind valid for time-varying essence, such as: "Picture", "Sound".

sourceSlotId - Slot id of the source mob slot to be referenced from this master mob.

sourceMob - Source mob containing the slot to be referenced from this master mob.

masterSlotId - Slot id to be assigned to the new master mob slot.

slotName - Name to assign to new slot in master mob. Set this property to null to omit the optional mob slot name.

Throws:

NullPointerException - One or both of the data definition and/or source mob parameters is/are null.

InvalidDataDefinitionException - The data kind of the source MOB slot to be added to the Master Mob does not match what is specified in dataDef.

SlotNotFoundException - The given source mob slot was not found.

SlotExistsException - The given master slot id already identifies a slot in this master mob.

IllegalArgumentException - The given master slot is is negative.

See Also:

SourceClip, TimelineMobSlot, Mob.getSlots()

getTapeName

@AAFString
String getTapeName(@SlotID
                             int masterSlotId)
                   throws SlotNotFoundException,
                          NotTapeMobException

Finds the tape source mob associated with a slot of this master mob and returns the name of the tape, which is stored in the source mob's name property. If the property name has not yet been set, a zero-length string will be returned.

A tape source mob is a source mob described by a tape descriptor.

Parameters:

masterSlotId - Slot id of this master mob slot to use to find the tape name.

Returns:

Tape name of the tape source mob in the given slot.

Throws:

SlotNotFoundException - The specified master mob slot was not found.

NotTapeMobException - The specified master mob slot does not contain a tape mob.

See Also:

TapeDescriptor, SourceMob.getEssenceDescriptor()

getNumberOfRepresentations

@NumSlots
int getNumberOfRepresentations(@SlotID
                                        int slotID)
                               throws SlotNotFoundException

This function returns the number of media representations available for the specified slot of this master mob. Each different representation will have a media criteria that can be used to select it. Use getCriteriaSegment(int, CriteriaType) to handle multiple representations.

Parameters:

slotID - Slot id the count of the number of representations are required for.

Returns:

Number of different media type representations in the slot.

Throws:

SlotNotFoundException - The master slot specified by slot is was not found for this master mob.

getRepresentation

Segment getRepresentation(@SlotID
                          int slotId,
                          @UInt32
                          int representationIndex)
                          throws SlotNotFoundException,
                                 IndexOutOfBoundsException

This method returns the indexed media representation for this master mob, for this given slot 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 mob at that representation index.

Parameters:

slotId - Slot id of this master mob to find a representation for.

representationIndex - Index of media representation in the given slot.

Returns:

Matching source clip.

Throws:

SlotNotFoundException - The master slot specified by slot id was not found in this master mob.

IndexOutOfBoundsException - No media representation is available at the specified index.

See Also:

CriteriaType

getCriteriaSegment

Segment getCriteriaSegment(@SlotID
                           int slotId,
                           CriteriaType criteria)
                           throws SlotNotFoundException,
                                  NullPointerException

Returns the segment on the specified slot of this master mob that references the source mob 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.

Parameters:

slotId - Slot id of a slot of this master mob to return a representation for.

criteria - Criteria for selecting one of the segments.

Returns:

Matching segment.

Throws:

SlotNotFoundException - The master slot specified by slot id was not found.

NullPointerException - One or both of the slot id and/or criteria is/are null.

appendPhysSourceRef

void appendPhysSourceRef(Rational editrate,
                         @SlotID
                         int mobSlot,
                         DataDefinition essenceKind,
                         SourceReferenceValue ref,
                         @LengthType
                         long srcRefLength)
                         throws NullPointerException

Connects this Master Mob with the physical Source Mob that describes the previous generation of essence, appending it to existing Mob data. If a physical Source Mob, such as a File Source Mob or tape Source Mob, references another physical Source Mob as its ancestor, with no pulldown, then this function makes the connection between the two.

Functionally, this is a helper method to create a slot 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 SourceMob with an AAFFileDescriptor is often a TapeDescriptor or null.

Parameters:

editrate - Edit rate of slot to contain reference.

mobSlot - Slot ID of slot to contain reference.

essenceKind - Data kind of slot to contain reference. Requires a data kind valid for a essence stream. Valid data kinds are: "Picture", "Sound"

ref - Reference to a Physical Source Mob.

srcRefLength - Length of the Source Clip.

Throws:

NullPointerException - One or more of the arguments is null.

newPhysSourceRef

void newPhysSourceRef(Rational editrate,
                      @SlotID
                      int mobSlot,
                      DataDefinition essenceKind,
                      SourceReferenceValue ref,
                      @LengthType
                      long srcRefLength)
                      throws NullPointerException

Connects this Source Mob with the physical Source Mob that describes the previous generation of essence, replacing any existing Mob data. If a physical Source Mob, such as a File Source Mob or tape Source Mob, references another physical Source Mob as its ancestor, with no pulldown, then this function makes the connection between the two.

Functionally, this is a helper method to create a slot 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 AAFSourceMob with an AAFFileDescriptor is often an TapeDescriptor or null.

Parameters:

editrate -

mobSlot -

essenceKind -

ref -

srcRefLength -

Throws:

NullPointerException

createEssence

EssenceAccess createEssence(@SlotID
                            int masterSlotId,
                            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 slot of this master mob. 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 mob. For audio, the sample rate should be the actual number of samples per second.

Parameters:

masterSlotId - Master slot id for 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.

Returns:

Access to the created essence.

Throws:

NullPointerException - One or more of the required arguments is null.

createMultiEssence

EssenceMultiAccess createMultiEssence(AUID codecID,
                                      MultiCreateItem[] mediaArray,
                                      CompressEnable enable,
                                      Locator destination,
                                      AUID fileFormat)
                                      throws NullPointerException

Creates a multi-channel interleaved stream of essence for this master mob. The essence handle from this call can be used with EssenceAccess.writeSamples(int, byte[]) or EssenceMultiAccess.writeMultiSamples(MultiXferItem[]).

Parameters:

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.

Returns:

Access to the created multi-essence.

Throws:

NullPointerException - One or more of the required arguments is null.

openEssence

EssenceAccess openEssence(@SlotID
                          int slotId,
                          CriteriaType mediaCriteria,
                          MediaOpenMode openMode,
                          CompressEnable compressEnable)
                          throws NullPointerException,
                                 SlotNotFoundException

Opens a single channel of a file source mob referenced from a slot of this master mob. If the essence is interleaved, then it will be de-interleaved when samples are read. This routine follows the locator of the source mob's essence descriptor.

The essence handle from this call can be used with EssenceAccess.readSamples(int), but NOT with EssenceMultiAccess.readMultiSamples(MultiXferItem[]).

Parameters:

slotId - Open essence on this slot.

mediaCriteria - Select essence using this criteria.

openMode - Open essence with this mode, either read only or append.

compressEnable - Should the essence be decompressed?

Returns:

Access to the essence.

Throws:

NullPointerException - One or more of the arguments was null.

SlotNotFoundException - The specified slot does not exist in the master mob.

openMultiEssence

EssenceMultiAccess openMultiEssence(@SlotID
                                    int slotId,
                                    CriteriaType mediaCriteria,
                                    MediaOpenMode openMode,
                                    CompressEnable compressEnable)
                                    throws NullPointerException,
                                           SlotNotFoundException

Opens all channels associated with a file source mob referenced from this master mob. This routine follows the locator of the essence descriptor of the source mob.

The essence handle from this call can be used with EssenceMultiAccess.writeMultiSamples(MultiXferItem[]) but not with EssenceAccess.writeSamples(int, byte[]).

Parameters:

slotId - Slot id of this master mob referencing the essence to open.

mediaCriteria - Select a kind of representation of the content in the slot using this criteria.

openMode - Open mode for essence access, either MediaOpenMode.ReadOnly or MediaOpenMode.Append.

compressEnable - Should the essence be decompressed?

Returns:

Access to the multi-channel essence.

Throws:

NullPointerException - One or more of the media criteria, open mode or compress enable arguments is/are null.

SlotNotFoundException - The given slot does not exist in this master mob.

countChannels

@UInt16
short countChannels(@SlotID
                           int slotId,
                           CriteriaType mediaCriteria,
                           DataDefinition mediaKind)
                    throws NullPointerException,
                           SlotNotFoundException

Returns the number of interleaved essence channels of a given type in the essence stream referenced from the given slot of this master mob. 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.

Parameters:

slotId - Count channels on this slot of this master mob.

mediaCriteria - Filter channels using this media criteria.

mediaKind - Count channels of this kind of essence.

Returns:

Number of channels in the given slot, matching the given media criteria and essence kind.

Throws:

NullPointerException - One or both of the media criteria and/or media kind arguments is/are null.

SlotNotFoundException - The specified slot does not exist in this master mob.

extendEssence

EssenceAccess extendEssence(@SlotID
                            int masterSlotID,
                            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 mob slot's source clip object to be replaced by a sequence. The initial source clip becomes the first component of the new sequence.

Parameters:

masterSlotID - Slot id of the essence to be extended on this master mob.

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.

Returns:

Essence access to the newly extended essence.

Throws:

NullPointerException - One of more of the required arguments is/are null.

extendMultiEssence

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 mob slot's source clip to be replaced by a sequence. The initial source clip becomes the first component of the new sequence.

Parameters:

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.

Returns:

Essence access to the extended essence.

Throws:

NullPointerException - One or more of the required arguments is/are null.

See Also:

MultiCreateItem, ContainerConstant

createStaticEssence

EssenceAccess createStaticEssence(@SlotID
                                  int masterSlotId,
                                  DataDefinition mediaKind,
                                  AUID codecId,
                                  CompressEnable compressEnable,
                                  Locator destination,
                                  AUID fileFormat)
                                  throws NullPointerException

Creates and initializes static essence as a referenced slot of this master mob, returning access to them.

This method is broadly similar to createEssence() except that the essence is created in a static mob slot in this master mob.

The essence handle from this call can be used with EssenceAccess.writeSamples(int, byte[]) but not with EssenceMultiAccess.writeMultiSamples(MultiXferItem[]).

Parameters:

masterSlotId - Slot of this master mob 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.

Returns:

Access to the newly created essence.

Throws:

NullPointerException - One or more of the required arguments is/are null.

See Also:

ContainerConstant

createEventEssence

EssenceAccess createEventEssence(@SlotID
                                 int masterSlotId,
                                 DataDefinition mediaKind,
                                 AUID codecId,
                                 Rational editRate,
                                 Rational sampleRate,
                                 CompressEnable compressEnable,
                                 Locator destination,
                                 AUID fileFormat)
                                 throws NullPointerException

Creates and initializes an event mob slot in a slot of this master mobs that represents a stream of events.

This method is broadly similar to createEssence() except that the essence is created in a event slot in this master mob.

The essence handle from this call can be used with EssenceAccess.writeSamples(int, byte[]) but not with EssenceMultiAccess.writeMultiSamples(MultiXferItem[]).

Parameters:

masterSlotId - Slot of this master mob 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.

Returns:

Access to the newly created essence.

Throws:

NullPointerException - One or more of the required arguments is/are null.

See Also:

ContainerConstant