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 Summary

Modifier and Type	Method and Description
Timecode	add(SampleCount samples) Add some samples to this timecode
Timecode	addPrecise(SampleCount samples) Add some samples to this timecode, throwing an exception if precision would be lost
boolean	between(Timecode start, Timecode end)
TimecodeBuilder	builder() Return a TimecodeBuilder for this Timecode instance
boolean	eq(Timecode that)
boolean	equals(Object o)
boolean	ge(Timecode that)
long	getDaysPart()
long	getDurationInFrames() Returns the duration of the timecode (from 00:00:00:00) in frames
long	getDurationInFrames(boolean allowDropFrameRemoval) Returns the duration of the timecode (from 00:00:00:00) in frames
long	getDurationInSeconds() Returns the duration of the timecode in seconds (from 00:00:00:00), ignoring frames
long	getFramesPart()
long	getFramesPartAsMicroseconds() Get the frames part of this timecode in microseconds
long	getFramesPartAsMilliseconds() Get the frames part of this timecode in milliseconds
long	getHoursPart()
static Timecode	getInstance(long frameNumber, boolean dropFrame, Timebase timebase)
static Timecode	getInstance(long frameNumber, boolean dropFrame, Timebase timebase, boolean supportDays) Deprecated. use method without supportDays
static Timecode	getInstance(SampleCount samples)
static Timecode	getInstance(SampleCount samples, boolean dropFrame) Deprecated. drop frame timecode is not correctly supported currently
static 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)
static Timecode	getInstance(String encoded) Parse a Timecode encoded in the encoded style for this library ([-][dd:]hh:mm:ss:ff@timebase).
static 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.
long	getMinutesPart()
SampleCount	getSampleCount() Returns a sample count as a delta from the timecode 00:00:00:00
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
SampleCount	getSampleCountPrecise(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
long	getSecondsPart()
static Timecode	getSmpteTimecode(String smpte, Timebase timebase) Deprecated.
Timebase	getTimebase()
boolean	gt(Timecode that)
int	hashCode()
boolean	isDropFrame()
boolean	isNegative()
boolean	le(Timecode that)
boolean	lt(Timecode that)
Timecode	resample(Timebase toRate) Resample this timecode to another timebase
Timecode	resamplePrecise(Timebase toRate) Resamples
Timecode	subtract(SampleCount samples) Subtract some samples from this timecode
String	toEncodedString() Returns the timecode in the Encoded Timecode format for this library.
String	toEncodedString(boolean includeDays) Returns the timecode in the Encoded Timecode format for this library.
String	toFfmpegString() Returns the timecode in FFmpeg format.
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.
String	toSMPTEString() Return a SMPTE string of the format, dropping the days component.
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)
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)
String	toVidispineString() Deprecated. use getSampleCount().toEncodedString();
static Timecode	valueOf(String encoded) Parse a Timecode encoded in the encoded style for this library ([-][dd:]hh:mm:ss:ff@timebase).

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Detail

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

Parameters:

toRate - the destination rate

Returns:

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

@Deprecated
public static final Timecode getInstance(SampleCount samples,
                                                     boolean dropFrame)

Deprecated. drop frame timecode is not correctly supported currently

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)