cmdutils.h 13.4 KB
Newer Older
Diego Biurrun's avatar
Diego Biurrun committed
1 2 3 4
/*
 * Various utilities for command line tools
 * copyright (c) 2003 Fabrice Bellard
 *
5
 * This file is part of Libav.
Diego Biurrun's avatar
Diego Biurrun committed
6
 *
7
 * Libav is free software; you can redistribute it and/or
Diego Biurrun's avatar
Diego Biurrun committed
8 9 10 11
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
12
 * Libav is distributed in the hope that it will be useful,
Diego Biurrun's avatar
Diego Biurrun committed
13 14 15 16 17
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
18
 * License along with Libav; if not, write to the Free Software
Diego Biurrun's avatar
Diego Biurrun committed
19 20 21
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

22 23
#ifndef LIBAV_CMDUTILS_H
#define LIBAV_CMDUTILS_H
Fabrice Bellard's avatar
Fabrice Bellard committed
24

25 26
#include <stdint.h>

27
#include "libavcodec/avcodec.h"
28
#include "libavfilter/avfilter.h"
29 30
#include "libavformat/avformat.h"
#include "libswscale/swscale.h"
31

32 33 34 35 36
/**
 * program name, defined by the program for show_version().
 */
extern const char program_name[];

37 38 39 40 41
/**
 * program birth year, defined by the program for show_banner()
 */
extern const int program_birth_year;

42
extern AVCodecContext *avcodec_opts[AVMEDIA_TYPE_NB];
43 44
extern AVFormatContext *avformat_opts;
extern struct SwsContext *sws_opts;
45
extern AVDictionary *format_opts, *codec_opts;
46

47 48 49 50 51 52 53 54 55 56 57
/**
 * Initialize the cmdutils option system, in particular
 * allocate the *_opts contexts.
 */
void init_opts(void);
/**
 * Uninitialize the cmdutils option system, in particular
 * free the *_opts contexts and their contents.
 */
void uninit_opts(void);

58 59 60 61 62 63
/**
 * Trivial log callback.
 * Only suitable for show_help and similar since it lacks prefix handling.
 */
void log_callback_help(void* ptr, int level, const char* fmt, va_list vl);

64
/**
65
 * Fallback for options that are not explicitly handled, these will be
66 67 68 69
 * parsed through AVOptions.
 */
int opt_default(const char *opt, const char *arg);

70
/**
71
 * Set the libav* libraries log level.
72 73 74
 */
int opt_loglevel(const char *opt, const char *arg);

Måns Rullgård's avatar
Måns Rullgård committed
75 76 77 78 79
/**
 * Limit the execution time.
 */
int opt_timelimit(const char *opt, const char *arg);

80
/**
81 82
 * Parse a string and return its corresponding value as a double.
 * Exit from the application if the string cannot be correctly
83
 * parsed or the corresponding value is invalid.
84 85
 *
 * @param context the context of the value to be set (e.g. the
Diego Biurrun's avatar
Diego Biurrun committed
86
 * corresponding command line option name)
87 88 89
 * @param numstr the string to be parsed
 * @param type the type (OPT_INT64 or OPT_FLOAT) as which the
 * string should be parsed
90 91
 * @param min the minimum valid accepted value
 * @param max the maximum valid accepted value
92
 */
93 94
double parse_number_or_die(const char *context, const char *numstr, int type,
                           double min, double max);
95

96
/**
97 98
 * Parse a string specifying a time and return its corresponding
 * value as a number of microseconds. Exit from the application if
99 100 101
 * the string cannot be correctly parsed.
 *
 * @param context the context of the value to be set (e.g. the
Diego Biurrun's avatar
Diego Biurrun committed
102
 * corresponding command line option name)
103
 * @param timestr the string to be parsed
104 105
 * @param is_duration a flag which tells how to interpret timestr, if
 * not zero timestr is interpreted as a duration, otherwise as a
106 107
 * date
 *
Stefano Sabatini's avatar
Typo  
Stefano Sabatini committed
108
 * @see parse_date()
109
 */
110 111
int64_t parse_time_or_die(const char *context, const char *timestr,
                          int is_duration);
112

