Media Authoring
with Java API

tv.amwa.maj.iface
Interface PCMDescriptor

All Superinterfaces:
AAFFileDescriptor, EssenceDescriptor, InterchangeObject, SoundDescriptor
All Known Subinterfaces:
AES3PCMDescriptor
All Known Implementing Classes:
AES3PCMDescriptor, PCMDescriptor

public interface PCMDescriptor
extends SoundDescriptor

Specifies the description of a file source mob that is associated with audio essence formatted according to the BWF file format.

See section 13.2 of the AAF object specification v1.1 for details of mapping BWF file metadata to the AAF object model.

Author:
Richard Cartwright
See Also:
makePCMDescriptor(), CodecConstant.PCM, AES3PCMDescriptor

Method Summary
 boolean areAllPeakEnvelopePropertiesPresent()
          Returns true if all the following optional properties are set for this PCM descriptor:
 int getAverageBPS()
          Returns the average bytes per second of the essence stream described by this PCM descriptor.
 short getBlockAlign()
          Returns the number of bytes used to store one sample of all channels of data associated with this PCM descriptor.
 AUID getChannelAssignment()
          Returns the channel assignment scheme for this PCM descriptor.
 int getPeakChannelCount()
          Returns the number of peak channels for this PCM descriptor.
 int getPeakEnvelopeBlockSize()
          Returns the number of audio samples used to generate each peak frame for this PCM descriptor.
 long getPeakEnvelopeDataPosition()
          Returns the offset from the beginning of the peak envelope data for this PCM descriptor.
 long getPeakEnvelopeDataSize()
          Returns the size of the peak envelope data of this PCM descriptor.
 int getPeakEnvelopeFormat()
          Returns the format of the peak point for this PCM descriptor.
 TimeStamp getPeakEnvelopeTimestamp()
          Returns the time stamp for the date and time of the creation of this peak data for this PCM descriptor.
 int getPeakEnvelopeVersion()
          Returns the version information of the peak envelope data of this PCM descriptor.
 int getPeakFrameCount()
          Returns the number of peak frames for this PCM descriptor.
 long getPeakOfPeaksPosition()
          Returns the offset to the first audio sample whose absolute value is the maximum value of the entire audio file represented by this PCM descriptor.
 int getPointsPerPeakValue()
          Returns the number of peak points per peak value for this PCM descriptor.
 byte getSequenceOffset()
          Returns the frame number of the beginning of the essence data within a five-frame sequence for this PCM descriptor.
 byte[] readPeakEnvelopeData(int bytes)
          Read the given number of bytes of data from the peak envelope data stream of this PCM descriptor at the getPeakEnvelopeDataPosition() current position.
 void setAverageBPS(int bps)
          Sets the average bytes per second of the essence stream described by this PCM descriptor.
 void setBlockAlign(short blockAlign)
          Sets the number of bytes used to store one sample of all channels of data associated with this PCM descriptor.
 void setChannelAssignment(AUID channelAssignment)
          Sets the channel assignment scheme of this PCM descriptor.
 void setPeakChannelCount(Integer channelCount)
          Sets the number of peak channels for this PCM descriptor.
 void setPeakEnvelopeBlockSize(Integer blockSize)
          Sets the number of audio samples used to generate each peak frame for this PCM descriptor.
 void setPeakEnvelopeDataPosition(long position)
          Sets the offset from the beginning of the peak envelope data for this PCM descriptor.
 void setPeakEnvelopeFormat(Integer format)
          Sets the format of the peak point for this PCM descriptor.
 void setPeakEnvelopeTimestamp(TimeStamp timeStamp)
          Sets the time stamp for the date and time of the creation of the peak data for the PCM descriptor.
 void setPeakEnvelopeVersion(Integer version)
          Sets the version information of the peak envelope data of this PCM descriptor.
 void setPeakFrameCount(Integer frameCount)
          Sets the number of peak frames for this PCM descriptor.
 void setPeakOfPeaksPosition(Long position)
          Sets the offset to the first audio sample whose absolute value is the maximum value of the entire audio file described by this PCM descriptor.
 void setPointsPerPeakValue(Integer pointCount)
          Sets the number of peak points per peak value for this PCM descriptor.
 void setSequenceOffset(Byte offset)
          Sets the frame number of the beginning of the essence data within a five-frame sequence for this PCM descriptor.
 int writePeakEnvelopeData(byte[] bytes)
          Write the given bytes to the peak envelope data stream of the PCM descriptor at the current position, as determined by calling getPeakEnvelopeDataPosition().
 
