|
Media Authoring with Java API |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface SourceMob
Specifies the description of essence that is either stored in a digital form in a file or stored on a physical media, such as tape or film. The description is provided by an essence descriptor, which is either a tape descriptor, file descriptor, film descriptor, or some extended descriptor.
This described essence is immutable. If the essence changes, such as if a videotape is redigitized, a new source mob must be created with a new mob id.
Some methods exist in this interface that are only applicable for one kind of essence descriptor.
appendTimecodeSlot()
- works only on tape source mobs.appendEdgecodeSlot()
- works only on film source mobs.These methods will throw an exception if the wrong descriptor is present.
If a source mob points to another source mob at the same rate
(or non-picture), then appendPhysicalSourceReference()
is used to create the relationship.
If a source mob points to picture on another source mob at a different
sample rate, then addPulldownReference()
is used to create the relationship, and
the pulldown which describes how to map between the two rates.
If a source mob is the end of the derivation chain for a particular
track, then addNilReference()
should be called for that slot, to say that that the slot
does exist on this source mob. For example, a video file mob with no
derivation would have a single slot of type video, with an original source reference
to show that video exists and was not derived from anything else on
record.
makeSourceMob()
Field Summary | |
---|---|
static long |
FULL_RANGE
Represents a length where an actual length value is not known. |
Method Summary | |
---|---|
void |
addNilReference(int slotId,
long length,
DataDefinition dataDefinition,
Rational editRate)
Adds a slot containing an original source reference to this source mob. |
void |
addPulldownReference(AppendOption addType,
Rational editRate,
int slotId,
DataDefinition essenceKind,
SourceReferenceValue sourceReference,
long sourceReferenceLength,
PulldownKindType pulldownKind,
int phaseFrame,
PulldownDirectionType direction)
Connects the given source mob with the physical source mob that describes the previous generation of essence, with an additional pulldown as part of the reference to indicate a non 1 to 1 relationship between the two. |
void |
appendEdgecodeSlot(Rational editRate,
int slotID,
long startEC,
long length,
FilmType filmKind,
EdgeType codeFormat,
byte[] header)
Creates and adds an edgecode slot to the film mob represented by this source mob, with the given starting edgecode, length and edit rate. |
void |
appendPhysicalSourceReference(Rational editRate,
int slotId,
DataDefinition essenceKind,
SourceReferenceValue reference,
long sourceReferenceLength)
Connects this source mob with the physical source mob that describes the previous generation of essence, appending it to the existing mob chain. |
void |
appendTimecodeSlot(Rational editRate,
int slotId,
TimecodeValue startTimecode,
long length)
Creates and adds a timecode slot to a tape mob represented by this source mob, with the given starting timecode, length and edit rate. |
EssenceDescriptor |
getEssenceDescriptor()
Returns the essence descriptor of this source mob, which describes the format of the essence associated with the source mob. |
void |
newPhysicalSourceReference(Rational editRate,
int slotId,
DataDefinition essenceKind,
SourceReferenceValue sourceReference,
long sourceReferenceLength)
Connects this source mob with the physical source mob that describes the previous generation of essence, appending it to the existing mob chain. |
void |
setEssenceDescriptor(EssenceDescriptor essence)
Sets the essence descriptor of this source mob, which describes the format of the essence associated with the source mob. |
void |
specifyValidCodeRange(DataDefinition essenceKind,
int slotId,
Rational editRate,
long startOffset,
long length)
Creates and adds a slot containing source clips to the source mob to indicate that a (recently added) timecode slot or edgecode slot is valid for that channel. |
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 |
Methods inherited from interface tv.amwa.maj.iface.SearchSource |
---|
searchSource |
Field Detail |
---|
static final long FULL_RANGE
Represents a length where an actual length value is not known.
appendTimecodeSlot(Rational, int, TimecodeValue, long)
,
Constant Field ValuesMethod Detail |
---|
EssenceDescriptor getEssenceDescriptor()
Returns the essence descriptor of this source mob, which describes the format of the essence associated with the source mob.
void setEssenceDescriptor(EssenceDescriptor essence) throws NullPointerException
Sets the essence descriptor of this source mob, which describes the format of the essence associated with the source mob.
essence
- Essence descriptor of this source mob.
NullPointerException
- The given essence descriptor is null
.void addNilReference(@SlotID int slotId, @LengthType long length, DataDefinition dataDefinition, Rational editRate) throws NullPointerException, IllegalArgumentException, BadRateException, BadLengthException, SlotExistsException
Adds a slot containing an original source reference to this source mob. This special source id indicates that the mob chain ends here, which indicates that no further record exists of where the essence was derived from. Some source clip is still required on the track to indicate that the track exists and may be referenced from other mobs.
Examples of source mobs that are not derived from a previous source of essence are:
slotId
- Slot id to be assigned to the new slot.length
- Duration of the source clip to be added to the new slot.dataDefinition
- Data definition for the new slot.editRate
- Edit rate for the new slot.
NullPointerException
- The given data definition and/or edit rate is/are
null
.
IllegalArgumentException
- The given slot identifier is null
BadRateException
- The edit rate is not valid.
BadLengthException
- The length cannot be a negative value.
SlotExistsException
- The given slot id matches that of a mob
slot already present in this source mob.SourceReferenceValue.isOriginalSource()
void appendTimecodeSlot(Rational editRate, @SlotID int slotId, TimecodeValue startTimecode, @FrameLength long length) throws NullPointerException, TapeDescriptorOnlyException, SlotExistsException
Creates and adds a timecode slot to a tape mob represented by this source
mob, with the given starting timecode, length and edit rate. It is then necessary to call
specifyValidCodeRange()
to add the filler to the
other essence slots to indicate that the timecode is valid for that
other slots (tracks) of this mob.
The start timecode parameter is expressed in frames
since midnight. The length parameter can be the value FULL_RANGE
,
in which case the length is 24 hours.
editRate
- Edit rate of the timecode slot.slotId
- Slot id for the new timecode slot.startTimecode
- Starting timecode for the timecode slot.length
- Duration of the new timecode slot.
NullPointerException
- One or both of the edit rate and/or start timecode arguments
is/are null
.
TapeDescriptorOnlyException
- This operation is only valid
for a source mob referencing a tape descriptor.
SlotExistsException
- The given slot id matches that of a mob
slot already present in this source mob.FULL_RANGE
,
makeTimecodeValue()
,
TimecodeValue specification
,
TimecodeValue implementation
void appendEdgecodeSlot(Rational editRate, @SlotID int slotID, @FrameOffset long startEC, @FrameLength long length, FilmType filmKind, EdgeType codeFormat, @EdgecodeHeader byte[] header) throws NullPointerException, IllegalArgumentException, FilmDescriptorOnlyException, BadLengthException, BadSizeException, SlotExistsException
Creates and adds an edgecode slot to the film mob represented by this
source mob, with the given starting edgecode, length and edit rate.
It is also necessary to then add an essence slot with
specifyValidCodeRange()
to make the new edgecode slot valid.
editRate
- Edit rate for the new edgecode slot.startEC
- Starting edgecode of the new edgecode slot.length
- Length of the new edgecode slot.filmKind
- Film kind for the new edgecode slot.codeFormat
- Code for the new edgecode slot.header
- Edgecode 8-byte header for the new edgecode slot.
NullPointerException
- One or more of the arguments is null.
FilmDescriptorOnlyException
- This operation is only valid
for a source mob referencing a film descriptor.
BadSizeException
- The size of the header is not the required 8 bytes.
BadLengthException
- The length value is negative.
SlotExistsException
- The given slot id matches that of a mob
slot already present in this source mob.
IllegalArgumentException
makeEdgecodeValue()
,
EdgecodeValue specification
,
EdgecodeValue implementation
void specifyValidCodeRange(DataDefinition essenceKind, @SlotID int slotId, Rational editRate, @FrameOffset long startOffset, @FrameLength long length) throws NullPointerException, BadLengthException, SlotExistsException
Creates and adds a slot containing source clips to the source mob to indicate that a (recently added) timecode slot or edgecode slot is valid for that channel.
The essence kind parameter requires a data kind with valid for an essence stream. Valid data kinds are:
essenceKind
- Data kind for the slot to be added.slotId
- Slot id for the slot to be added.editRate
- Edit rate for the slot to be added.startOffset
- Start offset for the slot to be added.length
- Duration of the source clip in the slot.
NullPointerException
- One or both of the edit rate and/or essence kind arguments
is/are null
.
BadLengthException
- The given length for the new source clip is negative.
SlotExistsException
- The given slot id matches that of a mob
slot already present in this source mob.void appendPhysicalSourceReference(Rational editRate, @SlotID int slotId, DataDefinition essenceKind, SourceReferenceValue reference, @LengthType long sourceReferenceLength) throws NullPointerException, BadLengthException, InvalidDataDefinitionException, SlotExistsException
Connects this source mob with the physical source mob that describes the previous generation of essence, appending it to the existing mob chain. 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.
This is a helper method to create a slot with a source clip referencing a particular piece of media.
The ancestor of a source mob with a file descriptor is often a tape descriptor.
The essenceKind
parameter requires a data kind
valid for an essence stream. Valid data kinds are:
editRate
- Edit rate of the slot to contain the reference.slotId
- Slot ID of the slot to contain the reference.essenceKind
- Data kind of the slot to contain the reference.reference
- Reference to a physical source mob.sourceReferenceLength
- Length of the referenced source clip.
NullPointerException
- One or more of the nullable parameters is/are
null
and all are required.
BadLengthException
- The source reference length is negative.
InvalidDataDefinitionException
- The given data definition is not
compatible with that of the slot this element will be appended to.
SlotExistsException
- The given slot id matches that of a mob
slot already present in this source mob.void newPhysicalSourceReference(Rational editRate, @SlotID int slotId, DataDefinition essenceKind, SourceReferenceValue sourceReference, @LengthType long sourceReferenceLength) throws NullPointerException, BadLengthException, SlotExistsException
Connects this source mob with the physical source mob that describes the previous generation of essence, appending it to the existing mob chain. 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 1 to 1 connection between the two.
This is a helper method to create a slot with a source clip referencing a particular piece of media.
The ancestor of a source mob with a file descriptor is often a tape descriptor.
The essence kind parameter requires a data kind valid for an essence stream. Valid data kinds are:
editRate
- Edit rate of the slot to contain the reference.slotId
- Slot id of the slot to contain the reference.essenceKind
- Data kind of the slot to contain the reference.sourceReference
- Reference to a physical source mob.sourceReferenceLength
- Length of the referenced source clip.
NullPointerException
- One or more of the nullable arguments is/are null
and all are required.
BadLengthException
- The given source reference length is negative.
SlotExistsException
- The given slot id matches that of a mob
slot already present in this source mob.SourceClip
void addPulldownReference(AppendOption addType, Rational editRate, @SlotID int slotId, DataDefinition essenceKind, SourceReferenceValue sourceReference, @LengthType long sourceReferenceLength, PulldownKindType pulldownKind, @PhaseFrameType int phaseFrame, PulldownDirectionType direction) throws NullPointerException, PulldownDirectionException, BadLengthException, NotSourceClipException, SlotExistsException
Connects the given source mob with the physical source mob that describes the previous generation of essence, with an additional pulldown as part of the reference to indicate a non 1 to 1 relationship between the two.
This is a helper method to create a slot with a pulldown object which references a source clip, which references a particular piece of media. This method takes many parameters because the components of a pulldown have been broken out as separate parameters.
The ancestor of a source mob described by a tape descriptor is often a film descriptor.
addType
- Overwrite existing slot sequence, or create a new sequence and append it.editRate
- Edit rate of slot to contain the reference.slotId
- Slot ID for the slot to contain the reference.essenceKind
- Data kind of slot to contain reference. Requires a data
kind valid for an essence stream. Valid data kinds are
DataDefinitionConstant.Picture and
DataDefinitionConstant.Sound.sourceReference
- Reference to a physical source mob.sourceReferenceLength
- Length of the referenced physical source mob.pulldownKind
- Method of conversion used between this physical
source mob and this source mob.phaseFrame
- Phase of the first frame.direction
- Direction of the pulldown operation.
NullPointerException
- One or more of the nullable arguments is/are null
and all are required.
PulldownDirectionException
- The given pullown direction is
invalid in this context, for example
tape to film speed
when this is a tape source mob.
BadLengthException
- The given source reference length cannot is negative.
NotSourceClipException
- The existing contents of the given slot does not
contain a source clip to add a pulldown reference to.
SlotExistsException
- The given slot id matches that of a mob
slot already present in this source mob.SourceClip
,
Pulldown
,
Sequence
|
Media Authoring with Java API |
|||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |