libltc: ltc.h Source File

| libltc 1.3.2 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
40extern "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#if defined(__GNUC__) && __GNUC__ >= 4
63# define DEPRECATED_EXPORT __attribute__((__deprecated__))
64#else
65# define DEPRECATED_EXPORT
66#endif
67
68#include <stddef.h> /* size_t */
69
70#ifndef DOXYGEN_IGNORE
71/* libltc version */
72#define LIBLTC_VERSION "1.3.2"
73#define LIBLTC_VERSION_MAJOR 1
74#define LIBLTC_VERSION_MINOR 3
75#define LIBLTC_VERSION_MICRO 2
76
77/* interface revision number
78 * http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
79 */
80#define LIBLTC_CUR 13
81#define LIBLTC_REV 0
82#define LIBLTC_AGE 2
83#endif /* end DOXYGEN_IGNORE */
84
88 typedef unsigned char ltcsnd_sample_t;
89
93 typedef long long int ltc_off_t;
94
95#define LTC_FRAME_BIT_COUNT 80
96
187#if (defined LTC_BIG_ENDIAN && !defined DOXYGEN_IGNORE)
188// Big Endian version, bytes are "upside down"
189struct LTCFrame {
190 unsigned int user1:4;
191 unsigned int frame_units:4;
192
193 unsigned int user2:4;
194 unsigned int col_frame:1;
195 unsigned int dfbit:1;
196 unsigned int frame_tens:2;
197
198 unsigned int user3:4;
199 unsigned int secs_units:4;
200
201 unsigned int user4:4;
202 unsigned int biphase_mark_phase_correction:1;
203 unsigned int secs_tens:3;
204
205 unsigned int user5:4;
206 unsigned int mins_units:4;
207
208 unsigned int user6:4;
209 unsigned int binary_group_flag_bit0:1;
210 unsigned int mins_tens:3;
211
212 unsigned int user7:4;
213 unsigned int hours_units:4;
214
215 unsigned int user8:4;
216 unsigned int binary_group_flag_bit2:1;
217 unsigned int binary_group_flag_bit1:1;
218 unsigned int hours_tens:2;
219
220 unsigned int sync_word:16;
221};
222#else
223/* Little Endian version -- and doxygen doc */
224 struct LTCFrame {
225 unsigned int frame_units:4;
226 unsigned int user1:4;
227
228 unsigned int frame_tens:2;
229 unsigned int dfbit:1;
230 unsigned int col_frame:1;
231 unsigned int user2:4;
232
233 unsigned int secs_units:4;
234 unsigned int user3:4;
235
236 unsigned int secs_tens:3;
237 unsigned int biphase_mark_phase_correction:1;
238 unsigned int user4:4;
239
240 unsigned int mins_units:4;
241 unsigned int user5:4;
242
243 unsigned int mins_tens:3;
244 unsigned int binary_group_flag_bit0:1;
245 unsigned int user6:4;
246
247 unsigned int hours_units:4;
248 unsigned int user7:4;
249
250 unsigned int hours_tens:2;
251 unsigned int binary_group_flag_bit1:1;
252 unsigned int binary_group_flag_bit2:1;
253 unsigned int user8:4;
254
255 unsigned int sync_word:16;
256};
257#endif
258
263 enum LTC_TV_STANDARD {
264 LTC_TV_525_60,
265 LTC_TV_625_50,
266 LTC_TV_1125_60,
267 LTC_TV_FILM_24
268};
269
271 enum LTC_BG_FLAGS {
272 LTC_USE_DATE = 1,
273 LTC_TC_CLOCK = 2,
274 LTC_BGF_DONT_TOUCH = 4,
275 LTC_NO_PARITY = 8
276};
277
281 typedef struct LTCFrame LTCFrame;
282
299 struct LTCFrameExt {
300 LTCFrame ltc;
301 ltc_off_t off_start;
302 ltc_off_t off_end;
303 int reverse;
304 float biphase_tics[LTC_FRAME_BIT_COUNT];
305 ltcsnd_sample_t sample_min;
306 ltcsnd_sample_t sample_max;
307 double volume;
308};
309
313 typedef struct LTCFrameExt LTCFrameExt;
314
318 struct SMPTETimecode {
319 char timezone[6];
320 unsigned char years;
321 unsigned char months;
322 unsigned char days;
323
324 unsigned char hours;
325 unsigned char mins;
326 unsigned char secs;
327 unsigned char frame;
328};
329
333 typedef struct SMPTETimecode SMPTETimecode;
334
335
340 typedef struct LTCDecoder LTCDecoder;
341
346 typedef struct LTCEncoder LTCEncoder;
347
357 void ltc_frame_to_time(SMPTETimecode* stime, LTCFrame* frame, int flags);
358
371 void ltc_time_to_frame(LTCFrame* frame, SMPTETimecode* stime, enum LTC_TV_STANDARD standard, int flags);
372
379 void ltc_frame_reset(LTCFrame* frame);
380
395 int ltc_frame_increment(LTCFrame* frame, int fps, enum LTC_TV_STANDARD standard, int flags);
396
412 int ltc_frame_decrement(LTCFrame* frame, int fps, enum LTC_TV_STANDARD standard, int flags);
413
422 LTCDecoder * ltc_decoder_create(int apv, int queue_size);
423
424
429 int ltc_decoder_free(LTCDecoder *d);
430
442 void ltc_decoder_write(LTCDecoder *d,
443 ltcsnd_sample_t *buf, size_t size,
444 ltc_off_t posinfo);
445
455 void ltc_decoder_write_double(LTCDecoder *d, double *buf, size_t size, ltc_off_t posinfo);
456
466 void ltc_decoder_write_float(LTCDecoder *d, float *buf, size_t size, ltc_off_t posinfo);
467
477 void ltc_decoder_write_s16(LTCDecoder *d, short *buf, size_t size, ltc_off_t posinfo);
478
488 void ltc_decoder_write_u16(LTCDecoder *d, unsigned short *buf, size_t size, ltc_off_t posinfo);
489
498 int ltc_decoder_read(LTCDecoder *d, LTCFrameExt *frame);
499
504 void ltc_decoder_queue_flush(LTCDecoder* d);
505
511 int ltc_decoder_queue_length(LTCDecoder* d);
512
513
514
525 LTCEncoder* ltc_encoder_create(double sample_rate, double fps, enum LTC_TV_STANDARD standard, int flags);
526
531 void ltc_encoder_free(LTCEncoder *e);
532
545 void ltc_encoder_set_timecode(LTCEncoder *e, SMPTETimecode *t);
546
557 void ltc_encoder_get_timecode(LTCEncoder *e, SMPTETimecode *t);
558
568 void ltc_encoder_set_user_bits(LTCEncoder *e, unsigned long data);
569
576 unsigned long ltc_frame_get_user_bits(LTCFrame *f);
577
582 int ltc_encoder_inc_timecode(LTCEncoder *e);
583
589 int ltc_encoder_dec_timecode(LTCEncoder *e);
590
600 void ltc_encoder_set_frame(LTCEncoder *e, LTCFrame *f);
601
608 void ltc_encoder_get_frame(LTCEncoder *e, LTCFrame *f);
609
622 int ltc_encoder_get_buffer(LTCEncoder *e, ltcsnd_sample_t *buf) DEPRECATED_EXPORT;
623
634 int ltc_encoder_copy_buffer(LTCEncoder *e, ltcsnd_sample_t *buf);
635
646 ltcsnd_sample_t *ltc_encoder_get_bufptr(LTCEncoder *e, int *size, int flush) DEPRECATED_EXPORT;
647
656 int ltc_encoder_get_bufferptr(LTCEncoder *e, ltcsnd_sample_t **buf, int flush);
657
662 void ltc_encoder_buffer_flush(LTCEncoder *e);
663
675 size_t ltc_encoder_get_buffersize(LTCEncoder *e);
676
703 int ltc_encoder_reinit(LTCEncoder *e, double sample_rate, double fps, enum LTC_TV_STANDARD standard, int flags);
704
711 void ltc_encoder_reset(LTCEncoder *e);
712
732 int ltc_encoder_set_bufsize(LTCEncoder *e, double sample_rate, double fps) DEPRECATED_EXPORT;
733
751 int ltc_encoder_set_buffersize(LTCEncoder *e, double sample_rate, double fps);
752
759 double ltc_encoder_get_volume(LTCEncoder *e);
760
777 int ltc_encoder_set_volume(LTCEncoder *e, double dBFS);
778
785 double ltc_encoder_get_filter(LTCEncoder *e);
786
803 void ltc_encoder_set_filter(LTCEncoder *e, double rise_time);
804
827 int ltc_encoder_encode_byte(LTCEncoder *e, int byte, double speed);
828
848 int ltc_encoder_end_encode(LTCEncoder *e);
849
863 void ltc_encoder_encode_frame(LTCEncoder *e);
864
876 void ltc_encoder_encode_reversed_frame(LTCEncoder *e);
877
895 void ltc_frame_set_parity(LTCFrame *frame, enum LTC_TV_STANDARD standard);
896
907 int ltc_frame_parse_bcg_flags(LTCFrame *frame, enum LTC_TV_STANDARD standard);
908
923 ltc_off_t ltc_frame_alignment(double samples_per_frame, enum LTC_TV_STANDARD standard);
924
925#ifdef __cplusplus
926}
927#endif
928
929#endif
LTCFrameExt::off_end
ltc_off_t off_end
the sample in the stream corresponding to the end of the LTC frame.
Definition ltc.h:302
ltc_encoder_get_buffersize
size_t ltc_encoder_get_buffersize(LTCEncoder *e)
ltc_encoder_copy_buffer
int ltc_encoder_copy_buffer(LTCEncoder *e, ltcsnd_sample_t *buf)
ltc_decoder_write_double
void ltc_decoder_write_double(LTCDecoder *d, double *buf, size_t size, ltc_off_t posinfo)
ltc_decoder_create
LTCDecoder * ltc_decoder_create(int apv, int queue_size)
ltc_encoder_get_buffer
int ltc_encoder_get_buffer(LTCEncoder *e, ltcsnd_sample_t *buf) DEPRECATED_EXPORT
ltc_encoder_free
void ltc_encoder_free(LTCEncoder *e)
ltc_decoder_write_s16
void ltc_decoder_write_s16(LTCDecoder *d, short *buf, size_t size, ltc_off_t posinfo)
ltc_encoder_get_timecode
void ltc_encoder_get_timecode(LTCEncoder *e, SMPTETimecode *t)
SMPTETimecode::frame
unsigned char frame
sub-second frame 0..(FPS - 1)
Definition ltc.h:327
ltcsnd_sample_t
unsigned char ltcsnd_sample_t
Definition ltc.h:88
LTC_BG_FLAGS
LTC_BG_FLAGS
Definition ltc.h:271
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:273
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:274
LTC_USE_DATE
@ LTC_USE_DATE
LTCFrame <> SMPTETimecode converter and LTCFrame increment/decrement use date, also set BGF2 to '1' w...
Definition ltc.h:272
LTC_NO_PARITY
@ LTC_NO_PARITY
parity bit is left untouched when setting or in/decrementing the encoder frame-number
Definition ltc.h:275
ltc_off_t
long long int ltc_off_t
Definition ltc.h:93
ltc_encoder_inc_timecode
int ltc_encoder_inc_timecode(LTCEncoder *e)
DEPRECATED_EXPORT
#define DEPRECATED_EXPORT
Definition ltc.h:65
ltc_frame_alignment
ltc_off_t ltc_frame_alignment(double samples_per_frame, enum LTC_TV_STANDARD standard)
LTCFrame::user7
unsigned int user7
Definition ltc.h:248
ltc_encoder_encode_byte
int ltc_encoder_encode_byte(LTCEncoder *e, int byte, double speed)
ltc_encoder_set_timecode
void ltc_encoder_set_timecode(LTCEncoder *e, SMPTETimecode *t)
LTC_FRAME_BIT_COUNT
#define LTC_FRAME_BIT_COUNT
Definition ltc.h:95
ltc_encoder_set_user_bits
void ltc_encoder_set_user_bits(LTCEncoder *e, unsigned long data)
SMPTETimecode::months
unsigned char months
valid months are 1..12
Definition ltc.h:321
ltc_encoder_dec_timecode
int ltc_encoder_dec_timecode(LTCEncoder *e)
LTCFrame::user4
unsigned int user4
Definition ltc.h:238
LTCFrame::frame_units
unsigned int frame_units
SMPTE framenumber BCD unit 0..9.
Definition ltc.h:225
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:237
ltc_encoder_buffer_flush
void ltc_encoder_buffer_flush(LTCEncoder *e)
SMPTETimecode::mins
unsigned char mins
minute 0..60
Definition ltc.h:325
LTCFrame::user3
unsigned int user3
Definition ltc.h:234
LTCEncoder
struct LTCEncoder LTCEncoder
Definition ltc.h:346
ltc_decoder_read
int ltc_decoder_read(LTCDecoder *d, LTCFrameExt *frame)
ltc_frame_set_parity
void ltc_frame_set_parity(LTCFrame *frame, enum LTC_TV_STANDARD standard)
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) DEPRECATED_EXPORT
ltc_frame_get_user_bits
unsigned long ltc_frame_get_user_bits(LTCFrame *f)
SMPTETimecode::hours
unsigned char hours
hour 0..23
Definition ltc.h:324
ltc_decoder_write_float
void ltc_decoder_write_float(LTCDecoder *d, float *buf, size_t size, ltc_off_t posinfo)
LTCFrame::frame_tens
unsigned int frame_tens
SMPTE framenumber BCD tens 0..3.
Definition ltc.h:228
LTCFrame::secs_units
unsigned int secs_units
SMPTE seconds BCD unit 0..9.
Definition ltc.h:233
ltc_encoder_set_filter
void ltc_encoder_set_filter(LTCEncoder *e, double rise_time)
LTCFrameExt::sample_max
ltcsnd_sample_t sample_max
the maximum input sample signal for this frame (0..255)
Definition ltc.h:306
LTCFrame::user8
unsigned int user8
Definition ltc.h:253
ltc_frame_increment
int ltc_frame_increment(LTCFrame *frame, int fps, enum LTC_TV_STANDARD standard, int flags)
ltc_decoder_write_u16
void ltc_decoder_write_u16(LTCDecoder *d, unsigned short *buf, size_t size, ltc_off_t posinfo)
LTCFrame::hours_tens
unsigned int hours_tens
SMPTE hours BCD tens 0..2.
Definition ltc.h:250
LTCFrameExt::off_start
ltc_off_t off_start
the approximate sample in the stream corresponding to the start of the LTC frame.
Definition ltc.h:301
LTCFrame::binary_group_flag_bit0
unsigned int binary_group_flag_bit0
indicate user-data char encoding, see table above - bit 43
Definition ltc.h:244
ltc_frame_decrement
int ltc_frame_decrement(LTCFrame *frame, int fps, enum LTC_TV_STANDARD standard, int flags)
ltc_frame_to_time
void ltc_frame_to_time(SMPTETimecode *stime, LTCFrame *frame, int flags)
ltc_frame_parse_bcg_flags
int ltc_frame_parse_bcg_flags(LTCFrame *frame, enum LTC_TV_STANDARD standard)
LTCFrame::col_frame
unsigned int col_frame
colour-frame: timecode intentionally synchronized to a colour TV field sequence
Definition ltc.h:230
LTC_TV_STANDARD
LTC_TV_STANDARD
Definition ltc.h:263
LTC_TV_FILM_24
@ LTC_TV_FILM_24
24fps
Definition ltc.h:267
LTC_TV_625_50
@ LTC_TV_625_50
25fps
Definition ltc.h:265
LTC_TV_525_60
@ LTC_TV_525_60
30fps
Definition ltc.h:264
LTC_TV_1125_60
@ LTC_TV_1125_60
30fps
Definition ltc.h:266
LTCFrame::sync_word
unsigned int sync_word
Definition ltc.h:255
ltc_time_to_frame
void ltc_time_to_frame(LTCFrame *frame, SMPTETimecode *stime, enum LTC_TV_STANDARD standard, int flags)
LTCFrame::user2
unsigned int user2
Definition ltc.h:231
ltc_encoder_encode_reversed_frame
void ltc_encoder_encode_reversed_frame(LTCEncoder *e)
LTCFrame::user6
unsigned int user6
Definition ltc.h:245
ltc_encoder_create
LTCEncoder * ltc_encoder_create(double sample_rate, double fps, enum LTC_TV_STANDARD standard, int flags)
LTCFrameExt::reverse
int reverse
if non-zero, a reverse played LTC frame was detected. Since the frame was reversed,...
Definition ltc.h:303
LTCFrameExt::ltc
LTCFrame ltc
the actual LTC frame. see LTCFrame
Definition ltc.h:300
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:304
ltc_encoder_reinit
int ltc_encoder_reinit(LTCEncoder *e, double sample_rate, double fps, enum LTC_TV_STANDARD standard, int flags)
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:252
LTCFrameExt::sample_min
ltcsnd_sample_t sample_min
the minimum input sample signal for this frame (0..255)
Definition ltc.h:305
SMPTETimecode::days
unsigned char days
day of month 1..31
Definition ltc.h:322
LTCFrame::mins_units
unsigned int mins_units
SMPTE minutes BCD unit 0..9.
Definition ltc.h:240
LTCFrame::dfbit
unsigned int dfbit
indicated drop-frame timecode
Definition ltc.h:229
ltc_encoder_reset
void ltc_encoder_reset(LTCEncoder *e)
ltc_decoder_write
void ltc_decoder_write(LTCDecoder *d, ltcsnd_sample_t *buf, size_t size, ltc_off_t posinfo)
ltc_decoder_queue_flush
void ltc_decoder_queue_flush(LTCDecoder *d)
ltc_frame_reset
void ltc_frame_reset(LTCFrame *frame)
SMPTETimecode::timezone
char timezone[6]
the timezone 6bytes: "+HHMM" textual representation
Definition ltc.h:319
ltc_encoder_set_frame
void ltc_encoder_set_frame(LTCEncoder *e, LTCFrame *f)
LTCFrame::secs_tens
unsigned int secs_tens
SMPTE seconds BCD tens 0..6.
Definition ltc.h:236
LTCFrame::mins_tens
unsigned int mins_tens
SMPTE minutes BCD tens 0..6.
Definition ltc.h:243
SMPTETimecode::secs
unsigned char secs
second 0..60
Definition ltc.h:326
ltc_encoder_set_bufsize
int ltc_encoder_set_bufsize(LTCEncoder *e, double sample_rate, double fps) DEPRECATED_EXPORT
ltc_encoder_get_bufferptr
int ltc_encoder_get_bufferptr(LTCEncoder *e, ltcsnd_sample_t **buf, int flush)
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:251
LTCDecoder
struct LTCDecoder LTCDecoder
Definition ltc.h:340
ltc_encoder_encode_frame
void ltc_encoder_encode_frame(LTCEncoder *e)
ltc_decoder_free
int ltc_decoder_free(LTCDecoder *d)
LTCFrame::user1
unsigned int user1
Definition ltc.h:226
ltc_encoder_end_encode
int ltc_encoder_end_encode(LTCEncoder *e)
LTCFrameExt::volume
double volume
the volume of the input signal in dbFS
Definition ltc.h:307
LTCFrame::user5
unsigned int user5
Definition ltc.h:241
SMPTETimecode::years
unsigned char years
LTC-date uses 2-digit year 00.99.
Definition ltc.h:320
ltc_encoder_set_volume
int ltc_encoder_set_volume(LTCEncoder *e, double dBFS)
ltc_decoder_queue_length
int ltc_decoder_queue_length(LTCDecoder *d)
ltc_encoder_get_volume
double ltc_encoder_get_volume(LTCEncoder *e)
ltc_encoder_set_buffersize
int ltc_encoder_set_buffersize(LTCEncoder *e, double sample_rate, double fps)
ltc_encoder_get_filter
double ltc_encoder_get_filter(LTCEncoder *e)
LTCFrame::hours_units
unsigned int hours_units
SMPTE hours BCD unit 0..9.
Definition ltc.h:247
LTCFrame
Definition ltc.h:224
LTCFrameExt
Definition ltc.h:299
SMPTETimecode
Definition ltc.h:318