| libltc 1.3.1 Linear/Logitudinal Time Code (LTC) Library

ltc.h
Go to the documentation of this file.
1
36 #ifndef LTC_H
37 #define LTC_H 1
38
39 #ifdef __cplusplus
40 extern "C" {
41 #endif
42
43 #if defined _WIN32 && !defined(__LITTLE_ENDIAN__)
44 #define __LITTLE_ENDIAN__
45 #endif
46
47 #ifdef __BIG_ENDIAN__
48 # define LTC_BIG_ENDIAN
49 #elif defined _BIG_ENDIAN
50 # define LTC_BIG_ENDIAN
51 #elif defined __BYTE_ORDER__
52 # if __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
53 # define LTC_BIG_ENDIAN
54 # endif
55 #elif !defined __LITTLE_ENDIAN__
56 # include <endian.h> // machine/endian.h
57 # if (defined __BYTE_ORDER__ && defined __ORDER_BIG_ENDIAN__ && __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__)
58 # define LTC_BIG_ENDIAN
59 # endif
60 #endif
61
62 #include <stddef.h> /* size_t */
63
64 #ifndef DOXYGEN_IGNORE
65 /* libltc version */
66 #define LIBLTC_VERSION "1.3.1"
67 #define LIBLTC_VERSION_MAJOR 1
68 #define LIBLTC_VERSION_MINOR 3
69 #define LIBLTC_VERSION_MICRO 1
70
71 /* interface revision number
72 * http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
73 */
74 #define LIBLTC_CUR 12
75 #define LIBLTC_REV 0
76 #define LIBLTC_AGE 1
77 #endif /* end DOXYGEN_IGNORE */
78
82 typedef unsigned char ltcsnd_sample_t;
83
87 typedef long long int ltc_off_t;
88
89 #define LTC_FRAME_BIT_COUNT 80
90
181 #if (defined LTC_BIG_ENDIAN && !defined DOXYGEN_IGNORE)
182 // Big Endian version, bytes are "upside down"
183 struct LTCFrame {
184 unsigned int user1:4;
185 unsigned int frame_units:4;
186
187 unsigned int user2:4;
188 unsigned int col_frame:1;
189 unsigned int dfbit:1;
190 unsigned int frame_tens:2;
191
192 unsigned int user3:4;
193 unsigned int secs_units:4;
194
195 unsigned int user4:4;
196 unsigned int biphase_mark_phase_correction:1;
197 unsigned int secs_tens:3;
198
199 unsigned int user5:4;
200 unsigned int mins_units:4;
201
202 unsigned int user6:4;
203 unsigned int binary_group_flag_bit0:1;
204 unsigned int mins_tens:3;
205
206 unsigned int user7:4;
207 unsigned int hours_units:4;
208
209 unsigned int user8:4;
210 unsigned int binary_group_flag_bit2:1;
211 unsigned int binary_group_flag_bit1:1;
212 unsigned int hours_tens:2;
213
214 unsigned int sync_word:16;
215 };
216 #else
217 /* Little Endian version -- and doxygen doc */
218 struct LTCFrame {
219 unsigned int frame_units:4;
220 unsigned int user1:4;
221
222 unsigned int frame_tens:2;
223 unsigned int dfbit:1;
224 unsigned int col_frame:1;
225 unsigned int user2:4;
226
227 unsigned int secs_units:4;
228 unsigned int user3:4;
229
230 unsigned int secs_tens:3;
231 unsigned int biphase_mark_phase_correction:1;
232 unsigned int user4:4;
233
234 unsigned int mins_units:4;
235 unsigned int user5:4;
236
237 unsigned int mins_tens:3;
238 unsigned int binary_group_flag_bit0:1;
239 unsigned int user6:4;
240
241 unsigned int hours_units:4;
242 unsigned int user7:4;
243
244 unsigned int hours_tens:2;
245 unsigned int binary_group_flag_bit1:1;
246 unsigned int binary_group_flag_bit2:1;
247 unsigned int user8:4;
248
249 unsigned int sync_word:16;
250 };
251 #endif
252
257 enum LTC_TV_STANDARD {
258 LTC_TV_525_60,
259 LTC_TV_625_50,
260 LTC_TV_1125_60,
261 LTC_TV_FILM_24
262 };
263
265 enum LTC_BG_FLAGS {
266 LTC_USE_DATE = 1,
267 LTC_TC_CLOCK = 2,
268 LTC_BGF_DONT_TOUCH = 4,
269 LTC_NO_PARITY = 8
270 };
271
275 typedef struct LTCFrame LTCFrame;
276
293 struct LTCFrameExt {
294 LTCFrame ltc;
295 ltc_off_t off_start;
296 ltc_off_t off_end;
297 int reverse;
298 float biphase_tics[LTC_FRAME_BIT_COUNT];
299 ltcsnd_sample_t sample_min;
300 ltcsnd_sample_t sample_max;
301 double volume;
302 };
303
307 typedef struct LTCFrameExt LTCFrameExt;
308
312 struct SMPTETimecode {
313 char timezone[6];
314 unsigned char years;
315 unsigned char months;
316 unsigned char days;
317
318 unsigned char hours;
319 unsigned char mins;
320 unsigned char secs;
321 unsigned char frame;
322 };
323
327 typedef struct SMPTETimecode SMPTETimecode;
328
329
334 typedef struct LTCDecoder LTCDecoder;
335
340 typedef struct LTCEncoder LTCEncoder;
341
351 void ltc_frame_to_time(SMPTETimecode* stime, LTCFrame* frame, int flags);
352
365 void ltc_time_to_frame(LTCFrame* frame, SMPTETimecode* stime, enum LTC_TV_STANDARD standard, int flags);
366
373 void ltc_frame_reset(LTCFrame* frame);
374
389 int ltc_frame_increment(LTCFrame* frame, int fps, enum LTC_TV_STANDARD standard, int flags);
390
406 int ltc_frame_decrement(LTCFrame* frame, int fps, enum LTC_TV_STANDARD standard, int flags);
407
416 LTCDecoder * ltc_decoder_create(int apv, int queue_size);
417
418
423 int ltc_decoder_free(LTCDecoder *d);
424
436 void ltc_decoder_write(LTCDecoder *d,
437 ltcsnd_sample_t *buf, size_t size,
438 ltc_off_t posinfo);
439
449 void ltc_decoder_write_float(LTCDecoder *d, float *buf, size_t size, ltc_off_t posinfo);
450
460 void ltc_decoder_write_s16(LTCDecoder *d, short *buf, size_t size, ltc_off_t posinfo);
461
471 void ltc_decoder_write_u16(LTCDecoder *d, unsigned short *buf, size_t size, ltc_off_t posinfo);
472
481 int ltc_decoder_read(LTCDecoder *d, LTCFrameExt *frame);
482
487 void ltc_decoder_queue_flush(LTCDecoder* d);
488
494 int ltc_decoder_queue_length(LTCDecoder* d);
495
496
497
508 LTCEncoder* ltc_encoder_create(double sample_rate, double fps, enum LTC_TV_STANDARD standard, int flags);
509
514 void ltc_encoder_free(LTCEncoder *e);
515
528 void ltc_encoder_set_timecode(LTCEncoder *e, SMPTETimecode *t);
529
540 void ltc_encoder_get_timecode(LTCEncoder *e, SMPTETimecode *t);
541
551 void ltc_encoder_set_user_bits(LTCEncoder *e, unsigned long data);
552
560 unsigned long ltc_frame_get_user_bits(LTCFrame *f);
561
566 int ltc_encoder_inc_timecode(LTCEncoder *e);
567
573 int ltc_encoder_dec_timecode(LTCEncoder *e);
574
584 void ltc_encoder_set_frame(LTCEncoder *e, LTCFrame *f);
585
592 void ltc_encoder_get_frame(LTCEncoder *e, LTCFrame *f);
593
604 int ltc_encoder_get_buffer(LTCEncoder *e, ltcsnd_sample_t *buf);
605
606
615 ltcsnd_sample_t *ltc_encoder_get_bufptr(LTCEncoder *e, int *size, int flush);
616
621 void ltc_encoder_buffer_flush(LTCEncoder *e);
622
634 size_t ltc_encoder_get_buffersize(LTCEncoder *e);
635
662 int ltc_encoder_reinit(LTCEncoder *e, double sample_rate, double fps, enum LTC_TV_STANDARD standard, int flags);
663
670 void ltc_encoder_reset(LTCEncoder *e);
671
689 int ltc_encoder_set_bufsize(LTCEncoder *e, double sample_rate, double fps);
690
707 int ltc_encoder_set_volume(LTCEncoder *e, double dBFS);
708
725 void ltc_encoder_set_filter(LTCEncoder *e, double rise_time);
726
749 int ltc_encoder_encode_byte(LTCEncoder *e, int byte, double speed);
750
764 void ltc_encoder_encode_frame(LTCEncoder *e);
765
783 void ltc_frame_set_parity(LTCFrame *frame, enum LTC_TV_STANDARD standard);
784
795 int parse_bcg_flags(LTCFrame *f, enum LTC_TV_STANDARD standard);
796
811 ltc_off_t ltc_frame_alignment(double samples_per_frame, enum LTC_TV_STANDARD standard);
812
813 #ifdef __cplusplus
814 }
815 #endif
816
817 #endif
LTCFrame
Definition: ltc.h:218
ltc_encoder_buffer_flush
void ltc_encoder_buffer_flush(LTCEncoder *e)
LTCFrame::hours_units
unsigned int hours_units
SMPTE hours BCD unit 0..9.
Definition: ltc.h:241
ltc_encoder_set_user_bits
void ltc_encoder_set_user_bits(LTCEncoder *e, unsigned long data)
ltc_decoder_queue_length
int ltc_decoder_queue_length(LTCDecoder *d)
LTC_BGF_DONT_TOUCH
@ LTC_BGF_DONT_TOUCH
encoder init or re-init does not touch the BGF bits (initial values after initialization is zero)
Definition: ltc.h:268
ltc_encoder_encode_byte
int ltc_encoder_encode_byte(LTCEncoder *e, int byte, double speed)
LTCFrameExt::sample_max
ltcsnd_sample_t sample_max
the maximum input sample signal for this frame (0..255)
Definition: ltc.h:300
LTCFrame::secs_tens
unsigned int secs_tens
SMPTE seconds BCD tens 0..6.
Definition: ltc.h:230
LTCFrameExt::sample_min
ltcsnd_sample_t sample_min
the minimum input sample signal for this frame (0..255)
Definition: ltc.h:299
LTCFrame::frame_tens
unsigned int frame_tens
SMPTE framenumber BCD tens 0..3.
Definition: ltc.h:222
LTCFrame::frame_units
unsigned int frame_units
SMPTE framenumber BCD unit 0..9.
Definition: ltc.h:219
SMPTETimecode::hours
unsigned char hours
hour 0..23
Definition: ltc.h:318
LTCFrameExt
Definition: ltc.h:293
ltc_encoder_get_buffersize
size_t ltc_encoder_get_buffersize(LTCEncoder *e)
ltc_decoder_write_s16
void ltc_decoder_write_s16(LTCDecoder *d, short *buf, size_t size, ltc_off_t posinfo)
LTCFrameExt::biphase_tics
float biphase_tics[LTC_FRAME_BIT_COUNT]
detailed timing info: phase of the LTC signal; the time between each bit in the LTC-frame in audio-fr...
Definition: ltc.h:298
ltc_off_t
long long int ltc_off_t
Definition: ltc.h:87
LTC_TV_525_60
@ LTC_TV_525_60
30fps
Definition: ltc.h:258
SMPTETimecode::timezone
char timezone[6]
the timezone 6bytes: "+HHMM" textual representation
Definition: ltc.h:313
ltc_time_to_frame
void ltc_time_to_frame(LTCFrame *frame, SMPTETimecode *stime, enum LTC_TV_STANDARD standard, int flags)
ltc_frame_to_time
void ltc_frame_to_time(SMPTETimecode *stime, LTCFrame *frame, int flags)
ltc_frame_set_parity
void ltc_frame_set_parity(LTCFrame *frame, enum LTC_TV_STANDARD standard)
LTCFrameExt::off_start
ltc_off_t off_start
Definition: ltc.h:295
LTCFrame::dfbit
unsigned int dfbit
indicated drop-frame timecode
Definition: ltc.h:223
ltc_decoder_create
LTCDecoder * ltc_decoder_create(int apv, int queue_size)
ltc_decoder_write
void ltc_decoder_write(LTCDecoder *d, ltcsnd_sample_t *buf, size_t size, ltc_off_t posinfo)
LTC_FRAME_BIT_COUNT
#define LTC_FRAME_BIT_COUNT
Definition: ltc.h:89
LTCFrame::user2
unsigned int user2
Definition: ltc.h:225
ltc_decoder_read
int ltc_decoder_read(LTCDecoder *d, LTCFrameExt *frame)
LTCFrame::mins_tens
unsigned int mins_tens
SMPTE minutes BCD tens 0..6.
Definition: ltc.h:237
LTC_TC_CLOCK
@ LTC_TC_CLOCK
the Timecode is wall-clock aka freerun. This also sets BGF1 (unless LTC_BGF_DONT_TOUCH is given)
Definition: ltc.h:267
LTCFrame::binary_group_flag_bit0
unsigned int binary_group_flag_bit0
indicate user-data char encoding, see table above - bit 43
Definition: ltc.h:238
ltc_decoder_write_u16
void ltc_decoder_write_u16(LTCDecoder *d, unsigned short *buf, size_t size, ltc_off_t posinfo)
ltc_frame_increment
int ltc_frame_increment(LTCFrame *frame, int fps, enum LTC_TV_STANDARD standard, int flags)
LTCDecoder
struct LTCDecoder LTCDecoder
Definition: ltc.h:334
LTCFrame::user5
unsigned int user5
Definition: ltc.h:235
ltc_encoder_get_frame
void ltc_encoder_get_frame(LTCEncoder *e, LTCFrame *f)
ltc_encoder_get_bufptr
ltcsnd_sample_t * ltc_encoder_get_bufptr(LTCEncoder *e, int *size, int flush)
ltc_encoder_set_timecode
void ltc_encoder_set_timecode(LTCEncoder *e, SMPTETimecode *t)
parse_bcg_flags
int parse_bcg_flags(LTCFrame *f, enum LTC_TV_STANDARD standard)
LTCFrame::secs_units
unsigned int secs_units
SMPTE seconds BCD unit 0..9.
Definition: ltc.h:227
LTCFrame::user4
unsigned int user4
Definition: ltc.h:232
ltc_decoder_free
int ltc_decoder_free(LTCDecoder *d)
SMPTETimecode::secs
unsigned char secs
second 0..60
Definition: ltc.h:320
LTCEncoder
struct LTCEncoder LTCEncoder
Definition: ltc.h:340
ltc_encoder_create
LTCEncoder * ltc_encoder_create(double sample_rate, double fps, enum LTC_TV_STANDARD standard, int flags)
LTCFrame::user3
unsigned int user3
Definition: ltc.h:228
LTCFrame::hours_tens
unsigned int hours_tens
SMPTE hours BCD tens 0..2.
Definition: ltc.h:244
SMPTETimecode::frame
unsigned char frame
sub-second frame 0..(FPS - 1)
Definition: ltc.h:321
LTCFrame::biphase_mark_phase_correction
unsigned int biphase_mark_phase_correction
see note on Bit 27 in description and ltc_frame_set_parity .
Definition: ltc.h:231
ltc_frame_reset
void ltc_frame_reset(LTCFrame *frame)
LTCFrame::user1
unsigned int user1
Definition: ltc.h:220
ltc_encoder_get_buffer
int ltc_encoder_get_buffer(LTCEncoder *e, ltcsnd_sample_t *buf)
ltc_encoder_set_bufsize
int ltc_encoder_set_bufsize(LTCEncoder *e, double sample_rate, double fps)
SMPTETimecode::months
unsigned char months
valid months are 1..12
Definition: ltc.h:315
ltc_encoder_encode_frame
void ltc_encoder_encode_frame(LTCEncoder *e)
ltc_frame_get_user_bits
unsigned long ltc_frame_get_user_bits(LTCFrame *f)
LTC_TV_1125_60
@ LTC_TV_1125_60
30fps
Definition: ltc.h:260
ltc_encoder_reinit
int ltc_encoder_reinit(LTCEncoder *e, double sample_rate, double fps, enum LTC_TV_STANDARD standard, int flags)
SMPTETimecode
Definition: ltc.h:312
LTCFrame::mins_units
unsigned int mins_units
SMPTE minutes BCD unit 0..9.
Definition: ltc.h:234
SMPTETimecode::days
unsigned char days
day of month 1..31
Definition: ltc.h:316
LTCFrame::user8
unsigned int user8
Definition: ltc.h:247
LTC_TV_FILM_24
@ LTC_TV_FILM_24
24fps
Definition: ltc.h:261
ltc_encoder_inc_timecode
int ltc_encoder_inc_timecode(LTCEncoder *e)
LTC_TV_STANDARD
LTC_TV_STANDARD
Definition: ltc.h:257
ltc_encoder_set_frame
void ltc_encoder_set_frame(LTCEncoder *e, LTCFrame *f)
LTC_USE_DATE
@ LTC_USE_DATE
LTCFrame <> SMPTETimecode converter and LTCFrame increment/decrement use date, also set BGF2 to '1' w...
Definition: ltc.h:266
LTC_BG_FLAGS
LTC_BG_FLAGS
Definition: ltc.h:265
ltc_encoder_get_timecode
void ltc_encoder_get_timecode(LTCEncoder *e, SMPTETimecode *t)
LTCFrame::col_frame
unsigned int col_frame
colour-frame: timecode intentionally synchronized to a colour TV field sequence
Definition: ltc.h:224
LTCFrameExt::off_end
ltc_off_t off_end
Definition: ltc.h:296
LTCFrameExt::volume
double volume
the volume of the input signal in dbFS
Definition: ltc.h:301
SMPTETimecode::mins
unsigned char mins
minute 0..60
Definition: ltc.h:319
ltc_frame_decrement
int ltc_frame_decrement(LTCFrame *frame, int fps, enum LTC_TV_STANDARD standard, int flags)
ltcsnd_sample_t
unsigned char ltcsnd_sample_t
Definition: ltc.h:82
ltc_decoder_queue_flush
void ltc_decoder_queue_flush(LTCDecoder *d)
LTCFrame::binary_group_flag_bit2
unsigned int binary_group_flag_bit2
indicate user-data char encoding (or parity with 25fps), see table above - bit 59
Definition: ltc.h:246
ltc_decoder_write_float
void ltc_decoder_write_float(LTCDecoder *d, float *buf, size_t size, ltc_off_t posinfo)
ltc_frame_alignment
ltc_off_t ltc_frame_alignment(double samples_per_frame, enum LTC_TV_STANDARD standard)
ltc_encoder_free
void ltc_encoder_free(LTCEncoder *e)
LTC_NO_PARITY
@ LTC_NO_PARITY
parity bit is left untouched when setting or in/decrementing the encoder frame-number
Definition: ltc.h:269
LTCFrame::sync_word
unsigned int sync_word
Definition: ltc.h:249
LTCFrameExt::ltc
LTCFrame ltc
the actual LTC frame. see LTCFrame
Definition: ltc.h:294
LTCFrame::user6
unsigned int user6
Definition: ltc.h:239
LTC_TV_625_50
@ LTC_TV_625_50
25fps
Definition: ltc.h:259
SMPTETimecode::years
unsigned char years
LTC-date uses 2-digit year 00.99.
Definition: ltc.h:314
LTCFrame::user7
unsigned int user7
Definition: ltc.h:242
ltc_encoder_reset
void ltc_encoder_reset(LTCEncoder *e)
ltc_encoder_dec_timecode
int ltc_encoder_dec_timecode(LTCEncoder *e)
LTCFrameExt::reverse
int reverse
if non-zero, a reverse played LTC frame was detected. Since the frame was reversed,...
Definition: ltc.h:297
LTCFrame::binary_group_flag_bit1
unsigned int binary_group_flag_bit1
indicate timecode is local time wall-clock, see table above - bit 58
Definition: ltc.h:245
ltc_encoder_set_filter
void ltc_encoder_set_filter(LTCEncoder *e, double rise_time)
ltc_encoder_set_volume
int ltc_encoder_set_volume(LTCEncoder *e, double dBFS)