FFmpeg coverage

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