cmdutils.h 17.3 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, *resample_opts;
46

Luca Barbato's avatar
Luca Barbato committed
47 48 49 50 51 52 53 54 55 56
/**
 * Register a program-specific cleanup routine.
 */
void register_exit(void (*cb)(int ret));

/**
 * Wraps exit with a program-specific cleanup routine.
 */
void exit_program(int ret);

57 58 59 60 61 62 63 64 65 66 67
/**
 * 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);

68 69 70 71 72 73
/**
 * 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);

74
/**
75
 * Fallback for options that are not explicitly handled, these will be
76 77
 * parsed through AVOptions.
 */
78
int opt_default(void *optctx, const char *opt, const char *arg);
79

80
/**
81
 * Set the libav* libraries log level.
82
 */
83
int opt_loglevel(void *optctx, const char *opt, const char *arg);
84

Måns Rullgård's avatar
Måns Rullgård committed
85 86 87
/**
 * Limit the execution time.
 */
88
int opt_timelimit(void *optctx, const char *opt, const char *arg);
Måns Rullgård's avatar
Måns Rullgård committed
89

90
/**
91 92
 * Parse a string and return its corresponding value as a double.
 * Exit from the application if the string cannot be correctly
93
 * parsed or the corresponding value is invalid.
94 95
 *
 * @param context the context of the value to be set (e.g. the
Diego Biurrun's avatar
Diego Biurrun committed
96
 * corresponding command line option name)
97 98 99
 * @param numstr the string to be parsed
 * @param type the type (OPT_INT64 or OPT_FLOAT) as which the
 * string should be parsed
100 101
 * @param min the minimum valid accepted value
 * @param max the maximum valid accepted value
102
 */
103 104
double parse_number_or_die(const char *context, const char *numstr, int type,
                           double min, double max);
105

106
/**
107 108
 * Parse a string specifying a time and return its corresponding
 * value as a number of microseconds. Exit from the application if
109 110 111
 * 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
112
 * corresponding command line option name)
113
 * @param timestr the string to be parsed
114 115
 * @param is_duration a flag which tells how to interpret timestr, if
 * not zero timestr is interpreted as a duration, otherwise as a
116 117
 * date
 *
Stefano Sabatini's avatar
Typo  
Stefano Sabatini committed
118
 * @see parse_date()
119
 */
120 121
int64_t parse_time_or_die(const char *context, const char *timestr,
                          int is_duration);
122

123 124 125 126 127 128 129
typedef struct SpecifierOpt {
    char *specifier;    /**< stream/chapter/program/... specifier */
    union {
        uint8_t *str;
        int        i;
        int64_t  i64;
        float      f;
130
        double   dbl;
131 132 133
    } u;
} SpecifierOpt;

134
typedef struct OptionDef {
Fabrice Bellard's avatar
Fabrice Bellard committed
135 136 137 138 139 140
    const char *name;
    int flags;
#define HAS_ARG    0x0001
#define OPT_BOOL   0x0002
#define OPT_EXPERT 0x0004
#define OPT_STRING 0x0008
141 142
#define OPT_VIDEO  0x0010
#define OPT_AUDIO  0x0020
Michael Niedermayer's avatar
OPT_INT  
Michael Niedermayer committed
143
#define OPT_INT    0x0080
Michael Niedermayer's avatar
Michael Niedermayer committed
144
#define OPT_FLOAT  0x0100
Fabrice Bellard's avatar
Fabrice Bellard committed
145
#define OPT_SUBTITLE 0x0200
Stefano Sabatini's avatar
Stefano Sabatini committed
146 147 148
#define OPT_INT64  0x0400
#define OPT_EXIT   0x0800
#define OPT_DATA   0x1000
149 150
#define OPT_PERFILE  0x2000     /* the option is per-file (currently avconv-only).
                                   implied by OPT_OFFSET or OPT_SPEC */
151
#define OPT_OFFSET 0x4000       /* option is specified as an offset in a passed optctx */
152 153 154
#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. */
155
#define OPT_TIME  0x10000
156
#define OPT_DOUBLE 0x20000
157 158
#define OPT_INPUT  0x40000
#define OPT_OUTPUT 0x80000
Fabrice Bellard's avatar
Fabrice Bellard committed
159
     union {
160
        void *dst_ptr;
161
        int (*func_arg)(void *, const char *, const char *);
162
        size_t off;
Fabrice Bellard's avatar
Fabrice Bellard committed
163 164 165 166 167
    } u;
    const char *help;
    const char *argname;
} OptionDef;