113 114 115 116 117 118 119
typedef struct SpecifierOpt {
    char *specifier;    /**< stream/chapter/program/... specifier */
    union {
        uint8_t *str;
        int        i;
        int64_t  i64;
        float      f;
120
        double   dbl;
121 122 123
    } u;
} SpecifierOpt;

Fabrice Bellard's avatar
Fabrice Bellard committed
124 125 126 127 128 129 130
typedef struct {
    const char *name;
    int flags;
#define HAS_ARG    0x0001
#define OPT_BOOL   0x0002
#define OPT_EXPERT 0x0004
#define OPT_STRING 0x0008
131 132 133
#define OPT_VIDEO  0x0010
#define OPT_AUDIO  0x0020
#define OPT_GRAB   0x0040
Michael Niedermayer's avatar
OPT_INT  
Michael Niedermayer committed
134
#define OPT_INT    0x0080
Michael Niedermayer's avatar
Michael Niedermayer committed
135
#define OPT_FLOAT  0x0100
Fabrice Bellard's avatar
Fabrice Bellard committed
136
#define OPT_SUBTITLE 0x0200
Stefano Sabatini's avatar
Stefano Sabatini committed
137 138 139
#define OPT_INT64  0x0400
#define OPT_EXIT   0x0800
#define OPT_DATA   0x1000
140 141
#define OPT_FUNC2  0x2000
#define OPT_OFFSET 0x4000       /* option is specified as an offset in a passed optctx */
142 143 144
#define OPT_SPEC   0x8000       /* option is to be stored in an array of SpecifierOpt.
                                   Implies OPT_OFFSET. Next element after the offset is
                                   an int containing element count in the array. */
145
#define OPT_TIME  0x10000
146
#define OPT_DOUBLE 0x20000
Fabrice Bellard's avatar
Fabrice Bellard committed
147
     union {
148
        void *dst_ptr;
Stefano Sabatini's avatar
Stefano Sabatini committed
149
        int (*func_arg)(const char *, const char *);
150 151
        int (*func2_arg)(void *, const char *, const char *);
        size_t off;
Fabrice Bellard's avatar
Fabrice Bellard committed
152 153 154 155 156
    } u;
    const char *help;
    const char *argname;
} OptionDef;

157 158
void show_help_options(const OptionDef *options, const char *msg, int mask,
                       int value);
159

160 161 162 163 164 165
/**
 * Show help for all options with given flags in class and all its
 * children.
 */
void show_help_children(const AVClass *class, int flags);

166
/**
167
 * Parse the command line arguments.
168 169
 *
 * @param optctx an opaque options context
170
 * @param options Array with the definitions required to interpret every
171
 * option of the form: -option_name [argument]
172 173 174 175
 * @param parse_arg_function Name of the function called to process every
 * argument without a leading option name flag. NULL if such arguments do
 * not have to be processed.
 */
176 177
void parse_options(void *optctx, int argc, char **argv, const OptionDef *options,
                   void (* parse_arg_function)(void *optctx, const char*));
178

179 180 181 182 183
/**
 * Parse one given option.
 *
 * @return on success 1 if arg was consumed, 0 otherwise; negative number on error
 */
184 185
int parse_option(void *optctx, const char *opt, const char *arg,
                 const OptionDef *options);
186

187
/**
Diego Biurrun's avatar
Diego Biurrun committed
188
 * Find the '-loglevel' option in the command line args and apply it.
189 190 191
 */
void parse_loglevel(int argc, char **argv, const OptionDef *options);

192 193 194 195 196 197
/**
 * Return index of option opt in argv or 0 if not found.
 */
int locate_option(int argc, char **argv, const OptionDef *options,
                  const char *optname);

198 199 200 201 202
/**
 * Check if the given stream matches a stream specifier.
 *
 * @param s  Corresponding format context.
 * @param st Stream from s to be checked.
203
 * @param spec A stream specifier of the [v|a|s|d]:[\<stream index\>] form.
204 205 206 207 208
 *
 * @return 1 if the stream matches, 0 if it doesn't, <0 on error
 */
int check_stream_specifier(AVFormatContext *s, AVStream *st, const char *spec);

