cmdutils.h 18.5 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
/*
 * Various utilities for command line tools
 * copyright (c) 2003 Fabrice Bellard
 *
 * This file is part of FFmpeg.
 *
 * FFmpeg is free software; you can redistribute it and/or
 * 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.
 *
 * FFmpeg is distributed in the hope that it will be useful,
 * 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
 * License along with FFmpeg; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

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

25 26
#include <stdint.h>

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

33
#ifdef _WIN32
34 35 36
#undef main /* We don't want SDL to override our main() */
#endif

37 38 39 40 41
/**
 * program name, defined by the program for show_version().
 */
extern const char program_name[];

42 43 44 45 46
/**
 * program birth year, defined by the program for show_banner()
 */
extern const int program_birth_year;

47
extern AVCodecContext *avcodec_opts[AVMEDIA_TYPE_NB];
48
extern AVFormatContext *avformat_opts;
49
extern AVDictionary *sws_dict;
50
extern AVDictionary *swr_opts;
51
extern AVDictionary *format_opts, *codec_opts, *resample_opts;
52
extern int hide_banner;
53

54 55 56 57 58 59 60 61
/**
 * Register a program-specific cleanup routine.
 */
void register_exit(void (*cb)(int ret));

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

64 65 66 67 68
/**
 * Initialize dynamic library loading
 */
void init_dynload(void);

69 70 71 72 73 74 75 76 77 78 79
/**
 * 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);

80 81
/**
 * Trivial log callback.
82
 * Only suitable for opt_help and similar since it lacks prefix handling.
83 84 85
 */
void log_callback_help(void* ptr, int level, const char* fmt, va_list vl);

86
/**
87
 * Override the cpuflags.
88 89 90
 */
int opt_cpuflags(void *optctx, const char *opt, const char *arg);

91
/**
92
 * Fallback for options that are not explicitly handled, these will be
93 94
 * parsed through AVOptions.
 */
95
int opt_default(void *optctx, const char *opt, const char *arg);
96

97
/**
98
 * Set the libav* libraries log level.
99
 */
100
int opt_loglevel(void *optctx, const char *opt, const char *arg);
101

102
int opt_report(const char *opt);
103

104
int opt_max_alloc(void *optctx, const char *opt, const char *arg);
105

106
int opt_codec_debug(void *optctx, const char *opt, const char *arg);
107

108
#if CONFIG_OPENCL
109 110
int opt_opencl(void *optctx, const char *opt, const char *arg);

111 112 113
int opt_opencl_bench(void *optctx, const char *opt, const char *arg);
#endif

Måns Rullgård's avatar
Måns Rullgård committed
114 115 116
/**
 * Limit the execution time.
 */
117
int opt_timelimit(void *optctx, const char *opt, const char *arg);
Måns Rullgård's avatar
Måns Rullgård committed
118

119
/**
120 121
 * Parse a string and return its corresponding value as a double.
 * Exit from the application if the string cannot be correctly
122
 * parsed or the corresponding value is invalid.
123 124
 *
 * @param context the context of the value to be set (e.g. the
125
 * corresponding command line option name)
126 127 128
 * @param numstr the string to be parsed
 * @param type the type (OPT_INT64 or OPT_FLOAT) as which the
 * string should be parsed
129 130
 * @param min the minimum valid accepted value
 * @param max the maximum valid accepted value
131
 */
132 133
double parse_number_or_die(const char *context, const char *numstr, int type,
                           double min, double max);
134

135
/**
136 137
 * Parse a string specifying a time and return its corresponding
 * value as a number of microseconds. Exit from the application if
138 139 140
 * the string cannot be correctly parsed.
 *
 * @param context the context of the value to be set (e.g. the
141
 * corresponding command line option name)
142
 * @param timestr the string to be parsed
143 144
 * @param is_duration a flag which tells how to interpret timestr, if
 * not zero timestr is interpreted as a duration, otherwise as a
145 146
 * date
 *
147
 * @see av_parse_time()
148
 */
149 150
int64_t parse_time_or_die(const char *context, const char *timestr,
                          int is_duration);
151

152 153 154 155 156 157 158
typedef struct SpecifierOpt {
    char *specifier;    /**< stream/chapter/program/... specifier */
    union {
        uint8_t *str;
        int        i;
        int64_t  i64;
        float      f;
159
        double   dbl;
160 161 162
    } u;
} SpecifierOpt;

