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

tv.amwa.maj.model

## Interface SourceReferenceSegment

- All Superinterfaces:
    Component, InterchangeObject, MediaEntity, MetadataObject, Segment
  All Known Subinterfaces:
    DescriptiveClip, HTMLClip, QSourceClip, SourceClip, TextClip
  All Known Implementing Classes:
    DescriptiveClipImpl, HTMLClipImpl, SourceClipImpl, SourceReferenceSegmentImpl, TextClipImpl

      public interface SourceReferenceSegment
      extends Segment

  Specifies the representation of essence or other data described by a track in a package.

  To reference a single channel of a multi-channel track from a mono track, the channel ids property is used with a single element in the array. To reference multiple channels of a multi-channel track from a multi-channel track, the channel ids property is used with multiple elements in the array.

  To reference multiple mono tracks from a multi-channel track, the mono source track ids property is used with multiple elements in the array.

  See the section on naming conflicts in the package documentation.

  See Also:
    `SourceReferenceValue`, `TypeDefinitions.SourceReferenceStrongReference`, `TypeDefinitions.SourceReferenceStrongReferenceVector`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `SourceReferenceSegment` | `clone()` Create a cloned copy of this source reference segment.
    `int[]` | `getChannelIDs()` For references to a multi-channel track, returns the channel ids property of this source reference, which specifies the channels within that tracks that are referenced.
    `int` | `getChannelIDsSize()` Returns the number of elements of the channel ids array of this source reference.
    `int[]` | `getMonoSourceTrackIDs()` For references from a multi-channel track to multiple mono tracks, returns the mono source track ids property of this source reference, which specifies multiple mono tracks that are referenced.
    `int` | `getMonoSourceTrackIDsSize()` Returns the size of the mono source track ids array.
    `PackageID` | `getSourcePackageID()` Returns the package id of the package that is the target of this reference.
    `int` | `getSourceTrackID()` Returns the track id of this source reference.
    `void` | `setChannelIDs(int[] channelIDs)` For references to a multi-channel track, sets the channel ids property of this source reference, which specifies the channels within that tracks that are referenced.
    `void` | `setMonoSourceTrackIDs(int[] monoSourceTrackIDs)` For references from a multi-channel track to multiple mono tracks, sets the mono source track ids property of this source reference, which specifies multiple mono tracks that are referenced.
    `void` | `setSourcePackageID(PackageID sourcePackageID)` Set the source package id of this source reference, which identifies the package that is the target of this reference.
    `void` | `setSourceTrackID(int trackID)` Sets the track id of this source reference.

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

      `generateSequence, segmentOffsetToTC, segmentTCToOffset`

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

      `appendComponentAttribute, appendComponentAttribute, appendComponentKLVData, appendComponentUserComment, appendComponentUserComment, clearComponentAttributes, clearComponentKLVData, clearComponentUserComments, countComponentAttributes, countComponentKLVData, countComponentUserComments, getComponentAttributes, getComponentDataDefinition, getComponentKLVData, getComponentLength, getComponentUserComments, getLengthPresent, removeComponentAttribute, removeComponentKLVData, removeComponentUserComment, setComponentDataDefinition, setComponentLength, setLengthPresent`

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

    - #### getSourcePackageID

          PackageID getSourcePackageID()
                                throws PropertyNotPresentException

      Returns the package id of the package that is the target of this reference. This is an optional property.

      If the source package id property is the zero package id, the package owning the source reference describes the original source. If this property is omitted, the reference is to another track within the same package.

      Returns:
        Source package id that is the target of this source reference.
      Throws:
        `PropertyNotPresentException` - The optional source package id property is not present in this source reference, implying that this is a reference to a track within the same package.
      See Also:
        `SourceReferenceValue.getSourcePackageID()`

    - #### setSourcePackageID

          void setSourcePackageID(PackageID sourcePackageID)

      Set the source package id of this source reference, which identifies the package that is the target of this reference.

      If the property has a value of the zero pcakage id, it means that the package owning this source reference describes the original source. Set this optional property to `null` to omit and indicate that this reference is to another track in the same package.

      For source clips, it is recommended that the `setSourceReference()` method is used to set the source package id property in preference to this method.

      Parameters:
        `sourcePackageID` - Source package id of this source reference.
      See Also:
        `SourceReferenceValue.setSourcePackageID(PackageID)`, `Forge.zeroPackageID()`, `SourceClip.setSourceReference(SourceReferenceValue)`

    - #### getSourceTrackID

          @TrackID
          int getSourceTrackID()

      Returns the track id of this source reference. If the source package id property is the the package package id, the source track id should be 0.

      Returns:
        Track id of this source reference.
      See Also:
        `SourceReferenceValue.getSourceTrackID()`, `TrackID`

    - #### setSourceTrackID

          void setSourceTrackID(@TrackID
                                int trackID)
                         throws IllegalArgumentException

      Sets the track id of this source reference. If the source package id property is the the zero package id, the source track id should be 0.

      Parameters:
        `trackID` - Track id of this source reference.
      Throws:
        `IllegalArgumentException` - The given source track id is negative.
      See Also:
        `SourceReferenceValue.setSourceTrackID(int)`

    - #### setChannelIDs

          void setChannelIDs(@UInt32Array
                             int[] channelIDs)

      For references to a multi-channel track, sets the channel ids property of this source reference, which specifies the channels within that tracks that are referenced. Set this optional property to `null` to omit it and indicate that all channels in the referenced track are referenced in the same order.

      The number of channel ids shall equal the number of channels being described the `track` containing the source reference, e.g. 1 element for a mono audio track, 6 elements for a 5.1 multi-channel audio track.

      Parameters:
        `channelIDs` - Array of channel IDs to set for the source reference.

    - #### getChannelIDs

          @UInt32Array
          int[] getChannelIDs()
                                    throws PropertyNotPresentException

      For references to a multi-channel track, returns the channel ids property of this source reference, which specifies the channels within that tracks that are referenced. This optional property is omitted to indicate that all channels in the referenced track are referenced in the same order.

      The number of channel ids shall equal the number of channels being described the track containing the source reference, e.g. 1 element for a mono audio track, 6 elements for a 5.1 multi-channel audio track.

      Returns:
        Array of channel ids for this source reference.
      Throws:
        `PropertyNotPresentException` - The optional channel ids property is not present in this source reference.

    - #### getChannelIDsSize

          @UInt32
          int getChannelIDsSize()
                                 throws PropertyNotPresentException

      Returns the number of elements of the channel ids array of this source reference. For references to a multi-channel track, the channel ids property specifies the channels within the tracks that are referenced. This is an optional property.

      Returns:
        Number of elements of the channel ids array of the source reference.
      Throws:
        `PropertyNotPresentException` - The optional channel ids property is not present in this source reference.

    - #### setMonoSourceTrackIDs

          void setMonoSourceTrackIDs(@UInt32
                                     int[] monoSourceTrackIDs)

      For references from a multi-channel track to multiple mono tracks, sets the mono source track ids property of this source reference, which specifies multiple mono tracks that are referenced. Set this optional property to `null` to omit it and specify that this is a single-channel reference.

      The number of elements in the mono source track ids array shall equal the number of channels being described by the track containing this source reference, e.g. 6 elements for a 5.1 multi-channel audio track.

      Parameters:
        `monoSourceTrackIDs` - Array of mono source track ids for this source reference.

    - #### getMonoSourceTrackIDs

          @UInt32
          int[] getMonoSourceTrackIDs()
                                       throws PropertyNotPresentException

      For references from a multi-channel track to multiple mono tracks, returns the mono source track ids property of this source reference, which specifies multiple mono tracks that are referenced. This is an optional property that is omitted to specify that this is a single-channel reference.

      The number of elements in the mono source track ids array shall equal the number of channels being described by the track containing this source reference, e.g. 6 elements for a 5.1 multi-channel audio track.

      Returns:
        Array of mono source track ids of this source reference.
      Throws:
        `PropertyNotPresentException` - This optional mono source track ids property is not present in this source reference.

    - #### getMonoSourceTrackIDsSize

          @UInt32
          int getMonoSourceTrackIDsSize()
                                         throws PropertyNotPresentException

      Returns the size of the mono source track ids array. For references from a multi-channel track to multiple mono tracks, the mono source track ids property specifies multiple mono tracks that are referenced. This is an optional property.

      Returns:
        Size of the mono source track ids array.
      Throws:
        `PropertyNotPresentException` - The optional mono source track ids property is not present for this source reference.

    - #### clone

          SourceReferenceSegment clone()

      Create a cloned copy of this source reference segment.

      Specified by:
        `clone` in interface `Component`
      Specified by:
        `clone` in interface `InterchangeObject`
      Specified by:
        `clone` in interface `MediaEntity`
      Specified by:
        `clone` in interface `Segment`
      Returns:
        Cloned copy of this source reference segment.

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