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

tv.amwa.maj.record

## Interface TimecodeValue

- All Superinterfaces:
    Comparable<TimecodeValue>
  All Known Implementing Classes:
    TimecodeValueImpl

      public interface TimecodeValue
      extends Comparable<TimecodeValue>

  Specifies videotape or audio tape timecode information. The timecode interface is capable of representing timecode values specified by SMPTE 12M.

  To make values of this type, use the following methods from the MAJ forge:

  - From its underlying component parts of frame count, frames per second and drop frame flag: `Forge.makeTimecode(long, short, boolean)`;
  - Calculated from the SMPTE 12M component values: `Forge.calculateTimecode(short, short, short, short, short, boolean)`;
  - Duration calculated from SOM and EOM timecodes: `Forge.calculateDuration(TimecodeValue, TimecodeValue)`;>
  - End timecode calculated from SOM and duration: `Forge.calculateEndTimecode(TimecodeValue, TimecodeValue)`;
  - From a string representation as generated by `toString()`: `Forge.parseTimecode(String)`.
  See Also:
    `TimecodeSegment`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `TimecodeValue` | `clone()` Create a cloned copy of this timecode value.
    `int` | `compareTo(TimecodeValue o)` Chronologically compare this timecode value to another one based on real time, which is calculated to take account of frames per second and drop frame values.
    `TimeStruct` | `convertToRealTime()` Converts the timecode value to a real time, taking account of the frames per second and drop frame values.
    `boolean` | `getDropFrame()` Determines whether the timecode is drop (`true` value) or nondrop (`false` value).
    `short` | `getFramesPerSecond()` Returns the frames per second of the videotape or audio tape of the timecode.
    `long` | `getStartTimecode()` Returns the timecode value by the number of frames offset from the start of the video or audio.
    `void` | `setDropFrame(boolean dropFrame)` Sets whether the timecode is drop (`true` value) or nondrop (`false` value).
    `void` | `setFramesPerSecond(short framesPerSecond)` Sets the frames per second of the videotape or audio tape of the timecode.
    `void` | `setStartTimecode(long offsetFrame)` Sets the timecode value by the number of frames offset from the start of the video or audio.
    `String` | `toString()` Formats a timecode value representation in accordance with the SMPTE and EBU specifications.

- - ### Method Detail

    - #### getDropFrame

          boolean getDropFrame()

      Determines whether the timecode is drop (`true` value) or nondrop (`false` value).

      If drop is set to `true`, the real frames-per-second rate represented by the timecode is 29.97. Calculations of the real time represented by a timecode or to create a textual representation of the time code drop 108 selected frames per hour.

      Returns:
        Is the timecode a drop value?

    - #### setDropFrame

          void setDropFrame(boolean dropFrame)

      Sets whether the timecode is drop (`true` value) or nondrop (`false` value).

      Parameters:
        `dropFrame` - Is the timecode a drop value?

    - #### getFramesPerSecond

          @UInt16
          short getFramesPerSecond()

      Returns the frames per second of the videotape or audio tape of the timecode.

      Returns:
        Frames per second of the videotape or audiotape of the timecode.

    - #### setFramesPerSecond

          void setFramesPerSecond(@UInt16
                                  short framesPerSecond)

      Sets the frames per second of the videotape or audio tape of the timecode.

      Parameters:
        `framesPerSecond` - Frames per second of the videotape or audiotape of the timecode.

    - #### getStartTimecode

          @FrameOffset
          long getStartTimecode()

      Returns the timecode value by the number of frames offset from the start of the video or audio.

      Returns:
        Timecode offset value.

    - #### setStartTimecode

          void setStartTimecode(@FrameOffset
                                long offsetFrame)

      Sets the timecode value by the number of frames offset from the start of the video or audio.

      Parameters:
        `offsetFrame` - Frame offset value to use to set the timecode.

    - #### convertToRealTime

          TimeStruct convertToRealTime()
                                throws NumberFormatException

      Converts the timecode value to a real time, taking account of the frames per second and drop frame values. The value returned is a `TimeStruct` value, containing the hours, minutes, seconds and fractions of a second represented by the frame offset value returned by `getStartTimecode()`.

      Returns:
        A time value representing the real time offset of the timecode value.
      Throws:
        `NumberFormatException` - The timecode value is larger than the range it is possible to represent with a time structure value.

    - #### compareTo

          int compareTo(TimecodeValue o)
                 throws NullPointerException

      Chronologically compare this timecode value to another one based on real time, which is calculated to take account of frames per second and drop frame values.

      Specified by:
        `compareTo` in interface `Comparable<TimecodeValue>`
      Parameters:
        `o` - Timecode value to compare this value to.
      Returns:
        A value of -1 if this timecode value is less than the given value, 0 if they are equal and 1 if this one is greater than the one given.
      Throws:
        `NullPointerException` - The given timecode value to compare to this one is `null`.

    - #### clone

          TimecodeValue clone()

      Create a cloned copy of this timecode value.

      Returns:
        Cloned copy of this timecode value.

    - #### toString

          String toString()

      Formats a timecode value representation in accordance with the SMPTE and EBU specifications. Specifically:

      - EBU TS N12-1999: "Time-and-control codes for television recording". 1999.
      - SMPTE 0012-2008: "SMPTE standard for television, audio and film - time and control code". February 2008. (Character format from SMPTE 0258-2004).

      The format of the returned value is "`hh:mm:ss;ff(.p)?`" for timecodes with drop frames and "`hh:mm:ss:ff(.p)?`" for timecodes with no drop frame. The components of the value of the timecode are:

      - `hh` is the number of hours
      - `mm` is the number of minutes;
      - `ss` is the number of seconds;
      - `ff` is the number of frames through this second;
      .
      - `(.p)?` for frame rates over 30, whether the frame is the first (`.0`) or second (`.1`) of the pair.
      Overrides:
        `toString` in class `Object`
      Returns:
        String representation of this timecode value.
      See Also:
        `Forge.parseTimecode(String)`

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