163
typedef struct OptionDef {
Fabrice Bellard's avatar
Fabrice Bellard committed
164 165 166 167 168 169
    const char *name;
    int flags;
#define HAS_ARG    0x0001
#define OPT_BOOL   0x0002
#define OPT_EXPERT 0x0004
#define OPT_STRING 0x0008
170 171
#define OPT_VIDEO  0x0010
#define OPT_AUDIO  0x0020
Michael Niedermayer's avatar
Michael Niedermayer committed
172
#define OPT_INT    0x0080
173
#define OPT_FLOAT  0x0100
Fabrice Bellard's avatar
Fabrice Bellard committed
174
#define OPT_SUBTITLE 0x0200
175 176 177
#define OPT_INT64  0x0400
#define OPT_EXIT   0x0800
#define OPT_DATA   0x1000
178
#define OPT_PERFILE  0x2000     /* the option is per-file (currently ffmpeg-only).
179
                                   implied by OPT_OFFSET or OPT_SPEC */
180
#define OPT_OFFSET 0x4000       /* option is specified as an offset in a passed optctx */
181 182 183
#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. */
184
#define OPT_TIME  0x10000
185
#define OPT_DOUBLE 0x20000
186 187
#define OPT_INPUT  0x40000
#define OPT_OUTPUT 0x80000
Fabrice Bellard's avatar
Fabrice Bellard committed
188
     union {
189
        void *dst_ptr;
190
        int (*func_arg)(void *, const char *, const char *);
191
        size_t off;
Fabrice Bellard's avatar
Fabrice Bellard committed
192 193 194 195 196
    } u;
    const char *help;
    const char *argname;
} OptionDef;

197 198 199 200 201 202 203
/**
 * 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.
204
 * @param alt_flags print only options that have at least one of those flags set
205 206
 */
void show_help_options(const OptionDef *options, const char *msg, int req_flags,
207
                       int rej_flags, int alt_flags);
208

209 210 211 212 213 214
/**
 * Show help for all options with given flags in class and all its
 * children.
 */
void show_help_children(const AVClass *class, int flags);

215
/**
216 217
 * Per-fftool specific help handler. Implemented in each
 * fftool, called by show_help().
218 219 220 221
 */
void show_help_default(const char *opt, const char *arg);

/**
222
 * Generic -h handler common to all fftools.
223
 */
224
int show_help(void *optctx, const char *opt, const char *arg);
225

226
/**
227
 * Parse the command line arguments.
228 229
 *
 * @param optctx an opaque options context
230 231
 * @param argc   number of command line arguments
 * @param argv   values of command line arguments
232
 * @param options Array with the definitions required to interpret every
233
 * option of the form: -option_name [argument]
234 235 236 237
 * @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.
 */
238 239
void parse_options(void *optctx, int argc, char **argv, const OptionDef *options,
                   void (* parse_arg_function)(void *optctx, const char*));
240

241 242 243 244 245
/**
 * Parse one given option.
 *
 * @return on success 1 if arg was consumed, 0 otherwise; negative number on error
 */
246 247
int parse_option(void *optctx, const char *opt, const char *arg,
                 const OptionDef *options);
248

249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264
/**
 * 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
265
     * are terminated by a non-option argument (e.g. ffmpeg output files)
266 267
     */
    const char *sep;
268 269 270 271 272
    /**
     * Option flags that must be set on each option that is
     * applied to this group
     */
    int flags;
273 274 275 276 277 278 279 280 281 282 283
} OptionGroupDef;

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

    Option *opts;
    int  nb_opts;

    AVDictionary *codec_opts;
    AVDictionary *format_opts;
284
    AVDictionary *resample_opts;
285
    AVDictionary *sws_dict;
286
    AVDictionary *swr_opts;
287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336
} 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,
337
                      const OptionGroupDef *groups, int nb_groups);
338 339 340 341 342 343

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

344
/**
345
 * Find the '-loglevel' option in the command line args and apply it.
346 347 348
 */
void parse_loglevel(int argc, char **argv, const OptionDef *options);

349 350 351 352 353 354
/**
 * 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);

355 356 357 358 359
/**
 * Check if the given stream matches a stream specifier.
 *
 * @param s  Corresponding format context.
 * @param st Stream from s to be checked.
360
 * @param spec A stream specifier of the [v|a|s|d]:[\<stream index\>] form.
361 362 363 364 365
 *
 * @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);

366 367
/**
 * Filter out options for given codec.
368 369 370 371
 *
 * Create a new options dictionary containing only the options from
 * opts which apply to the codec with ID codec_id.
 *
372 373
 * @param opts     dictionary to place options in
 * @param codec_id ID of the codec that should be filtered for
374 375
 * @param s Corresponding format context.
 * @param st A stream from s for which the options should be filtered.
376 377
 * @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.
378
 * @return a pointer to the created dictionary
379
 */
380
AVDictionary *filter_codec_opts(AVDictionary *opts, enum AVCodecID codec_id,
381
                                AVFormatContext *s, AVStream *st, AVCodec *codec);
382

383 384 385 386 387 388 389 390 391 392
/**
 * 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
393
 */
394 395
AVDictionary **setup_find_stream_info_opts(AVFormatContext *s,
                                           AVDictionary *codec_opts);
396

397
/**
398
 * Print an error message to stderr, indicating filename and a human
399 400 401 402 403 404 405
 * 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
406 407
void print_error(const char *filename, int err);

408
/**
409
 * Print the program banner to stderr. The banner contents depend on the
410 411
 * current version of the repository and of the libav* libraries used by
 * the program.
412
 */
413
void show_banner(int argc, char **argv, const OptionDef *options);
414 415

/**
416
 * Print the version of the program to stdout. The version message
417 418
 * depends on the current versions of the repository and of the libav*
 * libraries.
419
 * This option processing function does not utilize the arguments.
420
 */
