1 /* 2 * Various utilities for command line tools 3 * copyright (c) 2003 Fabrice Bellard 4 * 5 * This file is part of FFmpeg. 6 * 7 * FFmpeg is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU Lesser General Public 9 * License as published by the Free Software Foundation; either 10 * version 2.1 of the License, or (at your option) any later version. 11 * 12 * FFmpeg is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Lesser General Public License for more details. 16 * 17 * You should have received a copy of the GNU Lesser General Public 18 * License along with FFmpeg; if not, write to the Free Software 19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA 20 */ 21 22 #ifndef FFTOOLS_CMDUTILS_H 23 #define FFTOOLS_CMDUTILS_H 24 25 #include <stdint.h> 26 27 #include "config.h" 28 #include "libavcodec/avcodec.h" 29 #include "libavfilter/avfilter.h" 30 #include "libavformat/avformat.h" 31 #include "libswscale/swscale.h" 32 33 #ifdef _WIN32 34 #undef main /* We don't want SDL to override our main() */ 35 #endif 36 37 /** 38 * program name, defined by the program for show_version(). 39 */ 40 extern const char program_name[]; 41 42 /** 43 * program birth year, defined by the program for show_banner() 44 */ 45 extern const int program_birth_year; 46 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 * Register a program-specific cleanup routine. 56 */ 57 void register_exit(void (*cb)(int ret)); 58 59 /** 60 * Wraps exit with a program-specific cleanup routine. 61 */ 62 void exit_program(int ret) av_noreturn; 63 64 /** 65 * Initialize dynamic library loading 66 */ 67 void init_dynload(void); 68 69 /** 70 * Initialize the cmdutils option system, in particular 71 * allocate the *_opts contexts. 72 */ 73 void init_opts(void); 74 /** 75 * Uninitialize the cmdutils option system, in particular 76 * free the *_opts contexts and their contents. 77 */ 78 void uninit_opts(void); 79 80 /** 81 * Trivial log callback. 82 * Only suitable for opt_help and similar since it lacks prefix handling. 83 */ 84 void log_callback_help(void* ptr, int level, const char* fmt, va_list vl); 85 86 /** 87 * Override the cpuflags. 88 */ 89 int opt_cpuflags(void *optctx, const char *opt, const char *arg); 90 91 /** 92 * Fallback for options that are not explicitly handled, these will be 93 * parsed through AVOptions. 94 */ 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(void *optctx, const char *opt, const char *arg); 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 /** 109 * Limit the execution time. 110 */ 111 int opt_timelimit(void *optctx, const char *opt, const char *arg); 112 113 /** 114 * Parse a string and return its corresponding value as a double. 115 * Exit from the application if the string cannot be correctly 116 * parsed or the corresponding value is invalid. 117 * 118 * @param context the context of the value to be set (e.g. the 119 * corresponding command line option name) 120 * @param numstr the string to be parsed 121 * @param type the type (OPT_INT64 or OPT_FLOAT) as which the 122 * string should be parsed 123 * @param min the minimum valid accepted value 124 * @param max the maximum valid accepted value 125 */ 126 double parse_number_or_die(const char *context, const char *numstr, int type, 127 double min, double max); 128 129 /** 130 * Parse a string specifying a time and return its corresponding 131 * value as a number of microseconds. Exit from the application if 132 * the string cannot be correctly parsed. 133 * 134 * @param context the context of the value to be set (e.g. the 135 * corresponding command line option name) 136 * @param timestr the string to be parsed 137 * @param is_duration a flag which tells how to interpret timestr, if 138 * not zero timestr is interpreted as a duration, otherwise as a 139 * date 140 * 141 * @see av_parse_time() 142 */ 143 int64_t parse_time_or_die(const char *context, const char *timestr, 144 int is_duration); 145 146 typedef struct SpecifierOpt { 147 char *specifier; /**< stream/chapter/program/... specifier */ 148 union { 149 uint8_t *str; 150 int i; 151 int64_t i64; 152 uint64_t ui64; 153 float f; 154 double dbl; 155 } u; 156 } SpecifierOpt; 157 158 typedef struct OptionDef { 159 const char *name; 160 int flags; 161 #define HAS_ARG 0x0001 162 #define OPT_BOOL 0x0002 163 #define OPT_EXPERT 0x0004 164 #define OPT_STRING 0x0008 165 #define OPT_VIDEO 0x0010 166 #define OPT_AUDIO 0x0020 167 #define OPT_INT 0x0080 168 #define OPT_FLOAT 0x0100 169 #define OPT_SUBTITLE 0x0200 170 #define OPT_INT64 0x0400 171 #define OPT_EXIT 0x0800 172 #define OPT_DATA 0x1000 173 #define OPT_PERFILE 0x2000 /* the option is per-file (currently ffmpeg-only). 174 implied by OPT_OFFSET or OPT_SPEC */ 175 #define OPT_OFFSET 0x4000 /* option is specified as an offset in a passed optctx */ 176 #define OPT_SPEC 0x8000 /* option is to be stored in an array of SpecifierOpt. 177 Implies OPT_OFFSET. Next element after the offset is 178 an int containing element count in the array. */ 179 #define OPT_TIME 0x10000 180 #define OPT_DOUBLE 0x20000 181 #define OPT_INPUT 0x40000 182 #define OPT_OUTPUT 0x80000 183 union { 184 void *dst_ptr; 185 int (*func_arg)(void *, const char *, const char *); 186 size_t off; 187 } u; 188 const char *help; 189 const char *argname; 190 } OptionDef; 191 192 /** 193 * Print help for all options matching specified flags. 194 * 195 * @param options a list of options 196 * @param msg title of this group. Only printed if at least one option matches. 197 * @param req_flags print only options which have all those flags set. 198 * @param rej_flags don't print options which have any of those flags set. 199 * @param alt_flags print only options that have at least one of those flags set 200 */ 201 void show_help_options(const OptionDef *options, const char *msg, int req_flags, 202 int rej_flags, int alt_flags); 203 204 #if CONFIG_AVDEVICE 205 #define CMDUTILS_COMMON_OPTIONS_AVDEVICE \ 206 { "sources" , OPT_EXIT | HAS_ARG, { .func_arg = show_sources }, \ 207 "list sources of the input device", "device" }, \ 208 { "sinks" , OPT_EXIT | HAS_ARG, { .func_arg = show_sinks }, \ 209 "list sinks of the output device", "device" }, \ 210 211 #else 212 #define CMDUTILS_COMMON_OPTIONS_AVDEVICE 213 #endif 214 215 #define CMDUTILS_COMMON_OPTIONS \ 216 { "L", OPT_EXIT, { .func_arg = show_license }, "show license" }, \ 217 { "h", OPT_EXIT, { .func_arg = show_help }, "show help", "topic" }, \ 218 { "?", OPT_EXIT, { .func_arg = show_help }, "show help", "topic" }, \ 219 { "help", OPT_EXIT, { .func_arg = show_help }, "show help", "topic" }, \ 220 { "-help", OPT_EXIT, { .func_arg = show_help }, "show help", "topic" }, \ 221 { "version", OPT_EXIT, { .func_arg = show_version }, "show version" }, \ 222 { "buildconf", OPT_EXIT, { .func_arg = show_buildconf }, "show build configuration" }, \ 223 { "formats", OPT_EXIT, { .func_arg = show_formats }, "show available formats" }, \ 224 { "muxers", OPT_EXIT, { .func_arg = show_muxers }, "show available muxers" }, \ 225 { "demuxers", OPT_EXIT, { .func_arg = show_demuxers }, "show available demuxers" }, \ 226 { "devices", OPT_EXIT, { .func_arg = show_devices }, "show available devices" }, \ 227 { "codecs", OPT_EXIT, { .func_arg = show_codecs }, "show available codecs" }, \ 228 { "decoders", OPT_EXIT, { .func_arg = show_decoders }, "show available decoders" }, \ 229 { "encoders", OPT_EXIT, { .func_arg = show_encoders }, "show available encoders" }, \ 230 { "bsfs", OPT_EXIT, { .func_arg = show_bsfs }, "show available bit stream filters" }, \ 231 { "protocols", OPT_EXIT, { .func_arg = show_protocols }, "show available protocols" }, \ 232 { "filters", OPT_EXIT, { .func_arg = show_filters }, "show available filters" }, \ 233 { "pix_fmts", OPT_EXIT, { .func_arg = show_pix_fmts }, "show available pixel formats" }, \ 234 { "layouts", OPT_EXIT, { .func_arg = show_layouts }, "show standard channel layouts" }, \ 235 { "sample_fmts", OPT_EXIT, { .func_arg = show_sample_fmts }, "show available audio sample formats" }, \ 236 { "colors", OPT_EXIT, { .func_arg = show_colors }, "show available color names" }, \ 237 { "loglevel", HAS_ARG, { .func_arg = opt_loglevel }, "set logging level", "loglevel" }, \ 238 { "v", HAS_ARG, { .func_arg = opt_loglevel }, "set logging level", "loglevel" }, \ 239 { "report", 0, { .func_arg = opt_report }, "generate a report" }, \ 240 { "max_alloc", HAS_ARG, { .func_arg = opt_max_alloc }, "set maximum size of a single allocated block", "bytes" }, \ 241 { "cpuflags", HAS_ARG | OPT_EXPERT, { .func_arg = opt_cpuflags }, "force specific cpu flags", "flags" }, \ 242 { "hide_banner", OPT_BOOL | OPT_EXPERT, {&hide_banner}, "do not show program banner", "hide_banner" }, \ 243 CMDUTILS_COMMON_OPTIONS_AVDEVICE \ 244 245 /** 246 * Show help for all options with given flags in class and all its 247 * children. 248 */ 249 void show_help_children(const AVClass *class, int flags); 250 251 /** 252 * Per-fftool specific help handler. Implemented in each 253 * fftool, called by show_help(). 254 */ 255 void show_help_default(const char *opt, const char *arg); 256 257 /** 258 * Generic -h handler common to all fftools. 259 */ 260 int show_help(void *optctx, const char *opt, const char *arg); 261 262 /** 263 * Parse the command line arguments. 264 * 265 * @param optctx an opaque options context 266 * @param argc number of command line arguments 267 * @param argv values of command line arguments 268 * @param options Array with the definitions required to interpret every 269 * option of the form: -option_name [argument] 270 * @param parse_arg_function Name of the function called to process every 271 * argument without a leading option name flag. NULL if such arguments do 272 * not have to be processed. 273 */ 274 void parse_options(void *optctx, int argc, char **argv, const OptionDef *options, 275 void (* parse_arg_function)(void *optctx, const char*)); 276 277 /** 278 * Parse one given option. 279 * 280 * @return on success 1 if arg was consumed, 0 otherwise; negative number on error 281 */ 282 int parse_option(void *optctx, const char *opt, const char *arg, 283 const OptionDef *options); 284 285 /** 286 * An option extracted from the commandline. 287 * Cannot use AVDictionary because of options like -map which can be 288 * used multiple times. 289 */ 290 typedef struct Option { 291 const OptionDef *opt; 292 const char *key; 293 const char *val; 294 } Option; 295 296 typedef struct OptionGroupDef { 297 /**< group name */ 298 const char *name; 299 /** 300 * Option to be used as group separator. Can be NULL for groups which 301 * are terminated by a non-option argument (e.g. ffmpeg output files) 302 */ 303 const char *sep; 304 /** 305 * Option flags that must be set on each option that is 306 * applied to this group 307 */ 308 int flags; 309 } OptionGroupDef; 310 311 typedef struct OptionGroup { 312 const OptionGroupDef *group_def; 313 const char *arg; 314 315 Option *opts; 316 int nb_opts; 317 318 AVDictionary *codec_opts; 319 AVDictionary *format_opts; 320 AVDictionary *resample_opts; 321 AVDictionary *sws_dict; 322 AVDictionary *swr_opts; 323 } OptionGroup; 324 325 /** 326 * A list of option groups that all have the same group type 327 * (e.g. input files or output files) 328 */ 329 typedef struct OptionGroupList { 330 const OptionGroupDef *group_def; 331 332 OptionGroup *groups; 333 int nb_groups; 334 } OptionGroupList; 335 336 typedef struct OptionParseContext { 337 OptionGroup global_opts; 338 339 OptionGroupList *groups; 340 int nb_groups; 341 342 /* parsing state */ 343 OptionGroup cur_group; 344 } OptionParseContext; 345 346 /** 347 * Parse an options group and write results into optctx. 348 * 349 * @param optctx an app-specific options context. NULL for global options group 350 */ 351 int parse_optgroup(void *optctx, OptionGroup *g); 352 353 /** 354 * Split the commandline into an intermediate form convenient for further 355 * processing. 356 * 357 * The commandline is assumed to be composed of options which either belong to a 358 * group (those with OPT_SPEC, OPT_OFFSET or OPT_PERFILE) or are global 359 * (everything else). 360 * 361 * A group (defined by an OptionGroupDef struct) is a sequence of options 362 * terminated by either a group separator option (e.g. -i) or a parameter that 363 * is not an option (doesn't start with -). A group without a separator option 364 * must always be first in the supplied groups list. 365 * 366 * All options within the same group are stored in one OptionGroup struct in an 367 * OptionGroupList, all groups with the same group definition are stored in one 368 * OptionGroupList in OptionParseContext.groups. The order of group lists is the 369 * same as the order of group definitions. 370 */ 371 int split_commandline(OptionParseContext *octx, int argc, char *argv[], 372 const OptionDef *options, 373 const OptionGroupDef *groups, int nb_groups); 374 375 /** 376 * Free all allocated memory in an OptionParseContext. 377 */ 378 void uninit_parse_context(OptionParseContext *octx); 379 380 /** 381 * Find the '-loglevel' option in the command line args and apply it. 382 */ 383 void parse_loglevel(int argc, char **argv, const OptionDef *options); 384 385 /** 386 * Return index of option opt in argv or 0 if not found. 387 */ 388 int locate_option(int argc, char **argv, const OptionDef *options, 389 const char *optname); 390 391 /** 392 * Check if the given stream matches a stream specifier. 393 * 394 * @param s Corresponding format context. 395 * @param st Stream from s to be checked. 396 * @param spec A stream specifier of the [v|a|s|d]:[\<stream index\>] form. 397 * 398 * @return 1 if the stream matches, 0 if it doesn't, <0 on error 399 */ 400 int check_stream_specifier(AVFormatContext *s, AVStream *st, const char *spec); 401 402 /** 403 * Filter out options for given codec. 404 * 405 * Create a new options dictionary containing only the options from 406 * opts which apply to the codec with ID codec_id. 407 * 408 * @param opts dictionary to place options in 409 * @param codec_id ID of the codec that should be filtered for 410 * @param s Corresponding format context. 411 * @param st A stream from s for which the options should be filtered. 412 * @param codec The particular codec for which the options should be filtered. 413 * If null, the default one is looked up according to the codec id. 414 * @return a pointer to the created dictionary 415 */ 416 AVDictionary *filter_codec_opts(AVDictionary *opts, enum AVCodecID codec_id, 417 AVFormatContext *s, AVStream *st, const AVCodec *codec); 418 419 /** 420 * Setup AVCodecContext options for avformat_find_stream_info(). 421 * 422 * Create an array of dictionaries, one dictionary for each stream 423 * contained in s. 424 * Each dictionary will contain the options from codec_opts which can 425 * be applied to the corresponding stream codec context. 426 * 427 * @return pointer to the created array of dictionaries, NULL if it 428 * cannot be created 429 */ 430 AVDictionary **setup_find_stream_info_opts(AVFormatContext *s, 431 AVDictionary *codec_opts); 432 433 /** 434 * Print an error message to stderr, indicating filename and a human 435 * readable description of the error code err. 436 * 437 * If strerror_r() is not available the use of this function in a 438 * multithreaded application may be unsafe. 439 * 440 * @see av_strerror() 441 */ 442 void print_error(const char *filename, int err); 443 444 /** 445 * Print the program banner to stderr. The banner contents depend on the 446 * current version of the repository and of the libav* libraries used by 447 * the program. 448 */ 449 void show_banner(int argc, char **argv, const OptionDef *options); 450 451 /** 452 * Print the version of the program to stdout. The version message 453 * depends on the current versions of the repository and of the libav* 454 * libraries. 455 * This option processing function does not utilize the arguments. 456 */ 457 int show_version(void *optctx, const char *opt, const char *arg); 458 459 /** 460 * Print the build configuration of the program to stdout. The contents 461 * depend on the definition of FFMPEG_CONFIGURATION. 462 * This option processing function does not utilize the arguments. 463 */ 464 int show_buildconf(void *optctx, const char *opt, const char *arg); 465 466 /** 467 * Print the license of the program to stdout. The license depends on 468 * the license of the libraries compiled into the program. 469 * This option processing function does not utilize the arguments. 470 */ 471 int show_license(void *optctx, const char *opt, const char *arg); 472 473 /** 474 * Print a listing containing all the formats supported by the 475 * program (including devices). 476 * This option processing function does not utilize the arguments. 477 */ 478 int show_formats(void *optctx, const char *opt, const char *arg); 479 480 /** 481 * Print a listing containing all the muxers supported by the 482 * program (including devices). 483 * This option processing function does not utilize the arguments. 484 */ 485 int show_muxers(void *optctx, const char *opt, const char *arg); 486 487 /** 488 * Print a listing containing all the demuxer supported by the 489 * program (including devices). 490 * This option processing function does not utilize the arguments. 491 */ 492 int show_demuxers(void *optctx, const char *opt, const char *arg); 493 494 /** 495 * Print a listing containing all the devices supported by the 496 * program. 497 * This option processing function does not utilize the arguments. 498 */ 499 int show_devices(void *optctx, const char *opt, const char *arg); 500 501 #if CONFIG_AVDEVICE 502 /** 503 * Print a listing containing autodetected sinks of the output device. 504 * Device name with options may be passed as an argument to limit results. 505 */ 506 int show_sinks(void *optctx, const char *opt, const char *arg); 507 508 /** 509 * Print a listing containing autodetected sources of the input device. 510 * Device name with options may be passed as an argument to limit results. 511 */ 512 int show_sources(void *optctx, const char *opt, const char *arg); 513 #endif 514 515 /** 516 * Print a listing containing all the codecs supported by the 517 * program. 518 * This option processing function does not utilize the arguments. 519 */ 520 int show_codecs(void *optctx, const char *opt, const char *arg); 521 522 /** 523 * Print a listing containing all the decoders supported by the 524 * program. 525 */ 526 int show_decoders(void *optctx, const char *opt, const char *arg); 527 528 /** 529 * Print a listing containing all the encoders supported by the 530 * program. 531 */ 532 int show_encoders(void *optctx, const char *opt, const char *arg); 533 534 /** 535 * Print a listing containing all the filters supported by the 536 * program. 537 * This option processing function does not utilize the arguments. 538 */ 539 int show_filters(void *optctx, const char *opt, const char *arg); 540 541 /** 542 * Print a listing containing all the bit stream filters supported by the 543 * program. 544 * This option processing function does not utilize the arguments. 545 */ 546 int show_bsfs(void *optctx, const char *opt, const char *arg); 547 548 /** 549 * Print a listing containing all the protocols supported by the 550 * program. 551 * This option processing function does not utilize the arguments. 552 */ 553 int show_protocols(void *optctx, const char *opt, const char *arg); 554 555 /** 556 * Print a listing containing all the pixel formats supported by the 557 * program. 558 * This option processing function does not utilize the arguments. 559 */ 560 int show_pix_fmts(void *optctx, const char *opt, const char *arg); 561 562 /** 563 * Print a listing containing all the standard channel layouts supported by 564 * the program. 565 * This option processing function does not utilize the arguments. 566 */ 567 int show_layouts(void *optctx, const char *opt, const char *arg); 568 569 /** 570 * Print a listing containing all the sample formats supported by the 571 * program. 572 */ 573 int show_sample_fmts(void *optctx, const char *opt, const char *arg); 574 575 /** 576 * Print a listing containing all the color names and values recognized 577 * by the program. 578 */ 579 int show_colors(void *optctx, const char *opt, const char *arg); 580 581 /** 582 * Return a positive value if a line read from standard input 583 * starts with [yY], otherwise return 0. 584 */ 585 int read_yesno(void); 586 587 /** 588 * Get a file corresponding to a preset file. 589 * 590 * If is_path is non-zero, look for the file in the path preset_name. 591 * Otherwise search for a file named arg.ffpreset in the directories 592 * $FFMPEG_DATADIR (if set), $HOME/.ffmpeg, and in the datadir defined 593 * at configuration time or in a "ffpresets" folder along the executable 594 * on win32, in that order. If no such file is found and 595 * codec_name is defined, then search for a file named 596 * codec_name-preset_name.avpreset in the above-mentioned directories. 597 * 598 * @param filename buffer where the name of the found filename is written 599 * @param filename_size size in bytes of the filename buffer 600 * @param preset_name name of the preset to search 601 * @param is_path tell if preset_name is a filename path 602 * @param codec_name name of the codec for which to look for the 603 * preset, may be NULL 604 */ 605 FILE *get_preset_file(char *filename, size_t filename_size, 606 const char *preset_name, int is_path, const char *codec_name); 607 608 /** 609 * Realloc array to hold new_size elements of elem_size. 610 * Calls exit() on failure. 611 * 612 * @param array array to reallocate 613 * @param elem_size size in bytes of each element 614 * @param size new element count will be written here 615 * @param new_size number of elements to place in reallocated array 616 * @return reallocated array 617 */ 618 void *grow_array(void *array, int elem_size, int *size, int new_size); 619 620 #define media_type_string av_get_media_type_string 621 622 #define GROW_ARRAY(array, nb_elems)\ 623 array = grow_array(array, sizeof(*array), &nb_elems, nb_elems + 1) 624 625 #define GET_PIX_FMT_NAME(pix_fmt)\ 626 const char *name = av_get_pix_fmt_name(pix_fmt); 627 628 #define GET_CODEC_NAME(id)\ 629 const char *name = avcodec_descriptor_get(id)->name; 630 631 #define GET_SAMPLE_FMT_NAME(sample_fmt)\ 632 const char *name = av_get_sample_fmt_name(sample_fmt) 633 634 #define GET_SAMPLE_RATE_NAME(rate)\ 635 char name[16];\ 636 snprintf(name, sizeof(name), "%d", rate); 637 638 #define GET_CH_LAYOUT_NAME(ch_layout)\ 639 char name[16];\ 640 snprintf(name, sizeof(name), "0x%"PRIx64, ch_layout); 641 642 #define GET_CH_LAYOUT_DESC(ch_layout)\ 643 char name[128];\ 644 av_get_channel_layout_string(name, sizeof(name), 0, ch_layout); 645 646 double get_rotation(AVStream *st); 647 648 #endif /* FFTOOLS_CMDUTILS_H */ 649