public interface SourcePackage extends Package, SearchSource
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 package must be created with a new package id.
Some methods exist in this interface that are only applicable for one kind of essence descriptor.
appendTimecodeTrack() - works only on tape source packages.appendEdgecodeTrack() - works only on film source packages.These methods will throw an exception if the wrong descriptor is present.
If a source package points to another source package at the same rate
(or non-picture), then appendPhysicalSourceReference() is used to create the relationship.
If a source package points to picture on another source package 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 package is the end of the derivation chain for a particular
track, then addNilReference() should be called for that track, to say that that the track
does exist on this source package. For example, a video file package with no
derivation would have a single track of type video, with an original source reference
to show that video exists and was not derived from anything else on
record.
| Modifier and Type | Field and Description |
|---|---|
static long |
FULL_RANGE
Represents a length where an actual length value is not known.
|
| Modifier and Type | Method and Description |
|---|---|
void |
addNilReference(int trackId,
long length,
DataDefinition dataDefinition,
Rational editRate)
Adds a track containing an original source reference to this source package.
|
void |
addPulldownReference(AppendOption addType,
Rational editRate,
int trackId,
DataDefinition essenceKind,
SourceReferenceValue sourceReference,
long sourceReferenceLength,
PulldownKindType pulldownKind,
int phaseFrame,
PulldownDirectionType direction)
Connects the given source package with the physical source package
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 |
appendEdgecodeTrack(Rational editRate,
int trackID,
long startEC,
long length,
FilmType filmKind,
EdgeType codeFormat,
byte[] header)
Creates and adds an edgecode track to the film package represented by this
source package, with the given starting edgecode, length and edit rate.
|
void |
appendPhysicalSourceReference(Rational editRate,
int trackId,
DataDefinition essenceKind,
SourceReferenceValue reference,
long sourceReferenceLength)
Connects this source package with the physical source package that
describes the previous generation of essence, appending it to the
existing package chain.
|
void |
appendTimecodeTrack(Rational editRate,
int trackID,
TimecodeValue startTimecode,
long length)
Creates and adds a timecode track to a tape package represented by this source
package, with the given starting timecode, length and edit rate.
|
SourcePackage |
clone()
Create a cloned copy of this source package.
|
EssenceDescriptor |
getEssenceDescription()
Returns the essence descriptor of this source package, which describes the format of the essence
associated with the source package.
|
EssenceDescriptor |
getEssenceDescriptor()
Deprecated.
|
void |
newPhysicalSourceReference(Rational editRate,
int trackId,
DataDefinition essenceKind,
SourceReferenceValue sourceReference,
long sourceReferenceLength)
Connects this source package with the physical source package that
describes the previous generation of essence, appending it to the
existing package chain.
|
void |
setEssenceDescription(EssenceDescriptor essenceDescriptor)
Sets the essence descriptor of this source package, which describes the format of the essence
associated with the source package.
|
void |
setEssenceDescriptor(EssenceDescriptor essence)
Deprecated.
|
void |
specifyValidCodeRange(DataDefinition essenceKind,
int trackId,
Rational editRate,
long startOffset,
long length)
Creates and adds a track containing source clips to the
source package to indicate that a (recently added) timecode track or edgecode track is
valid for that channel.
|
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, getWeakTargetReferencesearchSourcestatic final long FULL_RANGE
Represents a length where an actual length value is not known.
@Deprecated EssenceDescriptor getEssenceDescriptor()
Returns the essence descriptor of this source package, which describes the format of the essence associated with the source package.
TypeDefinitions.EssenceDescriptorStrongReferenceEssenceDescriptor getEssenceDescription()
Returns the essence descriptor of this source package, which describes the format of the essence associated with the source package.
TypeDefinitions.EssenceDescriptorStrongReference@Deprecated void setEssenceDescriptor(EssenceDescriptor essence) throws NullPointerException
Sets the essence descriptor of this source package, which describes the format of the essence associated with the source package.
essence - Essence descriptor of this source package.NullPointerException - The given essence descriptor is null.void setEssenceDescription(EssenceDescriptor essenceDescriptor) throws NullPointerException
Sets the essence descriptor of this source package, which describes the format of the essence associated with the source package.
essenceDescriptor - Essence descriptor of this source package.NullPointerException - The given essence descriptor is null.void addNilReference(@TrackID int trackId, @LengthType long length, DataDefinition dataDefinition, Rational editRate) throws NullPointerException, IllegalArgumentException, BadRateException, BadLengthException, TrackExistsException
Adds a track containing an original source reference to this source package. This special source id indicates that the package 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 packages.
Examples of source packages that are not derived from a previous source of essence are:
trackId - Track id to be assigned to the new track.length - Duration of the source clip to be added to the new track.dataDefinition - Data definition for the new track.editRate - Edit rate for the new track.NullPointerException - The given data definition and/or edit rate is/are
null.IllegalArgumentException - The given track identifier is nullBadRateException - The edit rate is not valid.BadLengthException - The length cannot be a negative value.TrackExistsException - The given track id matches that of a
track already present in this source package.SourceReferenceValue.isOriginalSource()void appendTimecodeTrack(Rational editRate, @TrackID int trackID, TimecodeValue startTimecode, @FrameLength long length) throws NullPointerException, TapeDescriptorOnlyException, TrackExistsException
Creates and adds a timecode track to a tape package represented by this source
package, with the given starting timecode, length and edit rate. It is then necessary to call
specifyValidCodeRange() to add the filler to the
other essence tracks to indicate that the timecode is valid for that
other tracks of this package.
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 track.trackID - Track id for the new timecode track.startTimecode - Starting timecode for the timecode track.length - Duration of the new timecode track.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 package referencing a tape descriptor.TrackExistsException - The given track id matches that of a track already present in this source package.FULL_RANGE,
Forge.makeTimecode(long, short, boolean),
TimecodeValue specificationvoid appendEdgecodeTrack(Rational editRate, @TrackID int trackID, @FrameOffset long startEC, @FrameLength long length, FilmType filmKind, EdgeType codeFormat, @EdgecodeHeader byte[] header) throws NullPointerException, IllegalArgumentException, FilmDescriptorOnlyException, BadLengthException, BadSizeException, TrackExistsException
Creates and adds an edgecode track to the film package represented by this
source package, with the given starting edgecode, length and edit rate.
It is also necessary to then add an essence track with
specifyValidCodeRange() to make the new edgecode track valid.
editRate - Edit rate for the new edgecode track.trackID - Track id for the new track.startEC - Starting edgecode of the new edgecode track.length - Length of the new edgecode track.filmKind - Film kind for the new edgecode track.codeFormat - Code for the new edgecode track.header - Edgecode 8-byte header for the new edgecode track.NullPointerException - One or more of the arguments is null.FilmDescriptorOnlyException - This operation is only valid
for a source package referencing a film descriptor.BadSizeException - The size of the header is not the required 8 bytes.BadLengthException - The length value is negative.TrackExistsException - The given track id matches that of a track already
present in this source package.IllegalArgumentExceptionForge.makeEdgeCode(long, FilmType, EdgeType),
EdgecodeValue specificationvoid specifyValidCodeRange(DataDefinition essenceKind, @TrackID int trackId, Rational editRate, @FrameOffset long startOffset, @FrameLength long length) throws NullPointerException, BadLengthException, TrackExistsException
Creates and adds a track containing source clips to the source package to indicate that a (recently added) timecode track or edgecode track 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 track to be added.trackId - Track id for the track to be added.editRate - Edit rate for the track to be added.startOffset - Start offset for the track to be added.length - Duration of the source clip in the track.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.TrackExistsException - The given track id matches that of a track already present
in this source package.void appendPhysicalSourceReference(Rational editRate, @TrackID int trackId, DataDefinition essenceKind, SourceReferenceValue reference, @LengthType long sourceReferenceLength) throws NullPointerException, BadLengthException, InvalidDataDefinitionException, TrackExistsException
Connects this source package with the physical source package that describes the previous generation of essence, appending it to the existing package chain. 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.
This is a helper method to create a track with a source clip referencing a particular piece of media.
The ancestor of a source package 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 track to contain the reference.trackId - Track ID of the track to contain the reference.essenceKind - Data kind of the track to contain the reference.reference - Reference to a physical source package.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 track this element will be appended to.TrackExistsException - The given track id matches that of a track
already present in this source package.void newPhysicalSourceReference(Rational editRate, @TrackID int trackId, DataDefinition essenceKind, SourceReferenceValue sourceReference, @LengthType long sourceReferenceLength) throws NullPointerException, BadLengthException, TrackExistsException
Connects this source package with the physical source package that describes the previous generation of essence, appending it to the existing package chain. 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 1 to 1 connection between the two.
This is a helper method to create a track with a source clip referencing a particular piece of media.
The ancestor of a source package 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 track to contain the reference.trackId - Track id of the track to contain the reference.essenceKind - Data kind of the track to contain the reference.sourceReference - Reference to a physical source package.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.TrackExistsException - The given track id matches that of a package
track already present in this source package.SourceClipvoid addPulldownReference(AppendOption addType, Rational editRate, @TrackID int trackId, DataDefinition essenceKind, SourceReferenceValue sourceReference, @LengthType long sourceReferenceLength, PulldownKindType pulldownKind, @PhaseFrameType int phaseFrame, PulldownDirectionType direction) throws NullPointerException, PulldownDirectionException, BadLengthException, NotSourceClipException, TrackExistsException
Connects the given source package with the physical source package 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 track 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 package described by a tape descriptor is often a film descriptor.
addType - Overwrite existing track sequence, or create a new sequence and append it.editRate - Edit rate of track to contain the reference.trackId - Track id for the track to contain the reference.essenceKind - Data kind of track 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 package.sourceReferenceLength - Length of the referenced physical source package.pulldownKind - Method of conversion used between this physical
source package and this source package.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 package.BadLengthException - The given source reference length cannot is negative.NotSourceClipException - The existing contents of the given track does not
contain a source clip to add a pulldown reference to.TrackExistsException - The given track id matches that of a package
track already present in this source package.SourceClip,
Pulldown,
SequenceSourcePackage clone()
Create a cloned copy of this source 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.