timecode.h File Reference

libtimecode - convert A/V timecode and framerate More...

Go to the source code of this file.

Data Structures
struct	TimecodeTime
struct	TimecodeDate
struct	TimecodeRate
struct	Timecode

Macros
#define	TCFPS23976   (&tcfps23976)
#define	TCFPS24   (&tcfps24)
#define	TCFPS24976   (&tcfps24976)
#define	TCFPS25   (&tcfps25)
#define	TCFPS2997DF   (&tcfps2997df)
#define	TCFPS30   (&tcfps30)
#define	TCFPSMS   (&tcfpsMS)

Typedefs
typedef int	int32_t
typedef long long int	int64_t
typedef struct TimecodeTime	TimecodeTime
typedef struct TimecodeDate	TimecodeDate
typedef struct TimecodeRate	TimecodeRate
typedef struct Timecode	Timecode

Functions
double	timecode_rate_to_double (TimecodeRate const *const r)
double	timecode_frames_per_timecode_frame (TimecodeRate const *const r, const double samplerate)
int64_t	timecode_to_sample (TimecodeTime const *const t, TimecodeRate const *const r, const double samplerate)
void	timecode_sample_to_time (TimecodeTime *const t, TimecodeRate const *const r, const double samplerate, const int64_t sample)
int64_t	timecode_to_framenumber (TimecodeTime const *const t, TimecodeRate const *const r)
void	timecode_framenumber_to_time (TimecodeTime *const t, TimecodeRate const *const r, const int64_t frameno)
void	timecode_convert_rate (TimecodeTime *const t_out, TimecodeRate const *const r_out, TimecodeTime *const t_in, TimecodeRate const *const r_in)
double	timecode_sample_to_seconds (const int64_t sample, double samplerate)
int64_t	timecode_seconds_to_sample (const double sec, double samplerate)
double	timecode_framenumber_to_seconds (const int64_t frameno, TimecodeRate const *const r)
int64_t	timecode_seconds_to_framenumber (const double sec, TimecodeRate const *const r)
void	timecode_seconds_to_time (TimecodeTime *const t, TimecodeRate const *const r, const double sec)
double	timecode_to_sec (TimecodeTime const *const t, TimecodeRate const *const r)
void	timecode_time_add (TimecodeTime *const res, TimecodeRate const *const r, TimecodeTime const *const t1, TimecodeTime const *const t2)
void	timecode_time_subtract (TimecodeTime *const res, TimecodeRate const *const r, TimecodeTime const *const t1, TimecodeTime const *const t2)
int	timecode_time_compare (TimecodeRate const *const r, TimecodeTime const *const a, TimecodeTime const *const b)
int	timecode_date_compare (TimecodeDate const *const a, TimecodeDate const *const b)
int	timecode_datetime_compare (TimecodeRate const *const r, Timecode const *const a, Timecode const *const b)
void	timecode_date_increment (TimecodeDate *const d)
void	timecode_date_decrement (TimecodeDate *const d)
int	timecode_time_increment (TimecodeTime *const t, TimecodeRate const *const r)
int	timecode_time_decrement (TimecodeTime *const t, TimecodeRate const *const r)
int	timecode_datetime_increment (Timecode *const dt)
int	timecode_datetime_decrement (Timecode *const dt)
void	timecode_time_to_string (char *smptestring, TimecodeTime const *const t)
size_t	timecode_strftimecode (char *str, const size_t maxsize, const char *format, const Timecode const *const t)
size_t	timecode_strftime (char *str, const size_t maxsize, const char *format, const TimecodeTime const *const t, const TimecodeRate const *const r)
void	timecode_parse_time (TimecodeTime *const t, TimecodeRate const *const r, const char *val)

