lavc: deprecate the use of AVCodecContext.time_base for decoding

When decoding, this field holds the inverse of the framerate that can be
written in the headers for some codecs. Using a field called 'time_base'
for this is very misleading, as there are no timestamps associated with
it. Furthermore, this field is used for a very different purpose during
encoding.

Add a new field, called 'framerate', to replace the use of time_base for
decoding.

doc/APIchanges

@@ -13,6 +13,10 @@ libavutil:     2014-08-09
 
 API changes, most recent first:
 
+2014-10-xx - xxxxxxx - lavc 56.5.0 - avcodec.h
+  Replace AVCodecContext.time_base used for decoding
+  with AVCodecContext.framerate.
+
 2014-10-xx - xxxxxxx - lavc 56.4.0 - avcodec.h
   Add AV_HWACCEL_FLAG_IGNORE_LEVEL flag to av_vdpau_bind_context().
 

libavcodec/avcodec.h

@@ -1170,7 +1170,8 @@ typedef struct AVCodecContext {
      * timebase should be 1/framerate and timestamp increments should be
      * identically 1.
      * - encoding: MUST be set by user.
-     * - decoding: Set by libavcodec.
+     * - decoding: the use of this field for decoding is deprecated.
+     *             Use framerate instead.
      */
     AVRational time_base;
 
@@ -2788,6 +2789,14 @@ typedef struct AVCodecContext {
      *             -initial_padding.
      */
     int initial_padding;
+
+    /*
+     * - decoding: For codecs that store a framerate value in the compressed
+     *             bitstream, the decoder may export it here. { 0, 1} when
+     *             unknown.
+     * - encoding: unused
+     */
+    AVRational framerate;
 } AVCodecContext;
 
 /**

libavcodec/cavsdec.c

@@ -1106,8 +1106,7 @@ static int decode_seq_header(AVSContext *h)
     h->low_delay =  get_bits1(&h->gb);
     h->mb_width  = (h->width  + 15) >> 4;
     h->mb_height = (h->height + 15) >> 4;
-    h->avctx->time_base.den = ff_mpeg12_frame_rate_tab[frame_rate_code].num;
-    h->avctx->time_base.num = ff_mpeg12_frame_rate_tab[frame_rate_code].den;
+    h->avctx->framerate = ff_mpeg12_frame_rate_tab[frame_rate_code];
     h->avctx->width  = h->width;
     h->avctx->height = h->height;
     if (!h->top_qp)

libavcodec/dirac.c

@@ -172,8 +172,7 @@ static int parse_source_parameters(AVCodecContext *avctx, GetBitContext *gb,
             /* [DIRAC_STD] Table 10.3 values 9-10 */
             frame_rate = dirac_frame_rate[source->frame_rate_index - 9];
     }
-    av_reduce(&avctx->time_base.num, &avctx->time_base.den,
-              frame_rate.den, frame_rate.num, 1 << 30);
+    avctx->framerate = frame_rate;
 
     /* [DIRAC_STD] 10.3.6 Pixel Aspect Ratio.
      * pixel_aspect_ratio(video_params) */

libavcodec/dvdec.c