209 210
/**
 * Filter out options for given codec.
211 212 213 214
 *
 * Create a new options dictionary containing only the options from
 * opts which apply to the codec with ID codec_id.
 *
215 216
 * @param s Corresponding format context.
 * @param st A stream from s for which the options should be filtered.
217 218
 * @param codec The particular codec for which the options should be filtered.
 *              If null, the default one is looked up according to the codec id.
219
 * @return a pointer to the created dictionary
220
 */
221
AVDictionary *filter_codec_opts(AVDictionary *opts, enum AVCodecID codec_id,
222
                                AVFormatContext *s, AVStream *st, AVCodec *codec);
223

224 225 226 227 228 229 230 231 232 233
/**
 * Setup AVCodecContext options for avformat_find_stream_info().
 *
 * Create an array of dictionaries, one dictionary for each stream
 * contained in s.
 * Each dictionary will contain the options from codec_opts which can
 * be applied to the corresponding stream codec context.
 *
 * @return pointer to the created array of dictionaries, NULL if it
 * cannot be created
234
 */
235 236
AVDictionary **setup_find_stream_info_opts(AVFormatContext *s,
                                           AVDictionary *codec_opts);
237

238
/**
239
 * Print an error message to stderr, indicating filename and a human
240 241 242 243 244 245 246
 * readable description of the error code err.
 *
 * If strerror_r() is not available the use of this function in a
 * multithreaded application may be unsafe.
 *
 * @see av_strerror()
 */
Fabrice Bellard's avatar
Fabrice Bellard committed
247
void print_error(const char *filename, int err);
248

249
/**
250
 * Print the program banner to stderr. The banner contents depend on the
251 252
 * current version of the repository and of the libav* libraries used by
 * the program.
253
 */
254
void show_banner(void);
255 256

/**
257
 * Print the version of the program to stdout. The version message
258 259 260
 * depends on the current versions of the repository and of the libav*
 * libraries.
 */
261
void show_version(void);
262

263
/**
264
 * Print the license of the program to stdout. The license depends on
265
 * the license of the libraries compiled into the program.
266 267 268
 */
void show_license(void);

269
/**
270
 * Print a listing containing all the formats supported by the
271 272 273 274
 * program.
 */
void show_formats(void);

Michael Niedermayer's avatar
Michael Niedermayer committed
275
/**
276
 * Print a listing containing all the codecs supported by the
Michael Niedermayer's avatar
Michael Niedermayer committed
277 278 279 280
 * program.
 */
void show_codecs(void);

281 282 283 284 285 286 287 288 289 290 291 292
/**
 * Print a listing containing all the decoders supported by the
 * program.
 */
int show_decoders(const char *opt, const char *arg);

/**
 * Print a listing containing all the encoders supported by the
 * program.
 */
int show_encoders(const char *opt, const char *arg);

293
/**
294
 * Print a listing containing all the filters supported by the
295 296 297 298
 * program.
 */
void show_filters(void);

Michael Niedermayer's avatar
Michael Niedermayer committed
299
/**
300
 * Print a listing containing all the bit stream filters supported by the
Michael Niedermayer's avatar
Michael Niedermayer committed
301 302 303 304 305
 * program.
 */
void show_bsfs(void);

/**
306
 * Print a listing containing all the protocols supported by the
Michael Niedermayer's avatar
Michael Niedermayer committed
307 308 309 310
 * program.
 */
void show_protocols(void);

311
/**
312
 * Print a listing containing all the pixel formats supported by the
313 314 315 316
 * program.
 */
void show_pix_fmts(void);

317 318 319 320 321 322
/**
 * Print a listing containing all the sample formats supported by the
 * program.
 */
int show_sample_fmts(const char *opt, const char *arg);

Stefano Sabatini's avatar
Stefano Sabatini committed
323
/**
Måns Rullgård's avatar
Måns Rullgård committed
324 325
 * Return a positive value if a line read from standard input
 * starts with [yY], otherwise return 0.
Stefano Sabatini's avatar
Stefano Sabatini committed
326 327 328
 */
int read_yesno(void);

329
/**
330
 * Read the file with name filename, and put its content in a newly
331 332
 * allocated 0-terminated buffer.
 *
333 334
 * @param bufptr location where pointer to buffer is returned
 * @param size   location where size of buffer is returned
335 336 337
 * @return 0 in case of success, a negative value corresponding to an
 * AVERROR error code in case of failure.
 */
