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

tv.amwa.maj.model

## Interface SoundDescriptor

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

      public interface SoundDescriptor
      extends AAFFileDescriptor

  Specifies the description of a file source package that is associated with audio essence.

  See Also:
    `DataDefinitionConstant.Sound`, `SourcePackage.getEssenceDescriptor()`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `SoundDescriptor` | `clone()` Create a cloned copy of this sound descriptor.
    `byte` | `getAudioReferenceLevel()` Returns the audio reference level of this sound descriptor.
    `Rational` | `getAudioSampleRate()` Returns the audio sampling rate of audio essence described by this sound descriptor.
    `int` | `getChannelCount()` Returns the number of audio channels described by this sound descriptor.
    `byte` | `getDialNorm()` Returns the dial norm property of this sound descriptor, which specifies the gain to be applied to normalize perceived loudness of the sound, as defined by ITU-R Recommendation BS.1196 (1dB per step).
    `ElectroSpatialFormulation` | `getElectrospatialFormulation()` Returns the electro-spatial formulation of the signal described by this sound descriptor.
    `boolean` | `getLocked()` Returns the locked flag for the audio essence described by this sound descriptor, which indicates whether the number of samples per frame is locked.
    `int` | `getQuantizationBits()` Returns the number of quantization bits used for the audio essence described by this sound descriptor.
    `AUID` | `getSoundCompression()` Returns he kind of compression and format of compression information of this sound essence data.
    `boolean` | `isLocked()` Returns the locked flag for the audio essence described by this sound descriptor, which indicates whether the number of samples per frame is locked.
    `void` | `setAudioReferenceLevel(Byte level)` Sets the audio reference level of the audio essence described by this sound descriptor.
    `void` | `setAudioSampleRate(Rational audioSamplingRate)` Sets the audio sampling rate of audio essence described by this sound descriptor.
    `void` | `setChannelCount(int channelCount)` Sets the number of audio channels described by this sound descriptor.
    `void` | `setDialNorm(Byte dialNorm)` Sets the dial norm of this sound descriptor, which specifies the gain to be applied to normalize perceived loudness of the sound, as defined by ITU-R Recommendation BS.1196 (1dB per step).
    `void` | `setElectrospatialFormulation(ElectroSpatialFormulation formulation)` Sets the electro-spatial formulation of the signal of the audio essence described by this sound descriptor.
    `void` | `setIsLocked(Boolean locked)` Sets the locked flag for the audio essence described this sound descriptor, which indicates whether the number of samples per frame is locked.
    `void` | `setQuantizationBits(int bitsCount)` Sets the number of quantization bits used for the audio essence described by this sound descriptor.
    `void` | `setSoundCompression(AUID compression)` Sets the kind of compression and format of compression information of this sound essence data.

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

    - #### setSoundCompression

          void setSoundCompression(AUID compression)

      Sets the kind of compression and format of compression information of this sound essence data. This property is optional and if the property is not present then the described audio essence is not compressed. Set to `null` to indicate that the described audio essence is not compressed.

      Parameters:
        `compression` - Kind of compression and format of the compression for this sound essence data.

    - #### getSoundCompression

          AUID getSoundCompression()
                            throws PropertyNotPresentException

      Returns he kind of compression and format of compression information of this sound essence data. This property is optional.

      Returns:
        The kind of compression and format of compression for the sound essence data.
      Throws:
        `PropertyNotPresentException` - The optional property is not present in the sound descriptor, indicating that the described sound essence is not compressed.

    - #### setChannelCount

          void setChannelCount(@UInt32
                               int channelCount)
                        throws IllegalArgumentException

      Sets the number of audio channels described by this sound descriptor.

      Parameters:
        `channelCount` - Number of audio channels described by this sound descriptor.
      Throws:
        `IllegalArgumentException` - The given channel count is negative.

    - #### getChannelCount

          @UInt32
          int getChannelCount()

      Returns the number of audio channels described by this sound descriptor.

      Returns:
        Number of audio channels described by this sound descriptor.

    - #### setAudioSampleRate

          void setAudioSampleRate(Rational audioSamplingRate)
                           throws NullPointerException

      Sets the audio sampling rate of audio essence described by this sound descriptor.

      Parameters:
        `audioSamplingRate` - Audio sampling rate of the audio essence described by this sound descriptor.
      Throws:
        `NullPointerException` - The given audio sampling rate is `null`.

    - #### getAudioSampleRate

          Rational getAudioSampleRate()

      Returns the audio sampling rate of audio essence described by this sound descriptor.

      Returns:
        Audio sampling rate of audio essence described by this sound descriptor.

    - #### setIsLocked

          void setIsLocked(@Bool
                           Boolean locked)

      Sets the locked flag for the audio essence described this sound descriptor, which indicates whether the number of samples per frame is locked. Set this optional property to `null` to omit it.

      Parameters:
        `locked` - Are the number of samples per frame locked?

    - #### isLocked

          @Bool
          boolean isLocked()
                          throws PropertyNotPresentException

      Returns the locked flag for the audio essence described by this sound descriptor, which indicates whether the number of samples per frame is locked. This property is optional.

      Returns:
        Are the number of samples per frame locked?
      Throws:
        `PropertyNotPresentException` - The optional locked property is not present in this sound descriptor.
      See Also:
        `getLocked()`

    - #### getLocked

          @Bool
          boolean getLocked()
                           throws PropertyNotPresentException

      Returns the locked flag for the audio essence described by this sound descriptor, which indicates whether the number of samples per frame is locked. This property is optional.

      Returns:
        Are the number of samples per frame locked?
      Throws:
        `PropertyNotPresentException` - The optional locked property is not present in this sound descriptor.
      See Also:
        `isLocked()`

    - #### setElectrospatialFormulation

          void setElectrospatialFormulation(ElectroSpatialFormulation formulation)

      Sets the electro-spatial formulation of the signal of the audio essence described by this sound descriptor. Set this optional property to `null` to omit it.

      Possible values for the electo-spatial formulation include:

      - `ElectroSpatialFormulation.MultiChannelMode`
      - `ElectroSpatialFormulation.TwoChannelMode`
      - `ElectroSpatialFormulation.SingleChannelMode`
      Parameters:
        `formulation` - Electro-spatial formulation of the signal described by this sound descriptor.

    - #### getElectrospatialFormulation

          ElectroSpatialFormulation getElectrospatialFormulation()
                                                          throws PropertyNotPresentException

      Returns the electro-spatial formulation of the signal described by this sound descriptor. This property is optional.

      Possible values for the electo-spatial formulation include:

      - `ElectroSpatialFormulation.MultiChannelMode`
      - `ElectroSpatialFormulation.TwoChannelMode`
      - `ElectroSpatialFormulation.SingleChannelMode`
      Returns:
        Electro-spatial formulation of the signal of this sound descriptor.
      Throws:
        `PropertyNotPresentException` - The optional electro-spatial formulation property is not present in this sound descriptor.

    - #### setAudioReferenceLevel

          void setAudioReferenceLevel(@Int8
                                      Byte level)

      Sets the audio reference level of the audio essence described by this sound descriptor. This property specifies the number of dBm for 0VU. Set this optional property to `null` to omit it.

      Parameters:
        `level` - Audio reference level property of this sound descriptor.

    - #### getAudioReferenceLevel

          @Int8
          byte getAudioReferenceLevel()
                                     throws PropertyNotPresentException

      Returns the audio reference level of this sound descriptor. This specifies the number of dBm for 0VU. This property is optional.

      Returns:
        Audio reference level property of this sound descriptor.
      Throws:
        `PropertyNotPresentException` - The optional audio reference level property is not present in this sound descriptor.

    - #### setDialNorm

          void setDialNorm(@Int8
                           Byte dialNorm)

      Sets the dial norm of this sound descriptor, which specifies the gain to be applied to normalize perceived loudness of the sound, as defined by ITU-R Recommendation BS.1196 (1dB per step). Set this optional property to `null` to omit it.

      Parameters:
        `dialNorm` - Dial norm property of the sound descriptor.

    - #### getDialNorm

          @Int8
          byte getDialNorm()
                          throws PropertyNotPresentException

      Returns the dial norm property of this sound descriptor, which specifies the gain to be applied to normalize perceived loudness of the sound, as defined by ITU-R Recommendation BS.1196 (1dB per step). This property is optional.

      Returns:
        Dial norm property of this sound descriptor.
      Throws:
        `PropertyNotPresentException` - This optional dial norm property is not present in this sound descriptor.

    - #### setQuantizationBits

          void setQuantizationBits(@UInt32
                                   int bitsCount)
                            throws IllegalArgumentException

      Sets the number of quantization bits used for the audio essence described by this sound descriptor.

      Parameters:
        `bitsCount` - Number of quantization bits of this sound descriptor.
      Throws:
        `IllegalArgumentException` - The given quantization bits value is negative.

    - #### getQuantizationBits

          @UInt32
          int getQuantizationBits()

      Returns the number of quantization bits used for the audio essence described by this sound descriptor.

      Returns:
        Number of quantization bits of this sound descriptor.

    - #### clone

          SoundDescriptor clone()

      Create a cloned copy of this 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`
      Returns:
        Cloned copy of this sound descriptor.

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