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

tv.amwa.maj.model

## Interface MaterialPackage

- All Superinterfaces:
    InterchangeObject, MediaEntity, MetadataObject, Package, WeakReferenceTarget
  All Known Subinterfaces:
    QMaterialPackage
  All Known Implementing Classes:
    MaterialPackageImpl

      public interface MaterialPackage
      extends Package

  Specifies a material object that provides access to source packages and essence data.

  This interface provides a number of methods that are useful for the management of tracks.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addMaterialTrack(DataDefinition dataDefinition, int sourceTrackID, SourcePackage sourcePackage, int materialTrackID, String trackName)` Adds a track to this material package that references the specified track in the specified `source package`.
    `void` | `appendPhysSourceRef(Rational editrate, int trackID, DataDefinition essenceKind, SourceReferenceValue ref, long srcRefLength)` Connects this material package with the physical Source package that describes the previous generation of essence, appending it to existing package data.
    `MaterialPackage` | `clone()` Create a cloned copy of this material package.
    `short` | `countChannels(int trackID, CriteriaType mediaCriteria, DataDefinition mediaKind)` Returns the number of interleaved essence channels of a given type in the essence stream referenced from the given track of this material package.
    `EssenceAccess` | `createEssence(int materialTrackID, DataDefinition mediaKind, AUID codecID, Rational editRate, Rational samplerate, CompressEnable compressEnable, Locator destination, AUID fileFormat)` Creates a single channel stream of essence in the given track of this material package.
    `EssenceAccess` | `createEventEssence(int materialTrackID, DataDefinition mediaKind, AUID codecID, Rational editRate, Rational sampleRate, CompressEnable compressEnable, Locator destination, AUID fileFormat)` Creates and initializes an event track in a track of this material packages that represents a stream of events.
    `EssenceMultiAccess` | `createMultiEssence(AUID codecID, MultiCreateItem[] mediaArray, CompressEnable enable, Locator destination, AUID fileFormat)` Creates a multi-channel interleaved stream of essence for this material package.
    `EssenceAccess` | `createStaticEssence(int materialTrackID, DataDefinition mediaKind, AUID codecID, CompressEnable compressEnable, Locator destination, AUID fileFormat)` Creates and initializes static essence as a referenced track of this material package, returning access to them.
    `EssenceAccess` | `extendEssence(int materialTrackID, DataDefinition mediaKind, AUID codecID, Rational editRate, Rational sampleRate, CompressEnable enable, Locator destintation, AUID fileFormat)` Extends a single stream of essence that was originally created using `createEssence()`.
    `EssenceMultiAccess` | `extendMultiEssence(AUID codecId, MultiCreateItem[] mediaArray, CompressEnable compressEnable, Locator destination, AUID fileFormat)` Extends a multi-channel interleaved stream of essence that was originally created using `createMultiEssence()`.
    `Segment` | `getCriteriaSegment(int trackID, CriteriaType criteria)` Returns the segment on the specified track of this material package that references the source package that best meets the specified criteria.
    `int` | `getNumberOfRepresentations(int trackID)` This function returns the number of media representations available for the specified track of this material package.
    `PackageMarker` | `getPackageMarker()` Returns the package marker for this material package, which specifies an optional sub-section that may be played as an alternative to the full material package.
    `Segment` | `getRepresentation(int trackID, int representationIndex)` This method returns the indexed media representation for this material package, for this given track id and index through the different representations.
    `String` | `getTapeName(int materialTrackId)` Finds the tape source package associated with a track of this material package and returns the name of the tape, which is stored in the source package's name property.
    `void` | `newPhysSourceRef(Rational editrate, int track, DataDefinition essenceKind, SourceReferenceValue ref, long srcRefLength)` Connects this Source package with the physical Source package that describes the previous generation of essence, replacing any existing package data.
    `EssenceAccess` | `openEssence(int trackID, CriteriaType mediaCriteria, MediaOpenMode openMode, CompressEnable compressEnable)` Opens a single channel of a file source package referenced from a track of this material package.
    `EssenceMultiAccess` | `openMultiEssence(int trackID, CriteriaType mediaCriteria, MediaOpenMode openMode, CompressEnable compressEnable)` Opens all channels associated with a file source package referenced from this material package.
    `void` | `setPackageMarker(PackageMarker packageMarker)` Sets the package marker for this material package, which specifies an optional sub-section that may be played as an alternative to the full material package.

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

      `appendNewEventTrack, appendNewStaticTrack, appendNewTimelineTrack, appendPackageAttribute, appendPackageAttribute, appendPackageKLVData, appendPackageTrack, appendPackageUserComment, appendPackageUserComment, changeReference, clearPackageAttributes, clearPackageKLVData, clearPackageTracks, clearPackageUserComments, cloneExternal, copy, countPackageAttributes, countPackageKLVData, countPackageTracks, countPackageUserComments, getCreationTime, getPackageAttributes, getPackageID, getPackageKLVData, getPackageLastModified, getPackageName, getPackageTrackAt, getPackageTracks, getPackageUsage, getPackageUserComments, insertPackageTrackAt, lookupPackageTrack, offsetToPackageTimecode, prependPackageTrack, removePackageAttribute, removePackageKLVData, removePackageTrackAt, removePackageUserComment, setCreationTime, setPackageID, setPackageLastModified, setPackageName, setPackageUsage`

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

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

      `getAUID, getWeakTargetReference`

- - ### Method Detail

    - #### getPackageMarker

          PackageMarker getPackageMarker()
                                  throws PropertyNotPresentException

      Returns the package marker for this material package, which specifies an optional sub-section that may be played as an alternative to the full material package. This is an optional property.

      Returns:
        Package marker for this material package.
      Throws:
        `PropertyNotPresentException` - The optional package marker property is not present for this material package.

    - #### setPackageMarker

          void setPackageMarker(PackageMarker packageMarker)

      Sets the package marker for this material package, which specifies an optional sub-section that may be played as an alternative to the full material package. Set this optional property to `null` to omit it.

      Parameters:
        `packageMarker` - Package marker for this material package.

    - #### addMaterialTrack

          void addMaterialTrack(DataDefinition dataDefinition,
                                @TrackID
                                int sourceTrackID,
                                SourcePackage sourcePackage,
                                @TrackID
                                int materialTrackID,
                                @AAFString
                                String trackName)
                         throws NullPointerException,
                                InvalidDataDefinitionException,
                                TrackNotFoundException,
                                TrackExistsException,
                                IllegalArgumentException

      Adds a track to this material package that references the specified track in the specified `source package`. The new track in the material package contains a `source clip` that specifies the `source package` in its source reference properties.

      Parameters:
        `dataDefinition` - Essence kind of the new track. Requires an essence kind valid for time-varying essence, such as: "Picture", "Sound".
        `sourceTrackID` - Track id of the source track to be referenced from this material package.
        `sourcePackage` - Source package containing the track to be referenced from this material package.
        `materialTrackID` - Track id to be assigned to the new material track.
        `trackName` - Name to assign to new track in the material package. Set this property to `null` to omit the optional track name.
      Throws:
        `NullPointerException` - One or both of the data definition and/or source package parameters is/are `null`.
        `InvalidDataDefinitionException` - The data kind of the source track to be added to the material package does not match what is specified in `dataDefinition`.
        `TrackNotFoundException` - The given source track was not found.
        `TrackExistsException` - The given material track id already identifies a track in this material package.
        `IllegalArgumentException` - The given material track id is is negative.
      See Also:
        `SourceClip`, `TimelineTrack`, `Package.getPackageTracks()`

    - #### getTapeName

          @AAFString
          String getTapeName(@TrackID
                                        int materialTrackId)
                                 throws TrackNotFoundException,
                                        NotTapePackageException

      Finds the tape source package associated with a track of this material package and returns the name of the tape, which is stored in the source package's name property. If the property name has not yet been set, a zero-length string will be returned.

      A tape source package is a source package described by a tape descriptor.

      Parameters:
        `materialTrackId` - Track id of this material track to use to find the tape name.
      Returns:
        Tape name of the tape source package in the given track.
      Throws:
        `TrackNotFoundException` - The specified material track was not found.
        `NotTapePackageException` - The specified material track does not contain a tape package.
      See Also:
        `TapeDescriptor`, `SourcePackage.getEssenceDescriptor()`

    - #### getNumberOfRepresentations

          @NumTracks
          int getNumberOfRepresentations(@TrackID
                                                    int trackID)
                                             throws TrackNotFoundException

      This function returns the number of media representations available for the specified track of this material package. Each different representation will have a media criteria that can be used to select it. Use `getCriteriaSegment(int, CriteriaType)` to handle multiple representations.

      Parameters:
        `trackID` - Track id the count of the number of representations are required for.
      Returns:
        Number of different media type representations in the track.
      Throws:
        `TrackNotFoundException` - The material track specified by track is was not found for this material package.

    - #### getRepresentation

          Segment getRepresentation(@TrackID
                                    int trackID,
                                    @UInt32
                                    int representationIndex)
                             throws TrackNotFoundException,
                                    IndexOutOfBoundsException

      This method returns the indexed media representation for this material package, for this given track id and index through the different representations. This call is designed to work with `getNumberOfRepresentations(int)` so that the user can iterate through all of the choices. This method uses an integer index, not an iterator. The method takes an index between 0 and one less than the number of representations, and returns the source package at that representation index.

      Parameters:
        `trackID` - Track id of this material package to find a representation for.
        `representationIndex` - Index of media representation in the given track.
      Returns:
        Matching source clip.
      Throws:
        `TrackNotFoundException` - The material track specified by track id was not found in this material package.
        `IndexOutOfBoundsException` - No media representation is available at the specified index.
      See Also:
        `CriteriaType`

    - #### getCriteriaSegment

          Segment getCriteriaSegment(@TrackID
                                     int trackID,
                                     CriteriaType criteria)
                              throws TrackNotFoundException,
                                     NullPointerException

      Returns the segment on the specified track of this material package that references the source package that best meets the specified criteria. This function will return a result whether multiple media representations exist or not, as one representation not matching a criteria is considered better than no representation for any given media criteria.

      Parameters:
        `trackID` - Track id of a track of this material package to return a representation for.
        `criteria` - Criteria for selecting one of the segments.
      Returns:
        Matching segment.
      Throws:
        `TrackNotFoundException` - The material track specified by track id was not found.
        `NullPointerException` - One or both of the track id and/or criteria is/are `null`.

    - #### appendPhysSourceRef

          void appendPhysSourceRef(Rational editrate,
                                   @TrackID
                                   int trackID,
                                   DataDefinition essenceKind,
                                   SourceReferenceValue ref,
                                   @LengthType
                                   long srcRefLength)
                            throws NullPointerException

      Connects this material package with the physical Source package that describes the previous generation of essence, appending it to existing package data. If a physical Source package, such as a File Source package or tape Source package, references another physical Source package as its ancestor, with no pulldown, then this function makes the connection between the two.

      Functionally, this is a helper method to create a track with an `SourceClip` referencing a particular piece of media. This method takes many parameters because the components of an `SourceReferenceValue` have been broken out as separate parameters.

      The ancestor of a `SourcePackage` with an `AAFFileDescriptor` is often a `TapeDescriptor` or `null`.

      Parameters:
        `editrate` - Edit rate of track to contain reference.
        `trackID` - Track id of track to contain reference.
        `essenceKind` - Data kind of track to contain reference. Requires a data kind valid for a essence stream. Valid data kinds are: "`Picture`", "`Sound`"
        `ref` - Reference to a Physical Source package.
        `srcRefLength` - Length of the Source Clip.
      Throws:
        `NullPointerException` - One or more of the arguments is null.

    - #### newPhysSourceRef

          void newPhysSourceRef(Rational editrate,
                                @TrackID
                                int track,
                                DataDefinition essenceKind,
                                SourceReferenceValue ref,
                                @LengthType
                                long srcRefLength)
                         throws NullPointerException

      Connects this Source package with the physical Source package that describes the previous generation of essence, replacing any existing package data. If a physical Source package, such as a File Source package or tape Source package, references another physical Source package as its ancestor, with no pulldown, then this function makes the connection between the two.

      Functionally, this is a helper method to create a track with a `SourceClip` referencing a particular piece of media. This function takes many parameters because the components of a `SourceReferenceValue` have been broken out as separate parameters.

      The ancestor of an source package with an `AAFFileDescriptor` is often an `TapeDescriptor` or `null`.

      Parameters:
        `editrate` -
        `track` -
        `essenceKind` -
        `ref` -
        `srcRefLength` -
      Throws:
        `NullPointerException`

    - #### createEssence

          EssenceAccess createEssence(@TrackID
                                      int materialTrackID,
                                      DataDefinition mediaKind,
                                      AUID codecID,
                                      Rational editRate,
                                      Rational samplerate,
                                      CompressEnable compressEnable,
                                      Locator destination,
                                      AUID fileFormat)
                               throws NullPointerException

      Creates a single channel stream of essence in the given track of this material package. Convenience functions exist to create audio or video essence, and a separate call (`createMultiEssence(AUID, MultiCreateItem[], CompressEnable, Locator, AUID)`) exists to create interleaved audio and video data.

      The essence handle from this call can be used with `EssenceAccess.writeSamples(int, byte[])`, but not with `EssenceMultiAccess.writeMultiSamples(MultiXferItem[])`.

      For video, the sample rate should be the edit rate of the file source package. For audio, the sample rate should be the actual number of samples per second.

      Parameters:
        `materialTrackID` - Material track id for the new essence.
        `mediaKind` - Create essence of this type.
        `codecID` - Create essence according to this codec.
        `editRate` - Create essence with this edit rate.
        `samplerate` - Create essence with this sample rate.
        `compressEnable` - Is compression enabled?
        `destination` - Create the essence at this location, or `null` for the default location.
        `fileFormat` - Create essence to this file format.
      Returns:
        Access to the created essence.
      Throws:
        `NullPointerException` - One or more of the required arguments is `null`.

    - #### createMultiEssence

          EssenceMultiAccess createMultiEssence(AUID codecID,
                                                MultiCreateItem[] mediaArray,
                                                CompressEnable enable,
                                                Locator destination,
                                                AUID fileFormat)
                                         throws NullPointerException

      Creates a multi-channel interleaved stream of essence for this material package. The essence handle from this call can be used with `EssenceAccess.writeSamples(int, byte[])` or `EssenceMultiAccess.writeMultiSamples(MultiXferItem[])`.

      Parameters:
        `codecID` - Create multi-essence using this codec.
        `mediaArray` - Create multi-essence using this array of definitions.
        `enable` - Is multi-essence compressed?
        `destination` - Create the interleaved essence file at this location, or `null` for default location.
        `fileFormat` - If a file is created, use this file format as specified by the identifier of a container definition.
      Returns:
        Access to the created multi-essence.
      Throws:
        `NullPointerException` - One or more of the required arguments is `null`.

    - #### openEssence

          EssenceAccess openEssence(@TrackID
                                    int trackID,
                                    CriteriaType mediaCriteria,
                                    MediaOpenMode openMode,
                                    CompressEnable compressEnable)
                             throws NullPointerException,
                                    TrackNotFoundException

      Opens a single channel of a file source package referenced from a track of this material package. If the essence is interleaved, then it will be de-interleaved when samples are read. This routine follows the locator of the source package's essence descriptor.

      The essence handle from this call can be used with `EssenceAccess.readSamples(int)`, but NOT with `EssenceMultiAccess.readMultiSamples(MultiXferItem[])`.

      Parameters:
        `trackID` - Open essence on this track.
        `mediaCriteria` - Select essence using this criteria.
        `openMode` - Open essence with this mode, either read only or append.
        `compressEnable` - Should the essence be decompressed?
      Returns:
        Access to the essence.
      Throws:
        `NullPointerException` - One or more of the arguments was null.
        `TrackNotFoundException` - The specified track does not exist in the material package.

    - #### openMultiEssence

          EssenceMultiAccess openMultiEssence(@TrackID
                                              int trackID,
                                              CriteriaType mediaCriteria,
                                              MediaOpenMode openMode,
                                              CompressEnable compressEnable)
                                       throws NullPointerException,
                                              TrackNotFoundException

      Opens all channels associated with a file source package referenced from this material package. This routine follows the locator of the essence descriptor of the source package.

      The essence handle from this call can be used with `EssenceMultiAccess.writeMultiSamples(MultiXferItem[])` but not with `EssenceAccess.writeSamples(int, byte[])`.

      Parameters:
        `trackID` - Track id of this material package referencing the essence to open.
        `mediaCriteria` - Select a kind of representation of the content in the track using this criteria.
        `openMode` - Open mode for essence access, either `MediaOpenMode.ReadOnly` or `MediaOpenMode.Append`.
        `compressEnable` - Should the essence be decompressed?
      Returns:
        Access to the multi-channel essence.
      Throws:
        `NullPointerException` - One or more of the media criteria, open mode or compress enable arguments is/are `null`.
        `TrackNotFoundException` - The given track does not exist in this material package.

    - #### countChannels

          @UInt16
          short countChannels(@TrackID
                                      int trackID,
                                      CriteriaType mediaCriteria,
                                      DataDefinition mediaKind)
                               throws NullPointerException,
                                      TrackNotFoundException

      Returns the number of interleaved essence channels of a given type in the essence stream referenced from the given track of this material package. This method is structured so that it can be called before essence is opened.

      If the data format is not interleaved, then the answer will always be zero or one. This function correctly returns zero for essence types not handled by a given codec, and handles codecs which work with multiple essence types.

      Parameters:
        `trackID` - Count channels on this track of this material package.
        `mediaCriteria` - Filter channels using this media criteria.
        `mediaKind` - Count channels of this kind of essence.
      Returns:
        Number of channels in the given track, matching the given media criteria and essence kind.
      Throws:
        `NullPointerException` - One or both of the media criteria and/or media kind arguments is/are `null`.
        `TrackNotFoundException` - The specified track does not exist in this material package.

    - #### extendEssence

          EssenceAccess extendEssence(@TrackID
                                      int materialTrackID,
                                      DataDefinition mediaKind,
                                      AUID codecID,
                                      Rational editRate,
                                      Rational sampleRate,
                                      CompressEnable enable,
                                      Locator destintation,
                                      AUID fileFormat)
                               throws NullPointerException

      Extends a single stream of essence that was originally created using `createEssence()`. Extended essence is represented by a sequence of source clips. The first call to this method will cause the timeline track's source clip object to be replaced by a sequence. The initial source clip becomes the first component of the new sequence.

      Parameters:
        `materialTrackID` - Track id of the essence to be extended on this material package.
        `mediaKind` - Create the extended essence with this type.
        `codecID` - Create the extended essence with this codec.
        `editRate` - Create the extended essence with this edit rate.
        `sampleRate` - Create the extended essence with this sample rage.
        `enable` - Should the extended essence by compressed?
        `destintation` - Optionally create a file of extended essence at this location.
        `fileFormat` - If a file is created, use this file format, as specified by a the identifier of a container definition.
      Returns:
        Essence access to the newly extended essence.
      Throws:
        `NullPointerException` - One of more of the required arguments is/are `null`.

    - #### extendMultiEssence

          EssenceMultiAccess extendMultiEssence(AUID codecId,
                                                MultiCreateItem[] mediaArray,
                                                CompressEnable compressEnable,
                                                Locator destination,
                                                AUID fileFormat)
                                         throws NullPointerException

      Extends a multi-channel interleaved stream of essence that was originally created using `createMultiEssence()`. Extended essence is represented by a sequence of source clips. The first call to this method will cause the timeline track's source clip to be replaced by a sequence. The initial source clip becomes the first component of the new sequence.

      Parameters:
        `codecId` - Extend the multi-channel essence using this codec.
        `mediaArray` - Use these media definitions to extend the essence.
        `compressEnable` - Should the extension be done with compression enabled?
        `destination` - Optionally create a file at this location.
        `fileFormat` - If the file is created, use this format, as specified by the identifier of a container definition.
      Returns:
        Essence access to the extended essence.
      Throws:
        `NullPointerException` - One or more of the required arguments is/are `null`.
      See Also:
        `MultiCreateItem`, `ContainerConstant`

    - #### createStaticEssence

          EssenceAccess createStaticEssence(@TrackID
                                            int materialTrackID,
                                            DataDefinition mediaKind,
                                            AUID codecID,
                                            CompressEnable compressEnable,
                                            Locator destination,
                                            AUID fileFormat)
                                     throws NullPointerException

      Creates and initializes static essence as a referenced track of this material package, returning access to them.

      This method is broadly similar to `createEssence()` except that the essence is created in a `static track` in this material package.

      The essence handle from this call can be used with `EssenceAccess.writeSamples(int, byte[])` but not with `EssenceMultiAccess.writeMultiSamples(MultiXferItem[])`.

      Parameters:
        `materialTrackID` - Track of this material package in which to create static essence.
        `mediaKind` - Create essence of this type.
        `codecID` - Create essence using this codec.
        `compressEnable` - Compress the created essence?
        `destination` - Optionally create the essence file at this location.
        `fileFormat` - If the file is created, use this file format, as specified by a `container definition`.
      Returns:
        Access to the newly created essence.
      Throws:
        `NullPointerException` - One or more of the required arguments is/are `null`.
      See Also:
        `ContainerConstant`

    - #### createEventEssence

          EssenceAccess createEventEssence(@TrackID
                                           int materialTrackID,
                                           DataDefinition mediaKind,
                                           AUID codecID,
                                           Rational editRate,
                                           Rational sampleRate,
                                           CompressEnable compressEnable,
                                           Locator destination,
                                           AUID fileFormat)
                                    throws NullPointerException

      Creates and initializes an event track in a track of this material packages that represents a stream of events.

      This method is broadly similar to `createEssence()` except that the essence is created in a `event track` in this material package.

      The essence handle from this call can be used with `EssenceAccess.writeSamples(int, byte[])` but not with `EssenceMultiAccess.writeMultiSamples(MultiXferItem[])`.

      Parameters:
        `materialTrackID` - Track of this material package in which to create the event essence.
        `mediaKind` - Create essence of this type.
        `codecID` - Create essence with this codec.
        `editRate` - Create essence with this edit rate.
        `sampleRate` - Create essence with this sample rate.
        `compressEnable` - Compress the created essence?
        `destination` - Optionally create a the essence file at this location.
        `fileFormat` - If the file is created, use this file format, as specified by the identifier of a container definition.
      Returns:
        Access to the newly created essence.
      Throws:
        `NullPointerException` - One or more of the required arguments is/are `null`.
      See Also:
        `ContainerConstant`, `CodecConstant`

    - #### clone

          MaterialPackage clone()

      Create a cloned copy of this material package.

      Specified by:
        `clone` in interface `InterchangeObject`
      Specified by:
        `clone` in interface `MediaEntity`
      Specified by:
        `clone` in interface `Package`
      Returns:
        Cloned copy of this material package.

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