168 169 170 171 172 173 174
/**
 * Print help for all options matching specified flags.
 *
 * @param options a list of options
 * @param msg title of this group. Only printed if at least one option matches.
 * @param req_flags print only options which have all those flags set.
 * @param rej_flags don't print options which have any of those flags set.
175
 * @param alt_flags print only options that have at least one of those flags set
176 177
 */
void show_help_options(const OptionDef *options, const char *msg, int req_flags,
178
                       int rej_flags, int alt_flags);
179

180 181 182 183 184 185
/**
 * Show help for all options with given flags in class and all its
 * children.
 */
void show_help_children(const AVClass *class, int flags);

186 187 188 189 190 191 192 193 194
/**
 * Per-avtool specific help handler. Implemented in each
 * avtool, called by show_help().
 */
void show_help_default(const char *opt, const char *arg);

/**
 * Generic -h handler common to all avtools.
 */
195
int show_help(void *optctx, const char *opt, const char *arg);
196

197
/**
198
 * Parse the command line arguments.
199 200
 *
 * @param optctx an opaque options context
201 202
 * @param argc   number of command line arguments
 * @param argv   values of command line arguments
203
 * @param options Array with the definitions required to interpret every
204
 * option of the form: -option_name [argument]
205 206 207 208
 * @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.
 */
209 210
void parse_options(void *optctx, int argc, char **argv, const OptionDef *options,
                   void (* parse_arg_function)(void *optctx, const char*));
211

212 213 214 215 216
/**
 * Parse one given option.
 *
 * @return on success 1 if arg was consumed, 0 otherwise; negative number on error
 */
217 218
int parse_option(void *optctx, const char *opt, const char *arg,
                 const OptionDef *options);
219

220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238
/**
 * An option extracted from the commandline.
 * Cannot use AVDictionary because of options like -map which can be
 * used multiple times.
 */
typedef struct Option {
    const OptionDef  *opt;
    const char       *key;
    const char       *val;
} Option;

typedef struct OptionGroupDef {
    /**< group name */
    const char *name;
    /**
     * Option to be used as group separator. Can be NULL for groups which
     * are terminated by a non-option argument (e.g. avconv output files)
     */
    const char *sep;
239 240 241 242 243
    /**
     * Option flags that must be set on each option that is
     * applied to this group
     */
    int flags;
244 245 246 247 248 249 250 251 252 253 254
} OptionGroupDef;

typedef struct OptionGroup {
    const OptionGroupDef *group_def;
    const char *arg;

    Option *opts;
    int  nb_opts;

    AVDictionary *codec_opts;
    AVDictionary *format_opts;
255
    AVDictionary *resample_opts;
256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306
    struct SwsContext *sws_opts;
} OptionGroup;

/**
 * A list of option groups that all have the same group type
 * (e.g. input files or output files)
 */
typedef struct OptionGroupList {
    const OptionGroupDef *group_def;

    OptionGroup *groups;
    int       nb_groups;
} OptionGroupList;

typedef struct OptionParseContext {
    OptionGroup global_opts;

    OptionGroupList *groups;
    int           nb_groups;

    /* parsing state */
    OptionGroup cur_group;
} OptionParseContext;

/**
 * Parse an options group and write results into optctx.
 *
 * @param optctx an app-specific options context. NULL for global options group
 */
int parse_optgroup(void *optctx, OptionGroup *g);

/**
 * Split the commandline into an intermediate form convenient for further
 * processing.
 *
 * The commandline is assumed to be composed of options which either belong to a
 * group (those with OPT_SPEC, OPT_OFFSET or OPT_PERFILE) or are global
 * (everything else).
 *
 * A group (defined by an OptionGroupDef struct) is a sequence of options
 * terminated by either a group separator option (e.g. -i) or a parameter that
 * is not an option (doesn't start with -). A group without a separator option
 * must always be first in the supplied groups list.
 *
 * All options within the same group are stored in one OptionGroup struct in an
 * OptionGroupList, all groups with the same group definition are stored in one
 * OptionGroupList in OptionParseContext.groups. The order of group lists is the
 * same as the order of group definitions.
 */
