lavfi/kerndeint: remove unused pixel_step.
[ffmpeg.git] / doc / syntax.texi
1 @chapter Syntax
2 @c man begin SYNTAX
3
4 This section documents the syntax and formats employed by the FFmpeg
5 libraries and tools.
6
7 @anchor{quoting_and_escaping}
8 @section Quoting and escaping
9
10 FFmpeg adopts the following quoting and escaping mechanism, unless
11 explicitly specified. The following rules are applied:
12
13 @itemize
14 @item
15 @code{'} and @code{\} are special characters (respectively used for
16 quoting and escaping). In addition to them, there might be other
17 special characters depending on the specific syntax where the escaping
18 and quoting are employed.
19
20 @item
21 A special character is escaped by prefixing it with a '\'.
22
23 @item
24 All characters enclosed between '' are included literally in the
25 parsed string. The quote character @code{'} itself cannot be quoted,
26 so you may need to close the quote and escape it.
27
28 @item
29 Leading and trailing whitespaces, unless escaped or quoted, are
30 removed from the parsed string.
31 @end itemize
32
33 Note that you may need to add a second level of escaping when using
34 the command line or a script, which depends on the syntax of the
35 adopted shell language.
36
37 The function @code{av_get_token} defined in
38 @file{libavutil/avstring.h} can be used to parse a token quoted or
39 escaped according to the rules defined above.
40
41 The tool @file{tools/ffescape} in the FFmpeg source tree can be used
42 to automatically quote or escape a string in a script.
43
44 @subsection Examples
45
46 @itemize
47 @item
48 Escape the string @code{Crime d'Amour} containing the @code{'} special
49 character:
50 @example
51 Crime d\'Amour
52 @end example
53
54 @item
55 The string above contains a quote, so the @code{'} needs to be escaped
56 when quoting it:
57 @example
58 'Crime d'\''Amour'
59 @end example
60
61 @item
62 Include leading or trailing whitespaces using quoting:
63 @example
64 '  this string starts and ends with whitespaces  '
65 @end example
66
67 @item
68 Escaping and quoting can be mixed together:
69 @example
70 ' The string '\'string\'' is a string '
71 @end example
72
73 @item
74 To include a literal @code{\} you can use either escaping or quoting:
75 @example
76 'c:\foo' can be written as c:\\foo
77 @end example
78 @end itemize
79
80 @anchor{date syntax}
81 @section Date
82
83 The accepted syntax is:
84 @example
85 [(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z]
86 now
87 @end example
88
89 If the value is "now" it takes the current time.
90
91 Time is local time unless Z is appended, in which case it is
92 interpreted as UTC.
93 If the year-month-day part is not specified it takes the current
94 year-month-day.
95
96 @anchor{time duration syntax}
97 @section Time duration
98
99 The accepted syntax is:
100 @example
101 [-]HH:MM:SS[.m...]
102 [-]S+[.m...]
103 @end example
104
105 @var{HH} expresses the number of hours, @var{MM} the number a of minutes
106 and @var{SS} the number of seconds.
107
108 @anchor{video size syntax}
109 @section Video size
110 Specify the size of the sourced video, it may be a string of the form
111 @var{width}x@var{height}, or the name of a size abbreviation.
112
113 The following abbreviations are recognized:
114 @table @samp
115 @item sqcif
116 128x96
117 @item qcif
118 176x144
119 @item cif
120 352x288
121 @item 4cif
122 704x576
123 @item 16cif
124 1408x1152
125 @item qqvga
126 160x120
127 @item qvga
128 320x240
129 @item vga
130 640x480
131 @item svga
132 800x600
133 @item xga
134 1024x768
135 @item uxga
136 1600x1200
137 @item qxga
138 2048x1536
139 @item sxga
140 1280x1024
141 @item qsxga
142 2560x2048
143 @item hsxga
144 5120x4096
145 @item wvga
146 852x480
147 @item wxga
148 1366x768
149 @item wsxga
150 1600x1024
151 @item wuxga
152 1920x1200
153 @item woxga
154 2560x1600
155 @item wqsxga
156 3200x2048
157 @item wquxga
158 3840x2400
159 @item whsxga
160 6400x4096
161 @item whuxga
162 7680x4800
163 @item cga
164 320x200
165 @item ega
166 640x350
167 @item hd480
168 852x480
169 @item hd720
170 1280x720
171 @item hd1080
172 1920x1080
173 @end table
174
175 @anchor{video rate syntax}
176 @section Video rate
177
178 Specify the frame rate of a video, expressed as the number of frames
179 generated per second. It has to be a string in the format
180 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
181 number or a valid video frame rate abbreviation.
182
183 The following abbreviations are recognized:
184 @table @samp
185 @item ntsc
186 30000/1001
187 @item pal
188 25/1
189 @item qntsc
190 30000/1
191 @item qpal
192 25/1
193 @item sntsc
194 30000/1
195 @item spal
196 25/1
197 @item film
198 24/1
199 @item ntsc-film
200 24000/1
201 @end table
202
203 @anchor{ratio syntax}
204 @section Ratio
205
206 A ratio can be expressed as an expression, or in the form
207 @var{numerator}:@var{denominator}.
208
209 Note that a ratio with infinite (1/0) or negative value is
210 considered valid, so you should check on the returned value if you
211 want to exclude those values.
212
213 The undefined value can be expressed using the "0:0" string.
214
215 @anchor{color syntax}
216 @section Color
217
218 It can be the name of a color (case insensitive match) or a
219 [0x|#]RRGGBB[AA] sequence, possibly followed by "@@" and a string
220 representing the alpha component.
221
222 The alpha component may be a string composed by "0x" followed by an
223 hexadecimal number or a decimal number between 0.0 and 1.0, which
224 represents the opacity value (0x00/0.0 means completely transparent,
225 0xff/1.0 completely opaque).
226 If the alpha component is not specified then 0xff is assumed.
227
228 The string "random" will result in a random color.
229
230 @c man end SYNTAX