tv.amwa.maj.embeddable
Class TimecodeValue

java.lang.Object
  tv.amwa.maj.embeddable.TimecodeValue

All Implemented Interfaces:

Serializable, Cloneable, Comparable<TimecodeValue>, MAJCommon, XMLSerializable, TimecodeValue

public final class TimecodeValue
extends Object
implements TimecodeValue, Serializable, XMLSerializable, Comparable<TimecodeValue>, Cloneable, MAJCommon

Implementation of a value that represents video tape or audio tape timecode information. The timecode interface is capable of representing timecode values specified by SMPTE 12M.

Representation of timecode values based on a frame offset from the start of an item of content. This class also models the number of frames per second associated with a timecode value and whether the timecode requires the calculation of drop frames.

All methods that operate on the timecode value, such as compareTo(tv.amwa.maj.record.TimecodeValue), toString() and convertToRealTime() respect the number of frames-per-second and drop frame values. See the method descriptions for more details.

This implementation can support high frame rate television. In this case, timecode values will format in a way that is not compatible with SMPTE 12M. For example, a timecode value of 00:00:21:135 represents the 135th frame of the frame 21 seconds into a 300 fps item, frame 6435.

TODO insert database representation?

Author:

Richard Cartwright

See Also:

TimecodeSegment.getTimecode(), TimecodeSegment, Serialized Form

Nested Class Summary

class

TimecodeValue.TimeComponents Component parts of a timecode value, represented as hours, minutes, seconds and frames in a second.

Field Summary

static String	DROP_TAG
static String	FPS_TAG
static String	TIMECODESTART_TAG
static String	TIMECODEVALUE_TAG

Constructor Summary

TimecodeValue()
Create a default timecode value.

TimecodeValue(boolean drop, long startFrame, short fps)
Create a timecode value.

TimecodeValue(short fps, short hours, short minutes, short seconds, short frames, boolean drop)
Create a new timecode value from the given hours, minutes, seconds and frames according to the given number of frames per second and whether the timecode value requires drop frame calculations.

Method Summary

void	appendXMLChildren(Node parent) Append child elements to the given parent node to serialize the value of an object to an XML fragment.
void	appendXMLGrandchildren(Node timecodeElement) Append just the child elements specifying the value of this timecode to the given node.
static TimecodeValue	calculateDuration(TimecodeValue startValue, TimecodeValue endValue) Calculate the duration of a piece of media from its start timecode and end timecode.
static TimecodeValue	calculateEndTimecode(TimecodeValue startValue, TimecodeValue duration) Calculate the end timecode for a segment of media from its start timecode and a timecode value representing its duration.
static TimecodeValue	castFromInterface(TimecodeValue alien) Cast a value the implements the TimecodeValue interface to concrete value of this implementation.
TimecodeValue	clone() Creates a cloned deep copy of this embeddable 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.
TimecodeValue.TimeComponents	convertToActualTimeValues() Converts this timecode into a TimecodeValue.TimeComponents value.
TimeStruct	convertToRealTime() Converts the timecode value to a real time, taking account of the frames per second and drop frame values.
boolean	equals(Object o) Check to see if another timecode value is equal to this one.
boolean	getDrop() Determines whether the timecode is drop (true value) or nondrop (false value).
short	getFps() Returns the frames per second of the videotape or audio tape of the timecode.
long	getStartOffset() Returns the timecode value by the number of frames offset from the start of the video or audio.
int	hashCode() Returns a hash code value for this embeddable object.
static TimecodeValue	parseTimecode(String timecodeText) Parses a SMPTE-style string representation of a timecode and creates a MAJ API timecode value, implying default values for the frames per second and drop frame parameters from the timecode text.
static TimecodeValue	parseTimecode(String timecodeText, short fps) Parses a SMPTE-style string representation of a timecode and creates a MAJ API timecode value, working out the drop frame value from the given timcode text.
static TimecodeValue	parseTimecode(String timecodeText, short fps, boolean drop) Parses a SMPTE-style string representation of a timecode and creates a MAJ API timecode value, with all parameters specified.
void	setDrop(boolean drop) Sets whether the timecode is drop (true value) or nondrop (false value).
void	setFps(short fps) Sets the frames per second of the videotape or audio tape of the timecode.
void	setPropertiesFromInterface(TimecodeValue castFrom) Set the properties of this value from another value that implements that implements the TimecodeValue interface.
void	setStartOffset(long startFrame) Sets the timecode value by the number of frames offset from the start of the video or audio.
String	toString() Converts this string to a timecode value representation in accordance with the following timecode specifications:

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