@@ -373,7 +373,7 @@ static int dvvideo_decode_frame(AVCodecContext *avctx, void *data,
     s->frame->key_frame = 1;
     s->frame->pict_type = AV_PICTURE_TYPE_I;
     avctx->pix_fmt      = s->sys->pix_fmt;
-    avctx->time_base    = s->sys->time_base;
+    avctx->framerate    = av_inv_q(s->sys->time_base);
 
     ret = ff_set_dimensions(avctx, s->sys->width, s->sys->height);
     if (ret < 0)

libavcodec/eacmv.c

@@ -153,7 +153,7 @@ static int cmv_process_header(CmvContext *s, const uint8_t *buf, const uint8_t *
 
     fps = AV_RL16(&buf[10]);
     if (fps > 0)
-        s->avctx->time_base = (AVRational){ 1, fps };
+        s->avctx->framerate = (AVRational){ fps, 1 };
 
     pal_start = AV_RL16(&buf[12]);
     pal_count = AV_RL16(&buf[14]);

libavcodec/eamad.c

@@ -249,7 +249,7 @@ static int decode_frame(AVCodecContext *avctx,
     inter = (chunk_type == MADm_TAG || chunk_type == MADe_TAG);
     bytestream2_skip(&gb, 10);
 
-    av_reduce(&avctx->time_base.num, &avctx->time_base.den,
+    av_reduce(&avctx->framerate.den, &avctx->framerate.num,
               bytestream2_get_le16(&gb), 1000, 1<<30);
 
     width  = bytestream2_get_le16(&gb);

libavcodec/eatgq.c

@@ -53,7 +53,7 @@ static av_cold int tgq_decode_init(AVCodecContext *avctx)
     s->avctx = avctx;
     ff_init_scantable_permutation(idct_permutation, FF_IDCT_PERM_NONE);
     ff_init_scantable(idct_permutation, &s->scantable, ff_zigzag_direct);
-    avctx->time_base = (AVRational){1, 15};
+    avctx->framerate = (AVRational){ 15, 1 };
     avctx->pix_fmt   = AV_PIX_FMT_YUV420P;
     return 0;
 }

libavcodec/eatgv.c

@@ -55,7 +55,7 @@ static av_cold int tgv_decode_init(AVCodecContext *avctx)
 {
     TgvContext *s = avctx->priv_data;
     s->avctx         = avctx;
-    avctx->time_base = (AVRational){1, 15};
+    avctx->framerate = (AVRational){ 15, 1 };
     avctx->pix_fmt   = AV_PIX_FMT_PAL8;
 
     s->last_frame = av_frame_alloc();

libavcodec/eatqi.c

@@ -56,7 +56,7 @@ static av_cold int tqi_decode_init(AVCodecContext *avctx)
     ff_init_scantable_permutation(s->idsp.idct_permutation, FF_IDCT_PERM_NONE);
     ff_init_scantable(s->idsp.idct_permutation, &s->intra_scantable, ff_zigzag_direct);
     s->qscale = 1;
-    avctx->time_base = (AVRational){1, 15};
+    avctx->framerate = (AVRational){ 15, 1 };
     avctx->pix_fmt = AV_PIX_FMT_YUV420P;
     ff_mpeg12_init_vlcs();
     return 0;

libavcodec/h261dec.c

@@ -478,7 +478,7 @@ static int h261_decode_picture_header(H261Context *h)
         i += 32;
     s->picture_number = (s->picture_number & ~31) + i;
 
-    s->avctx->time_base      = (AVRational) { 1001, 30000 };
+    s->avctx->framerate = (AVRational) { 30000, 1001 };
 
     /* PTYPE starts here */
     skip_bits1(&s->gb); /* split screen off */

libavcodec/h264.c

@@ -656,7 +656,7 @@ av_cold int ff_h264_decode_init(AVCodecContext *avctx)
     h->frame_recovered = 0;
     if (avctx->codec_id == AV_CODEC_ID_H264) {
         if (avctx->ticks_per_frame == 1)
-            h->avctx->time_base.den *= 2;
+            h->avctx->framerate.num *= 2;
         avctx->ticks_per_frame = 2;
     }
 

libavcodec/h264_slice.c

@@ -1090,7 +1090,7 @@ static int h264_slice_header_init(H264Context *h, int reinit)
         int64_t den = h->sps.time_scale;
         if (h->x264_build < 44U)
             den *= 2;
-        av_reduce(&h->avctx->time_base.num, &h->avctx->time_base.den,
+        av_reduce(&h->avctx->framerate.den, &h->avctx->framerate.num,
                   h->sps.num_units_in_tick, den, 1 << 30);
     }
 

libavcodec/hevc.c

@@ -442,7 +442,7 @@ static int set_sps(HEVCContext *s, const HEVCSPS *sps)
     }
 
     if (num != 0 && den != 0)
-        av_reduce(&s->avctx->time_base.num, &s->avctx->time_base.den,
+        av_reduce(&s->avctx->framerate.den, &s->avctx->framerate.num,
                   num, den, 1 << 30);
 
     return 0;

libavcodec/ituh263dec.c

@@ -81,7 +81,7 @@ void ff_h263_show_pict_info(MpegEncContext *s){
          s->modified_quant ? " MQ" : "",
          s->loop_filter ? " LOOP" : "",
          s->h263_slice_structured ? " SS" : "",
-         s->avctx->time_base.den, s->avctx->time_base.num
+         s->avctx->framerate.num, s->avctx->framerate.den
     );
     }
 }
@@ -938,7 +938,7 @@ int ff_h263_decode_picture_header(MpegEncContext *s)
         s->width = width;
         s->height = height;
         s->avctx->sample_aspect_ratio= (AVRational){12,11};
-        s->avctx->time_base= (AVRational){1001, 30000};
+        s->avctx->framerate = (AVRational){ 30000, 1001 };
     } else {
         int ufep;
 
@@ -1034,18 +1034,18 @@ int ff_h263_decode_picture_header(MpegEncContext *s)
 
             if(s->custom_pcf){
                 int gcd;
-                s->avctx->time_base.den= 1800000;
-                s->avctx->time_base.num= 1000 + get_bits1(&s->gb);
-                s->avctx->time_base.num*= get_bits(&s->gb, 7);
-                if(s->avctx->time_base.num == 0){
+                s->avctx->framerate.num  = 1800000;
+                s->avctx->framerate.den  = 1000 + get_bits1(&s->gb);
+                s->avctx->framerate.den *= get_bits(&s->gb, 7);
+                if(s->avctx->framerate.den == 0){
                     av_log(s, AV_LOG_ERROR, "zero framerate\n");
                     return -1;
                 }
-                gcd= av_gcd(s->avctx->time_base.den, s->avctx->time_base.num);
-                s->avctx->time_base.den /= gcd;
-                s->avctx->time_base.num /= gcd;
+                gcd= av_gcd(s->avctx->framerate.den, s->avctx->framerate.num);
+                s->avctx->framerate.den /= gcd;
+                s->avctx->framerate.num /= gcd;
             }else{
-                s->avctx->time_base= (AVRational){1001, 30000};
+                s->avctx->framerate = (AVRational){ 30000, 1001 };
             }
         }
 

libavcodec/libschroedingerdec.c

@@ -199,8 +199,8 @@ static void libschroedinger_handle_first_access_unit(AVCodecContext *avctx)
         return;
     }
 
-    avctx->time_base.den = p_schro_params->format->frame_rate_numerator;
-    avctx->time_base.num = p_schro_params->format->frame_rate_denominator;
+    avctx->framerate.num = p_schro_params->format->frame_rate_numerator;
+    avctx->framerate.den = p_schro_params->format->frame_rate_denominator;
 }
 
 static int libschroedinger_decode_frame(AVCodecContext *avctx,

libavcodec/mpeg12dec.c

@@ -1257,15 +1257,14 @@ static int mpeg_decode_postinit(AVCodecContext *avctx)
 
         if (avctx->codec_id == AV_CODEC_ID_MPEG1VIDEO) {
             // MPEG-1 fps
-            avctx->time_base.den = ff_mpeg12_frame_rate_tab[s->frame_rate_index].num;
-            avctx->time_base.num = ff_mpeg12_frame_rate_tab[s->frame_rate_index].den;
+            avctx->framerate = ff_mpeg12_frame_rate_tab[s->frame_rate_index];
             // MPEG-1 aspect
             avctx->sample_aspect_ratio = av_d2q(1.0 / ff_mpeg1_aspect[s->aspect_ratio_info], 255);
             avctx->ticks_per_frame     = 1;
         } else { // MPEG-2
             // MPEG-2 fps
-            av_reduce(&s->avctx->time_base.den,
-                      &s->avctx->time_base.num,
+            av_reduce(&s->avctx->framerate.num,
+                      &s->avctx->framerate.den,
                       ff_mpeg12_frame_rate_tab[s->frame_rate_index].num * s1->frame_rate_ext.num * 2,
                       ff_mpeg12_frame_rate_tab[s->frame_rate_index].den * s1->frame_rate_ext.den,
                       1 << 30);

libavcodec/mpeg4videodec.c

@@ -1722,23 +1722,22 @@ static int decode_vol_header(Mpeg4DecContext *ctx, GetBitContext *gb)
 
     check_marker(gb, "before time_increment_resolution");
 
-    s->avctx->time_base.den = get_bits(gb, 16);
-    if (!s->avctx->time_base.den) {
-        av_log(s->avctx, AV_LOG_ERROR, "time_base.den==0\n");
-        s->avctx->time_base.num = 0;
+    s->avctx->framerate.num = get_bits(gb, 16);
+    if (!s->avctx->framerate.num) {
+        av_log(s->avctx, AV_LOG_ERROR, "framerate==0\n");
         return -1;
     }
 
-    ctx->time_increment_bits = av_log2(s->avctx->time_base.den - 1) + 1;
+    ctx->time_increment_bits = av_log2(s->avctx->framerate.num - 1) + 1;
     if (ctx->time_increment_bits < 1)
         ctx->time_increment_bits = 1;
 
     check_marker(gb, "before fixed_vop_rate");
 
     if (get_bits1(gb) != 0)     /* fixed_vop_rate  */
-        s->avctx->time_base.num = get_bits(gb, ctx->time_increment_bits);
+        s->avctx->framerate.den = get_bits(gb, ctx->time_increment_bits);
     else
-        s->avctx->time_base.num = 1;
+        s->avctx->framerate.den = 1;
 
     ctx->t_frame = 0;
 
@@ -2126,19 +2125,19 @@ static int decode_vop_header(Mpeg4DecContext *ctx, GetBitContext *gb)
     if (s->pict_type != AV_PICTURE_TYPE_B) {
         s->last_time_base = s->time_base;
         s->time_base     += time_incr;
-        s->time = s->time_base * s->avctx->time_base.den + time_increment;
+        s->time = s->time_base * s->avctx->framerate.num + time_increment;
         if (s->workaround_bugs & FF_BUG_UMP4) {
             if (s->time < s->last_non_b_time) {
                 /* header is not mpeg-4-compatible, broken encoder,
                  * trying to workaround */
                 s->time_base++;
-                s->time += s->avctx->time_base.den;
+                s->time += s->avctx->framerate.num;
             }
         }
         s->pp_time         = s->time - s->last_non_b_time;
         s->last_non_b_time = s->time;
     } else {
-        s->time    = (s->last_time_base + time_incr) * s->avctx->time_base.den + time_increment;
+        s->time    = (s->last_time_base + time_incr) * s->avctx->framerate.num + time_increment;
         s->pb_time = s->pp_time - (s->last_non_b_time - s->time);
         if (s->pp_time <= s->pb_time ||
             s->pp_time <= s->pp_time - s->pb_time ||

libavcodec/mpegvideo_parser.c

@@ -66,8 +66,7 @@ static void mpegvideo_extract_headers(AVCodecParserContext *s,
                     did_set_size=1;
                 }
                 frame_rate_index = buf[3] & 0xf;
-                pc->frame_rate.den = avctx->time_base.den = ff_mpeg12_frame_rate_tab[frame_rate_index].num;
-                pc->frame_rate.num = avctx->time_base.num = ff_mpeg12_frame_rate_tab[frame_rate_index].den;
+                pc->frame_rate = avctx->framerate = ff_mpeg12_frame_rate_tab[frame_rate_index];
                 avctx->bit_rate = ((buf[4]<<10) | (buf[5]<<2) | (buf[6]>>6))*400;
                 avctx->codec_id = AV_CODEC_ID_MPEG1VIDEO;
             }
@@ -91,8 +90,8 @@ static void mpegvideo_extract_headers(AVCodecParserContext *s,
                         avctx->bit_rate += (bit_rate_ext << 18) * 400;
                         if(did_set_size)
                             ff_set_dimensions(avctx, pc->width, pc->height);
-                        avctx->time_base.den = pc->frame_rate.den * (frame_rate_ext_n + 1) * 2;
-                        avctx->time_base.num = pc->frame_rate.num * (frame_rate_ext_d + 1);
+                        avctx->framerate.num = pc->frame_rate.num * (frame_rate_ext_n + 1) * 2;
+                        avctx->framerate.den = pc->frame_rate.den * (frame_rate_ext_d + 1);
                         avctx->codec_id = AV_CODEC_ID_MPEG2VIDEO;
                     }
                     break;
@@ -139,6 +138,10 @@ static void mpegvideo_extract_headers(AVCodecParserContext *s,
         }
     }
  the_end: ;
+#if FF_API_AVCTX_TIMEBASE
+    if (avctx->framerate.num)
+        avctx->time_base = av_inv_q(avctx->framerate);
+#endif
 }
 
 static int mpegvideo_parse(AVCodecParserContext *s,

libavcodec/options.c

@@ -88,6 +88,7 @@ int avcodec_get_context_defaults3(AVCodecContext *s, const AVCodec *codec)
     av_opt_set_defaults(s);
 
     s->time_base           = (AVRational){0,1};
+    s->framerate           = (AVRational){ 0, 1 };
     s->get_buffer2         = avcodec_default_get_buffer2;
     s->get_format          = avcodec_default_get_format;
     s->execute             = avcodec_default_execute;

libavcodec/pthread_frame.c

@@ -178,6 +178,7 @@ static int update_context_from_thread(AVCodecContext *dst, AVCodecContext *src,
 
     if (dst != src) {
         dst->time_base = src->time_base;
+        dst->framerate = src->framerate;
         dst->width     = src->width;
         dst->height    = src->height;
         dst->pix_fmt   = src->pix_fmt;

libavcodec/utils.c

@@ -1262,6 +1262,11 @@ int attribute_align_arg avcodec_open2(AVCodecContext *avctx, const AVCodec *code
             ret = AVERROR(EINVAL);
             goto free_and_end;
         }
+
+#if FF_API_AVCTX_TIMEBASE
+        if (avctx->framerate.num > 0 && avctx->framerate.den > 0)
+            avctx->time_base = av_inv_q(avctx->framerate);
+#endif
     }
 end:
     entangled_thread_counter--;
@@ -1674,6 +1679,11 @@ int attribute_align_arg avcodec_decode_video2(AVCodecContext *avctx, AVFrame *pi
     } else
         ret = 0;
 
+#if FF_API_AVCTX_TIMEBASE
+    if (avctx->framerate.num > 0 && avctx->framerate.den > 0)
+        avctx->time_base = av_inv_q(avctx->framerate);
+#endif
+
     return ret;
 }
 

libavcodec/vaapi_mpeg4.c

@@ -88,7 +88,7 @@ static int vaapi_mpeg4_start_frame(AVCodecContext *avctx, av_unused const uint8_
     pic_param->vop_fields.bits.alternate_vertical_scan_flag = s->alternate_scan;
     pic_param->vop_fcode_forward                        = s->f_code;
     pic_param->vop_fcode_backward                       = s->b_code;
-    pic_param->vop_time_increment_resolution            = avctx->time_base.den;
+    pic_param->vop_time_increment_resolution            = avctx->framerate.num;
     pic_param->num_macroblocks_in_gob                   = s->mb_width * ff_h263_get_gob_height(s);
     pic_param->num_gobs_in_vop                          = (s->mb_width * s->mb_height) / pic_param->num_macroblocks_in_gob;
     pic_param->TRB                                      = s->pb_time;

libavcodec/vc1.c

@@ -485,19 +485,19 @@ static int decode_sequence_header_adv(VC1Context *v, GetBitContext *gb)
 
         if (get_bits1(gb)) { //framerate stuff
             if (get_bits1(gb)) {
-                v->s.avctx->time_base.num = 32;
-                v->s.avctx->time_base.den = get_bits(gb, 16) + 1;
+                v->s.avctx->framerate.den = 32;
+                v->s.avctx->framerate.num = get_bits(gb, 16) + 1;
             } else {
                 int nr, dr;
                 nr = get_bits(gb, 8);
                 dr = get_bits(gb, 4);
                 if (nr > 0 && nr < 8 && dr > 0 && dr < 3) {
-                    v->s.avctx->time_base.num = ff_vc1_fps_dr[dr - 1];
-                    v->s.avctx->time_base.den = ff_vc1_fps_nr[nr - 1] * 1000;
+                    v->s.avctx->framerate.den = ff_vc1_fps_dr[dr - 1];
+                    v->s.avctx->framerate.num = ff_vc1_fps_nr[nr - 1] * 1000;
                 }
             }
             if (v->broadcast) { // Pulldown may be present
-                v->s.avctx->time_base.den  *= 2;
+                v->s.avctx->framerate.num  *= 2;
                 v->s.avctx->ticks_per_frame = 2;
             }
         }

libavcodec/vdpau_mpeg4.c

@@ -61,7 +61,7 @@ static int vdpau_mpeg4_start_frame(AVCodecContext *avctx,
     info->trb[0]                            = s->pb_time;
     info->trd[1]                            = s->pp_field_time >> 1;
     info->trb[1]                            = s->pb_field_time >> 1;
-    info->vop_time_increment_resolution     = s->avctx->time_base.den;
+    info->vop_time_increment_resolution     = s->avctx->framerate.num;
     info->vop_fcode_forward                 = s->f_code;
     info->vop_fcode_backward                = s->b_code;
     info->resync_marker_disable             = !ctx->resync_marker;

libavcodec/version.h

@@ -29,7 +29,7 @@
 #include "libavutil/version.h"
 
 #define LIBAVCODEC_VERSION_MAJOR 56
-#define LIBAVCODEC_VERSION_MINOR  4
+#define LIBAVCODEC_VERSION_MINOR  5
 #define LIBAVCODEC_VERSION_MICRO  0
 
 #define LIBAVCODEC_VERSION_INT  AV_VERSION_INT(LIBAVCODEC_VERSION_MAJOR, \
@@ -156,5 +156,8 @@
 #ifndef FF_API_AUDIOENC_DELAY
 #define FF_API_AUDIOENC_DELAY    (LIBAVCODEC_VERSION_MAJOR < 58)
 #endif
+#ifndef FF_API_AVCTX_TIMEBASE
+#define FF_API_AVCTX_TIMEBASE    (LIBAVCODEC_VERSION_MAJOR < 59)
+#endif
 
 #endif /* AVCODEC_VERSION_H */

libavcodec/vp3.c

@@ -2233,7 +2233,7 @@ static int theora_decode_header(AVCodecContext *avctx, GetBitContext *gb)
             av_log(avctx, AV_LOG_ERROR, "Invalid framerate\n");
             return AVERROR_INVALIDDATA;
         }
-        av_reduce(&avctx->time_base.num, &avctx->time_base.den,
+        av_reduce(&avctx->framerate.den, &avctx->framerate.num,
                   fps.den, fps.num, 1 << 30);
     }