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

tv.amwa.maj.model

## Interface AAFFileDescriptor

- All Superinterfaces:
    EssenceDescriptor, InterchangeObject, MediaEntity, MetadataObject
  All Known Subinterfaces:
    AES3PCMDescriptor, AIFCDescriptor, ANCDataDescriptor, CDCIDescriptor, CDCIDescriptor, DataEssenceDescriptor, HTMLDescriptor, MPEGVideoDescriptor, MultipleDescriptor, PictureDescriptor, PictureDescriptor, PolyFileDescriptor, QAAFFileDescriptor, RGBADescriptor, SoundDescriptor, TIFFDescriptor, VBIDataDescriptor, WAVEDescriptor, WAVEPCMDescriptor, WAVEPCMDescriptor
  All Known Implementing Classes:
    AAFFileDescriptorImpl, AES3PCMDescriptorImpl, AIFCDescriptorImpl, ANCDataDescriptorImpl, CDCIDescriptorImpl, DataEssenceDescriptorImpl, HTMLDescriptorImpl, MPEGVideoDescriptorImpl, MultipleDescriptorImpl, PictureDescriptorImpl, PolyFileDescriptorImpl, RGBADescriptorImpl, SoundDescriptorImpl, TIFFDescriptorImpl, VBIDataDescriptorImpl, WAVEDescriptorImpl, WAVEPCMDescriptorImpl

      public interface AAFFileDescriptor
      extends EssenceDescriptor

  Specifies a file descriptor that describes an essence source that is directly manipulated by an AAF application.

  A source package that contains a file descriptor is also known as an MXF file package or a file source package.

  See Also:
    `EssenceDescriptor`, `SourcePackage.getEssenceDescriptor()`, `MultipleDescriptor.getFileDescriptors()`, `TypeDefinitions.FileDescriptorStrongReference`, `TypeDefinitions.FileDescriptorStrongReferenceVector`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `AAFFileDescriptor` | `clone()` Create a cloned copy of this file descriptor.
    `CodecDefinition` | `getCodec()` Returns the codec of the described file, which identifies the mechanism used to compress and uncompress samples of essence or used to convert samples of essence from one format to another.
    `ContainerDefinition` | `getContainerFormat()` Returns the file format of the described file, which identifies the container mechanism used to store the essence.
    `long` | `getEssenceLength()` Returns the length of the essence in sample units.
    `int` | `getLinkedTrackID()` Returns the linked track id of this file descriptor, which specifies which track of the associated source package this descriptor describes when the source package is described by a multiple descriptor.
    `Rational` | `getSampleRate()` Returns the sample rate of the essence.
    `void` | `setCodec(CodecDefinition codecDef)` Set the codec of the described file, which identifies the mechanism used to compress and uncompress samples of essence or used to convert samples of essence from one format to another.
    `void` | `setContainerFormat(ContainerDefinition format)` Specifies the file format of the described file, which identifies the container mechanism used to store the essence.
    `void` | `setEssenceLength(Long length)` Sets the length of the essence in sample units.
    `void` | `setLinkedTrackID(Integer linkedTrackID)` Set the linked track id of this file descriptor, which specifies which track of the associated source package this descriptor describes when the source package is described by a multiple descriptor.
    `void` | `setSampleRate(Rational rate)` Sets sample rate of the essence.

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

    - #### setEssenceLength

          void setEssenceLength(@LengthType
                                Long length)
                         throws BadPropertyException,
                                BadLengthException

      Sets the length of the essence in sample units. This is an optional property that should only be set when the encoder knows the value.

      Note that the sample rate is defined in MXF in terms of the number of addressable units, so for PCM audio this is one unit per audio sample and for MPEG audio this is one unit per frame.

      Parameters:
        `length` - Length of the essence in samples.
      Throws:
        `BadPropertyException` - The length property is not present as this file descriptor describes static essence.
        `BadLengthException` - The length of the described material is negative.

    - #### getEssenceLength

          @LengthType
          long getEssenceLength()
                                     throws BadPropertyException,
                                            PropertyNotPresentException

      Returns the length of the essence in sample units. Set this optional property to `null` to omit it.

      Note that the sample rate is defined in MXF in terms of the number of addressable units, so for PCM audio this is one unit per audio sample and for MPEG audio this is one unit per frame.

      Returns:
        Length of essence in samples.
      Throws:
        `BadPropertyException` - The length property is not present as this file descriptor describes static essence.
        `PropertyNotPresentException` - The optional essence length property is not present for this file descriptor.

    - #### setCodec

          void setCodec(CodecDefinition codecDef)

      Set the codec of the described file, which identifies the mechanism used to compress and uncompress samples of essence or used to convert samples of essence from one format to another.

      Parameters:
        `codecDef` - Codec that was used for the file.
      Throws:
        `NullPointerException` - The given codec is `null`.
      See Also:
        `CodecConstant`

    - #### getCodec

          CodecDefinition getCodec()
                            throws PropertyNotPresentException

      Returns the codec of the described file, which identifies the mechanism used to compress and uncompress samples of essence or used to convert samples of essence from one format to another.

      Returns:
        Codec used to make the file.
      Throws:
        `PropertyNotPresentException` - The optional codec definition property is not present for this file descriptor.
      See Also:
        `TypeDefinitions.CodecDefinitionWeakReference`

    - #### setSampleRate

          void setSampleRate(Rational rate)
                      throws NullPointerException,
                             BadPropertyException

      Sets sample rate of the essence.

      The MXF specification further defines this to be the rate of the addressable units in the stream. For PCM audio, this is the same as the audio sampling rate, for MPEG audio this is the same as the audio frame rate (e.g. AAC audio has 1024 samples per frame, so the rate is 48000/1024).

      Parameters:
        `rate` - Sample rate of the essence.
      Throws:
        `NullPointerException` - The given sample rate is `null`.
        `BadPropertyException` - The sample rate property is not present as this file descriptor describes static essence.

    - #### getSampleRate

          Rational getSampleRate()
                          throws BadPropertyException

      Returns the sample rate of the essence.

      The MXF specification further defines this to be the rate of the addressable units in the stream. For PCM audio, this is the same as the audio sampling rate. For MPEG audio, this is the same as the audio frame rate (e.g. AAC-encoding of 48kHz audio has 1024 samples per frame, so the rate is 48000/1024).

      Returns:
        Sample rate of the essence.
      Throws:
        `BadPropertyException` - The sample rate property is not present as this file descriptor describes static essence.

    - #### setContainerFormat

          void setContainerFormat(ContainerDefinition format)

      Specifies the file format of the described file, which identifies the container mechanism used to store the essence.

      The container format is defined as an optional property but version 1.1 of the AAF object specification requires it to be specified for each file. The property can be omitted by setting its value to `null` for compatibility with older versions of the specification.

      Parameters:
        `format` - File format to set for this file descriptor.
      See Also:
        `ContainerConstant`

    - #### getContainerFormat

          ContainerDefinition getContainerFormat()
                                          throws PropertyNotPresentException

      Returns the file format of the described file, which identifies the container mechanism used to store the essence.

      The container format is defined as an optional property but version 1.1 of the AAF object specification requires it to be specified for each file. However, file descriptors created with tools supporting earlier versions of the AAF specification may omit the property, in which case a `PropertyNotPresentException` is thrown.

      Returns:
        File format of the described file.
      Throws:
        `PropertyNotPresentException` - The (rarely) optional container format property is not present in this file descriptor.
      See Also:
        `TypeDefinitions.ContainerDefinitionWeakReference`

    - #### setLinkedTrackID

          void setLinkedTrackID(@TrackID
                                Integer linkedTrackID)
                         throws IllegalArgumentException

      Set the linked track id of this file descriptor, which specifies which track of the associated source package this descriptor describes when the source package is described by a multiple descriptor. In this case, this file descriptor is one of the collection of file descriptors that are part of a multiple descriptor, as returned by `MultipleDescriptor.getFileDescriptors()`. If this file descriptor is not part of a multiple descriptor collection, set this optional property to `null` to omit it.

      Parameters:
        `linkedTrackID` - Linked track id of this file descriptor.
      Throws:
        `IllegalArgumentException` - The linked track id is negative.

    - #### getLinkedTrackID

          @TrackID
          int getLinkedTrackID()
                                 throws PropertyNotPresentException

      Returns the linked track id of this file descriptor, which specifies which track of the associated source package this descriptor describes when the source package is described by a multiple descriptor. This is an optional property.

      Returns:
        Linked track id of this file descriptor.
      Throws:
        `PropertyNotPresentException` - The optional linked track id property is not present in this file descriptor.

    - #### clone

          AAFFileDescriptor clone()

      Create a cloned copy of this file descriptor.

      Specified by:
        `clone` in interface `EssenceDescriptor`
      Specified by:
        `clone` in interface `InterchangeObject`
      Specified by:
        `clone` in interface `MediaEntity`
      Returns:
        Cloned copy of this file descriptor.

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