public interface EssenceData extends InterchangeObject
Specifies an essence container. The methods can be used to modify essence data objects that contain the actual essence data (excluding WAVE) when it is contained within an AAF file. Normally, the client application would access the essence through the essence access interface, which handles the work of finding and (de)compressing the data. However, in rare cases direct access to the data is required, the read and write methods of this interface are provided.
All methods of this interface use bytes to measure the size of buffers. Access to
sample-sized sections can only be provided with reference to the associated
codec, which is provided by an implementation of
EssenceAccess or EssenceMultiAccess.
| Modifier and Type | Method and Description |
|---|---|
EssenceData |
clone()
Create a cloned copy of this essence data.
|
int |
getBodySID()
Returns the identifier for the essence container of this this essence data, known as the
body stream identifier.
|
Stream |
getEssenceStream()
Returns the underlying essence stream of this essence data.
|
SourcePackage |
getFilePackage()
Returns a reference to the file source package that describes this essence
data.
|
int |
getIndexSID()
Returns the identifier of the index table for the essence container of this essence
data.
|
PackageID |
getLinkedPackageID()
Returns the oackage id of the file source package that describes this essence data.
|
long |
getPosition()
Get the absolute position within the stream of essence data.
|
Stream |
getSampleIndex()
Returns the sample index for the essence data, which contains an index to the
samples or frames.
|
long |
getSampleIndexPosition()
Returns the current sample index position, measured in bytes rather than samples.
|
long |
getSampleIndexSize()
Returns the total size of the sample index data, measured in bytes rather than the
total number of samples.
|
long |
getSize()
Returns the total size of the stream of essence data.
|
ByteBuffer |
read(int bytes)
Read the given number of bytes from the pre-interleaved data of an essence stream
at the current position.
|
ByteBuffer |
readSampleIndex(int size)
Reads raw data from a sample index stream at the current sample
index position.
|
void |
setBodySID(Integer bodySID)
Sets the identifier for the essence container of this essence data, known as the
body stream identifier.
|
void |
setEssenceStream(Stream essenceStream)
Sets the underlying essence stream of this essence data.
|
void |
setFilePackage(SourcePackage sourcePackage)
Sets a reference to the file source package that describes this essence
data.
|
void |
setIndexSID(Integer indexSID)
Sets the identifier of the index table for the essence container of this essence data.
|
void |
setPosition(long offset)
Seek to an absolute position within the stream of essence data.
|
void |
setSampleIndex(Stream sampleIndex)
Set the sample index of this essence data to the given
stream.
|
void |
setSampleIndexPosition(long offset)
Seek to an absolute position within the sample index data, measured in bytes
rather than samples.
|
void |
setSampleIndexSize(long sampleIndexSize)
Sets the size of the sample index.
|
int |
write(ByteBuffer buffer)
Write a pre-interleaved data item into the essence stream, starting
at the current position.
|
int |
writeSampleIndex(ByteBuffer buffer)
Writes the given sample index data to the sample index data at
the current sample index stream position.
|
addApplicationPlugin, clearApplicationPlugins, containsApplicationPlugin, containsApplicationPlugin, countApplicationPlugins, deepEquals, disableGenerationTracking, enableGenerationTracking, equals, getApplicationPlugins, getGeneration, getLinkedGenerationID, getObjectClass, isGenerationTracked, removeApplicationPlugin, removeApplicationPlugin, setLinkedGenerationID, setObjectClass, toStringgetPersistentID, setPersistentIndex@UInt32 int write(@DataBuffer ByteBuffer buffer) throws EndOfDataException, IOException
Write a pre-interleaved data item into the essence stream, starting at the current position. The number of bytes actually written into the essence data is returned.
buffer - Buffer containing the data to be written.EndOfDataException - Cannot write beyond the end of the bounds of the
underlying stream.IOException - Error occurred when trying to write data to the
underlying stream.@DataBuffer ByteBuffer read(@UInt32 int bytes) throws IOException, EndOfDataException
Read the given number of bytes from the pre-interleaved data of an essence stream at the current position.
bytes - Number of bytes to read from the data streamIOException - Error when trying to read data from the underlying stream.EndOfDataException - Attempting to read beyond the bounds of the data
stream.void setPosition(@PositionType long offset) throws IllegalArgumentException, IOException
Seek to an absolute position within the stream of essence data.
offset - Offset from the beginning of the essence.IllegalArgumentException - Cannot set the position outside the bounds of
the underlying stream.IOException - An error occurred when trying to set the position for
the underlying stream.@PositionType long getPosition() throws IOException
Get the absolute position within the stream of essence data.
IOException - Error trying to determine position from the underlying
stream.@LengthType long getSize() throws IOException
Returns the total size of the stream of essence data.
IOException - Error accessing the underlying stream to determine the length.@UInt32 int writeSampleIndex(@DataBuffer ByteBuffer buffer) throws PropertyNotPresentException, EndOfDataException, IOException
Writes the given sample index data to the sample index data at the current sample index stream position. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec. The number of samples actually written is returned and may be less than those requested at the end of the buffer.
The sample index property is optional. It is not possible to write sample index
data if the property is not present. To write data, call setSampleIndexSize(long)
first with sufficient size to write the required buffer.
buffer - Buffer of sample data to write into the essence data.PropertyNotPresentException - The optional sample index data is not present for
this essence data.EndOfDataException - Cannot write data beyond the bounds of the sample index
stream.IOException - Error occurred when trying to write data to the underlying stream.getSampleIndexPosition()@DataBuffer ByteBuffer readSampleIndex(@UInt32 int size) throws PropertyNotPresentException, IOException, EndOfDataException
Reads raw data from a sample index stream at the current sample index position. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec which is why the parameter of this method is measured in bytes rather than number of samples. The sample index property is optional.
size - Read this many bytes from the sample index stream.PropertyNotPresentException - The optional sample index property is
not present for this essence data.IOException - Error trying to read data from the underlying stream.EndOfDataException - Cannot read data beyond the end of the sample
index.void setSampleIndexPosition(@PositionType long offset) throws PropertyNotPresentException, IllegalArgumentException, IOException
Seek to an absolute position within the sample index data, measured in bytes rather than samples. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec. If the given offset is beyond the end of the stream, the position is set to be the end of the stream.
offset - Offset from the beginning of the data measured in
bytes.PropertyNotPresentException - The optional sample index property is not
present for this essence data.IllegalArgumentException - Cannot set the position outside the bounds of the
underlying stream.IOException - Error trying to set the position for the underlying stream.@PositionType long getSampleIndexPosition() throws PropertyNotPresentException, IOException
Returns the current sample index position, measured in bytes rather than samples. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec. The sample index property is optional.
PropertyNotPresentException - The optional sample index data is not present for this
essence data.IOException - Error trying to retrieve the position from the underlying stream.@LengthType long getSampleIndexSize() throws PropertyNotPresentException, IOException
Returns the total size of the sample index data, measured in bytes rather than the total number of samples. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec. The sample index property is optional.
PropertyNotPresentException - The optional sample index data is not present for this
essence data.IOException - Error accessing the underlying stream to determine the stream length.void setSampleIndex(Stream sampleIndex)
Set the sample index of this essence data to the given
stream. Set this optional
property to null to omit it.
sampleIndex - Stream of sample index data.void setSampleIndexSize(@LengthType long sampleIndexSize) throws IllegalArgumentException, NotImplementedException
Sets the size of the sample index. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec. Set this value to 0 to omit this optional property.
This method will extend an existing buffer but will not truncate it. To decrease the size of the buffer, copy the data, call this method with 0 and then write the copied bytes back into the buffer.
sampleIndexSize - Size for the sample index data.IllegalArgumentException - The given sample index size is negative or smaller
than the sample index already stored.NotImplementedException - Creating a non existent buffer is not supported in
this version of MAJ.void setFilePackage(SourcePackage sourcePackage) throws NullPointerException
Sets a reference to the file source package that describes this essence data. This reference will provide the persistent file package id property for this essence data.
sourcePackage - Reference to a source package that describes this essence data.NullPointerException - The given file source package is null.SourcePackage getFilePackage()
Returns a reference to the file source package that describes this essence
data. This method will return null unless the file package reference has previously
been set using setFilePackage(SourcePackage).
PackageID getLinkedPackageID()
Returns the oackage id of the file source package that describes this essence data. The linked source package must exist in the same file as the essence data.
This is a required persistent property of essence data.
Stream getEssenceStream() throws PropertyNotPresentException
Returns the underlying essence stream of this essence data. This is an optional property for MXF applications only, where the body stream identifier is used instead.
PropertyNotPresentException - The essence stream data is not (yet) present for this
essence data.read(int),
write(ByteBuffer),
getPosition(),
setPosition(long),
getSize()void setEssenceStream(Stream essenceStream)
Sets the underlying essence stream of this essence data. This is an optional
property for MXF applications only, where the body stream identifier
is used instead. Set this optional property to null to omit it.
essenceStream - Underlying essence stream of this essence data.read(int),
write(ByteBuffer),
getPosition(),
setPosition(long),
getSize()Stream getSampleIndex() throws PropertyNotPresentException
Returns the sample index for the essence data, which contains an index to the samples or frames. The format of the index is determined by the associated codec. This is an optional property.
PropertyNotPresentException - The optional sample index is not present for
this essence data.@UInt32 int getIndexSID() throws PropertyNotPresentException
Returns the identifier of the index table for the essence container of this essence data. The index stream identifier is an optional property used in the encoding of essence streams in MXF files.
PropertyNotPresentException - The optional index table stream identifier property
is not present for this essence data.IndexTableSegment,
PartitionPack.getIndexSID()void setIndexSID(@UInt32 Integer indexSID) throws IllegalArgumentException
Sets the identifier of the index table for the essence container of this essence data.
The index stream identifier is an optional property used in the encoding of essence streams
in MXF files. Set this optional property to null to omit it.
indexSID - Identifier of the index table for the essence container of this essence data.IllegalArgumentException - Cannot set the index stream identifier to a negative value.IndexTableSegment,
PartitionPack.getIndexSID()@UInt32 int getBodySID() throws PropertyNotPresentException
Returns the identifier for the essence container of this this essence data, known as the body stream identifier. The body stream identifier is an optional property used in the encoding of essence streams in MXF files.
PropertyNotPresentException - The optional body stream identifier property is not
present for this essence data.EssencePartition,
PartitionPack.getBodySID()void setBodySID(@UInt32 Integer bodySID) throws IllegalArgumentException
Sets the identifier for the essence container of this essence data, known as the
body stream identifier. The body stream identifier is an optional property used in
the encoding of essence streams in MXF files. Set this optional property to null
to omit it.
bodySID - Identifier for the essence container of this essence data.IllegalArgumentException - Cannot set the body stream identifier to a negative value.EssencePartition,
PartitionPack.getBodySID()EssenceData clone()
Create a cloned copy of this essence data. The essence data itself is not cloned, just the references to the essence data.
clone in interface InterchangeObjectclone in interface MediaEntity(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.