Methods inherited from interface tv.amwa.maj.iface.SoundDescriptor
getAudioRefLevel, getAudioSamplingRate, getChannelCount, getCompression, getDialNorm, getElectroSpatialFormulation, getQuantizationBits, isLocked, setAudioRefLevel, setAudioSamplingRate, setChannelCount, setCompression, setDialNorm, setElectroSpatialFormulation, setIsLocked, setQuantizationBits
 
Methods inherited from interface tv.amwa.maj.iface.AAFFileDescriptor
getCodecDefinition, getContainerFormat, getLength, getLinkedSlotID, getSampleRate, setCodecDefinition, setContainerFormat, setLength, setLinkedSlotID, setSampleRate
 
Methods inherited from interface tv.amwa.maj.iface.EssenceDescriptor
appendLocator, appendSubDescriptor, countLocators, countSubDescriptors, getLocatorAt, getLocators, getSubDescriptorAt, getSubDescriptors, insertLocatorAt, insertSubDescriptorAt, prependLocator, prependSubDescriptor, removeLocatorAt, removeSubDescriptorAt
 
Methods inherited from interface tv.amwa.maj.iface.InterchangeObject
countProperties, createOptionalPropertyValue, disableGenerationTracking, enableGenerationTracking, getDefinition, getGeneration, getGenerationAUID, getProperties, getPropertyValue, isGenerationTracked, isPropertyPresent, omitOpionalProperty, setPropertyValue
 

Method Detail

setBlockAlign

void setBlockAlign(@UInt16
                   short blockAlign)

Sets the number of bytes used to store one sample of all channels of data associated with this PCM descriptor. This property is required.

Parameters:
blockAlign - The number of bytes used to store one sample of all channels.
Throws:
IllegalArgumentException - The given block align value is negative.

getBlockAlign

@UInt16
short getBlockAlign()

Returns the number of bytes used to store one sample of all channels of data associated with this PCM descriptor. This property is required.

Returns:
Number of bytes used to store one sample of all channels.

setSequenceOffset

void setSequenceOffset(@UInt8
                       Byte offset)
                       throws IllegalArgumentException

Sets the frame number of the beginning of the essence data within a five-frame sequence for this PCM descriptor. This property is optional and zero-based. Set to null omit it.

Parameters:
offset - Frame number of the beginning of the essence data within a five-frame sequence.
Throws:
IllegalArgumentException - The given sequence offset value is negative.

getSequenceOffset

@UInt8
byte getSequenceOffset()
                       throws PropertyNotPresentException

Returns the frame number of the beginning of the essence data within a five-frame sequence for this PCM descriptor. This property is optional and zero-based.

Returns:
Frame number of the beginning of the essence data within a five-frame sequence.
Throws:
PropertyNotPresentException - This optional property is not present in this PCM descriptor.

setAverageBPS

void setAverageBPS(@UInt32
                   int bps)
                   throws IllegalArgumentException

Sets the average bytes per second of the essence stream described by this PCM descriptor. This property is required.

Parameters:
bps - Average bytes per second of the essence stream.
Throws:
IllegalArgumentException - The given average bytes per second value is negative.

getAverageBPS

@UInt32
int getAverageBPS()

Returns the average bytes per second of the essence stream described by this PCM descriptor.

Returns:
Average bytes per second of the essence stream described by this PCM descriptor.

setChannelAssignment

void setChannelAssignment(AUID channelAssignment)

Sets the channel assignment scheme of this PCM descriptor. An example of this would be an AUID representing "SMPTE 320M-B". This property is optional and set by default to the identifier for "SMPTE 320M-B". Calling this method with null will restore the default value.

Parameters:
channelAssignment - Channel assignment to use for this PCM descriptor.

getChannelAssignment

AUID getChannelAssignment()

Returns the channel assignment scheme for this PCM descriptor. An example of this would be an AUID representing "SMPTE 320M-B". This property is optional and has a default value of "SMPTE 320M-B".

Returns:
Channel assignment scheme for the PCM descriptor.

areAllPeakEnvelopePropertiesPresent

@Bool
boolean areAllPeakEnvelopePropertiesPresent()

Returns true if all the following optional properties are set for this PCM descriptor:

Returns:
Are all the optional peak envelope properties present in this PCM descriptor?