TIMECODEVALUE_TAG

public static final String TIMECODEVALUE_TAG

See Also:

Constant Field Values

TIMECODESTART_TAG

public static final String TIMECODESTART_TAG

See Also:

Constant Field Values

FPS_TAG

public static final String FPS_TAG

See Also:

Constant Field Values

DROP_TAG

public static final String DROP_TAG

See Also:

Constant Field Values

Constructor Detail

TimecodeValue

public TimecodeValue(boolean drop,
                     @FrameOffset
                     long startFrame,
                     @UInt16
                     short fps)
              throws IllegalArgumentException

Create a timecode value.

Parameters:

drop - Indicates whether the timecode is drop (True value) or nondrop (False value).

startFrame - Specifies the timecode as the number of frames offset from the start of the video or audio.

fps - Frames per second of the videotape or audio tape.

Throws:

IllegalArgumentException - The frames per second value is not a positive value.

TimecodeValue

public TimecodeValue()

Create a default timecode value. Default values are non-drop, start frame set to 0 and frame rate of 0 frames per second.

TimecodeValue

public TimecodeValue(@UInt16
                     short fps,
                     short hours,
                     short minutes,
                     short seconds,
                     short frames,
                     boolean drop)
              throws IllegalArgumentException

Create a new timecode value from the given hours, minutes, seconds and frames according to the given number of frames per second and whether the timecode value requires drop frame calculations. Internally, these values are converted to an offset value.

This method does not apply strict boundaries. Negative values and values greater than the acceptable bounds when displaying a timecode will be accepted and mapped to an appropriate offset. For example, the following three calls to this method create equivalent timecode values:

 time1 = new TimecodeValue(25, 0, 0, 63,   0, false);
 time2 = new TimecodeValue(25, 0, 1, 03,   0, false);
 time3 = new TimecodeValue(25, 0, 1, 04, -25, false);
 

Parameters:

fps - Number of frames per second for this timecode value.

hours - Number of hours since the start of an item represented by this timecode.

minutes - Number of minutes in the hour of an item represented by this timecode.

seconds - Number of seconds in the minute of an item represented by this timecode.

frames - Number of frames through the second of an item represented by this timecode.

drop - Does this timecode require drop frame calculation?

Throws:

IllegalArgumentException - The number of frames per second is not a positive (greater than zero) number.

Method Detail

castFromInterface

public static TimecodeValue castFromInterface(TimecodeValue alien)
                                       throws NullPointerException

Cast a value the implements the TimecodeValue interface to concrete value of this implementation.

Parameters:

alien - Value to cast to a concrete instance.

Returns:

Concrete version of the given interface.

Throws:

NullPointerException - Argument is null.

setPropertiesFromInterface

public final void setPropertiesFromInterface(TimecodeValue castFrom)

Set the properties of this value from another value that implements that implements the TimecodeValue interface.

Parameters:

castFrom - Value to use to set this timecode value.

getDrop

public boolean getDrop()

Description copied from interface: TimecodeValue

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.

Specified by:

getDrop in interface TimecodeValue

Returns:

Is the timecode a drop value?

setDrop

public void setDrop(boolean drop)

Description copied from interface: TimecodeValue

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

Specified by:

setDrop in interface TimecodeValue

Parameters:

drop - Is the timecode a drop value?

getFps

public short getFps()

Description copied from interface: TimecodeValue

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

Specified by:

getFps in interface TimecodeValue

Returns:

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

setFps

public void setFps(short fps)

Description copied from interface: TimecodeValue

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

Specified by:

setFps in interface TimecodeValue

Parameters:

fps - Frames per second of the videotape or audiotape of the timecode.

getStartOffset

public long getStartOffset()

Description copied from interface: TimecodeValue

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

Specified by:

getStartOffset in interface TimecodeValue

Returns:

Timecode offset value.

setStartOffset

public void setStartOffset(long startFrame)

Description copied from interface: TimecodeValue

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