int split_commandline(OptionParseContext *octx, int argc, char *argv[],
                      const OptionDef *options,
307
                      const OptionGroupDef *groups, int nb_groups);
308 309 310 311 312 313

/**
 * Free all allocated memory in an OptionParseContext.
 */
void uninit_parse_context(OptionParseContext *octx);

314
/**
Diego Biurrun's avatar
Diego Biurrun committed
315
 * Find the '-loglevel' option in the command line args and apply it.
316 317 318
 */
void parse_loglevel(int argc, char **argv, const OptionDef *options);

319 320 321 322 323 324
/**
 * 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);

325 326 327 328 329
/**
 * Check if the given stream matches a stream specifier.
 *
 * @param s  Corresponding format context.
 * @param st Stream from s to be checked.
330
 * @param spec A stream specifier of the [v|a|s|d]:[\<stream index\>] form.
331 332 333 334 335
 *
 * @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);

336 337
/**
 * Filter out options for given codec.
338 339 340 341
 *
 * Create a new options dictionary containing only the options from
 * opts which apply to the codec with ID codec_id.
 *
342 343
 * @param opts     dictionary to place options in
 * @param codec_id ID of the codec that should be filtered for
344 345
 * @param s Corresponding format context.
 * @param st A stream from s for which the options should be filtered.
346 347
 * @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.
348
 * @return a pointer to the created dictionary
349
 */
350
AVDictionary *filter_codec_opts(AVDictionary *opts, enum AVCodecID codec_id,
351
                                AVFormatContext *s, AVStream *st, AVCodec *codec);
352

353 354 355 356 357 358 359 360 361 362
/**
 * 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
363
 */
364 365
AVDictionary **setup_find_stream_info_opts(AVFormatContext *s,
                                           AVDictionary *codec_opts);
366

367
/**
368
 * Print an error message to stderr, indicating filename and a human
369 370 371 372 373 374 375
 * 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
376
void print_error(const char *filename, int err);
377

378
/**
379
 * Print the program banner to stderr. The banner contents depend on the
380 381
 * current version of the repository and of the libav* libraries used by
 * the program.
382
 */
383
void show_banner(void);
384 385

/**
386
 * Print the version of the program to stdout. The version message
387 388 389
 * depends on the current versions of the repository and of the libav*
 * libraries.
 */
390
int show_version(void *optctx, const char *opt, const char *arg);
391

392
/**
393
 * Print the license of the program to stdout. The license depends on
394
 * the license of the libraries compiled into the program.
395
 */
396
int show_license(void *optctx, const char *opt, const char *arg);
397

398
/**
399
 * Print a listing containing all the formats supported by the
400 401
 * program.
 */
402
int show_formats(void *optctx, const char *opt, const char *arg);
403

Michael Niedermayer's avatar
Michael Niedermayer committed
404
/**
405
 * Print a listing containing all the codecs supported by the
Michael Niedermayer's avatar
Michael Niedermayer committed
406 407
 * program.
 */
408
int show_codecs(void *optctx, const char *opt, const char *arg);
Michael Niedermayer's avatar
Michael Niedermayer committed
409

410 411 412 413
/**
 * Print a listing containing all the decoders supported by the
 * program.
 */
414
int show_decoders(void *optctx, const char *opt, const char *arg);
415 416 417 418 419

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

422
/**
423
 * Print a listing containing all the filters supported by the
424 425
 * program.
 */
426
int show_filters(void *optctx, const char *opt, const char *arg);
427

Michael Niedermayer's avatar
Michael Niedermayer committed
428
/**
429
 * Print a listing containing all the bit stream filters supported by the
Michael Niedermayer's avatar
Michael Niedermayer committed
430 431
 * program.
 */
432
int show_bsfs(void *optctx, const char *opt, const char *arg);
Michael Niedermayer's avatar
Michael Niedermayer committed
433 434

/**
435
 * Print a listing containing all the protocols supported by the
Michael Niedermayer's avatar
Michael Niedermayer committed
436 437
 * program.
 */
438
int show_protocols(void *optctx, const char *opt, const char *arg);
Michael Niedermayer's avatar
Michael Niedermayer committed
439