setPeakEnvelopeVersion

void setPeakEnvelopeVersion(@UInt32
                            Integer version)
                            throws IllegalArgumentException

Sets the version information of the peak envelope data of this PCM descriptor. Set this optional property to null to omit it.

Parameters:
version - Version information of the peak envelope data of this PCM descriptor.
Throws:
IllegalArgumentException - Cannot set the peak envelope version property of this PCM descriptor to a negative value.

getPeakEnvelopeVersion

@UInt32
int getPeakEnvelopeVersion()
                           throws PropertyNotPresentException

Returns the version information of the peak envelope data of this PCM descriptor. This property is optional.

Returns:
Version information of the peak envelope data of this PCM descriptor.
Throws:
PropertyNotPresentException - The optional peak envelope version property is not present in this PCM descriptor.

setPeakEnvelopeFormat

void setPeakEnvelopeFormat(@UInt32
                           Integer format)
                           throws IllegalArgumentException

Sets the format of the peak point for this PCM descriptor. Set this optional property to null to omit it.

Parameters:
format - Format of the peak point for this PCM descriptor.
Throws:
IllegalArgumentException - The given peak envelope format is negative.

getPeakEnvelopeFormat

@UInt32
int getPeakEnvelopeFormat()
                          throws PropertyNotPresentException

Returns the format of the peak point for this PCM descriptor. This property is optional.

Returns:
Format of the peak point for this PCM descriptor.
Throws:
PropertyNotPresentException - The optional peak envelope format property is not present in this PCM descriptor.

setPointsPerPeakValue

void setPointsPerPeakValue(@UInt32
                           Integer pointCount)
                           throws IllegalArgumentException

Sets the number of peak points per peak value for this PCM descriptor. Set this optional property to null to omit it.

Parameters:
pointCount - Number of peak points per peak value for this PCM descriptor.
Throws:
IllegalArgumentException - The given number of peak points per peak value is negative.

getPointsPerPeakValue

@UInt32
int getPointsPerPeakValue()
                          throws PropertyNotPresentException

Returns the number of peak points per peak value for this PCM descriptor. This value is optional.

Returns:
Number of peak points per peak value for this PCM descriptor.
Throws:
PropertyNotPresentException - The optional points per peak value property is not present in this PCM descriptor.

setPeakEnvelopeBlockSize

void setPeakEnvelopeBlockSize(@UInt32
                              Integer blockSize)
                              throws IllegalArgumentException

Sets the number of audio samples used to generate each peak frame for this PCM descriptor. Set this optional property to null to omit it.

Parameters:
blockSize - Number of audio samples used to generate each peak frame for this PCM descriptor.
Throws:
IllegalArgumentException - The given peak envelope block size is negative.

getPeakEnvelopeBlockSize

@UInt32
int getPeakEnvelopeBlockSize()
                             throws PropertyNotPresentException

Returns the number of audio samples used to generate each peak frame for this PCM descriptor. This property is optional.

Returns:
Number of audio samples used to generate each peak frame for this PCM descriptor.
Throws:
PropertyNotPresentException - The optional peak envelope block size property is not present in this PCM descriptor.

setPeakChannelCount

void setPeakChannelCount(@UInt32
                         Integer channelCount)
                         throws IllegalArgumentException

Sets the number of peak channels for this PCM descriptor. Set this optional property of null to omit it.

Parameters:
channelCount - Number of peak channels for this PCM descriptor.
Throws:
IllegalArgumentException - Cannot set the peak channels property of this PCM descriptor to a negative value.

getPeakChannelCount

@UInt32
int getPeakChannelCount()
                        throws PropertyNotPresentException

Returns the number of peak channels for this PCM descriptor. This property is optional.

Returns:
Number of peak channels for this PCM descriptor.
Throws:
PropertyNotPresentException - The optional peak channels property is not present in this PCM descriptor.

setPeakFrameCount

void setPeakFrameCount(@UInt32
                       Integer frameCount)
                       throws IllegalArgumentException

Sets the number of peak frames for this PCM descriptor. Set this optional property to null to omit it.

Parameters:
frameCount - Number of peak frames for this PCM descriptor.
Throws:
IllegalArgumentException - The given peak frames count is negative.

getPeakFrameCount

@UInt32
int getPeakFrameCount()
                      throws PropertyNotPresentException

Returns the number of peak frames for this PCM descriptor. This property is optional.

