timecode.h (7843B)
1 /* 2 * Copyright (c) 2006 Smartjog S.A.S, Baptiste Coudurier <baptiste.coudurier@gmail.com> 3 * Copyright (c) 2011-2012 Smartjog S.A.S, Clément Bœsch <clement.boesch@smartjog.com> 4 * 5 * This file is part of FFmpeg. 6 * 7 * FFmpeg is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU Lesser General Public 9 * License as published by the Free Software Foundation; either 10 * version 2.1 of the License, or (at your option) any later version. 11 * 12 * FFmpeg is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Lesser General Public License for more details. 16 * 17 * You should have received a copy of the GNU Lesser General Public 18 * License along with FFmpeg; if not, write to the Free Software 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 20 */ 21 22 /** 23 * @file 24 * Timecode helpers header 25 */ 26 27 #ifndef AVUTIL_TIMECODE_H 28 #define AVUTIL_TIMECODE_H 29 30 #include <stdint.h> 31 #include "rational.h" 32 33 #define AV_TIMECODE_STR_SIZE 23 34 35 enum AVTimecodeFlag { 36 AV_TIMECODE_FLAG_DROPFRAME = 1<<0, ///< timecode is drop frame 37 AV_TIMECODE_FLAG_24HOURSMAX = 1<<1, ///< timecode wraps after 24 hours 38 AV_TIMECODE_FLAG_ALLOWNEGATIVE = 1<<2, ///< negative time values are allowed 39 }; 40 41 typedef struct { 42 int start; ///< timecode frame start (first base frame number) 43 uint32_t flags; ///< flags such as drop frame, +24 hours support, ... 44 AVRational rate; ///< frame rate in rational form 45 unsigned fps; ///< frame per second; must be consistent with the rate field 46 } AVTimecode; 47 48 /** 49 * Adjust frame number for NTSC drop frame time code. 50 * 51 * @param framenum frame number to adjust 52 * @param fps frame per second, multiples of 30 53 * @return adjusted frame number 54 * @warning adjustment is only valid for multiples of NTSC 29.97 55 */ 56 int av_timecode_adjust_ntsc_framenum2(int framenum, int fps); 57 58 /** 59 * Convert frame number to SMPTE 12M binary representation. 60 * 61 * @param tc timecode data correctly initialized 62 * @param framenum frame number 63 * @return the SMPTE binary representation 64 * 65 * See SMPTE ST 314M-2005 Sec 4.4.2.2.1 "Time code pack (TC)" 66 * the format description as follows: 67 * bits 0-5: hours, in BCD(6bits) 68 * bits 6: BGF1 69 * bits 7: BGF2 (NTSC) or FIELD (PAL) 70 * bits 8-14: minutes, in BCD(7bits) 71 * bits 15: BGF0 (NTSC) or BGF2 (PAL) 72 * bits 16-22: seconds, in BCD(7bits) 73 * bits 23: FIELD (NTSC) or BGF0 (PAL) 74 * bits 24-29: frames, in BCD(6bits) 75 * bits 30: drop frame flag (0: non drop, 1: drop) 76 * bits 31: color frame flag (0: unsync mode, 1: sync mode) 77 * @note BCD numbers (6 or 7 bits): 4 or 5 lower bits for units, 2 higher bits for tens. 78 * @note Frame number adjustment is automatically done in case of drop timecode, 79 * you do NOT have to call av_timecode_adjust_ntsc_framenum2(). 80 * @note The frame number is relative to tc->start. 81 * @note Color frame (CF) and binary group flags (BGF) bits are set to zero. 82 */ 83 uint32_t av_timecode_get_smpte_from_framenum(const AVTimecode *tc, int framenum); 84 85 /** 86 * Convert sei info to SMPTE 12M binary representation. 87 * 88 * @param rate frame rate in rational form 89 * @param drop drop flag 90 * @param hh hour 91 * @param mm minute 92 * @param ss second 93 * @param ff frame number 94 * @return the SMPTE binary representation 95 */ 96 uint32_t av_timecode_get_smpte(AVRational rate, int drop, int hh, int mm, int ss, int ff); 97 98 /** 99 * Load timecode string in buf. 100 * 101 * @param tc timecode data correctly initialized 102 * @param buf destination buffer, must be at least AV_TIMECODE_STR_SIZE long 103 * @param framenum frame number 104 * @return the buf parameter 105 * 106 * @note Timecode representation can be a negative timecode and have more than 107 * 24 hours, but will only be honored if the flags are correctly set. 108 * @note The frame number is relative to tc->start. 109 */ 110 char *av_timecode_make_string(const AVTimecode *tc, char *buf, int framenum); 111 112 /** 113 * Get the timecode string from the SMPTE timecode format. 114 * 115 * In contrast to av_timecode_make_smpte_tc_string this function supports 50/60 116 * fps timecodes by using the field bit. 117 * 118 * @param buf destination buffer, must be at least AV_TIMECODE_STR_SIZE long 119 * @param rate frame rate of the timecode 120 * @param tcsmpte the 32-bit SMPTE timecode 121 * @param prevent_df prevent the use of a drop flag when it is known the DF bit 122 * is arbitrary 123 * @param skip_field prevent the use of a field flag when it is known the field 124 * bit is arbitrary (e.g. because it is used as PC flag) 125 * @return the buf parameter 126 */ 127 char *av_timecode_make_smpte_tc_string2(char *buf, AVRational rate, uint32_t tcsmpte, int prevent_df, int skip_field); 128 129 /** 130 * Get the timecode string from the SMPTE timecode format. 131 * 132 * @param buf destination buffer, must be at least AV_TIMECODE_STR_SIZE long 133 * @param tcsmpte the 32-bit SMPTE timecode 134 * @param prevent_df prevent the use of a drop flag when it is known the DF bit 135 * is arbitrary 136 * @return the buf parameter 137 */ 138 char *av_timecode_make_smpte_tc_string(char *buf, uint32_t tcsmpte, int prevent_df); 139 140 /** 141 * Get the timecode string from the 25-bit timecode format (MPEG GOP format). 142 * 143 * @param buf destination buffer, must be at least AV_TIMECODE_STR_SIZE long 144 * @param tc25bit the 25-bits timecode 145 * @return the buf parameter 146 */ 147 char *av_timecode_make_mpeg_tc_string(char *buf, uint32_t tc25bit); 148 149 /** 150 * Init a timecode struct with the passed parameters. 151 * 152 * @param tc pointer to an allocated AVTimecode 153 * @param rate frame rate in rational form 154 * @param flags miscellaneous flags such as drop frame, +24 hours, ... 155 * (see AVTimecodeFlag) 156 * @param frame_start the first frame number 157 * @param log_ctx a pointer to an arbitrary struct of which the first field 158 * is a pointer to an AVClass struct (used for av_log) 159 * @return 0 on success, AVERROR otherwise 160 */ 161 int av_timecode_init(AVTimecode *tc, AVRational rate, int flags, int frame_start, void *log_ctx); 162 163 /** 164 * Init a timecode struct from the passed timecode components. 165 * 166 * @param tc pointer to an allocated AVTimecode 167 * @param rate frame rate in rational form 168 * @param flags miscellaneous flags such as drop frame, +24 hours, ... 169 * (see AVTimecodeFlag) 170 * @param hh hours 171 * @param mm minutes 172 * @param ss seconds 173 * @param ff frames 174 * @param log_ctx a pointer to an arbitrary struct of which the first field 175 * is a pointer to an AVClass struct (used for av_log) 176 * @return 0 on success, AVERROR otherwise 177 */ 178 int av_timecode_init_from_components(AVTimecode *tc, AVRational rate, int flags, int hh, int mm, int ss, int ff, void *log_ctx); 179 180 /** 181 * Parse timecode representation (hh:mm:ss[:;.]ff). 182 * 183 * @param tc pointer to an allocated AVTimecode 184 * @param rate frame rate in rational form 185 * @param str timecode string which will determine the frame start 186 * @param log_ctx a pointer to an arbitrary struct of which the first field is a 187 * pointer to an AVClass struct (used for av_log). 188 * @return 0 on success, AVERROR otherwise 189 */ 190 int av_timecode_init_from_string(AVTimecode *tc, AVRational rate, const char *str, void *log_ctx); 191 192 /** 193 * Check if the timecode feature is available for the given frame rate 194 * 195 * @return 0 if supported, <0 otherwise 196 */ 197 int av_timecode_check_frame_rate(AVRational rate); 198 199 #endif /* AVUTIL_TIMECODE_H */