cmdutils.h 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548
  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 FFTOOLS_CMDUTILS_H
  22. #define FFTOOLS_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 AVDictionary *sws_dict;
  41. extern AVDictionary *swr_opts;
  42. extern AVDictionary *format_opts, *codec_opts;
  43. extern int hide_banner;
  44. /**
  45. * Initialize dynamic library loading
  46. */
  47. void init_dynload(void);
  48. /**
  49. * Uninitialize the cmdutils option system, in particular
  50. * free the *_opts contexts and their contents.
  51. */
  52. void uninit_opts(void);
  53. /**
  54. * Trivial log callback.
  55. * Only suitable for opt_help and similar since it lacks prefix handling.
  56. */
  57. void log_callback_help(void* ptr, int level, const char* fmt, va_list vl);
  58. /**
  59. * Fallback for options that are not explicitly handled, these will be
  60. * parsed through AVOptions.
  61. */
  62. int opt_default(void *optctx, const char *opt, const char *arg);
  63. /**
  64. * Limit the execution time.
  65. */
  66. int opt_timelimit(void *optctx, const char *opt, const char *arg);
  67. enum OptionType {
  68. OPT_TYPE_FUNC,
  69. OPT_TYPE_BOOL,
  70. OPT_TYPE_STRING,
  71. OPT_TYPE_INT,
  72. OPT_TYPE_INT64,
  73. OPT_TYPE_FLOAT,
  74. OPT_TYPE_DOUBLE,
  75. OPT_TYPE_TIME,
  76. };
  77. /**
  78. * Parse a string and return its corresponding value as a double.
  79. *
  80. * @param context the context of the value to be set (e.g. the
  81. * corresponding command line option name)
  82. * @param numstr the string to be parsed
  83. * @param type the type (OPT_INT64 or OPT_FLOAT) as which the
  84. * string should be parsed
  85. * @param min the minimum valid accepted value
  86. * @param max the maximum valid accepted value
  87. */
  88. int parse_number(const char *context, const char *numstr, enum OptionType type,
  89. double min, double max, double *dst);
  90. enum StreamList {
  91. STREAM_LIST_ALL,
  92. STREAM_LIST_STREAM_ID,
  93. STREAM_LIST_PROGRAM,
  94. STREAM_LIST_GROUP_ID,
  95. STREAM_LIST_GROUP_IDX,
  96. };
  97. typedef struct StreamSpecifier {
  98. // trailing stream index - pick idx-th stream that matches
  99. // all the other constraints; -1 when not present
  100. int idx;
  101. // which stream list to consider
  102. enum StreamList stream_list;
  103. // STREAM_LIST_STREAM_ID: stream ID
  104. // STREAM_LIST_GROUP_IDX: group index
  105. // STREAM_LIST_GROUP_ID: group ID
  106. // STREAM_LIST_PROGRAM: program ID
  107. int64_t list_id;
  108. // when not AVMEDIA_TYPE_UNKNOWN, consider only streams of this type
  109. enum AVMediaType media_type;
  110. uint8_t no_apic;
  111. uint8_t usable_only;
  112. int disposition;
  113. char *meta_key;
  114. char *meta_val;
  115. char *remainder;
  116. } StreamSpecifier;
  117. /**
  118. * Parse a stream specifier string into a form suitable for matching.
  119. *
  120. * @param ss Parsed specifier will be stored here; must be uninitialized
  121. * with stream_specifier_uninit() when no longer needed.
  122. * @param spec String containing the stream specifier to be parsed.
  123. * @param allow_remainder When 1, the part of spec that is left after parsing
  124. * the stream specifier is stored into ss->remainder.
  125. * When 0, any remainder will cause parsing to fail.
  126. */
  127. int stream_specifier_parse(StreamSpecifier *ss, const char *spec,
  128. int allow_remainder, void *logctx);
  129. /**
  130. * @return 1 if st matches the parsed specifier, 0 if it does not
  131. */
  132. unsigned stream_specifier_match(const StreamSpecifier *ss,
  133. const AVFormatContext *s, const AVStream *st,
  134. void *logctx);
  135. void stream_specifier_uninit(StreamSpecifier *ss);
  136. typedef struct SpecifierOpt {
  137. // original specifier or empty string
  138. char *specifier;
  139. // parsed specifier for OPT_FLAG_PERSTREAM options
  140. StreamSpecifier stream_spec;
  141. union {
  142. uint8_t *str;
  143. int i;
  144. int64_t i64;
  145. uint64_t ui64;
  146. float f;
  147. double dbl;
  148. } u;
  149. } SpecifierOpt;
  150. typedef struct SpecifierOptList {
  151. SpecifierOpt *opt;
  152. int nb_opt;
  153. /* Canonical option definition that was parsed into this list. */
  154. const struct OptionDef *opt_canon;
  155. /* Type corresponding to the field that should be used from SpecifierOpt.u.
  156. * May not match the option type, e.g. OPT_TYPE_BOOL options are stored as
  157. * int, so this field would be OPT_TYPE_INT for them */
  158. enum OptionType type;
  159. } SpecifierOptList;
  160. typedef struct OptionDef {
  161. const char *name;
  162. enum OptionType type;
  163. int flags;
  164. /* The OPT_TYPE_FUNC option takes an argument.
  165. * Must not be used with other option types, as for those it holds:
  166. * - OPT_TYPE_BOOL do not take an argument
  167. * - all other types do
  168. */
  169. #define OPT_FUNC_ARG (1 << 0)
  170. /* Program will immediately exit after processing this option */
  171. #define OPT_EXIT (1 << 1)
  172. /* Option is intended for advanced users. Only affects
  173. * help output.
  174. */
  175. #define OPT_EXPERT (1 << 2)
  176. #define OPT_VIDEO (1 << 3)
  177. #define OPT_AUDIO (1 << 4)
  178. #define OPT_SUBTITLE (1 << 5)
  179. #define OPT_DATA (1 << 6)
  180. /* The option is per-file (currently ffmpeg-only). At least one of OPT_INPUT,
  181. * OPT_OUTPUT, OPT_DECODER must be set when this flag is in use.
  182. */
  183. #define OPT_PERFILE (1 << 7)
  184. /* Option is specified as an offset in a passed optctx.
  185. * Always use as OPT_OFFSET in option definitions. */
  186. #define OPT_FLAG_OFFSET (1 << 8)
  187. #define OPT_OFFSET (OPT_FLAG_OFFSET | OPT_PERFILE)
  188. /* Option is to be stored in a SpecifierOptList.
  189. Always use as OPT_SPEC in option definitions. */
  190. #define OPT_FLAG_SPEC (1 << 9)
  191. #define OPT_SPEC (OPT_FLAG_SPEC | OPT_OFFSET)
  192. /* Option applies per-stream (implies OPT_SPEC). */
  193. #define OPT_FLAG_PERSTREAM (1 << 10)
  194. #define OPT_PERSTREAM (OPT_FLAG_PERSTREAM | OPT_SPEC)
  195. /* ffmpeg-only - specifies whether an OPT_PERFILE option applies to input,
  196. * output, or both. */
  197. #define OPT_INPUT (1 << 11)
  198. #define OPT_OUTPUT (1 << 12)
  199. /* This option is a "canonical" form, to which one or more alternatives
  200. * exist. These alternatives are listed in u1.names_alt. */
  201. #define OPT_HAS_ALT (1 << 13)
  202. /* This option is an alternative form of some other option, whose
  203. * name is stored in u1.name_canon */
  204. #define OPT_HAS_CANON (1 << 14)
  205. /* ffmpeg-only - OPT_PERFILE may apply to standalone decoders */
  206. #define OPT_DECODER (1 << 15)
  207. union {
  208. void *dst_ptr;
  209. int (*func_arg)(void *, const char *, const char *);
  210. size_t off;
  211. } u;
  212. const char *help;
  213. const char *argname;
  214. union {
  215. /* Name of the canonical form of this option.
  216. * Is valid when OPT_HAS_CANON is set. */
  217. const char *name_canon;
  218. /* A NULL-terminated list of alternate forms of this option.
  219. * Is valid when OPT_HAS_ALT is set. */
  220. const char * const *names_alt;
  221. } u1;
  222. } OptionDef;
  223. /**
  224. * Print help for all options matching specified flags.
  225. *
  226. * @param options a list of options
  227. * @param msg title of this group. Only printed if at least one option matches.
  228. * @param req_flags print only options which have all those flags set.
  229. * @param rej_flags don't print options which have any of those flags set.
  230. */
  231. void show_help_options(const OptionDef *options, const char *msg, int req_flags,
  232. int rej_flags);
  233. /**
  234. * Show help for all options with given flags in class and all its
  235. * children.
  236. */
  237. void show_help_children(const AVClass *class, int flags);
  238. /**
  239. * Per-fftool specific help handler. Implemented in each
  240. * fftool, called by show_help().
  241. */
  242. void show_help_default(const char *opt, const char *arg);
  243. /**
  244. * Parse the command line arguments.
  245. *
  246. * @param optctx an opaque options context
  247. * @param argc number of command line arguments
  248. * @param argv values of command line arguments
  249. * @param options Array with the definitions required to interpret every
  250. * option of the form: -option_name [argument]
  251. * @param parse_arg_function Name of the function called to process every
  252. * argument without a leading option name flag. NULL if such arguments do
  253. * not have to be processed.
  254. */
  255. int parse_options(void *optctx, int argc, char **argv, const OptionDef *options,
  256. int (* parse_arg_function)(void *optctx, const char*));
  257. /**
  258. * Parse one given option.
  259. *
  260. * @return on success 1 if arg was consumed, 0 otherwise; negative number on error
  261. */
  262. int parse_option(void *optctx, const char *opt, const char *arg,
  263. const OptionDef *options);
  264. /**
  265. * An option extracted from the commandline.
  266. * Cannot use AVDictionary because of options like -map which can be
  267. * used multiple times.
  268. */
  269. typedef struct Option {
  270. const OptionDef *opt;
  271. const char *key;
  272. const char *val;
  273. } Option;
  274. typedef struct OptionGroupDef {
  275. /**< group name */
  276. const char *name;
  277. /**
  278. * Option to be used as group separator. Can be NULL for groups which
  279. * are terminated by a non-option argument (e.g. ffmpeg output files)
  280. */
  281. const char *sep;
  282. /**
  283. * Option flags that must be set on each option that is
  284. * applied to this group
  285. */
  286. int flags;
  287. } OptionGroupDef;
  288. typedef struct OptionGroup {
  289. const OptionGroupDef *group_def;
  290. const char *arg;
  291. Option *opts;
  292. int nb_opts;
  293. AVDictionary *codec_opts;
  294. AVDictionary *format_opts;
  295. AVDictionary *sws_dict;
  296. AVDictionary *swr_opts;
  297. } OptionGroup;
  298. /**
  299. * A list of option groups that all have the same group type
  300. * (e.g. input files or output files)
  301. */
  302. typedef struct OptionGroupList {
  303. const OptionGroupDef *group_def;
  304. OptionGroup *groups;
  305. int nb_groups;
  306. } OptionGroupList;
  307. typedef struct OptionParseContext {
  308. OptionGroup global_opts;
  309. OptionGroupList *groups;
  310. int nb_groups;
  311. /* parsing state */
  312. OptionGroup cur_group;
  313. } OptionParseContext;
  314. /**
  315. * Parse an options group and write results into optctx.
  316. *
  317. * @param optctx an app-specific options context. NULL for global options group
  318. */
  319. int parse_optgroup(void *optctx, OptionGroup *g, const OptionDef *defs);
  320. /**
  321. * Split the commandline into an intermediate form convenient for further
  322. * processing.
  323. *
  324. * The commandline is assumed to be composed of options which either belong to a
  325. * group (those with OPT_SPEC, OPT_OFFSET or OPT_PERFILE) or are global
  326. * (everything else).
  327. *
  328. * A group (defined by an OptionGroupDef struct) is a sequence of options
  329. * terminated by either a group separator option (e.g. -i) or a parameter that
  330. * is not an option (doesn't start with -). A group without a separator option
  331. * must always be first in the supplied groups list.
  332. *
  333. * All options within the same group are stored in one OptionGroup struct in an
  334. * OptionGroupList, all groups with the same group definition are stored in one
  335. * OptionGroupList in OptionParseContext.groups. The order of group lists is the
  336. * same as the order of group definitions.
  337. */
  338. int split_commandline(OptionParseContext *octx, int argc, char *argv[],
  339. const OptionDef *options,
  340. const OptionGroupDef *groups, int nb_groups);
  341. /**
  342. * Free all allocated memory in an OptionParseContext.
  343. */
  344. void uninit_parse_context(OptionParseContext *octx);
  345. /**
  346. * Find the '-loglevel' option in the command line args and apply it.
  347. */
  348. void parse_loglevel(int argc, char **argv, const OptionDef *options);
  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. * Check if the given stream matches a stream specifier.
  356. *
  357. * @param s Corresponding format context.
  358. * @param st Stream from s to be checked.
  359. * @param spec A stream specifier of the [v|a|s|d]:[\<stream index\>] form.
  360. *
  361. * @return 1 if the stream matches, 0 if it doesn't, <0 on error
  362. */
  363. int check_stream_specifier(AVFormatContext *s, AVStream *st, const char *spec);
  364. /**
  365. * Filter out options for given codec.
  366. *
  367. * Create a new options dictionary containing only the options from
  368. * opts which apply to the codec with ID codec_id.
  369. *
  370. * @param opts dictionary to place options in
  371. * @param codec_id ID of the codec that should be filtered for
  372. * @param s Corresponding format context.
  373. * @param st A stream from s for which the options should be filtered.
  374. * @param codec The particular codec for which the options should be filtered.
  375. * If null, the default one is looked up according to the codec id.
  376. * @param dst a pointer to the created dictionary
  377. * @param opts_used if non-NULL, every option stored in dst is also stored here,
  378. * with specifiers preserved
  379. * @return a non-negative number on success, a negative error code on failure
  380. */
  381. int filter_codec_opts(const AVDictionary *opts, enum AVCodecID codec_id,
  382. AVFormatContext *s, AVStream *st, const AVCodec *codec,
  383. AVDictionary **dst, AVDictionary **opts_used);
  384. /**
  385. * Setup AVCodecContext options for avformat_find_stream_info().
  386. *
  387. * Create an array of dictionaries, one dictionary for each stream
  388. * contained in s.
  389. * Each dictionary will contain the options from codec_opts which can
  390. * be applied to the corresponding stream codec context.
  391. */
  392. int setup_find_stream_info_opts(AVFormatContext *s,
  393. AVDictionary *codec_opts,
  394. AVDictionary ***dst);
  395. /**
  396. * Print an error message to stderr, indicating filename and a human
  397. * readable description of the error code err.
  398. *
  399. * If strerror_r() is not available the use of this function in a
  400. * multithreaded application may be unsafe.
  401. *
  402. * @see av_strerror()
  403. */
  404. static inline void print_error(const char *filename, int err)
  405. {
  406. av_log(NULL, AV_LOG_ERROR, "%s: %s\n", filename, av_err2str(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. * Return a positive value if a line read from standard input
  416. * starts with [yY], otherwise return 0.
  417. */
  418. int read_yesno(void);
  419. /**
  420. * Get a file corresponding to a preset file.
  421. *
  422. * If is_path is non-zero, look for the file in the path preset_name.
  423. * Otherwise search for a file named arg.ffpreset in the directories
  424. * $FFMPEG_DATADIR (if set), $HOME/.ffmpeg, and in the datadir defined
  425. * at configuration time or in a "ffpresets" folder along the executable
  426. * on win32, in that order. If no such file is found and
  427. * codec_name is defined, then search for a file named
  428. * codec_name-preset_name.avpreset in the above-mentioned directories.
  429. *
  430. * @param filename buffer where the name of the found filename is written
  431. * @param filename_size size in bytes of the filename buffer
  432. * @param preset_name name of the preset to search
  433. * @param is_path tell if preset_name is a filename path
  434. * @param codec_name name of the codec for which to look for the
  435. * preset, may be NULL
  436. */
  437. FILE *get_preset_file(char *filename, size_t filename_size,
  438. const char *preset_name, int is_path, const char *codec_name);
  439. /**
  440. * Realloc array to hold new_size elements of elem_size.
  441. *
  442. * @param array pointer to the array to reallocate, will be updated
  443. * with a new pointer on success
  444. * @param elem_size size in bytes of each element
  445. * @param size new element count will be written here
  446. * @param new_size number of elements to place in reallocated array
  447. * @return a non-negative number on success, a negative error code on failure
  448. */
  449. int grow_array(void **array, int elem_size, int *size, int new_size);
  450. /**
  451. * Atomically add a new element to an array of pointers, i.e. allocate
  452. * a new entry, reallocate the array of pointers and make the new last
  453. * member of this array point to the newly allocated buffer.
  454. *
  455. * @param array array of pointers to reallocate
  456. * @param elem_size size of the new element to allocate
  457. * @param nb_elems pointer to the number of elements of the array array;
  458. * *nb_elems will be incremented by one by this function.
  459. * @return pointer to the newly allocated entry or NULL on failure
  460. */
  461. void *allocate_array_elem(void *array, size_t elem_size, int *nb_elems);
  462. #define GROW_ARRAY(array, nb_elems)\
  463. grow_array((void**)&array, sizeof(*array), &nb_elems, nb_elems + 1)
  464. double get_rotation(const int32_t *displaymatrix);
  465. /* read file contents into a string */
  466. char *file_read(const char *filename);
  467. /* Remove keys in dictionary b from dictionary a */
  468. void remove_avoptions(AVDictionary **a, AVDictionary *b);
  469. /* Check if any keys exist in dictionary m */
  470. int check_avoptions(AVDictionary *m);
  471. int cmdutils_isalnum(char c);
  472. #endif /* FFTOOLS_CMDUTILS_H */