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

tv.amwa.maj.model

## Interface SourcePackage

- All Superinterfaces:
    InterchangeObject, MediaEntity, MetadataObject, Package, SearchSource, WeakReferenceTarget
  All Known Implementing Classes:
    SourcePackageImpl

      public interface SourcePackage
      extends Package, SearchSource

  Specifies the description of essence that is either stored in a digital form in a file or stored on a physical media, such as tape or film. The description is provided by an essence descriptor, which is either a tape descriptor, file descriptor, film descriptor, or some extended descriptor.

  This described essence is immutable. If the essence changes, such as if a videotape is redigitized, a new source package must be created with a new package id.

  Some methods exist in this interface that are only applicable for one kind of essence descriptor.

  - `appendTimecodeTrack()` - works only on tape source packages.
  - `appendEdgecodeTrack()` - works only on film source packages.

  These methods will throw an exception if the wrong descriptor is present.

  If a source package points to another source package at the same rate (or non-picture), then `appendPhysicalSourceReference()` is used to create the relationship.

  If a source package points to picture on another source package at a different sample rate, then `addPulldownReference()` is used to create the relationship, and the pulldown which describes how to map between the two rates.

  If a source package is the end of the derivation chain for a particular track, then `addNilReference()` should be called for that track, to say that that the track does exist on this source package. For example, a video file package with no derivation would have a single track of type video, with an original source reference to show that video exists and was not derived from anything else on record.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static long` | `FULL_RANGE` Represents a length where an actual length value is not known.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addNilReference(int trackId, long length, DataDefinition dataDefinition, Rational editRate)` Adds a track containing an original source reference to this source package.
    `void` | `addPulldownReference(AppendOption addType, Rational editRate, int trackId, DataDefinition essenceKind, SourceReferenceValue sourceReference, long sourceReferenceLength, PulldownKindType pulldownKind, int phaseFrame, PulldownDirectionType direction)` Connects the given source package with the physical source package that describes the previous generation of essence, with an additional pulldown as part of the reference to indicate a non 1 to 1 relationship between the two.
    `void` | `appendEdgecodeTrack(Rational editRate, int trackID, long startEC, long length, FilmType filmKind, EdgeType codeFormat, byte[] header)` Creates and adds an edgecode track to the film package represented by this source package, with the given starting edgecode, length and edit rate.
    `void` | `appendPhysicalSourceReference(Rational editRate, int trackId, DataDefinition essenceKind, SourceReferenceValue reference, long sourceReferenceLength)` Connects this source package with the physical source package that describes the previous generation of essence, appending it to the existing package chain.
    `void` | `appendTimecodeTrack(Rational editRate, int trackID, TimecodeValue startTimecode, long length)` Creates and adds a timecode track to a tape package represented by this source package, with the given starting timecode, length and edit rate.
    `SourcePackage` | `clone()` Create a cloned copy of this source package.
    `EssenceDescriptor` | `getEssenceDescription()` Returns the essence descriptor of this source package, which describes the format of the essence associated with the source package.
    `EssenceDescriptor` | `getEssenceDescriptor()` Deprecated.
    `void` | `newPhysicalSourceReference(Rational editRate, int trackId, DataDefinition essenceKind, SourceReferenceValue sourceReference, long sourceReferenceLength)` Connects this source package with the physical source package that describes the previous generation of essence, appending it to the existing package chain.
    `void` | `setEssenceDescription(EssenceDescriptor essenceDescriptor)` Sets the essence descriptor of this source package, which describes the format of the essence associated with the source package.
    `void` | `setEssenceDescriptor(EssenceDescriptor essence)` Deprecated.
    `void` | `specifyValidCodeRange(DataDefinition essenceKind, int trackId, Rational editRate, long startOffset, long length)` Creates and adds a track containing source clips to the source package to indicate that a (recently added) timecode track or edgecode track is valid for that channel.

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

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

      `searchSource`

