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 FFMPEG_CMDUTILS_H 23#define FFMPEG_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 */ 40extern const char program_name[]; 41 42/** 43 * program birth year, defined by the program for show_banner() 44 */ 45extern const int program_birth_year; 46 47extern AVCodecContext *avcodec_opts[AVMEDIA_TYPE_NB]; 48extern AVFormatContext *avformat_opts; 49extern struct SwsContext *sws_opts; 50extern AVDictionary *swr_opts; 51extern AVDictionary *format_opts, *codec_opts, *resample_opts; 52extern int hide_banner; 53 54/** 55 * Register a program-specific cleanup routine. 56 */ 57void register_exit(void (*cb)(int ret)); 58 59/** 60 * Wraps exit with a program-specific cleanup routine. 61 */ 62void exit_program(int ret) av_noreturn; 63 64/** 65 * Initialize the cmdutils option system, in particular 66 * allocate the *_opts contexts. 67 */ 68void init_opts(void); 69/** 70 * Uninitialize the cmdutils option system, in particular 71 * free the *_opts contexts and their contents. 72 */ 73void uninit_opts(void); 74 75/** 76 * Trivial log callback. 77 * Only suitable for opt_help and similar since it lacks prefix handling. 78 */ 79void log_callback_help(void* ptr, int level, const char* fmt, va_list vl); 80 81/** 82 * Override the cpuflags. 83 */ 84int opt_cpuflags(void *optctx, const char *opt, const char *arg); 85 86/** 87 * Fallback for options that are not explicitly handled, these will be 88 * parsed through AVOptions. 89 */ 90int opt_default(void *optctx, const char *opt, const char *arg); 91 92/** 93 * Set the libav* libraries log level. 94 */ 95int opt_loglevel(void *optctx, const char *opt, const char *arg); 96 97int opt_report(const char *opt); 98 99int opt_max_alloc(void *optctx, const char *opt, const char *arg); 100 101int opt_codec_debug(void *optctx, const char *opt, const char *arg); 102 103#if CONFIG_OPENCL 104int opt_opencl(void *optctx, const char *opt, const char *arg); 105 106int opt_opencl_bench(void *optctx, const char *opt, const char *arg); 107#endif 108 109/** 110 * Limit the execution time. 111 */ 112int opt_timelimit(void *optctx, const char *opt, const char *arg); 113 114/** 115 * Parse a string and return its corresponding value as a double. 116 * Exit from the application if the string cannot be correctly 117 * parsed or the corresponding value is invalid. 118 * 119 * @param context the context of the value to be set (e.g. the 120 * corresponding command line option name) 121 * @param numstr the string to be parsed 122 * @param type the type (OPT_INT64 or OPT_FLOAT) as which the 123 * string should be parsed 124 * @param min the minimum valid accepted value 125 * @param max the maximum valid accepted value 126 */ 127double parse_number_or_die(const char *context, const char *numstr, int type, 128 double min, double max); 129 130/** 131 * Parse a string specifying a time and return its corresponding 132 * value as a number of microseconds. Exit from the application if 133 * the string cannot be correctly parsed. 134 * 135 * @param context the context of the value to be set (e.g. the 136 * corresponding command line option name) 137 * @param timestr the string to be parsed 138 * @param is_duration a flag which tells how to interpret timestr, if 139 * not zero timestr is interpreted as a duration, otherwise as a 140 * date 141 * 142 * @see av_parse_time() 143 */ 144int64_t parse_time_or_die(const char *context, const char *timestr, 145 int is_duration); 146 147typedef struct SpecifierOpt { 148 char *specifier; /**< stream/chapter/program/... specifier */ 149 union { 150 uint8_t *str; 151 int i; 152 int64_t i64; 153 float f; 154 double dbl; 155 } u; 156} SpecifierOpt; 157 158typedef 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 */ 201void show_help_options(const OptionDef *options, const char *msg, int req_flags, 202 int rej_flags, int alt_flags); 203 204/** 205 * Show help for all options with given flags in class and all its 206 * children. 207 */ 208void show_help_children(const AVClass *class, int flags); 209 210/** 211 * Per-fftool specific help handler. Implemented in each 212 * fftool, called by show_help(). 213 */ 214void show_help_default(const char *opt, const char *arg); 215 216/** 217 * Generic -h handler common to all fftools. 218 */ 219int show_help(void *optctx, const char *opt, const char *arg); 220 221/** 222 * Parse the command line arguments. 223 * 224 * @param optctx an opaque options context 225 * @param argc number of command line arguments 226 * @param argv values of command line arguments 227 * @param options Array with the definitions required to interpret every 228 * option of the form: -option_name [argument] 229 * @param parse_arg_function Name of the function called to process every 230 * argument without a leading option name flag. NULL if such arguments do 231 * not have to be processed. 232 */ 233void parse_options(void *optctx, int argc, char **argv, const OptionDef *options, 234 void (* parse_arg_function)(void *optctx, const char*)); 235 236/** 237 * Parse one given option. 238 * 239 * @return on success 1 if arg was consumed, 0 otherwise; negative number on error 240 */ 241int parse_option(void *optctx, const char *opt, const char *arg, 242 const OptionDef *options); 243 244/** 245 * An option extracted from the commandline. 246 * Cannot use AVDictionary because of options like -map which can be 247 * used multiple times. 248 */ 249typedef struct Option { 250 const OptionDef *opt; 251 const char *key; 252 const char *val; 253} Option; 254 255typedef struct OptionGroupDef { 256 /**< group name */ 257 const char *name; 258 /** 259 * Option to be used as group separator. Can be NULL for groups which 260 * are terminated by a non-option argument (e.g. ffmpeg output files) 261 */ 262 const char *sep; 263 /** 264 * Option flags that must be set on each option that is 265 * applied to this group 266 */ 267 int flags; 268} OptionGroupDef; 269 270typedef struct OptionGroup { 271 const OptionGroupDef *group_def; 272 const char *arg; 273 274 Option *opts; 275 int nb_opts; 276 277 AVDictionary *codec_opts; 278 AVDictionary *format_opts; 279 AVDictionary *resample_opts; 280 struct SwsContext *sws_opts; 281 AVDictionary *swr_opts; 282} OptionGroup; 283 284/** 285 * A list of option groups that all have the same group type 286 * (e.g. input files or output files) 287 */ 288typedef struct OptionGroupList { 289 const OptionGroupDef *group_def; 290 291 OptionGroup *groups; 292 int nb_groups; 293} OptionGroupList; 294 295typedef struct OptionParseContext { 296 OptionGroup global_opts; 297 298 OptionGroupList *groups; 299 int nb_groups; 300 301 /* parsing state */ 302 OptionGroup cur_group; 303} OptionParseContext; 304 305/** 306 * Parse an options group and write results into optctx. 307 * 308 * @param optctx an app-specific options context. NULL for global options group 309 */ 310int parse_optgroup(void *optctx, OptionGroup *g); 311 312/** 313 * Split the commandline into an intermediate form convenient for further 314 * processing. 315 * 316 * The commandline is assumed to be composed of options which either belong to a 317 * group (those with OPT_SPEC, OPT_OFFSET or OPT_PERFILE) or are global 318 * (everything else). 319 * 320 * A group (defined by an OptionGroupDef struct) is a sequence of options 321 * terminated by either a group separator option (e.g. -i) or a parameter that 322 * is not an option (doesn't start with -). A group without a separator option 323 * must always be first in the supplied groups list. 324 * 325 * All options within the same group are stored in one OptionGroup struct in an 326 * OptionGroupList, all groups with the same group definition are stored in one 327 * OptionGroupList in OptionParseContext.groups. The order of group lists is the 328 * same as the order of group definitions. 329 */ 330int split_commandline(OptionParseContext *octx, int argc, char *argv[], 331 const OptionDef *options, 332 const OptionGroupDef *groups, int nb_groups); 333 334/** 335 * Free all allocated memory in an OptionParseContext. 336 */ 337void uninit_parse_context(OptionParseContext *octx); 338 339/** 340 * Find the '-loglevel' option in the command line args and apply it. 341 */ 342void parse_loglevel(int argc, char **argv, const OptionDef *options); 343 344/** 345 * Return index of option opt in argv or 0 if not found. 346 */ 347int locate_option(int argc, char **argv, const OptionDef *options, 348 const char *optname); 349 350/** 351 * Check if the given stream matches a stream specifier. 352 * 353 * @param s Corresponding format context. 354 * @param st Stream from s to be checked. 355 * @param spec A stream specifier of the [v|a|s|d]:[\<stream index\>] form. 356 * 357 * @return 1 if the stream matches, 0 if it doesn't, <0 on error 358 */ 359int check_stream_specifier(AVFormatContext *s, AVStream *st, const char *spec); 360 361/** 362 * Filter out options for given codec. 363 * 364 * Create a new options dictionary containing only the options from 365 * opts which apply to the codec with ID codec_id. 366 * 367 * @param opts dictionary to place options in 368 * @param codec_id ID of the codec that should be filtered for 369 * @param s Corresponding format context. 370 * @param st A stream from s for which the options should be filtered. 371 * @param codec The particular codec for which the options should be filtered. 372 * If null, the default one is looked up according to the codec id. 373 * @return a pointer to the created dictionary 374 */ 375AVDictionary *filter_codec_opts(AVDictionary *opts, enum AVCodecID codec_id, 376 AVFormatContext *s, AVStream *st, AVCodec *codec); 377 378/** 379 * Setup AVCodecContext options for avformat_find_stream_info(). 380 * 381 * Create an array of dictionaries, one dictionary for each stream 382 * contained in s. 383 * Each dictionary will contain the options from codec_opts which can 384 * be applied to the corresponding stream codec context. 385 * 386 * @return pointer to the created array of dictionaries, NULL if it 387 * cannot be created 388 */ 389AVDictionary **setup_find_stream_info_opts(AVFormatContext *s, 390 AVDictionary *codec_opts); 391 392/** 393 * Print an error message to stderr, indicating filename and a human 394 * readable description of the error code err. 395 * 396 * If strerror_r() is not available the use of this function in a 397 * multithreaded application may be unsafe. 398 * 399 * @see av_strerror() 400 */ 401void print_error(const char *filename, int err); 402 403/** 404 * Print the program banner to stderr. The banner contents depend on the 405 * current version of the repository and of the libav* libraries used by 406 * the program. 407 */ 408void show_banner(int argc, char **argv, const OptionDef *options); 409 410/** 411 * Print the version of the program to stdout. The version message 412 * depends on the current versions of the repository and of the libav* 413 * libraries. 414 * This option processing function does not utilize the arguments. 415 */ 416int show_version(void *optctx, const char *opt, const char *arg); 417 418/** 419 * Print the build configuration of the program to stdout. The contents 420 * depend on the definition of FFMPEG_CONFIGURATION. 421 * This option processing function does not utilize the arguments. 422 */ 423int show_buildconf(void *optctx, const char *opt, const char *arg); 424 425/** 426 * Print the license of the program to stdout. The license depends on 427 * the license of the libraries compiled into the program. 428 * This option processing function does not utilize the arguments. 429 */ 430int show_license(void *optctx, const char *opt, const char *arg); 431 432/** 433 * Print a listing containing all the formats supported by the 434 * program (including devices). 435 * This option processing function does not utilize the arguments. 436 */ 437int show_formats(void *optctx, const char *opt, const char *arg); 438 439/** 440 * Print a listing containing all the devices supported by the 441 * program. 442 * This option processing function does not utilize the arguments. 443 */ 444int show_devices(void *optctx, const char *opt, const char *arg); 445 446/** 447 * Print a listing containing all the codecs supported by the 448 * program. 449 * This option processing function does not utilize the arguments. 450 */ 451int show_codecs(void *optctx, const char *opt, const char *arg); 452 453/** 454 * Print a listing containing all the decoders supported by the 455 * program. 456 */ 457int show_decoders(void *optctx, const char *opt, const char *arg); 458 459/** 460 * Print a listing containing all the encoders supported by the 461 * program. 462 */ 463int show_encoders(void *optctx, const char *opt, const char *arg); 464 465/** 466 * Print a listing containing all the filters supported by the 467 * program. 468 * This option processing function does not utilize the arguments. 469 */ 470int show_filters(void *optctx, const char *opt, const char *arg); 471 472/** 473 * Print a listing containing all the bit stream filters supported by the 474 * program. 475 * This option processing function does not utilize the arguments. 476 */ 477int show_bsfs(void *optctx, const char *opt, const char *arg); 478 479/** 480 * Print a listing containing all the protocols supported by the 481 * program. 482 * This option processing function does not utilize the arguments. 483 */ 484int show_protocols(void *optctx, const char *opt, const char *arg); 485 486/** 487 * Print a listing containing all the pixel formats supported by the 488 * program. 489 * This option processing function does not utilize the arguments. 490 */ 491int show_pix_fmts(void *optctx, const char *opt, const char *arg); 492 493/** 494 * Print a listing containing all the standard channel layouts supported by 495 * the program. 496 * This option processing function does not utilize the arguments. 497 */ 498int show_layouts(void *optctx, const char *opt, const char *arg); 499 500/** 501 * Print a listing containing all the sample formats supported by the 502 * program. 503 */ 504int show_sample_fmts(void *optctx, const char *opt, const char *arg); 505 506/** 507 * Print a listing containing all the color names and values recognized 508 * by the program. 509 */ 510int show_colors(void *optctx, const char *opt, const char *arg); 511 512/** 513 * Return a positive value if a line read from standard input 514 * starts with [yY], otherwise return 0. 515 */ 516int read_yesno(void); 517 518/** 519 * Read the file with name filename, and put its content in a newly 520 * allocated 0-terminated buffer. 521 * 522 * @param filename file to read from 523 * @param bufptr location where pointer to buffer is returned 524 * @param size location where size of buffer is returned 525 * @return >= 0 in case of success, a negative value corresponding to an 526 * AVERROR error code in case of failure. 527 */ 528int cmdutils_read_file(const char *filename, char **bufptr, size_t *size); 529 530/** 531 * Get a file corresponding to a preset file. 532 * 533 * If is_path is non-zero, look for the file in the path preset_name. 534 * Otherwise search for a file named arg.ffpreset in the directories 535 * $FFMPEG_DATADIR (if set), $HOME/.ffmpeg, and in the datadir defined 536 * at configuration time or in a "ffpresets" folder along the executable 537 * on win32, in that order. If no such file is found and 538 * codec_name is defined, then search for a file named 539 * codec_name-preset_name.avpreset in the above-mentioned directories. 540 * 541 * @param filename buffer where the name of the found filename is written 542 * @param filename_size size in bytes of the filename buffer 543 * @param preset_name name of the preset to search 544 * @param is_path tell if preset_name is a filename path 545 * @param codec_name name of the codec for which to look for the 546 * preset, may be NULL 547 */ 548FILE *get_preset_file(char *filename, size_t filename_size, 549 const char *preset_name, int is_path, const char *codec_name); 550 551/** 552 * Realloc array to hold new_size elements of elem_size. 553 * Calls exit() on failure. 554 * 555 * @param array array to reallocate 556 * @param elem_size size in bytes of each element 557 * @param size new element count will be written here 558 * @param new_size number of elements to place in reallocated array 559 * @return reallocated array 560 */ 561void *grow_array(void *array, int elem_size, int *size, int new_size); 562 563#define media_type_string av_get_media_type_string 564 565#define GROW_ARRAY(array, nb_elems)\ 566 array = grow_array(array, sizeof(*array), &nb_elems, nb_elems + 1) 567 568#define GET_PIX_FMT_NAME(pix_fmt)\ 569 const char *name = av_get_pix_fmt_name(pix_fmt); 570 571#define GET_SAMPLE_FMT_NAME(sample_fmt)\ 572 const char *name = av_get_sample_fmt_name(sample_fmt) 573 574#define GET_SAMPLE_RATE_NAME(rate)\ 575 char name[16];\ 576 snprintf(name, sizeof(name), "%d", rate); 577 578#define GET_CH_LAYOUT_NAME(ch_layout)\ 579 char name[16];\ 580 snprintf(name, sizeof(name), "0x%"PRIx64, ch_layout); 581 582#define GET_CH_LAYOUT_DESC(ch_layout)\ 583 char name[128];\ 584 av_get_channel_layout_string(name, sizeof(name), 0, ch_layout); 585 586#endif /* CMDUTILS_H */ 587