Returns:
Number of peak frames for this PCM descriptor.
Throws:
PropertyNotPresentException - This optional peak of peaks property is not present in this PCM descriptor.

setPeakOfPeaksPosition

void setPeakOfPeaksPosition(@PositionType
                            Long position)

Sets the offset to the first audio sample whose absolute value is the maximum value of the entire audio file described by this PCM descriptor. Set this optional property to null to omit it.

Parameters:
position - Peak of peaks position in the described audio essence.

getPeakOfPeaksPosition

@PositionType
long getPeakOfPeaksPosition()
                            throws PropertyNotPresentException

Returns the offset to the first audio sample whose absolute value is the maximum value of the entire audio file represented by this PCM descriptor. This property is optional.

Returns:
Peak of peaks position in the described audio essence.
Throws:
PropertyNotPresentException - The optional peak of peaks position property is not present in this PCM descriptor.

setPeakEnvelopeTimestamp

void setPeakEnvelopeTimestamp(TimeStamp timeStamp)

Sets the time stamp for the date and time of the creation of the peak data for the PCM descriptor. Set this optional property to null to omit it.

Parameters:
timeStamp - Time stamp of the creation of the peak data for the PCM descriptor.
See Also:
TimeStamp.TimeStamp(java.util.Calendar), TimeStamp.parseTimeStamp(String), areAllPeakEnvelopePropertiesPresent()

getPeakEnvelopeTimestamp

TimeStamp getPeakEnvelopeTimestamp()
                                   throws PropertyNotPresentException

Returns the time stamp for the date and time of the creation of this peak data for this PCM descriptor. This property is optional.

Returns:
Time stamp of the creation of the peak data for this PCM descriptor.
Throws:
PropertyNotPresentException - This optional property is not present in this PCM descriptor.
See Also:
areAllPeakEnvelopePropertiesPresent(), TimeStamp.getTimeStamp()

setPeakEnvelopeDataPosition

void setPeakEnvelopeDataPosition(@PositionType
                                 long position)

Sets the offset from the beginning of the peak envelope data for this PCM descriptor. This property is optional and is used to define the point at which peak envelope data is read or written.

Parameters:
position - Offset from the beginning of the peak envelope data for this PCM descriptor.

getPeakEnvelopeDataPosition

@PositionType
long getPeakEnvelopeDataPosition()

Returns the offset from the beginning of the peak envelope data for this PCM descriptor. This transient property is used to define the point at which peak envelope data is read or written.

Returns:
Offset from the beginning of the peak envelope data for this PCM descriptor.

getPeakEnvelopeDataSize

@LengthType
long getPeakEnvelopeDataSize()
                             throws PropertyNotPresentException

Returns the size of the peak envelope data of this PCM descriptor. This peak envelope data property is optional. The value returned can be useful when working out how many bytes to read from the stream of peak envelope data.

Returns:
Size of the peak envelope data of this PCM descriptor.
Throws:
PropertyNotPresentException - The optional peak envelope data property is not present in this PCM descriptor.

writePeakEnvelopeData

@UInt32
int writePeakEnvelopeData(@DataBuffer
                                 byte[] bytes)
                          throws PropertyNotPresentException,
                                 ContainerWriteException

Write the given bytes to the peak envelope data stream of the PCM descriptor at the current position, as determined by calling getPeakEnvelopeDataPosition().

Parameters:
bytes - Data to write to the peak envelope data stream of this PCM descriptor.
Returns:
Number of bytes written.
Throws:
PropertyNotPresentException - The optional peak envelope data property is not present in this PCM descriptor and so cannot be written to.
ContainerWriteException - Writing to the container failed.

readPeakEnvelopeData

@DataBuffer
byte[] readPeakEnvelopeData(@UInt32
                                       int bytes)
                            throws EndOfDataException,
                                   PropertyNotPresentException

Read the given number of bytes of data from the peak envelope data stream of this PCM descriptor at the getPeakEnvelopeDataPosition() current position.

Parameters:
bytes - Number of bytes to read.
Returns:
The given number of bytes of data from the peak envelope data stream of this PCM descriptor.
Throws:
EndOfDataException - Attempt to read beyond the end of the peak envelope data.
PropertyNotPresentException - The optional peak envelope data property is not present in this PCM descriptor.

Media Authoring
with Java API

(c) 2007-2008 Richard Cartwright, all rights reserved. Subject to the terms of the AAF SDK Public Source License.