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

tv.amwa.maj.model

## Interface AES3PCMDescriptor

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

      public interface AES3PCMDescriptor
      extends WAVEPCMDescriptor

  Specifies an AES3 PCM descriptor that describes audio essence in the AES/EBU audio file format, as defined in the EBU/AES digital audio interface specification.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static byte[]` | `AES3DefaultUserData` Default AES3 fixed user data value.
    `static byte[]` | `AES3Minimum` Minimum channel status according to the AES3 specification, specified in section 5.2.1 of EBU Tech 3250.
    `static AuxBitsModeType` | `AUXBITSMODE_DEFAULT` Default value for the aux bits mode property, which is `AuxBitsModeType.NotDefined`.
    `static short` | `BLOCKSTARTOFFSET_DEFAULT` Default value for the block start offset property, which is 0.
    `static EmphasisType` | `EMPHASIS_DEFAULT` Default value for the emphasis property, which is `EmphasisType.Unknown`.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `AES3PCMDescriptor` | `clone()` Create a cloned copy of this AES3 PCM descriptor.
    `AuxBitsModeType` | `getAuxBitsMode()` Returns the AES3 use of auxiliary bits in the associated audio essence.
    `short` | `getBlockStartOffset()` Returns the AES3 position of the first Z preamble in the associated sound essence stream.
    `ChannelStatusModeType[]` | `getChannelStatusMode()` Returns the AES3 enumerated mode of carriage of channel status data for all channels of the associated audio essence.
    `ChannelStatusModeType` | `getChannelStatusModeAt(int index)` Returns the AES3 enumerated mode of carriage of channel status data for the associated audio essence for the given channel number.
    `EmphasisType` | `getEmphasis()` Returns the AES3 emphasis of the associated sound essence.
    `byte[]` | `getFixedChannelStatusData()` Returns the AES3 fixed channel status data for all channels in the associated audio essence.
    `byte[]` | `getFixedChannelStatusDataAt(int index)` Returns the AES3 fixed channel status data for the channel referenced by the given index in the associated audio essence.
    `byte[]` | `getFixedUserData()` Returns the AES3 fixed user data for all channels in the associated audio essence.
    `byte[]` | `getFixedUserDataAt(int index)` Returns the AES3 fixed user data for the given channel in the associated audio essence.
    `UserDataModeType[]` | `getUserDataMode()` Returns the user data mode for all the channels in the associated audio essence.
    `UserDataModeType` | `getUserDataModeAt(int index)` Returns the user data mode for the channel of the associated audio essence referenced by the given channel index.
    `void` | `omitChannelStatusData()` Omits the optional fixed channel status data and channel status mode properties from this AES3 PCM descriptor.
    `void` | `omitUserData()` Omit the optional fixed user data and user data mode properties from this AES3 PCM descriptor.
    `void` | `setAuxBitsMode(AuxBitsModeType auxBitsMode)` Sets the AES3 use of auxiliary bits in the associated audio essence.
    `void` | `setBlockStartOffset(Short blockStartOffset)` Sets the AES3 position of the first Z preamble in the associated sound essence stream.
    `void` | `setChannelStatusModeAt(int index, ChannelStatusModeType channelStatusMode)` Sets the AES3 enumerated mode of carriage of channel status data for the associated audio essence at the given channel number.
    `void` | `setEmphasis(EmphasisType emphasisType)` Sets the AES3 emphasis property of the associated sound essence.
    `void` | `setFixedChannelStatusDataAt(int index, byte[] fixedChannelStatusData)` Sets the AES3 fixed channel status data for the channel referenced by the given index in the associated audio essence.
    `void` | `setFixedUserDataAt(int index, byte[] fixedUserData)` Sets the AES3 fixed user data for the given channel in the associated audio essence.
    `void` | `setUserDataModeAt(int index, UserDataModeType userDataMode)` Sets the user data mode for the channel of the associated audio essence referenced by the given channel index.

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

      `areAllPeakEnvelopePropertiesPresent, getAverageBytesPerSecond, getBlockAlign, getChannelAssignment, getPeakChannelCount, getPeakEnvelopeBlockSize, getPeakEnvelopeData, getPeakEnvelopeDataPosition, getPeakEnvelopeDataSize, getPeakEnvelopeFormat, getPeakEnvelopeTimestamp, getPeakEnvelopeVersion, getPeakFrameCount, getPeakOfPeaksPosition, getPointsPerPeakValue, getSequenceOffset, readPeakEnvelopeData, setAverageBytesPerSecond, setBlockAlign, setChannelAssignment, setPeakChannelCount, setPeakEnvelopeBlockSize, setPeakEnvelopeData, setPeakEnvelopeDataPosition, setPeakEnvelopeFormat, setPeakEnvelopeTimestamp, setPeakEnvelopeVersion, setPeakFrameCount, setPeakOfPeaksPosition, setPointsPerPeakValue, setSequenceOffset, writePeakEnvelopeData`

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

- - ### Field Detail

    - #### EMPHASIS_DEFAULT

          static final EmphasisType EMPHASIS_DEFAULT

      Default value for the emphasis property, which is `EmphasisType.Unknown`.

    - #### BLOCKSTARTOFFSET_DEFAULT

          static final short BLOCKSTARTOFFSET_DEFAULT

      Default value for the block start offset property, which is 0.

      See Also:
        Constant Field Values

    - #### AUXBITSMODE_DEFAULT

          static final AuxBitsModeType AUXBITSMODE_DEFAULT

      Default value for the aux bits mode property, which is `AuxBitsModeType.NotDefined`.

    - #### AES3Minimum

          static final byte[] AES3Minimum

      Minimum channel status according to the AES3 specification, specified in section 5.2.1 of EBU Tech 3250. This is the default value returned by `getChannelStatusModeAt(int)`.

    - #### AES3DefaultUserData

          static final byte[] AES3DefaultUserData

      Default AES3 fixed user data value.

  - ### Method Detail

    - #### getEmphasis

          EmphasisType getEmphasis()

      Returns the AES3 emphasis of the associated sound essence. If this optional property is not present, the default value of this property is returned.

      Returns:
        AES3 emphasis of the associated sound essence.
      See Also:
        `EMPHASIS_DEFAULT`

    - #### setEmphasis

          void setEmphasis(EmphasisType emphasisType)

      Sets the AES3 emphasis property of the associated sound essence. Calling this method with `null` will omit this optional property.

      Parameters:
        `emphasisType` - AES3 emphasis property of the associated sound essence.
      See Also:
        `EMPHASIS_DEFAULT`

    - #### getBlockStartOffset

          @UInt16
          short getBlockStartOffset()

      Returns the AES3 position of the first Z preamble in the associated sound essence stream. If this optional property is not present, the default value of 0 is returned.

      Returns:
        AES3 position of the first Z preamble is the associated sound essence stream.
      See Also:
        `BLOCKSTARTOFFSET_DEFAULT`

    - #### setBlockStartOffset

          void setBlockStartOffset(@UInt16
                                   Short blockStartOffset)
                            throws IllegalArgumentException

      Sets the AES3 position of the first Z preamble in the associated sound essence stream. The default value of this optional property is 0. To omit this optional property, call this method with `null`.

      Parameters:
        `blockStartOffset` - AES3 position of the first Z preamble in the associated sound essence stream.
      Throws:
        `IllegalArgumentException` - The block start offset is negative.
      See Also:
        `BLOCKSTARTOFFSET_DEFAULT`

    - #### getAuxBitsMode

          AuxBitsModeType getAuxBitsMode()

      Returns the AES3 use of auxiliary bits in the associated audio essence. If this optional property is not present, the default value of `AuxBitsModeType.NotDefined` is returned.

      Returns:
        AES3 use of auxiliary bits in the associated audio essence.
      See Also:
        `AUXBITSMODE_DEFAULT`

    - #### setAuxBitsMode

          void setAuxBitsMode(AuxBitsModeType auxBitsMode)

      Sets the AES3 use of auxiliary bits in the associated audio essence. To omit this optional property, call this method with `null`.

      Parameters:
        `auxBitsMode` - AES3 use of auxiliary bits in the associated audio essence.
      See Also:
        `AUXBITSMODE_DEFAULT`

    - #### getChannelStatusMode

          ChannelStatusModeType[] getChannelStatusMode()

      Returns the AES3 enumerated mode of carriage of channel status data for all channels of the associated audio essence.

      Returns:
        AES3 enumerated mode of carriage of channel status data for all channels of the associated audio essence.
      See Also:
        `getChannelStatusModeAt(int)`

    - #### getChannelStatusModeAt

          ChannelStatusModeType getChannelStatusModeAt(@UInt32
                                                       int index)
                                                throws IndexOutOfBoundsException

      Returns the AES3 enumerated mode of carriage of channel status data for the associated audio essence for the given channel number. If the channel status mode property is not present, the default value of `ChannelStatusModeType.None` is returned.

      Parameters:
        `index` - Index into the AES3 channel status mode array.
      Returns:
        Element of the AES3 channel status mode at the given index.
      Throws:
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current channel status mode array.
      See Also:
        `getChannelStatusMode()`, `SoundDescriptor.getChannelCount()`

    - #### setChannelStatusModeAt

          void setChannelStatusModeAt(@UInt32
                                      int index,
                                      ChannelStatusModeType channelStatusMode)
                               throws IndexOutOfBoundsException,
                                      NullPointerException

      Sets the AES3 enumerated mode of carriage of channel status data for the associated audio essence at the given channel number.

      If the channel status mode property is not present at the time of calling the method, after completion of the method the property becomes present and properties at other indexes are initialized to `ChannelStatusModeType.None`.

      Parameters:
        `index` - Index of the channel status mode array to set the channel status for.
        `channelStatusMode` - Channel status for the given index.
      Throws:
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current channel status mode array.
        `NullPointerException` - Cannot set the channel status for a channel to `null`.
      See Also:
        `SoundDescriptor.getChannelCount()`

    - #### getFixedChannelStatusData

          byte[] getFixedChannelStatusData()

      Returns the AES3 fixed channel status data for all channels in the associated audio essence.

      Returns:
        AES3 fixed channel status data for all channels in the associated audio essence.
      See Also:
        `getFixedChannelStatusDataAt(int)`

    - #### getFixedChannelStatusDataAt

          byte[] getFixedChannelStatusDataAt(@UInt32
                                             int index)
                                      throws IndexOutOfBoundsException

      Returns the AES3 fixed channel status data for the channel referenced by the given index in the associated audio essence. The value returned is a 24-byte array.

      The default value is the AES3 minimum, which codes the most significant bit of the first byte as `1` and all other bits as `0`. If this optional property is omitted, the default value will be returned.

      Parameters:
        `index` - Channel index to retrieve the fixed channel status data for.
      Returns:
        Fixed channel status data for the given channel in the associated audio essence.
      Throws:
        `IndexOutOfBoundsException` - The given index is outside the acceptable range for the current range of channels for which fixed status data is represented.
      See Also:
        `getFixedChannelStatusData()`, `SoundDescriptor.getChannelCount()`

    - #### setFixedChannelStatusDataAt

          void setFixedChannelStatusDataAt(@UInt32
                                           int index,
                                           byte[] fixedChannelStatusData)
                                    throws NullPointerException,
                                           IndexOutOfBoundsException,
                                           BadSizeException

      Sets the AES3 fixed channel status data for the channel referenced by the given index in the associated audio essence. The data must take the form of a 24-byte array.

      Parameters:
        `index` - Channel number to set the AES3 fixed channel status data for.
        `fixedChannelStatusData` - Fixed channel status array.
      Throws:
        `NullPointerException` - The fixed channel status data argument is `null`.
        `IndexOutOfBoundsException` - The given channel index is outside the acceptable range for the associated audio essence.
        `BadSizeException` - The fixed channel status data must be an array of 24-bytes exactly.
      See Also:
        `SoundDescriptor.getChannelCount()`

    - #### omitChannelStatusData

          void omitChannelStatusData()

      Omits the optional fixed channel status data and channel status mode properties from this AES3 PCM descriptor. To make them present again, call `setFixedChannelStatusDataAt(int, byte[])` and `setChannelStatusModeAt(int, ChannelStatusModeType)`.

    - #### getUserDataMode

          UserDataModeType[] getUserDataMode()

      Returns the user data mode for all the channels in the associated audio essence.

      Returns:
        User data modes for all channels in the associated essence.
      See Also:
        `getUserDataModeAt(int)`

    - #### getUserDataModeAt

          UserDataModeType getUserDataModeAt(@UInt32
                                             int index)
                                      throws IndexOutOfBoundsException

      Returns the user data mode for the channel of the associated audio essence referenced by the given channel index.

      The default value for each element of this property is `UserDataModeType.NotDefined`. If this optional property is omitted, the default value will be returned.

      Parameters:
        `index` - Channel index to identify the channel to retrieve the user data mode for.
      Returns:
        Type of user data for the given channel number in the associated audio essence.
      Throws:
        `IndexOutOfBoundsException` - The given channel index is outside the acceptable range for the associated audio essence.
      See Also:
        `getUserDataMode()`, `SoundDescriptor.getChannelCount()`

    - #### setUserDataModeAt

          void setUserDataModeAt(@UInt32
                                 int index,
                                 UserDataModeType userDataMode)
                          throws NullPointerException,
                                 IndexOutOfBoundsException

      Sets the user data mode for the channel of the associated audio essence referenced by the given channel index.

      Parameters:
        `index` - Channel index to identify the channel to set the user data mode for.
        `userDataMode` - Type of user data for the given channel.
      Throws:
        `IndexOutOfBoundsException` - The given channel index is outside the acceptable range for the associated audio essence.
        `NullPointerException` - Cannot set the user data mode for a channel to `null`.
      See Also:
        `SoundDescriptor.getChannelCount()`

    - #### getFixedUserData

          byte[] getFixedUserData()

      Returns the AES3 fixed user data for all channels in the associated audio essence. The value is always the number of channels multiplied by 24.

      Returns:
        AES3 fixed user data for all channels.
      See Also:
        `getFixedUserDataAt(int)`

    - #### getFixedUserDataAt

          byte[] getFixedUserDataAt(@UInt32
                                    int index)
                             throws IndexOutOfBoundsException

      Returns the AES3 fixed user data for the given channel in the associated audio essence. The value is always a 24-byte array.

      The default value for fixed user data on a channel is all zero values, as represented by `AES3DefaultUserData`. If this optional property is not present, the default value will be returned.

      Parameters:
        `index` - Channel index of the fixed user data to retrieve.
      Returns:
        Retrieved fixed user data for the given channel number from the associated audio essence.
      Throws:
        `IndexOutOfBoundsException` - The channel number is outside the acceptable range for the associated audio essence.
      See Also:
        `getFixedUserData()`, `SoundDescriptor.getChannelCount()`

    - #### setFixedUserDataAt

          void setFixedUserDataAt(@UInt32
                                  int index,
                                  byte[] fixedUserData)
                           throws NullPointerException,
                                  IndexOutOfBoundsException,
                                  BadSizeException

      Sets the AES3 fixed user data for the given channel in the associated audio essence. The value is always a 24-byte array.

      Parameters:
        `index` - Channel index of the fixed user data to set.
        `fixedUserData` - Fixed user data for the given channel number of the associated audio essence.
      Throws:
        `NullPointerException` - Cannot set fixed user data to `null`.
        `IndexOutOfBoundsException` - The channel number is outside the acceptable range for the associated audio essence.
        `BadSizeException` - The fixed user data value must by a 24-byte array.
      See Also:
        `SoundDescriptor.getChannelCount()`

    - #### omitUserData

          void omitUserData()

      Omit the optional fixed user data and user data mode properties from this AES3 PCM descriptor. To make them present again, call `setFixedUserDataAt(int, byte[])` and `setUserDataModeAt(int, UserDataModeType)`.

    - #### clone

          AES3PCMDescriptor clone()

      Create a cloned copy of this AES3 PCM 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`
      Specified by:
        `clone` in interface `WAVEPCMDescriptor`
      Returns:
        Cloned copy of this AES3 PCM descriptor.

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