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

tv.amwa.maj.model

## Interface TimecodeStream

- All Superinterfaces:
    Component, InterchangeObject, MediaEntity, MetadataObject, Segment
  All Known Subinterfaces:
    TimecodeStream12M
  All Known Implementing Classes:
    TimecodeStream12MImpl, TimecodeStreamImpl

      public interface TimecodeStream
      extends Segment

  Specifies a stream of timecode data.

  In contrast to a timecode stream, a timecode specifies timecode by specifying the single starting timecode value; other timecode values are calculated from the starting timecode and the time offset.

  See Also:
    `Segment.segmentOffsetToTC(long)`, `Segment.segmentTCToOffset(TimecodeValue, Rational)`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `TimecodeStream` | `clone()` Create a cloned copy of this timecode stream.
    `TimecodeValue` | `getPositionTimecode(long position)` Returns the timecode value for a given frame of this timecode stream.
    `int` | `getSampleSize()` Returns the size of one sample of the timecode data of this timecode stream, measured in bytes.
    `long` | `getSourceBufferLength()` Returns the length of the timecode stream buffer contained within the timecode stream object.
    `TCSource` | `getTimecodeSource()` Returns the kind of timecode of this timecode stream, which is one of LTC or VITC.
    `Stream` | `getTimecodeStreamData()` Returns the data buffer containing the stream of timecode data of this timecode stream.
    `Rational` | `getTimecodeStreamSampleRate()` Returns the sample rate of the timecode stream, which specifies the sample rate of the timecode data contained in the source property.
    `ByteBuffer` | `getUserDataAtPosition(long position)` Returns the user data (user-bits) for a particular frame of this timecode stream.
    `int` | `getUserDataLength()` Returns the length of user data for one frame of this timecode stream.
    `void` | `setPositionTimecode(long position, TimecodeValue timecode)` Sets the timecode value for a given frame of this timecode stream.
    `void` | `setTimecodeSource(TCSource sourceType)` Sets the kind of timecode of this timecode stream, which is one of LTC or VITC.
    `void` | `setTimecodeStreamData(Stream timecodeStreamData)` Sets the data buffer containing the stream of timecode data of this timecode stream.
    `void` | `setTimecodeStreamSampleRate(Rational sampleRate)` Sets the sample rate of this timecode stream, which specifies the sample rate of the timecode data contained in the source property.
    `void` | `setUserDataAtPosition(long position, ByteBuffer buffer)` Sets the user data (userbits) for a particular frame of the timecode stream.

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

    - #### getPositionTimecode

          TimecodeValue getPositionTimecode(@PositionType
                                            long position)
                                     throws PositionOutOfRangeException,
                                            IOException

      Returns the timecode value for a given frame of this timecode stream. The frame index must be within the length of the stream.

      Parameters:
        `position` - Frame to find the timecode value for from the timecode stream.
      Returns:
        Timecode value at the given frame from the timecode stream.
      Throws:
        `PositionOutOfRangeException` - Frame index is outside the length of this timecode stream.
        `IOException` - Error occurred when trying to access data from the underlying stream.

    - #### setPositionTimecode

          void setPositionTimecode(@PositionType
                                   long position,
                                   TimecodeValue timecode)
                            throws NullPointerException,
                                   PositionOutOfRangeException,
                                   IOException

      Sets the timecode value for a given frame of this timecode stream. The frame index must be within the length of the stream.

      Parameters:
        `position` - Zero-based offset to set the timecode value at.
        `timecode` - Timecode value to set at the given frame for the timecode stream.
      Throws:
        `NullPointerException` - The given timecode value is `null`.
        `PositionOutOfRangeException` - Frame index is outside the length of the stream.
        `IOException` - Error occurred when trying to write data to the underlying stream.

    - #### getUserDataLength

          @Int32
          int getUserDataLength()

      Returns the length of user data for one frame of this timecode stream.

      Returns:
        Length of user data for one frame of this timecode stream.
      See Also:
        `getUserDataAtPosition(long)`

    - #### getUserDataAtPosition

          @DataBuffer
          ByteBuffer getUserDataAtPosition(@PositionType
                                                       long position)
                                                throws PositionOutOfRangeException,
                                                       IOException

      Returns the user data (user-bits) for a particular frame of this timecode stream.

      Parameters:
        `position` - Zero-based index to the frame to get the user bits from.
      Returns:
        User-bits from the timecode data for this given frame.
      Throws:
        `PositionOutOfRangeException` - The given user data is outside the acceptable range for this timecode stream.
        `IOException` - Error occurred when trying to read from the underlying stream.
        `PositionOutOfRangeException` - The given user data position is out of range for the timecode stream.
      See Also:
        `getUserDataLength()`

    - #### setUserDataAtPosition

          void setUserDataAtPosition(@PositionType
                                     long position,
                                     @DataBuffer
                                     ByteBuffer buffer)
                              throws NullPointerException,
                                     PositionOutOfRangeException,
                                     IOException

      Sets the user data (userbits) for a particular frame of the timecode stream.

      Parameters:
        `position` - Zero-based offset to the userbits to set.
        `buffer` - User data for the specified frame.
      Throws:
        `NullPointerException` - The given user data buffer is `null`.
        `PositionOutOfRangeException` - The given user data is outside the acceptable range for this timecode stream.
        `IOException` - Error occurred when trying to access date from the underlying stream.

    - #### setTimecodeStreamSampleRate

          void setTimecodeStreamSampleRate(Rational sampleRate)

      Sets the sample rate of this timecode stream, which specifies the sample rate of the timecode data contained in the source property.

      Parameters:
        `sampleRate` - Sample rate of this timecode stream.

    - #### getTimecodeStreamSampleRate

          Rational getTimecodeStreamSampleRate()

      Returns the sample rate of the timecode stream, which specifies the sample rate of the timecode data contained in the source property.

      Returns:
        Sample rate of this timecode stream.

    - #### setTimecodeSource

          void setTimecodeSource(TCSource sourceType)

      Sets the kind of timecode of this timecode stream, which is one of LTC or VITC.

      Parameters:
        `sourceType` - Kind of timecode of this timecode stream.

    - #### getTimecodeSource

          TCSource getTimecodeSource()

      Returns the kind of timecode of this timecode stream, which is one of LTC or VITC.

      Returns:
        Kind of timecode of this timecode stream.

    - #### getSampleSize

          @UInt32
          int getSampleSize()

      Returns the size of one sample of the timecode data of this timecode stream, measured in bytes.

      Returns:
        Size of one sample of the timecode data of this timecode stream.

    - #### getTimecodeStreamData

          @DataBuffer
          Stream getTimecodeStreamData()

      Returns the data buffer containing the stream of timecode data of this timecode stream.

      Returns:
        Stream of timecode data stored in this timecode stream.
      See Also:
        `getTimecodeStreamSampleRate()`

    - #### getSourceBufferLength

          @UInt32
          long getSourceBufferLength()
                                      throws IOException

      Returns the length of the timecode stream buffer contained within the timecode stream object. This is the size of the buffer and not the number of timecode entries in the stream.

      Returns:
        Length of the timecode stream buffer contained within the timecode stream object.
      Throws:
        `IOException` - Cannot access the underlying stream to determine the length.
      See Also:
        `getTimecodeStreamData()`

    - #### setTimecodeStreamData

          void setTimecodeStreamData(@DataBuffer
                                     Stream timecodeStreamData)
                              throws NullPointerException

      Sets the data buffer containing the stream of timecode data of this timecode stream.

      Parameters:
        `timecodeStreamData` - Stream of timecode data to store in this timecode stream.
      Throws:
        `NullPointerException` - The given timecode stream source property is `null`.
      See Also:
        `setTimecodeStreamSampleRate(Rational)`

    - #### clone

          TimecodeStream clone()

      Create a cloned copy of this timecode stream.

      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 timecode stream.

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