Variables
const TimecodeRate	tcfps23976 = { 24000, 1001, 0, 80}
const TimecodeRate	tcfps24 = { 24, 1, 0, 80}
const TimecodeRate	tcfps24976 = { 25000, 1001, 0, 80}
const TimecodeRate	tcfps25 = { 25, 1, 0, 80}
const TimecodeRate	tcfps2997ndf = { 30000, 1001, 0, 80}
const TimecodeRate	tcfps2997df = { 30000, 1001, 1, 80}
const TimecodeRate	tcfps30 = { 30, 1, 0, 80}
const TimecodeRate	tcfps30df = { 30, 1, 1, 80}
const TimecodeRate	tcfps5994 = { 60000, 1001, 0, 80}
const TimecodeRate	tcfps60 = { 30, 1, 0, 80}
const TimecodeRate	tcfpsDS = { 10, 1, 0, 1000}
const TimecodeRate	tcfpsCS = { 100, 1, 0, 1000}
const TimecodeRate	tcfpsMS = { 1000, 1, 0, 1000}
const TimecodeRate	tcfpsUS = { 1000000, 1, 0, 1}
const TimecodeRate	tcfpsNS = {1000000000, 1, 0, 1}

Detailed Description

libtimecode - convert A/V timecode and framerate

Author

Robin Gareus robin.nosp@m.@gar.nosp@m.eus.o.nosp@m.rg

Copyright (C) 2006, 2007, 2008, 2012 Robin Gareus robin.nosp@m.@gar.nosp@m.eus.o.nosp@m.rg

This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

---

Data Structure Documentation

struct TimecodeTime

classical timecode

Data Fields
int32_t	frame	timecode frames 0..fps
int32_t	hour	timecode hours 0..24
int32_t	minute	timecode minutes 0..59
int32_t	second	timecode seconds 0..59
int32_t	subframe	timecode subframes 0..

struct TimecodeDate

date and timezone

Data Fields
int32_t	day	day of month 0..31
int32_t	month	month 1..12
int32_t	timezone	minutes west of UTC +1245 (Chatham Island) .. -1200 (Kwaialein); LA: -0800, NYC: -0500, Paris: +0100, Bombay: +0530, Tokyo: +0900
int32_t	year	year A.D. 4 digits

struct TimecodeRate

define a frame rate

Data Fields
int32_t	den	fps denominator
int	drop	1: use drop-frame timecode (only valid for 2997/100)
int32_t	num	fps numerator
int32_t	subframes	number of subframes per frame

struct Timecode

complete date time description incl frame rate

Data Fields
TimecodeDate	d	date MM/DD/YYYY + Timezone
TimecodeRate	r	the frame rate used for TimecodeTime
TimecodeTime	t	timecode HH:MM:SS:FF.SSS

Macro Definition Documentation

#define TCFPS23976   (&tcfps23976)

#define TCFPS24   (&tcfps24)

#define TCFPS24976   (&tcfps24976)

#define TCFPS25   (&tcfps25)

#define TCFPS2997DF   (&tcfps2997df)

#define TCFPS30   (&tcfps30)

#define TCFPSMS   (&tcfpsMS)

Typedef Documentation

typedef int int32_t

typedef long long int int64_t

typedef struct Timecode Timecode

complete date time description incl frame rate

typedef struct TimecodeDate TimecodeDate

date and timezone

typedef struct TimecodeRate TimecodeRate

define a frame rate

typedef struct TimecodeTime TimecodeTime

classical timecode

Function Documentation

void timecode_convert_rate	(	TimecodeTime *const	t_out,
		TimecodeRate const *const	r_out,
		TimecodeTime *const	t_in,
		TimecodeRate const *const	r_in
	)

convert timecode from one rate to another.

Note: if t_out points to the same timecode as t_in, the timecode will be modified.

Parameters

t_out	[output] timecode t_in converted to frame rate r_out
r_out	frame rate to convert to
t_in	the timecode to convert (may be identical to t_out)
r_in	the frame rate of the timecode to convert from

