cmdutils.h 19 KB

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