[FFmpeg-devel] [PATCH 02/12] lavu: add public timecode API.

[Stefano Sabatini]

On date Monday 2012-01-23 17:04:21 +0100, Clément Bœsch encoded:
> From: Clément Bœsch <clement.boesch at smartjog.com>
> 
> ---
>  doc/APIchanges       |    3 +
>  libavutil/Makefile   |    2 +
>  libavutil/avutil.h   |    4 +-
>  libavutil/timecode.c |  174 ++++++++++++++++++++++++++++++++++++++++++++++++++
>  libavutil/timecode.h |  125 ++++++++++++++++++++++++++++++++++++
>  5 files changed, 306 insertions(+), 2 deletions(-)
>  create mode 100644 libavutil/timecode.c
>  create mode 100644 libavutil/timecode.h
[...] 
> +/**
> + * @file
> + * Timecode helpers header
> + */
> +
> +#ifndef AVUTIL_TIMECODE_H
> +#define AVUTIL_TIMECODE_H
> +
> +#include <stdint.h>
> +#include "rational.h"
> +
> +#define AV_TIMECODE_STR_SIZE 16
> +
> +#define AV_TIMECODE_OPTION(ctx, string_field, flags)                     \
> +    "timecode", "set timecode value following hh:mm:ss[:;.]ff format, "  \
> +                "use ';' or '.' before frame number for drop frame",     \
> +    offsetof(ctx, string_field),                                         \
> +    AV_OPT_TYPE_STRING, {.str=NULL}, CHAR_MIN, CHAR_MAX, flags
> +
> +enum AVTimecodeFlag {
> +    AV_TIMECODE_FLAG_DROPFRAME     = 1<<0, ///< timecode is drop frame
> +    AV_TIMECODE_FLAG_24HOURSMAX    = 1<<1, ///< timecode wraps after 24 hours
> +    AV_TIMECODE_FLAG_ALLOWNEGATIVE = 1<<2, ///< negative time values are allowed
> +};
> +
> +typedef struct {
> +    int start;          ///< timecode frame start (first base frame number)
> +    uint32_t flags;     ///< flags such as drop frame, +24 hours support, ...
> +    AVRational rate;    ///< frame rate in rational form
> +    unsigned fps;       ///< frame per second; must be consistent with the rate field
> +} AVTimecode;
> +
> +/**
> + * Adjust frame number for NTSC drop frame time code.
> + *
> + * @param framenum frame number to adjust
> + * @return         adjusted frame number
> + * @warning        adjustment is only valid in NTSC 29.97
> + */
> +int av_timecode_adjust_ntsc_framenum(int framenum);
> +

> +/**
> + * Convert frame number to SMPTE 12M binary representation.
> + *
> + * @param tc       timecode data correctly initialized
> + * @param framenum frame number
> + * @return         the SMPTE binary representation
> + *

> + * @note Frame number adjustment is automatically done in case of drop timecode,
> + *       you do NOT have to call av_adjust_ntsc_framenum().

nit++: no complete sentence, lowcased and no dot at the end

> + * @note The frame number is relative to tc->start.

same here

> + */
> +uint32_t av_timecode_get_smpte_from_framenum(const AVTimecode *tc, int framenum);

Nit: get->make is maybe more approriate (as noted by Alexander
Strasser in a recent mail)

> +
> +/**
> + * Load timecode string in buf.
> + *
> + * @param buf      destination buffer, must be at least AV_TIMECODE_STR_SIZE long
> + * @param tc       timecode data correctly initialized
> + * @param framenum frame number
> + * @return         the buf parameter
> + *

> + * @note Timecode representation can be a negative timecode and have more than
> + *       24 hours, but will only be honored if the flags are correctly set.
> + * @note The frame number is relative to tc->start.

ditto

> + */
> +char *av_timecode_get_string(char *buf, const AVTimecode *tc, int framenum);

ditto: get -> make?


> +/**
> + * Get the timecode string from the 25-bit timecode format (MPEG GOP format).
> + *
> + * @param buf     destination buffer, must be at least AV_TIMECODE_STR_SIZE long
> + * @param tc25bit the 25-bits timecode
> + * @return        the buf parameter
> + */
> +char *av_timecode_get_mpegtc_string(char *buf, uint32_t tc25bit);

make?

> +
> +/**
> + * Init a timecode struct with the passed parameters.
> + *
> + * @param log_ctx     a pointer to an arbitrary struct of which the first field
> + *                    is a pointer to an AVClass struct (used for av_log)
> + * @param tc          pointer to an allocated AVTimecode
> + * @param rate        frame rate in rational form
> + * @param flags       miscellaneous flags such as drop frame, +24 hours, ...
> + *                    (see AVTimecodeFlag)
> + * @param frame_start the first frame number
> + * @return            0 on success, AVERROR otherwise
> + */

> +int av_timecode_init(void *log_ctx, AVTimecode *tc, AVRational rate, int flags, int frame_start);
> +
> +/**
> + * Parse timecode representation (hh:mm:ss[:;.]ff).
> + *
> + * @param log_ctx a pointer to an arbitrary struct of which the first field is a
> + *                pointer to an AVClass struct (used for av_log).
> + * @param tc      pointer to an allocated AVTimecode
> + * @param rate    frame rate in rational form
> + * @param str     timecode string which will determine the frame start
> + * @return        0 on success, AVERROR otherwise
> + */
> +int av_timecode_init_from_string(void *log_ctx, AVTimecode *tc, AVRational rate, const char *str);

For these two, either make or init should be fine, I have no strong
opinion though but a slight bias towards "make" for internal
consistency reasons.
-- 
FFmpeg = Frightening and Funny Majestic Puristic Experimenting Generator