int timecode_date_compare	(	TimecodeDate const *const	a,
		TimecodeDate const *const	b
	)

The timecode_date_compare() function compares the two dates a and b. It returns an integer less than, equal to, or greater than zero if a is found, respectively, to be later than, to match, or be earlier than b.

Parameters

a	date to compare
b	date to compare

Returns

+1 if a is later than b, -1 if a is earlier than b, 0 if timecodes are equal

void timecode_date_decrement

(

TimecodeDate *const

d

)

decrement date by one day. Note: this function honors leap-years.

Parameters

d	the date to adjust

void timecode_date_increment

(

TimecodeDate *const

d

)

increment date by one day. Note: This function honors leap-years.

Parameters

d	the date to adjust

int timecode_datetime_compare	(	TimecodeRate const *const	r,
		Timecode const *const	a,
		Timecode const *const	b
	)

The timecode_datetime_compare() function compares the two datetimes a and b. It returns an integer less than, equal to, or greater than zero if a is found, respectively, to be later than, to match, or be earlier than b.

This function is a wrapper around timecode_time_compare and timecode_date_compare it includes additional functionality to handle timezones correctly.

Parameters

r	frame rate to use for both a and b
a	timecode to compare (using frame rate r)
b	timecode to compare (using frame rate r)

Returns

+1 if a is later than b, -1 if a is earlier than b, 0 if timecodes are equal

int timecode_datetime_decrement

(

Timecode *const

dt

)

increment datetime by one frame this is a wrapper function around timecode_date_increment and timecode_time_increment

Parameters

dt	the datetime to modify

Returns

1 if timecode wrapped 24 hours, 0 otherwise

int timecode_datetime_increment

(

Timecode *const

dt

)

increment datetime by one frame this is a wrapper function around timecode_date_increment and timecode_time_increment

Parameters

dt	the datetime to modify

Returns

1 if timecode wrapped 24 hours, 0 otherwise

double timecode_framenumber_to_seconds	(	const int64_t	frameno,
		TimecodeRate const *const	r
	)

convert frame number to floating point seconds

Parameters

frameno	frame number (starting at zero)
r	frame rate

Returns

seconds

void timecode_framenumber_to_time	(	TimecodeTime *const	t,
		TimecodeRate const *const	r,
		const int64_t	frameno
	)

convert video frame-number to timecode

this function simply calls timecode_framenumber_to_time with the sample rate set to the fps.

Parameters

t	[output] the timecode that corresponds to the frame
r	frame rate to use for conversion
frameno	the frame-number to convert

double timecode_frames_per_timecode_frame	(	TimecodeRate const *const	r,
		const double	samplerate
	)

calculate samples per timecode-frame for a given sample rate: (samplerate * r->num / r->den).

Parameters

r	frame rate to convert
samplerate	the sampling rate

Returns

number of samples per timecode-frame.

void timecode_parse_time	(	TimecodeTime *const	t,
		TimecodeRate const *const	r,
		const char *	val
	)

parse string to timecode time - separators may include ":.;" the format is "[[[HH:]MM:]SS:]FF", subframes are set to 0.

Parameters

t	[output] the parsed timecode
r	frame rate to use
val	the value to parse

double timecode_rate_to_double

(

TimecodeRate const *const

r

)

convert rational frame rate to double (r->num / r->den).

Parameters

r	frame rate to convert

Returns

double representation of frame rate

double timecode_sample_to_seconds	(	const int64_t	sample,
		double	samplerate
	)

convert sample number to floating point seconds

Parameters

sample	sample number (starting at zero)
samplerate	sample rate

Returns

seconds

void timecode_sample_to_time	(	TimecodeTime *const	t,
		TimecodeRate const *const	r,
		const double	samplerate,
		const int64_t	sample
	)

convert audio sample number to timecode

NB. this function can also be used to convert integer milli-seconds or micro-seconds by specifying a sample rate of 1000 or 10^6 respectively.

