WAVEPCMDescriptor (Media Authoring with Java API)
Date: 2016-02-05

tv.amwa.maj.model

## Interface WAVEPCMDescriptor

- All Superinterfaces:
    AAFFileDescriptor, EssenceDescriptor, InterchangeObject, MediaEntity, MetadataObject, SoundDescriptor
  All Known Subinterfaces:
    AES3PCMDescriptor, WAVEPCMDescriptor
  All Known Implementing Classes:
    AES3PCMDescriptorImpl, WAVEPCMDescriptorImpl

      public interface WAVEPCMDescriptor
      extends SoundDescriptor

  Specifies the description of a file source package 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.

  See Also:
    `CodecConstant.PCM`, `AES3PCMDescriptor`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `areAllPeakEnvelopePropertiesPresent()` Returns `true` if all the following optional properties are set for this PCM descriptor:
    `WAVEPCMDescriptor` | `clone()` Create a cloned copy of this WAVE PCM sound descriptor.
    `int` | `getAverageBytesPerSecond()` 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.
    `Stream` | `getPeakEnvelopeData()` Returns the stream containing the peak envelope data 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.
    `ByteBuffer` | `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` | `setAverageBytesPerSecond(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` | `setPeakEnvelopeData(Stream peakEnvelopeData)` Set the peak envelope data stream of 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(ByteBuffer 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.model.SoundDescriptor

      `getAudioReferenceLevel, getAudioSampleRate, getChannelCount, getDialNorm, getElectrospatialFormulation, getLocked, getQuantizationBits, getSoundCompression, isLocked, setAudioReferenceLevel, setAudioSampleRate, setChannelCount, setDialNorm, setElectrospatialFormulation, setIsLocked, setQuantizationBits, setSoundCompression`

    - ### Methods inherited from interface tv.amwa.maj.model.AAFFileDescriptor

      `getCodec, getContainerFormat, getEssenceLength, getLinkedTrackID, getSampleRate, setCodec, setContainerFormat, setEssenceLength, setLinkedTrackID, setSampleRate`

    - ### Methods inherited from interface tv.amwa.maj.model.EssenceDescriptor

      `appendLocator, appendSubDescriptor, clearLocators, countLocators, countSubDescriptors, getLocatorAt, getLocators, getSubDescriptorAt, getSubDescriptors, insertLocatorAt, insertSubDescriptorAt, prependLocator, prependSubDescriptor, removeLocatorAt, removeSubDescriptorAt`

    - ### Methods inherited from interface tv.amwa.maj.model.InterchangeObject

      `addApplicationPlugin, clearApplicationPlugins, containsApplicationPlugin, containsApplicationPlugin, countApplicationPlugins, deepEquals, disableGenerationTracking, enableGenerationTracking, equals, getApplicationPlugins, getGeneration, getLinkedGenerationID, getObjectClass, isGenerationTracked, removeApplicationPlugin, removeApplicationPlugin, setLinkedGenerationID, setObjectClass, toString`

    - ### Methods inherited from interface tv.amwa.maj.industry.MediaEntity

      `getPersistentID, setPersistentIndex`

- - ### 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.

    - #### setAverageBytesPerSecond

          void setAverageBytesPerSecond(@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.

    - #### getAverageBytesPerSecond

          @UInt32
          int getAverageBytesPerSecond()

      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:

      - PeakEnvelopeVersion - see `setPeakEnvelopeVersion(Integer)`
      - PeakEnvelopeFormat - see `setPeakEnvelopeFormat(Integer)`
      - PointsPerPeakValue - see `setPointsPerPeakValue(Integer)`
      - PeakEnvelopeBlockSize - see `setPeakEnvelopeBlockSize(Integer)`
      - PeakChannels - see `setPeakChannelCount(Integer)`
      - PeakFrames - see `setPeakChannelCount(Integer)`
      - PeakOfPeaksPosition - see `setPeakOfPeaksPosition(Long)`
      - PeakEnvelopeTimestamp - see `setPeakEnvelopeTimestamp(TimeStamp)`
      - PeakEnvelopeData - see `setPeakEnvelopeDataPosition(long)`, `getPeakEnvelopeDataSize()`, `writePeakEnvelopeData(ByteBuffer)` and `readPeakEnvelopeData(int)`.
      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:
        `Forge.makeTimeStamp(java.util.Calendar)`, `Forge.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()`

    - #### getPeakEnvelopeData

          Stream getPeakEnvelopeData()
                              throws PropertyNotPresentException

      Returns the stream containing the peak envelope data for this PCM descriptor. This is an optional property.

      Returns:
        Stream containing the peak envelope data.
      Throws:
        `PropertyNotPresentException` - The optional peak envelope data property is not present for this WAVE PCM descriptor.
      See Also:
        `getPeakEnvelopeDataPosition()`, `readPeakEnvelopeData(int)`, `writePeakEnvelopeData(ByteBuffer)`, `setPeakEnvelopeDataPosition(long)`

    - #### setPeakEnvelopeDataPosition

          void setPeakEnvelopeDataPosition(@PositionType
                                           long position)
                                    throws PropertyNotPresentException,
                                           IllegalArgumentException,
                                           IOException

      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.
      Throws:
        `PropertyNotPresentException` - The optional peak envelope data property is not present for this WAVE PCM descriptor.
        `IOException` - Error occurred when trying to set the position for the underlying stream.
        `IllegalArgumentException` - The given position is outside the acceptable range for the current stream.
      See Also:
        `getPeakEnvelopeData()`, `getPeakEnvelopeDataPosition()`, `readPeakEnvelopeData(int)`, `writePeakEnvelopeData(ByteBuffer)`

    - #### getPeakEnvelopeDataPosition

          @PositionType
          long getPeakEnvelopeDataPosition()
                                                  throws PropertyNotPresentException,
                                                         IOException

      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.
      Throws:
        `PropertyNotPresentException` - The optional peak envelope data property is not present for this WAVE PCM descriptor.
        `IOException` - Error occurred when trying to get the position from the underlying stream.
      See Also:
        `getPeakEnvelopeData()`, `setPeakEnvelopeDataPosition(long)`, `readPeakEnvelopeData(int)`, `writePeakEnvelopeData(ByteBuffer)`

    - #### getPeakEnvelopeDataSize

          @LengthType
          long getPeakEnvelopeDataSize()
                                            throws PropertyNotPresentException,
                                                   IOException

      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.
        `IOException` - Cannot access the underlying stream to determine the size.
      See Also:
        `getPeakEnvelopeData()`

    - #### writePeakEnvelopeData

          @UInt32
          int writePeakEnvelopeData(@DataBuffer
                                            ByteBuffer bytes)
                                     throws PropertyNotPresentException,
                                            EndOfDataException,
                                            IOException

      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.
        `IOException` - Error occurred when trying to write to the underlying stream.
        `EndOfDataException` - Cannot write beyond the end of the stream.
      See Also:
        `getPeakEnvelopeData()`

    - #### readPeakEnvelopeData

          @DataBuffer
          ByteBuffer readPeakEnvelopeData(@UInt32
                                                      int bytes)
                                               throws EndOfDataException,
                                                      PropertyNotPresentException,
                                                      IOException

      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.
        `IOException` - Error occurred when trying to read data from the underlying stream.

    - #### setPeakEnvelopeData

          void setPeakEnvelopeData(Stream peakEnvelopeData)

      Set the peak envelope data stream of this PCM descriptor. Set this optional property to `null` to omit it.

      Parameters:
        `peakEnvelopeData` - Peak envelope data stream of this PCM descriptor.
      See Also:
        `readPeakEnvelopeData(int)`, `writePeakEnvelopeData(ByteBuffer)`, `getPeakEnvelopeDataPosition()`, `getPeakEnvelopeDataSize()`, `setPeakEnvelopeDataPosition(long)`

    - #### clone

          WAVEPCMDescriptor clone()

      Create a cloned copy of this WAVE PCM sound descriptor.

      Specified by:
        `clone` in interface `AAFFileDescriptor`
      Specified by:
        `clone` in interface `EssenceDescriptor`
      Specified by:
        `clone` in interface `InterchangeObject`
      Specified by:
        `clone` in interface `MediaEntity`
      Specified by:
        `clone` in interface `SoundDescriptor`
      Returns:
        Cloned copy of this WAVE PCM sound descriptor.

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.