- - ### Field Detail

    - #### FULL_RANGE

          static final long FULL_RANGE

      Represents a length where an actual length value is not known.

      See Also:
        `appendTimecodeTrack(Rational, int, TimecodeValue, long)`, Constant Field Values

  - ### Method Detail

    - #### getEssenceDescriptor

          @Deprecated
          EssenceDescriptor getEssenceDescriptor()

      Deprecated.

      Returns the essence descriptor of this source package, which describes the format of the essence associated with the source package.

      Returns:
        Essence descriptor of this source package.
      See Also:
        `TypeDefinitions.EssenceDescriptorStrongReference`

    - #### getEssenceDescription

          EssenceDescriptor getEssenceDescription()

      Returns the essence descriptor of this source package, which describes the format of the essence associated with the source package.

      Returns:
        Essence descriptor of this source package.
      See Also:
        `TypeDefinitions.EssenceDescriptorStrongReference`

    - #### setEssenceDescriptor

          @Deprecated
          void setEssenceDescriptor(EssenceDescriptor essence)
                                         throws NullPointerException

      Deprecated.

      Sets the essence descriptor of this source package, which describes the format of the essence associated with the source package.

      Parameters:
        `essence` - Essence descriptor of this source package.
      Throws:
        `NullPointerException` - The given essence descriptor is `null`.

    - #### setEssenceDescription

          void setEssenceDescription(EssenceDescriptor essenceDescriptor)
                              throws NullPointerException

      Sets the essence descriptor of this source package, which describes the format of the essence associated with the source package.

      Parameters:
        `essenceDescriptor` - Essence descriptor of this source package.
      Throws:
        `NullPointerException` - The given essence descriptor is `null`.

    - #### addNilReference

          void addNilReference(@TrackID
                               int trackId,
                               @LengthType
                               long length,
                               DataDefinition dataDefinition,
                               Rational editRate)
                        throws NullPointerException,
                               IllegalArgumentException,
                               BadRateException,
                               BadLengthException,
                               TrackExistsException

      Adds a track containing an original source reference to this source package. This special source id indicates that the package chain ends here, which indicates that no further record exists of where the essence was derived from. Some source clip is still required on the track to indicate that the track exists and may be referenced from other packages.

      Examples of source packages that are not derived from a previous source of essence are:

      - tape source packages that were not created from film;
      - file source packages whose digital essence data was originally generated by computer and was not digitized from videotape.
      Parameters:
        `trackId` - Track id to be assigned to the new track.
        `length` - Duration of the source clip to be added to the new track.
        `dataDefinition` - Data definition for the new track.
        `editRate` - Edit rate for the new track.
      Throws:
        `NullPointerException` - The given data definition and/or edit rate is/are `null`.
        `IllegalArgumentException` - The given track identifier is `null`
        `BadRateException` - The edit rate is not valid.
        `BadLengthException` - The length cannot be a negative value.
        `TrackExistsException` - The given track id matches that of a track already present in this source package.
      See Also:
        `SourceReferenceValue.isOriginalSource()`

    - #### appendTimecodeTrack

          void appendTimecodeTrack(Rational editRate,
                                   @TrackID
                                   int trackID,
                                   TimecodeValue startTimecode,
                                   @FrameLength
                                   long length)
                            throws NullPointerException,
                                   TapeDescriptorOnlyException,
                                   TrackExistsException

      Creates and adds a timecode track to a tape package represented by this source package, with the given starting timecode, length and edit rate. It is then necessary to call `specifyValidCodeRange()` to add the filler to the other essence tracks to indicate that the timecode is valid for that other tracks of this package.

      The start timecode parameter is expressed in frames since midnight. The length parameter can be the value `FULL_RANGE`, in which case the length is 24 hours.

      Parameters:
        `editRate` - Edit rate of the timecode track.
        `trackID` - Track id for the new timecode track.
        `startTimecode` - Starting timecode for the timecode track.
        `length` - Duration of the new timecode track.
      Throws:
        `NullPointerException` - One or both of the edit rate and/or start timecode arguments is/are `null`.
        `TapeDescriptorOnlyException` - This operation is only valid for a source package referencing a tape descriptor.
        `TrackExistsException` - The given track id matches that of a track already present in this source package.
      See Also:
        `FULL_RANGE`, `Forge.makeTimecode(long, short, boolean)`, `TimecodeValue specification`

    - #### appendEdgecodeTrack

          void appendEdgecodeTrack(Rational editRate,
                                   @TrackID
                                   int trackID,
                                   @FrameOffset
                                   long startEC,
                                   @FrameLength
                                   long length,
                                   FilmType filmKind,
                                   EdgeType codeFormat,
                                   @EdgecodeHeader
                                   byte[] header)
                            throws NullPointerException,
                                   IllegalArgumentException,
                                   FilmDescriptorOnlyException,
                                   BadLengthException,
                                   BadSizeException,
                                   TrackExistsException

      Creates and adds an edgecode track to the film package represented by this source package, with the given starting edgecode, length and edit rate. It is also necessary to then add an essence track with `specifyValidCodeRange()` to make the new edgecode track valid.

      Parameters:
        `editRate` - Edit rate for the new edgecode track.
        `trackID` - Track id for the new track.
        `startEC` - Starting edgecode of the new edgecode track.
        `length` - Length of the new edgecode track.
        `filmKind` - Film kind for the new edgecode track.
        `codeFormat` - Code for the new edgecode track.
        `header` - Edgecode 8-byte header for the new edgecode track.
      Throws:
        `NullPointerException` - One or more of the arguments is null.
        `FilmDescriptorOnlyException` - This operation is only valid for a source package referencing a film descriptor.
        `BadSizeException` - The size of the header is not the required 8 bytes.
        `BadLengthException` - The length value is negative.
        `TrackExistsException` - The given track id matches that of a track already present in this source package.
        `IllegalArgumentException`
      See Also:
        `Forge.makeEdgeCode(long, FilmType, EdgeType)`, `EdgecodeValue specification`

    - #### specifyValidCodeRange

          void specifyValidCodeRange(DataDefinition essenceKind,
                                     @TrackID
                                     int trackId,
                                     Rational editRate,
                                     @FrameOffset
                                     long startOffset,
                                     @FrameLength
                                     long length)
                              throws NullPointerException,
                                     BadLengthException,
                                     TrackExistsException

      Creates and adds a track containing source clips to the source package to indicate that a (recently added) timecode track or edgecode track is valid for that channel.

      The essence kind parameter requires a data kind with valid for an essence stream. Valid data kinds are:

      - DataDefinitionConstant.Picture
      - DataDefinitionConstant.Sound
      Parameters:
        `essenceKind` - Data kind for the track to be added.
        `trackId` - Track id for the track to be added.
        `editRate` - Edit rate for the track to be added.
        `startOffset` - Start offset for the track to be added.
        `length` - Duration of the source clip in the track.
      Throws:
        `NullPointerException` - One or both of the edit rate and/or essence kind arguments is/are `null`.
        `BadLengthException` - The given length for the new source clip is negative.
        `TrackExistsException` - The given track id matches that of a track already present in this source package.

    - #### appendPhysicalSourceReference

          void appendPhysicalSourceReference(Rational editRate,
                                             @TrackID
                                             int trackId,
                                             DataDefinition essenceKind,
                                             SourceReferenceValue reference,
                                             @LengthType
                                             long sourceReferenceLength)
                                      throws NullPointerException,
                                             BadLengthException,
                                             InvalidDataDefinitionException,
                                             TrackExistsException

      Connects this source package with the physical source package that describes the previous generation of essence, appending it to the existing package chain. 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.

      This is a helper method to create a track with a source clip referencing a particular piece of media.

      The ancestor of a source package with a file descriptor is often a tape descriptor.

      The `essenceKind` parameter requires a data kind valid for an essence stream. Valid data kinds are:

      - DataDefinitionConstant.Picture
      - DataDefinitionConstant.Sound
      Parameters:
        `editRate` - Edit rate of the track to contain the reference.
        `trackId` - Track ID of the track to contain the reference.
        `essenceKind` - Data kind of the track to contain the reference.
        `reference` - Reference to a physical source package.
        `sourceReferenceLength` - Length of the referenced source clip.
      Throws:
        `NullPointerException` - One or more of the nullable parameters is/are `null` and all are required.
        `BadLengthException` - The source reference length is negative.
        `InvalidDataDefinitionException` - The given data definition is not compatible with that of the track this element will be appended to.
        `TrackExistsException` - The given track id matches that of a track already present in this source package.

    - #### newPhysicalSourceReference

          void newPhysicalSourceReference(Rational editRate,
                                          @TrackID
                                          int trackId,
                                          DataDefinition essenceKind,
                                          SourceReferenceValue sourceReference,
                                          @LengthType
                                          long sourceReferenceLength)
                                   throws NullPointerException,
                                          BadLengthException,
                                          TrackExistsException

      Connects this source package with the physical source package that describes the previous generation of essence, appending it to the existing package chain. 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 1 to 1 connection between the two.

      This is a helper method to create a track with a source clip referencing a particular piece of media.

      The ancestor of a source package with a file descriptor is often a tape descriptor.

      The essence kind parameter requires a data kind valid for an essence stream. Valid data kinds are:

      - DataDefinitionConstant.Picture
      - DataDefinitionConstant.Sound
      Parameters:
        `editRate` - Edit rate of the track to contain the reference.
        `trackId` - Track id of the track to contain the reference.
        `essenceKind` - Data kind of the track to contain the reference.
        `sourceReference` - Reference to a physical source package.
        `sourceReferenceLength` - Length of the referenced source clip.
      Throws:
        `NullPointerException` - One or more of the nullable arguments is/are `null` and all are required.
        `BadLengthException` - The given source reference length is negative.
        `TrackExistsException` - The given track id matches that of a package track already present in this source package.
      See Also:
        `SourceClip`

    - #### addPulldownReference

          void addPulldownReference(AppendOption addType,
                                    Rational editRate,
                                    @TrackID
                                    int trackId,
                                    DataDefinition essenceKind,
                                    SourceReferenceValue sourceReference,
                                    @LengthType
                                    long sourceReferenceLength,
                                    PulldownKindType pulldownKind,
                                    @PhaseFrameType
                                    int phaseFrame,
                                    PulldownDirectionType direction)
                             throws NullPointerException,
                                    PulldownDirectionException,
                                    BadLengthException,
                                    NotSourceClipException,
                                    TrackExistsException

      Connects the given source package with the physical source package that describes the previous generation of essence, with an additional pulldown as part of the reference to indicate a non 1 to 1 relationship between the two.

      This is a helper method to create a track with a pulldown object which references a source clip, which references a particular piece of media. This method takes many parameters because the components of a pulldown have been broken out as separate parameters.

      The ancestor of a source package described by a tape descriptor is often a film descriptor.

      Parameters:
        `addType` - Overwrite existing track sequence, or create a new sequence and append it.
        `editRate` - Edit rate of track to contain the reference.
        `trackId` - Track id for the track to contain the reference.
        `essenceKind` - Data kind of track to contain reference. Requires a data kind valid for an essence stream. Valid data kinds are DataDefinitionConstant.Picture and DataDefinitionConstant.Sound.
        `sourceReference` - Reference to a physical source package.
        `sourceReferenceLength` - Length of the referenced physical source package.
        `pulldownKind` - Method of conversion used between this physical source package and this source package.
        `phaseFrame` - Phase of the first frame.
        `direction` - Direction of the pulldown operation.
      Throws:
        `NullPointerException` - One or more of the nullable arguments is/are `null` and all are required.
        `PulldownDirectionException` - The given pullown direction is invalid in this context, for example tape to film speed when this is a tape source package.
        `BadLengthException` - The given source reference length cannot is negative.
        `NotSourceClipException` - The existing contents of the given track does not contain a source clip to add a pulldown reference to.
        `TrackExistsException` - The given track id matches that of a package track already present in this source package.
      See Also:
        `SourceClip`, `Pulldown`, `Sequence`

    - #### clone

          SourcePackage clone()

      Create a cloned copy of this source package.

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

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