When used with samplerate == timecode_rate_to_double this function can also convert video-frame number to timecode.

Parameters

t	[output] the timecode that corresponds to the sample
r	frame rate to use for conversion
samplerate	the sample rate the sample was taken at
sample	the audio sample number to convert

int64_t timecode_seconds_to_framenumber	(	const double	sec,
		TimecodeRate const *const	r
	)

convert floating-point seconds to timecode frame number at given frame rate. Opposed to timecode_seconds_to_sample which rounds the sample number to the nearest sample, this function always rounds down to the current frame.

Parameters

sec	seconds
r	frame rate

Returns

sample number (starting at zero)

int64_t timecode_seconds_to_sample	(	const double	sec,
		double	samplerate
	)

convert floating-point seconds to nearest sample number at given sample rate.

Parameters

sec	seconds
samplerate	sample rate

Returns

sample number (starting at zero)

void timecode_seconds_to_time	(	TimecodeTime *const	t,
		TimecodeRate const *const	r,
		const double	sec
	)

convert floating point seconds to timecode.

uses timecode_sample_to_time and timecode_seconds_to_sample.

Parameters

t	[output] the timecode that corresponds to the sample
r	frame rate to use for conversion
sec	seconds to convert

size_t timecode_strftime	(	char *	str,
		const size_t	maxsize,
		const char *	format,
		const TimecodeTime const *const	t,
		const TimecodeRate const *const	r
	)

wrapper around timecode_strftimecode for formatting timecode time.

Parameters

str	[output] formatted string str (must be large enough).
maxsize	write at most maxsize bytes (including the trailing null byte ('\0')) to str
format	the format directive
t	the timecode time to format
r	optional framerate (may be NULL)

Returns

number of bytes written to str

size_t timecode_strftimecode	(	char *	str,
		const size_t	maxsize,
		const char *	format,
		const Timecode const *const	t
	)

print formatted timecode to text string.

The formatting is very similar to that of strftime or printf: The format string is a a null-terminated string composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; and conversion specifications, each conversion specification is introduced by the character %, and ends with a conversion specifier.

The characters of conversion specifications are replaced as follows:

Time conversion:

• %H timecode hour as a 2-digit integer.

• %M timecode minute as a 2-digit integer.

• %S timecode second as a 2-digit integer.

• %F timecode frame number with leading zeros - the number of leading zeroes depends on the frame rate.

• %s timecode subframes with leading zeros - the number of leading zeroes depends on the frame rate.

Date conversion:

• %y The year as a decimal number without a century (range 00 to 99).

• %Y The year as a decimal number including the century.

• %m The month as a decimal number (range 01 to 12).

• %d The day of the month as a decimal number (range 01 to 31).

Frame rate conversion:

• %f frame rate incl. drop-frame postfix e.g. "25" or "29.97df"

• %: frame separator ':' for non-drop-frame, ';' for drop-frame timecode

Miscellaneous and presets:

• %t A tab character.

• %% A literal '' character.

• %T preset alias for "%H:%M:%S%;%F"

• %Z preset alias for "%Y-%m-%d %H:%M:%S%:%F.%s %z @%f fps"

Parameters

str	[output] formatted string str (must be large enough).
maxsize	write at most maxsize bytes (including the trailing null byte ('\0')) to str
format	the format directive
t	the timecode to format

Returns

number of bytes written to str

void timecode_time_add	(	TimecodeTime *const	res,
		TimecodeRate const *const	r,
		TimecodeTime const *const	t1,
		TimecodeTime const *const	t2
	)

add two timecodes at same frame rate.

Note: res, t1 and t2 may all point to the same structure.

Parameters

res	[output] result of addition
r	frame rate
t1	first summand
t2	second summand

int timecode_time_compare	(	TimecodeRate const *const	r,
		TimecodeTime const *const	a,
		TimecodeTime const *const	b
	)