421
int show_version(void *optctx, const char *opt, const char *arg);
422

423 424 425 426 427 428 429
/**
 * Print the build configuration of the program to stdout. The contents
 * depend on the definition of FFMPEG_CONFIGURATION.
 * This option processing function does not utilize the arguments.
 */
int show_buildconf(void *optctx, const char *opt, const char *arg);

430
/**
431
 * Print the license of the program to stdout. The license depends on
432
 * the license of the libraries compiled into the program.
433
 * This option processing function does not utilize the arguments.
434
 */
435
int show_license(void *optctx, const char *opt, const char *arg);
436

437
/**
438
 * Print a listing containing all the formats supported by the
439
 * program (including devices).
440
 * This option processing function does not utilize the arguments.
441
 */
442
int show_formats(void *optctx, const char *opt, const char *arg);
443

444 445 446 447 448 449 450
/**
 * Print a listing containing all the devices supported by the
 * program.
 * This option processing function does not utilize the arguments.
 */
int show_devices(void *optctx, const char *opt, const char *arg);

451 452 453 454 455 456 457 458 459 460 461 462 463 464
#if CONFIG_AVDEVICE
/**
 * Print a listing containing audodetected sinks of the output device.
 * Device name with options may be passed as an argument to limit results.
 */
int show_sinks(void *optctx, const char *opt, const char *arg);

/**
 * Print a listing containing audodetected sources of the input device.
 * Device name with options may be passed as an argument to limit results.
 */
int show_sources(void *optctx, const char *opt, const char *arg);
#endif

465
/**
466
 * Print a listing containing all the codecs supported by the
467
 * program.
468
 * This option processing function does not utilize the arguments.
469
 */
470
int show_codecs(void *optctx, const char *opt, const char *arg);
471

472 473 474 475
/**
 * Print a listing containing all the decoders supported by the
 * program.
 */
476
int show_decoders(void *optctx, const char *opt, const char *arg);
477 478 479 480 481

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

484
/**
485
 * Print a listing containing all the filters supported by the
486
 * program.
487
 * This option processing function does not utilize the arguments.
488
 */
489
int show_filters(void *optctx, const char *opt, const char *arg);
490

491
/**
492
 * Print a listing containing all the bit stream filters supported by the
493
 * program.
494
 * This option processing function does not utilize the arguments.
495
 */
496
int show_bsfs(void *optctx, const char *opt, const char *arg);
497 498

/**
499
 * Print a listing containing all the protocols supported by the
500
 * program.
501
 * This option processing function does not utilize the arguments.
502
 */
503
int show_protocols(void *optctx, const char *opt, const char *arg);
504

505
/**
506
 * Print a listing containing all the pixel formats supported by the
507
 * program.
508
 * This option processing function does not utilize the arguments.
509
 */
510
int show_pix_fmts(void *optctx, const char *opt, const char *arg);
511

512 513 514 515 516
/**
 * Print a listing containing all the standard channel layouts supported by
 * the program.
 * This option processing function does not utilize the arguments.
 */
517
int show_layouts(void *optctx, const char *opt, const char *arg);
518

519 520 521 522
/**
 * Print a listing containing all the sample formats supported by the
 * program.
 */
523
int show_sample_fmts(void *optctx, const char *opt, const char *arg);
524

525 526 527 528
/**
 * Print a listing containing all the color names and values recognized
 * by the program.
 */
529
int show_colors(void *optctx, const char *opt, const char *arg);
530

531
/**
Måns Rullgård's avatar
Måns Rullgård committed
532 533
 * Return a positive value if a line read from standard input
 * starts with [yY], otherwise return 0.
534 535 536
 */
int read_yesno(void);

537 538 539 540 541 542
/**
 * Get a file corresponding to a preset file.
 *
 * If is_path is non-zero, look for the file in the path preset_name.
 * Otherwise search for a file named arg.ffpreset in the directories
 * $FFMPEG_DATADIR (if set), $HOME/.ffmpeg, and in the datadir defined
Gianluigi Tiesi's avatar
Gianluigi Tiesi committed
543 544
 * at configuration time or in a "ffpresets" folder along the executable
 * on win32, in that order. If no such file is found and
545
 * codec_name is defined, then search for a file named
546
 * codec_name-preset_name.avpreset in the above-mentioned directories.
547 548 549 550 551 552 553 554 555 556 557
 *
 * @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);

558 559
/**
 * Realloc array to hold new_size elements of elem_size.
560
 * Calls exit() on failure.
561
 *
562
 * @param array array to reallocate
563 564
 * @param elem_size size in bytes of each element
 * @param size new element count will be written here
565
 * @param new_size number of elements to place in reallocated array
566 567 568 569
 * @return reallocated array
 */
void *grow_array(void *array, int elem_size, int *size, int new_size);

570
#define media_type_string av_get_media_type_string
571

572 573 574
#define GROW_ARRAY(array, nb_elems)\
    array = grow_array(array, sizeof(*array), &nb_elems, nb_elems + 1)

575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592
#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);

593 594
double get_rotation(AVStream *st);

595
#endif /* CMDUTILS_H */