440
/**
441
 * Print a listing containing all the pixel formats supported by the
442 443
 * program.
 */
444
int show_pix_fmts(void *optctx, const char *opt, const char *arg);
445

446 447 448 449
/**
 * Print a listing containing all the sample formats supported by the
 * program.
 */
450
int show_sample_fmts(void *optctx, const char *opt, const char *arg);
451

Stefano Sabatini's avatar
Stefano Sabatini committed
452
/**
Måns Rullgård's avatar
Måns Rullgård committed
453 454
 * Return a positive value if a line read from standard input
 * starts with [yY], otherwise return 0.
Stefano Sabatini's avatar
Stefano Sabatini committed
455 456 457
 */
int read_yesno(void);

458
/**
459
 * Read the file with name filename, and put its content in a newly
460 461
 * allocated 0-terminated buffer.
 *
462
 * @param filename file to read from
463 464
 * @param bufptr location where pointer to buffer is returned
 * @param size   location where size of buffer is returned
465 466 467
 * @return 0 in case of success, a negative value corresponding to an
 * AVERROR error code in case of failure.
 */
468
int cmdutils_read_file(const char *filename, char **bufptr, size_t *size);
469

470
typedef struct PtsCorrectionContext {
471 472 473 474 475 476 477
    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;

/**
478
 * Reset the state of the PtsCorrectionContext.
479 480 481 482
 */
void init_pts_correction(PtsCorrectionContext *ctx);

/**
483
 * Attempt to guess proper monotonic timestamps for decoded video frames
484 485 486
 * which might have incorrect times. Input timestamps may wrap around, in
 * which case the output will as well.
 *
487
 * @param ctx the PtsCorrectionContext carrying stream pts information
488
 * @param pts the pts field of the decoded AVPacket, as passed through
489
 * AVCodecContext.reordered_opaque
490 491
 * @param dts the dts field of the decoded AVPacket
 * @return one of the input values, may be AV_NOPTS_VALUE
492 493 494
 */
int64_t guess_correct_pts(PtsCorrectionContext *ctx, int64_t pts, int64_t dts);

495 496 497 498
/**
 * Get a file corresponding to a preset file.
 *
 * If is_path is non-zero, look for the file in the path preset_name.
499
 * Otherwise search for a file named arg.avpreset in the directories
500
 * $AVCONV_DATADIR (if set), $HOME/.avconv, and in the datadir defined
501 502
 * at configuration time, in that order. If no such file is found and
 * codec_name is defined, then search for a file named
503
 * codec_name-preset_name.avpreset in the above-mentioned directories.
504 505 506 507 508 509 510 511 512 513 514
 *
 * @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);

515 516
/**
 * Realloc array to hold new_size elements of elem_size.
517
 * Calls exit() on failure.
518
 *
519
 * @param array array to reallocate
520 521
 * @param elem_size size in bytes of each element
 * @param size new element count will be written here
522
 * @param new_size number of elements to place in reallocated array
523 524 525 526
 * @return reallocated array
 */
void *grow_array(void *array, int elem_size, int *size, int new_size);

527 528 529 530 531
/**
 * Get a string describing a media type.
 */
const char *media_type_string(enum AVMediaType media_type);

532 533 534
#define GROW_ARRAY(array, nb_elems)\
    array = grow_array(array, sizeof(*array), &nb_elems, nb_elems + 1)

535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552
#define GET_PIX_FMT_NAME(pix_fmt)\
    const char *name = av_get_pix_fmt_name(pix_fmt);

#define GET_SAMPLE_FMT_NAME(sample_fmt)\
    const char *name = av_get_sample_fmt_name(sample_fmt)

#define GET_SAMPLE_RATE_NAME(rate)\
    char name[16];\
    snprintf(name, sizeof(name), "%d", rate);

#define GET_CH_LAYOUT_NAME(ch_layout)\
    char name[16];\
    snprintf(name, sizeof(name), "0x%"PRIx64, ch_layout);

#define GET_CH_LAYOUT_DESC(ch_layout)\
    char name[128];\
    av_get_channel_layout_string(name, sizeof(name), 0, ch_layout);

553
#endif /* LIBAV_CMDUTILS_H */