Package com.peterphi.std.types

Class Timecode

java.lang.Object
com.peterphi.std.types.Timecode
public class Timecode extends Object
Represents a timecode, dd:hh:mm:ss:ff - where ff may be an arbitrary length
Timecodes containing days are not well supported.

  • Method Details

    • builder

      public TimecodeBuilder builder()
      Return a TimecodeBuilder for this Timecode instance
      Returns:
      a TimecodeBuilder pre-populated with this timecode

    • getDurationInFrames

      public long getDurationInFrames()
      Returns the duration of the timecode (from 00:00:00:00) in frames
      Returns:

    • getDurationInFrames

      public long getDurationInFrames(boolean allowDropFrameRemoval)
      Returns the duration of the timecode (from 00:00:00:00) in frames
      Returns:

    • getDurationInSeconds

      public long getDurationInSeconds()
      Returns the duration of the timecode in seconds (from 00:00:00:00), ignoring frames

    • getFramesPartAsMicroseconds

      public long getFramesPartAsMicroseconds()
      Get the frames part of this timecode in microseconds
      Returns:

    • getFramesPartAsMilliseconds

      public long getFramesPartAsMilliseconds()
      Get the frames part of this timecode in milliseconds
      Returns:

    • isDropFrame

      public boolean isDropFrame()

    • isNegative

      public boolean isNegative()

    • getFramesPart

      public long getFramesPart()

    • getSecondsPart

      public long getSecondsPart()

    • getMinutesPart

      public long getMinutesPart()

    • getHoursPart

      public long getHoursPart()

    • getDaysPart

      public long getDaysPart()

    • getTimebase

      public Timebase getTimebase()

    • toSMPTEString

      public String toSMPTEString()
      Return a SMPTE string of the format, dropping the days component.
      Returns:
      [-]hh:mm:ss:ff (or [-]hh:mm:ss;ff for drop-frame timecode)

    • toSMPTEString

      public String toSMPTEString(boolean includeDays)
      Return a SMPTE-style string of the format [-][dd:]hh:mm:ss:ff (or [-][dd:]hh:mm:ss;ff for drop-frame timecode)
      Parameters:
      includeDays - if true (and this timecode has a days component), emit a timecode with a days field. If false then the days component will be ignored
      Returns:

    • toFfmpegString

      public String toFfmpegString()
      Returns the timecode in FFmpeg format. The format of the timecode is hh:mm:ss:uuuuuu (where u = microseconds). The hours component counts days as well (i.e. 01:01:01:01:00 will be encoded as 25:01:01.000000)

    • toISODurationWithFrames

      public String toISODurationWithFrames(boolean includeDays)
      Returns the timecode in a format that is similar to the ISO 8601 Duration format, except with an F field for frames.
      Returns:

    • toEncodedString

      public String toEncodedString()
      Returns the timecode in the Encoded Timecode format for this library. The format of this timecode is smpte timecode including days@rate where rate is denominator:[numerator] (where numerator, if omitted, is 1). See Timebase for further information on the encoding of the timebase
      Returns:

    • toEncodedString

      public String toEncodedString(boolean includeDays)
      Returns the timecode in the Encoded Timecode format for this library. The format of this timecode is smpte timecode optionally including days@rate where rate is denominator:[numerator] (where numerator, if omitted, is 1). See Timebase for further information on the encoding of the timebase
      Parameters:
      includeDays - true if the days component should be emitted too (if non-zero)
      Returns:

    • toVidispineString

      @Deprecated public String toVidispineString()
      Deprecated.
      use getSampleCount().toEncodedString();
      Returns the timecode in the Vidispine Timecode format. The format of this timecode is frames@rate where rate is denominator:[numerator] (where numerator, if omitted, is 1)
      Returns:

    • between

      public boolean between(Timecode start, Timecode end)

    • eq

      public boolean eq(Timecode that)

    • gt

      public boolean gt(Timecode that)

    • lt

      public boolean lt(Timecode that)

    • le

      public boolean le(Timecode that)

    • ge

      public boolean ge(Timecode that)

    • subtract

      public Timecode subtract(SampleCount samples)
      Subtract some samples from this timecode
      Parameters:
      samples -
      Returns:

    • add

      public Timecode add(SampleCount samples)
      Add some samples to this timecode
      Parameters:
      samples -
      Returns:

    • addPrecise

      public Timecode addPrecise(SampleCount samples) throws ResamplingException
      Add some samples to this timecode, throwing an exception if precision would be lost
      Parameters:
      samples -
      Returns:
      Throws:
      ResamplingException - if the requested addition would result in a loss of accuracy due to resampling

    • getSampleCount

      public SampleCount getSampleCount()
      Returns a sample count as a delta from the timecode 00:00:00:00
      Returns:

    • getSampleCount

      public SampleCount getSampleCount(Timecode from)
      Returns a sample count as an offset from the provided timecode
      The resulting timecode will be expressed in the same timebase as this object
      Parameters:
      from - the start timecode
      Returns:
      a SampleCount expressing the delta between from and this
      Throws:
      ResamplingException - if the delta cannot be expressed without losing accuracy

    • getSampleCountPrecise

      public SampleCount getSampleCountPrecise(Timecode from) throws ResamplingException
      Returns a sample count as an offset from the provided timecode
      The resulting timecode will be expressed in the same timebase as this object
      Parameters:
      from - the start timecode
      Returns:
      a SampleCount expressing the delta between from and this
      Throws:
      ResamplingException - if the delta cannot be expressed without losing accuracy

    • resample

      public Timecode resample(Timebase toRate)
      Resample this timecode to another timebase. If the destination rate is NTSC (29.97) or NTSC_60 (59.94) then it will be resampled to a drop-frame Timecode
      Parameters:
      toRate - the destination rate
      Returns:

    • resample

      public Timecode resample(Timebase toRate, boolean toDropFrame)
      Resample this timecode to another timebase.
      • If source+destination timecodes are non-drop frame then this is achieved by resampling the frames part of the timecode.
      • If either side uses drop-frame then the resample works by converting this timecode into an amount of time (with half-up rounding rules, see Timebase.resample(double, Timebase, Timebase))
      Parameters:
      toRate - the destination rate
      toDropFrame - if true, resulting Timecode will be marked as drop-frame (N.B. this flag will be checked against canBeDropFrame on the timebase - so if it's not 29.97 or 59.94 then it'll throw an exception
      Returns:
      a Timecode expressed in toRate
      Throws:
      IllegalArgumentException - if toDropFrame is set to true but toRate is not on the approved drop-frame list (NTSC and NTSC_60)

    • resamplePrecise

      public Timecode resamplePrecise(Timebase toRate) throws ResamplingException
      Resamples
      Parameters:
      toRate -
      Returns:
      Throws:
      ResamplingException

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Returns the timecode as a String, formatted as either:
      • hh:mm:ss:ff for non-dropframe timecode (where ff is of arbitrary length)
      • hh:mm:ss;ff for dropframe timecode (where ff is of arbitrary length)
      Overrides:
      toString in class Object

    • getInstance

      public static final Timecode getInstance(long frameNumber, boolean dropFrame, Timebase timebase)
      Parameters:
      frameNumber -
      dropFrame - set to true to indicate that the frame-rate excludes dropframes
      timebase -
      Returns:
      a timecode representation of the given data, null when a timecode can not be generated (i.e. duration exceeds a day)

    • getInstance

      public static final Timecode getInstance(SampleCount samples)

    • getInstance

      public static final Timecode getInstance(SampleCount samples, boolean dropFrame)
      Parameters:
      samples -
      dropFrame -
      Returns:

    • getInstance

      @Deprecated public static final Timecode getInstance(SampleCount samples, boolean dropFrame, boolean supportDays)
      Deprecated.
      use method without supportDays (supportDays is now implicitly true) or dropFrame (drop frame timecode is not correctly supported currently)
      Parameters:
      samples -
      dropFrame -
      supportDays -
      Returns:

    • getInstance

      public static final Timecode getInstance(String encoded)
      Parse a Timecode encoded in the encoded style for this library ([-][dd:]hh:mm:ss:ff@timebase). See Timebase.getInstance(java.lang.String) for information on valid timebase representations
      Parameters:
      encoded - a timecode encoded as hh:mm:ss:ff@timebase
      Returns:
      a parsed timecode object
      Throws:
      RuntimeException - if the encoded string is not well-formed or could not be parsed

    • valueOf

      public static final Timecode valueOf(String encoded)
      Parse a Timecode encoded in the encoded style for this library ([-][dd:]hh:mm:ss:ff@timebase). See Timebase.getInstance(java.lang.String) for information on valid timebase representations
      Parameters:
      encoded - a timecode encoded as hh:mm:ss:ff@timebase
      Returns:
      a parsed timecode object (or null if the input is null)
      Throws:
      RuntimeException - if the encoded string is not well-formed or could not be parsed

    • getSmpteTimecode

      @Deprecated public static final Timecode getSmpteTimecode(String smpte, Timebase timebase)
      Deprecated.
      Part an SMPTE formatted timecode ([-][dd:]hh:mm:ss:ff -or [-][dd:]hh:mm:ss;ff for drop-frame timecode alongside a timebase
      Parameters:
      smpte -
      timebase -
      Returns:

    • getInstance

      public static final Timecode getInstance(String smpte, Timebase timebase)
      Part a Timecode encoded in the SMPTE style ([dd:]hh:mm:ss:ff - or [dd:]hh:mm:ss;ff for drop-frame timecode) alongside a timebase.
      Parameters:
      smpte - the SMPTE-encoded timecode
      timebase - the timebase to interpret the SMPTE timecode in
      Returns:
      a parsed timecode object
      Throws:
      RuntimeException - if parsing fails

    • getInstance

      @Deprecated public static final Timecode getInstance(long frameNumber, boolean dropFrame, Timebase timebase, boolean supportDays)
      Deprecated.
      use method without supportDays
      Parameters:
      frameNumber - the frame offset from zero
      dropFrame - set to true to indicate that the frame-rate excludes dropframes (keep false for PAL)
      timebase - the timebase
      supportDays - true if the resulting Timecode may use the days field (default false)
      Returns:
      a timecode representation of the given data, null when a timecode can not be generated (i.e. duration exceeds a day)