blob: e75d8d3161f11186ab86e1d0c61f690210a17e8d
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 CMDUTILS_H |
23 | #define 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(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 | int opt_opencl(void *optctx, const char *opt, const char *arg); |
110 | |
111 | int opt_opencl_bench(void *optctx, const char *opt, const char *arg); |
112 | #endif |
113 | |
114 | /** |
115 | * Limit the execution time. |
116 | */ |
117 | int opt_timelimit(void *optctx, const char *opt, const char *arg); |
118 | |
119 | /** |
120 | * Parse a string and return its corresponding value as a double. |
121 | * 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 | * @param numstr the string to be parsed |
127 | * @param type the type (OPT_INT64 or OPT_FLOAT) as which the |
128 | * string should be parsed |
129 | * @param min the minimum valid accepted value |
130 | * @param max the maximum valid accepted value |
131 | */ |
132 | double parse_number_or_die(const char *context, const char *numstr, int type, |
133 | double min, double max); |
134 | |
135 | /** |
136 | * Parse a string specifying a time and return its corresponding |
137 | * value as a number of microseconds. Exit from the application if |
138 | * the string cannot be correctly parsed. |
139 | * |
140 | * @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 | * @param is_duration a flag which tells how to interpret timestr, if |
144 | * not zero timestr is interpreted as a duration, otherwise as a |
145 | * date |
146 | * |
147 | * @see av_parse_time() |
148 | */ |
149 | int64_t parse_time_or_die(const char *context, const char *timestr, |
150 | int is_duration); |
151 | |
152 | typedef struct SpecifierOpt { |
153 | char *specifier; /**< stream/chapter/program/... specifier */ |
154 | union { |
155 | uint8_t *str; |
156 | int i; |
157 | int64_t i64; |
158 | float f; |
159 | double dbl; |
160 | } u; |
161 | } SpecifierOpt; |
162 | |
163 | typedef struct OptionDef { |
164 | const char *name; |
165 | int flags; |
166 | #define HAS_ARG 0x0001 |
167 | #define OPT_BOOL 0x0002 |
168 | #define OPT_EXPERT 0x0004 |
169 | #define OPT_STRING 0x0008 |
170 | #define OPT_VIDEO 0x0010 |
171 | #define OPT_AUDIO 0x0020 |
172 | #define OPT_INT 0x0080 |
173 | #define OPT_FLOAT 0x0100 |
174 | #define OPT_SUBTITLE 0x0200 |
175 | #define OPT_INT64 0x0400 |
176 | #define OPT_EXIT 0x0800 |
177 | #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 | #define OPT_SPEC 0x8000 /* option is to be stored in an array of SpecifierOpt. |
182 | Implies OPT_OFFSET. Next element after the offset is |
183 | an int containing element count in the array. */ |
184 | #define OPT_TIME 0x10000 |
185 | #define OPT_DOUBLE 0x20000 |
186 | #define OPT_INPUT 0x40000 |
187 | #define OPT_OUTPUT 0x80000 |
188 | union { |
189 | void *dst_ptr; |
190 | int (*func_arg)(void *, const char *, const char *); |
191 | size_t off; |
192 | } u; |
193 | const char *help; |
194 | const char *argname; |
195 | } OptionDef; |
196 | |
197 | /** |
198 | * Print help for all options matching specified flags. |
199 | * |
200 | * @param options a list of options |
201 | * @param msg title of this group. Only printed if at least one option matches. |
202 | * @param req_flags print only options which have all those flags set. |
203 | * @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 | * Show help for all options with given flags in class and all its |
211 | * children. |
212 | */ |
213 | void show_help_children(const AVClass *class, int flags); |
214 | |
215 | /** |
216 | * Per-fftool specific help handler. Implemented in each |
217 | * fftool, called by show_help(). |
218 | */ |
219 | void show_help_default(const char *opt, const char *arg); |
220 | |
221 | /** |
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 | * @param argc number of command line arguments |
231 | * @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 | * @param parse_arg_function Name of the function called to process every |
235 | * argument without a leading option name flag. NULL if such arguments do |
236 | * not have to be processed. |
237 | */ |
238 | void parse_options(void *optctx, int argc, char **argv, const OptionDef *options, |
239 | void (* parse_arg_function)(void *optctx, const char*)); |
240 | |
241 | /** |
242 | * Parse one given option. |
243 | * |
244 | * @return on success 1 if arg was consumed, 0 otherwise; negative number on error |
245 | */ |
246 | int parse_option(void *optctx, const char *opt, const char *arg, |
247 | const OptionDef *options); |
248 | |
249 | /** |
250 | * An option extracted from the commandline. |
251 | * Cannot use AVDictionary because of options like -map which can be |
252 | * used multiple times. |
253 | */ |
254 | typedef struct Option { |
255 | const OptionDef *opt; |
256 | const char *key; |
257 | const char *val; |
258 | } Option; |
259 | |
260 | typedef struct OptionGroupDef { |
261 | /**< group name */ |
262 | const char *name; |
263 | /** |
264 | * 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 | * Option flags that must be set on each option that is |
270 | * applied to this group |
271 | */ |
272 | int flags; |
273 | } OptionGroupDef; |
274 | |
275 | typedef struct OptionGroup { |
276 | const OptionGroupDef *group_def; |
277 | const char *arg; |
278 | |
279 | Option *opts; |
280 | int nb_opts; |
281 | |
282 | AVDictionary *codec_opts; |
283 | AVDictionary *format_opts; |
284 | AVDictionary *resample_opts; |
285 | AVDictionary *sws_dict; |
286 | AVDictionary *swr_opts; |
287 | } OptionGroup; |
288 | |
289 | /** |
290 | * A list of option groups that all have the same group type |
291 | * (e.g. input files or output files) |
292 | */ |
293 | typedef struct OptionGroupList { |
294 | const OptionGroupDef *group_def; |
295 | |
296 | OptionGroup *groups; |
297 | int nb_groups; |
298 | } OptionGroupList; |
299 | |
300 | typedef struct OptionParseContext { |
301 | OptionGroup global_opts; |
302 | |
303 | OptionGroupList *groups; |
304 | int nb_groups; |
305 | |
306 | /* parsing state */ |
307 | OptionGroup cur_group; |
308 | } OptionParseContext; |
309 | |
310 | /** |
311 | * Parse an options group and write results into optctx. |
312 | * |
313 | * @param optctx an app-specific options context. NULL for global options group |
314 | */ |
315 | int parse_optgroup(void *optctx, OptionGroup *g); |
316 | |
317 | /** |
318 | * Split the commandline into an intermediate form convenient for further |
319 | * processing. |
320 | * |
321 | * The commandline is assumed to be composed of options which either belong to a |
322 | * group (those with OPT_SPEC, OPT_OFFSET or OPT_PERFILE) or are global |
323 | * (everything else). |
324 | * |
325 | * A group (defined by an OptionGroupDef struct) is a sequence of options |
326 | * terminated by either a group separator option (e.g. -i) or a parameter that |
327 | * is not an option (doesn't start with -). A group without a separator option |
328 | * must always be first in the supplied groups list. |
329 | * |
330 | * All options within the same group are stored in one OptionGroup struct in an |
331 | * OptionGroupList, all groups with the same group definition are stored in one |
332 | * OptionGroupList in OptionParseContext.groups. The order of group lists is the |
333 | * same as the order of group definitions. |
334 | */ |
335 | int split_commandline(OptionParseContext *octx, int argc, char *argv[], |
336 | const OptionDef *options, |
337 | const OptionGroupDef *groups, int nb_groups); |
338 | |
339 | /** |
340 | * Free all allocated memory in an OptionParseContext. |
341 | */ |
342 | void uninit_parse_context(OptionParseContext *octx); |
343 | |
344 | /** |
345 | * Find the '-loglevel' option in the command line args and apply it. |
346 | */ |
347 | void parse_loglevel(int argc, char **argv, const OptionDef *options); |
348 | |
349 | /** |
350 | * Return index of option opt in argv or 0 if not found. |
351 | */ |
352 | int locate_option(int argc, char **argv, const OptionDef *options, |
353 | const char *optname); |
354 | |
355 | /** |
356 | * Check if the given stream matches a stream specifier. |
357 | * |
358 | * @param s Corresponding format context. |
359 | * @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 | * @return 1 if the stream matches, 0 if it doesn't, <0 on error |
363 | */ |
364 | int check_stream_specifier(AVFormatContext *s, AVStream *st, const char *spec); |
365 | |
366 | /** |
367 | * Filter out options for given codec. |
368 | * |
369 | * Create a new options dictionary containing only the options from |
370 | * opts which apply to the codec with ID codec_id. |
371 | * |
372 | * @param opts dictionary to place options in |
373 | * @param codec_id ID of the codec that should be filtered for |
374 | * @param s Corresponding format context. |
375 | * @param st A stream from s for which the options should be filtered. |
376 | * @param codec The particular codec for which the options should be filtered. |
377 | * 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 | * Setup AVCodecContext options for avformat_find_stream_info(). |
385 | * |
386 | * Create an array of dictionaries, one dictionary for each stream |
387 | * contained in s. |
388 | * Each dictionary will contain the options from codec_opts which can |
389 | * be applied to the corresponding stream codec context. |
390 | * |
391 | * @return pointer to the created array of dictionaries, NULL if it |
392 | * cannot be created |
393 | */ |
394 | AVDictionary **setup_find_stream_info_opts(AVFormatContext *s, |
395 | AVDictionary *codec_opts); |
396 | |
397 | /** |
398 | * Print an error message to stderr, indicating filename and a human |
399 | * readable description of the error code err. |
400 | * |
401 | * If strerror_r() is not available the use of this function in a |
402 | * multithreaded application may be unsafe. |
403 | * |
404 | * @see av_strerror() |
405 | */ |
406 | void print_error(const char *filename, int err); |
407 | |
408 | /** |
409 | * Print the program banner to stderr. The banner contents depend on the |
410 | * current version of the repository and of the libav* libraries used by |
411 | * 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 | * depends on the current versions of the repository and of the libav* |
418 | * 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 | * Print the build configuration of the program to stdout. The contents |
425 | * depend on the definition of FFMPEG_CONFIGURATION. |
426 | * This option processing function does not utilize the arguments. |
427 | */ |
428 | int show_buildconf(void *optctx, const char *opt, const char *arg); |
429 | |
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 | * Print a listing containing all the muxers supported by the |
446 | * program (including devices). |
447 | * This option processing function does not utilize the arguments. |
448 | */ |
449 | int show_muxers(void *optctx, const char *opt, const char *arg); |
450 | |
451 | /** |
452 | * Print a listing containing all the demuxer supported by the |
453 | * program (including devices). |
454 | * This option processing function does not utilize the arguments. |
455 | */ |
456 | int show_demuxers(void *optctx, const char *opt, const char *arg); |
457 | |
458 | /** |
459 | * Print a listing containing all the devices supported by the |
460 | * program. |
461 | * This option processing function does not utilize the arguments. |
462 | */ |
463 | int show_devices(void *optctx, const char *opt, const char *arg); |
464 | |
465 | #if CONFIG_AVDEVICE |
466 | /** |
467 | * Print a listing containing autodetected sinks of the output device. |
468 | * Device name with options may be passed as an argument to limit results. |
469 | */ |
470 | int show_sinks(void *optctx, const char *opt, const char *arg); |
471 | |
472 | /** |
473 | * Print a listing containing autodetected sources of the input device. |
474 | * Device name with options may be passed as an argument to limit results. |
475 | */ |
476 | int show_sources(void *optctx, const char *opt, const char *arg); |
477 | #endif |
478 | |
479 | /** |
480 | * Print a listing containing all the codecs supported by the |
481 | * program. |
482 | * This option processing function does not utilize the arguments. |
483 | */ |
484 | int show_codecs(void *optctx, const char *opt, const char *arg); |
485 | |
486 | /** |
487 | * Print a listing containing all the decoders supported by the |
488 | * program. |
489 | */ |
490 | int show_decoders(void *optctx, const char *opt, const char *arg); |
491 | |
492 | /** |
493 | * Print a listing containing all the encoders supported by the |
494 | * program. |
495 | */ |
496 | int show_encoders(void *optctx, const char *opt, const char *arg); |
497 | |
498 | /** |
499 | * Print a listing containing all the filters supported by the |
500 | * program. |
501 | * This option processing function does not utilize the arguments. |
502 | */ |
503 | int show_filters(void *optctx, const char *opt, const char *arg); |
504 | |
505 | /** |
506 | * Print a listing containing all the bit stream filters supported by the |
507 | * program. |
508 | * This option processing function does not utilize the arguments. |
509 | */ |
510 | int show_bsfs(void *optctx, const char *opt, const char *arg); |
511 | |
512 | /** |
513 | * Print a listing containing all the protocols supported by the |
514 | * program. |
515 | * This option processing function does not utilize the arguments. |
516 | */ |
517 | int show_protocols(void *optctx, const char *opt, const char *arg); |
518 | |
519 | /** |
520 | * Print a listing containing all the pixel formats supported by the |
521 | * program. |
522 | * This option processing function does not utilize the arguments. |
523 | */ |
524 | int show_pix_fmts(void *optctx, const char *opt, const char *arg); |
525 | |
526 | /** |
527 | * Print a listing containing all the standard channel layouts supported by |
528 | * the program. |
529 | * This option processing function does not utilize the arguments. |
530 | */ |
531 | int show_layouts(void *optctx, const char *opt, const char *arg); |
532 | |
533 | /** |
534 | * Print a listing containing all the sample formats supported by the |
535 | * program. |
536 | */ |
537 | int show_sample_fmts(void *optctx, const char *opt, const char *arg); |
538 | |
539 | /** |
540 | * Print a listing containing all the color names and values recognized |
541 | * by the program. |
542 | */ |
543 | int show_colors(void *optctx, const char *opt, const char *arg); |
544 | |
545 | /** |
546 | * Return a positive value if a line read from standard input |
547 | * starts with [yY], otherwise return 0. |
548 | */ |
549 | int read_yesno(void); |
550 | |
551 | /** |
552 | * Get a file corresponding to a preset file. |
553 | * |
554 | * If is_path is non-zero, look for the file in the path preset_name. |
555 | * Otherwise search for a file named arg.ffpreset in the directories |
556 | * $FFMPEG_DATADIR (if set), $HOME/.ffmpeg, and in the datadir defined |
557 | * at configuration time or in a "ffpresets" folder along the executable |
558 | * on win32, in that order. If no such file is found and |
559 | * codec_name is defined, then search for a file named |
560 | * codec_name-preset_name.avpreset in the above-mentioned directories. |
561 | * |
562 | * @param filename buffer where the name of the found filename is written |
563 | * @param filename_size size in bytes of the filename buffer |
564 | * @param preset_name name of the preset to search |
565 | * @param is_path tell if preset_name is a filename path |
566 | * @param codec_name name of the codec for which to look for the |
567 | * preset, may be NULL |
568 | */ |
569 | FILE *get_preset_file(char *filename, size_t filename_size, |
570 | const char *preset_name, int is_path, const char *codec_name); |
571 | |
572 | /** |
573 | * Realloc array to hold new_size elements of elem_size. |
574 | * Calls exit() on failure. |
575 | * |
576 | * @param array array to reallocate |
577 | * @param elem_size size in bytes of each element |
578 | * @param size new element count will be written here |
579 | * @param new_size number of elements to place in reallocated array |
580 | * @return reallocated array |
581 | */ |
582 | void *grow_array(void *array, int elem_size, int *size, int new_size); |
583 | |
584 | #define media_type_string av_get_media_type_string |
585 | |
586 | #define GROW_ARRAY(array, nb_elems)\ |
587 | array = grow_array(array, sizeof(*array), &nb_elems, nb_elems + 1) |
588 | |
589 | #define GET_PIX_FMT_NAME(pix_fmt)\ |
590 | const char *name = av_get_pix_fmt_name(pix_fmt); |
591 | |
592 | #define GET_SAMPLE_FMT_NAME(sample_fmt)\ |
593 | const char *name = av_get_sample_fmt_name(sample_fmt) |
594 | |
595 | #define GET_SAMPLE_RATE_NAME(rate)\ |
596 | char name[16];\ |
597 | snprintf(name, sizeof(name), "%d", rate); |
598 | |
599 | #define GET_CH_LAYOUT_NAME(ch_layout)\ |
600 | char name[16];\ |
601 | snprintf(name, sizeof(name), "0x%"PRIx64, ch_layout); |
602 | |
603 | #define GET_CH_LAYOUT_DESC(ch_layout)\ |
604 | char name[128];\ |
605 | av_get_channel_layout_string(name, sizeof(name), 0, ch_layout); |
606 | |
607 | double get_rotation(AVStream *st); |
608 | |
609 | #endif /* CMDUTILS_H */ |
610 |