Specified by:

setStartOffset in interface TimecodeValue

Parameters:

startFrame - Frame offset value to use to set the timecode.

hashCode

public int hashCode()

Description copied from interface: MAJCommon

Returns a hash code value for this embeddable object.

Specified by:

hashCode in interface MAJCommon

Overrides:

hashCode in class Object

Returns:

Hash code value for this embeddable object.

See Also:

Object.hashCode()

equals

public final boolean equals(Object o)

Check to see if another timecode value is equal to this one. Two timecode values are equal if they have the same start frame, number of frames per second and consistent drop frame or non-drop frame values.

To check to see if two timecode values are equal in time, use compareTo(tv.amwa.maj.record.TimecodeValue).

Specified by:

equals in interface MAJCommon

Overrides:

equals in class Object

Parameters:

o - Object to test for equality with this one.

Returns:

Is the given object equals to this value?

See Also:

Object.equals(Object)

compareTo

public final 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.

toString

public String toString()

Converts this string to a timecode value representation in accordance with the following timecode specifications:

• EBU TS N12-1999: "Time-and-control codes for television recording". 1999.
• ANSI/SMPTE 12M-1986: "SMPTE standard for television, audio and film - time and control code". September 1999.

The format of the returned value is "hh:mm:ss;ff" for timecodes with drop frames and "hh:mm:ss:ff" for timecodes with no drop frame. The componest 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.

For high frame rate television, the number of frames throgh a second may extend to "fff" when the value is greater than 99.

Specified by:

toString in interface MAJCommon

Overrides:

toString in class Object

Returns:

String representation of this timecode value.

See Also:

Object.toString()

convertToRealTime

public 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 getStartOffset().

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.

parseTimecode

public static final TimecodeValue parseTimecode(String timecodeText,
                                                @UInt16
                                                short fps,
                                                boolean drop)
                                         throws NumberFormatException,
                                                IllegalArgumentException

Parses a SMPTE-style string representation of a timecode and creates a MAJ API timecode value, with all parameters specified. The method will try and parse both drop and non-drop values, working with both SMPTE-12M values and a broader definition of timecodes as required for high frame rate television.

The format of a timecode parsed by this method is:

<hour>:<minute>:<second>:<frame>

The hour, minute, second and frame values should all be Java short values. The number of digits is not significant, although values are limited to being Int16. For example, the values "01:02:03:04" is parsed the same as "1:2:003:4".

Parameters:

timecodeText - String representation of a timecode value.

fps - Number of frames per second this timecode is measured against.

drop - Whether this timecode has drop values or not?

Returns:

A timecode value created by parsing the given textual representation.

Throws:

NumberFormatException - It is not possible to parse the given value to a MAJ API timecode value.

IllegalArgumentException - The given frames per second value is not a negative value.

parseTimecode

public static final TimecodeValue parseTimecode(String timecodeText,
                                                @UInt16
                                                short fps)
                                         throws IllegalArgumentException,
                                                NumberFormatException

Parses a SMPTE-style string representation of a timecode and creates a MAJ API timecode value, working out the drop frame value from the given timcode text. The method will try and parse both drop and non-drop values, working with both SMPTE-12M values and a broader definition of timecodes as required for high frame rate television. This method assumes any value with a ";" in it is a drop-frame value; otherwise the value is assumed to be a non-drop timecode.

String timecode representations are parsed as follows:

• The format of a non-drop timecode specified by frame is:
  <hour>:<minute>:<second>:<frame>
• The format of a drop timecode specified by frame is:
  <hour>:<minute>:<second>;<frame>

The hour, minute, second and frame values should all be Java short values. The number of digits is not significant, although values are limited to being Int16. For example, the values "01:02:03:04" is parsed the same as "1:2:003:4".

Parameters:

timecodeText - String representation of a timecode value.

fps - Number of frames per second this timecode is measured against.

Returns:

A timecode value created by parsing the given textual representation.

Throws:

NumberFormatException - It is not possible to parse the given value to a MAJ API timecode value.

IllegalArgumentException - The given frames per second value is not a negative value.

parseTimecode

public static final TimecodeValue parseTimecode(String timecodeText)
                                         throws IllegalArgumentException,
                                                NumberFormatException