338
int cmdutils_read_file(const char *filename, char **bufptr, size_t *size);
339

340 341 342 343 344 345 346 347
typedef struct {
    int64_t num_faulty_pts; /// Number of incorrect PTS values so far
    int64_t num_faulty_dts; /// Number of incorrect DTS values so far
    int64_t last_pts;       /// PTS of the last frame
    int64_t last_dts;       /// DTS of the last frame
} PtsCorrectionContext;

/**
348
 * Reset the state of the PtsCorrectionContext.
349 350 351 352
 */
void init_pts_correction(PtsCorrectionContext *ctx);

/**
353
 * Attempt to guess proper monotonic timestamps for decoded video frames
354 355 356
 * which might have incorrect times. Input timestamps may wrap around, in
 * which case the output will as well.
 *
357
 * @param pts the pts field of the decoded AVPacket, as passed through
358
 * AVCodecContext.reordered_opaque
359 360
 * @param dts the dts field of the decoded AVPacket
 * @return one of the input values, may be AV_NOPTS_VALUE
361 362 363
 */
int64_t guess_correct_pts(PtsCorrectionContext *ctx, int64_t pts, int64_t dts);

364 365 366 367
/**
 * Get a file corresponding to a preset file.
 *
 * If is_path is non-zero, look for the file in the path preset_name.
368
 * Otherwise search for a file named arg.avpreset in the directories
369
 * $AVCONV_DATADIR (if set), $HOME/.avconv, and in the datadir defined
370 371
 * at configuration time, in that order. If no such file is found and
 * codec_name is defined, then search for a file named
372
 * codec_name-preset_name.avpreset in the above-mentioned directories.
373 374 375 376 377 378 379 380 381 382 383
 *
 * @param filename buffer where the name of the found filename is written
 * @param filename_size size in bytes of the filename buffer
 * @param preset_name name of the preset to search
 * @param is_path tell if preset_name is a filename path
 * @param codec_name name of the codec for which to look for the
 * preset, may be NULL
 */
FILE *get_preset_file(char *filename, size_t filename_size,
                      const char *preset_name, int is_path, const char *codec_name);

384 385 386 387
/**
 * Do all the necessary cleanup and abort.
 * This function is implemented in the avtools, not cmdutils.
 */
Reinhard Tartler's avatar
Reinhard Tartler committed
388
av_noreturn void exit_program(int ret);
389

390 391 392 393 394 395 396 397 398 399
/**
 * Realloc array to hold new_size elements of elem_size.
 * Calls exit_program() on failure.
 *
 * @param elem_size size in bytes of each element
 * @param size new element count will be written here
 * @return reallocated array
 */
void *grow_array(void *array, int elem_size, int *size, int new_size);

400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441
typedef struct FrameBuffer {
    uint8_t *base[4];
    uint8_t *data[4];
    int  linesize[4];

    int h, w;
    enum PixelFormat pix_fmt;

    int refcount;
    struct FrameBuffer **pool;  ///< head of the buffer pool
    struct FrameBuffer *next;
} FrameBuffer;

/**
 * Get a frame from the pool. This is intended to be used as a callback for
 * AVCodecContext.get_buffer.
 *
 * @param s codec context. s->opaque must be a pointer to the head of the
 *          buffer pool.
 * @param frame frame->opaque will be set to point to the FrameBuffer
 *              containing the frame data.
 */
int codec_get_buffer(AVCodecContext *s, AVFrame *frame);

/**
 * A callback to be used for AVCodecContext.release_buffer along with
 * codec_get_buffer().
 */
void codec_release_buffer(AVCodecContext *s, AVFrame *frame);

/**
 * A callback to be used for AVFilterBuffer.free.
 * @param fb buffer to free. fb->priv must be a pointer to the FrameBuffer
 *           containing the buffer data.
 */
void filter_release_buffer(AVFilterBuffer *fb);

/**
 * Free all the buffers in the pool. This must be called after all the
 * buffers have been released.
 */
void free_buffer_pool(FrameBuffer **pool);
442
#endif /* LIBAV_CMDUTILS_H */