The timecode_time_compare() function compares the two timecodes a and b. It returns an integer less than, equal to, or greater than zero if a is found, respectively, to be later than, to match, or be earlier than b.

Parameters

r	frame rate to use for both a and b
a	timecode to compare (using frame rate r)
b	timecode to compare (using frame rate r)

Returns

+1 if a is later than b, -1 if a is earlier than b, 0 if timecodes are equal

int timecode_time_decrement	(	TimecodeTime *const	t,
		TimecodeRate const *const	r
	)

decrement timecode by one frame.

Parameters

t	the timecode to modify
r	frame rate to use

Returns

1 if timecode wrapped 24 hours, 0 otherwise

int timecode_time_increment	(	TimecodeTime *const	t,
		TimecodeRate const *const	r
	)

increment timecode by one frame.

Parameters

t	the timecode to modify
r	frame rate to use

Returns

1 if timecode wrapped 24 hours, 0 otherwise

void timecode_time_subtract	(	TimecodeTime *const	res,
		TimecodeRate const *const	r,
		TimecodeTime const *const	t1,
		TimecodeTime const *const	t2
	)

subtract timecode at same frame rate.

Note: res, t1 and t2 may all point to the same structure.

Parameters

res	[output] difference between t1 and t2: (t1-t2)
r	frame rate
t1	minuend
t2	subtrahend

void timecode_time_to_string	(	char *	smptestring,
		TimecodeTime const *const	t
	)

format timecode as string "HH:MM:SS:FF".

Parameters

smptestring	[output] formatted string, must be at least 12 bytes long.
t	the timecode to print

int64_t timecode_to_framenumber	(	TimecodeTime const *const	t,
		TimecodeRate const *const	r
	)

convert timecode to frame number

this function simply calls timecode_to_sample with the samplerate set to the fps.

Parameters

t	the timecode to convert
r	frame rate to use for conversion

Returns

frame-number

int64_t timecode_to_sample	(	TimecodeTime const *const	t,
		TimecodeRate const *const	r,
		const double	samplerate
	)

convert timecode to audio sample number

NB. this function can also be used to convert integer milli-seconds or micro-seconds by specifying a sample rate of 1000 or 10^6 respectively.

When used with samplerate == timecode_rate_to_double this function can also convert timecode to video-frame number.

Parameters

t	the timecode to convert
r	frame rate to use for conversion
samplerate	the sample rate the sample was taken at

Returns

audio sample number

double timecode_to_sec	(	TimecodeTime const *const	t,
		TimecodeRate const *const	r
	)

convert timecode to floating point seconds.

uses timecode_sample_to_seconds and timecode_to_sample.

Parameters

t	the timecode to convert
r	frame rate

Returns

seconds

Variable Documentation

const TimecodeRate tcfps23976 = { 24000, 1001, 0, 80}

const TimecodeRate tcfps24 = { 24, 1, 0, 80}

const TimecodeRate tcfps24976 = { 25000, 1001, 0, 80}

const TimecodeRate tcfps25 = { 25, 1, 0, 80}

const TimecodeRate tcfps2997df = { 30000, 1001, 1, 80}

const TimecodeRate tcfps2997ndf = { 30000, 1001, 0, 80}

const TimecodeRate tcfps30 = { 30, 1, 0, 80}

const TimecodeRate tcfps30df = { 30, 1, 1, 80}

const TimecodeRate tcfps5994 = { 60000, 1001, 0, 80}

const TimecodeRate tcfps60 = { 30, 1, 0, 80}

const TimecodeRate tcfpsCS = { 100, 1, 0, 1000}

const TimecodeRate tcfpsDS = { 10, 1, 0, 1000}

const TimecodeRate tcfpsMS = { 1000, 1, 0, 1000}

const TimecodeRate tcfpsNS = {1000000000, 1, 0, 1}

const TimecodeRate tcfpsUS = { 1000000, 1, 0, 1}