Parses a SMPTE-style string representation of a timecode and creates a MAJ API timecode value, implying default values for the frames per second and drop frame parameters from the timecode text. The method will try and parse both drop and non-drop values, working with both SMPTE-12M values and a broader definition of timecodes as required for high frame rate television. This method assumes any value with a ";" in it is a drop-frame value at 30 fps; otherwise the value is assumed to be a non-drop timecode at 25 fps.

String timecode representations are parsed as follows:

• The format of a non-drop timecode specified by frame is:
  <hour>:<minute>:<second>:<frame>
• The format of a drop timecode specified by frame is:
  <hour>:<minute>:<second>;<frame>

The hour, minute, second and frame values should all be Java short values. The number of digits is not significant, although values are limited to being Int16. For example, the values "01:02:03:04" is parsed the same as "1:2:003:4".

Parameters:

timecodeText - String representation of a timecode value.

Returns:

A timecode value created by parsing the given textual representation.

Throws:

NumberFormatException - It is not possible to parse the given value to a MAJ API timecode value.

IllegalArgumentException - The given frames per second value is not a negative value.

convertToActualTimeValues

public TimecodeValue.TimeComponents convertToActualTimeValues()

Converts this timecode into a TimecodeValue.TimeComponents value. This method will carry out drop frame calculations if required.

Returns:

Componentized representation of this timecode value.

clone

public final TimecodeValue clone()

Description copied from interface: MAJCommon

Creates a cloned deep copy of this embeddable value. The clone will be initialized to have the same value as this value but exists independently from then on. Changes to this value will not effect the clone and changes to the clone will not effect this. MAJ API clones are true deep clones with no shared references to areas of memory within the original.

This method does not throw a CloneNotSupportedException as all embeddable values must implement the Cloneable interface.

Specified by:

clone in interface MAJCommon

Overrides:

clone in class Object

Returns:

Independent clone of this value, which is a deep copy.

See Also:

Object.clone()

appendXMLChildren

public void appendXMLChildren(Node parent)

Description copied from interface: XMLSerializable

Append child elements to the given parent node to serialize the value of an object to an XML fragment. Methods of the XMLBuilder class are provided to help with this process.

Specified by:

appendXMLChildren in interface XMLSerializable

Parameters:

parent - XML parent element to append child nodes to.

appendXMLGrandchildren

public void appendXMLGrandchildren(Node timecodeElement)

Append just the child elements specifying the value of this timecode to the given node.

Parameters:

timecodeElement - Element to append timecode specifiers to.

calculateDuration

public static final TimecodeValue calculateDuration(TimecodeValue startValue,
                                                    TimecodeValue endValue)
                                             throws IllegalArgumentException

Calculate the duration of a piece of media from its start timecode and end timecode. The value returned is a timecode representing the duration. Both values must be specified with the same number of frames per second and matching drop timecode specifications. The end value must be the same or greater than the start value.

To calculate the number of frames of an item of media, call getStartOffset() on the value returned by this method.

Parameters:

startValue - Start timecode at the beginning of the segment of media, sometimes known as SOM (Start Of Message).

endValue - End timecode at the end of the segment of media, sometimes known as EOM (End Of Message).

Returns:

Duration timecode value calculated as the difference between the end value and the start value.

Throws:

IllegalArgumentException - It was not possible to calculate the duration as the timecode values are incompatible or the start value is after the end value.

See Also:

LengthType, calculateEndTimecode(tv.amwa.maj.record.TimecodeValue, tv.amwa.maj.record.TimecodeValue)

calculateEndTimecode

public static final TimecodeValue calculateEndTimecode(TimecodeValue startValue,
                                                       TimecodeValue duration)
                                                throws IllegalArgumentException

Calculate the end timecode for a segment of media from its start timecode and a timecode value representing its duration. Both values must be specified with the same number of frames per second and matching drop timecode specifications.

Parameters:

startValue - Start timecode at the beginning of a segment of media.

duration - Duration of the media specified as a timecode value.

Returns:

End timecode value calculated by adding the duration timecode's length to the start timecode.

Throws:

IllegalArgumentException - It was not possible to calculate the end timecode as the timecode values are incompatible.

See Also:

calculateDuration(tv.amwa.maj.record.TimecodeValue, tv.amwa.maj.record.TimecodeValue)