lavu/parseutils: add digital cinema frame sizes
[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 ntsc
116 720x480
117 @item pal
118 720x576
119 @item qntsc
120 352x240
121 @item qpal
122 352x288
123 @item sntsc
124 640x480
125 @item spal
126 768x576
127 @item film
128 352x240
129 @item ntsc-film
130 352x240
131 @item sqcif
132 128x96
133 @item qcif
134 176x144
135 @item cif
136 352x288
137 @item 4cif
138 704x576
139 @item 16cif
140 1408x1152
141 @item qqvga
142 160x120
143 @item qvga
144 320x240
145 @item vga
146 640x480
147 @item svga
148 800x600
149 @item xga
150 1024x768
151 @item uxga
152 1600x1200
153 @item qxga
154 2048x1536
155 @item sxga
156 1280x1024
157 @item qsxga
158 2560x2048
159 @item hsxga
160 5120x4096
161 @item wvga
162 852x480
163 @item wxga
164 1366x768
165 @item wsxga
166 1600x1024
167 @item wuxga
168 1920x1200
169 @item woxga
170 2560x1600
171 @item wqsxga
172 3200x2048
173 @item wquxga
174 3840x2400
175 @item whsxga
176 6400x4096
177 @item whuxga
178 7680x4800
179 @item cga
180 320x200
181 @item ega
182 640x350
183 @item hd480
184 852x480
185 @item hd720
186 1280x720
187 @item hd1080
188 1920x1080
189 @item 2k
190 2048x1080
191 @item 2kflat
192 1998x1080
193 @item 2kscope
194 2048x858
195 @item 4k
196 4096x2160
197 @item 4kflat
198 3996x2160
199 @item 4kscope
200 4096x1716
201 @end table
202
203 @anchor{video rate syntax}
204 @section Video rate
205
206 Specify the frame rate of a video, expressed as the number of frames
207 generated per second. It has to be a string in the format
208 @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float
209 number or a valid video frame rate abbreviation.
210
211 The following abbreviations are recognized:
212 @table @samp
213 @item ntsc
214 30000/1001
215 @item pal
216 25/1
217 @item qntsc
218 30000/1001
219 @item qpal
220 25/1
221 @item sntsc
222 30000/1001
223 @item spal
224 25/1
225 @item film
226 24/1
227 @item ntsc-film
228 24000/1001
229 @end table
230
231 @anchor{ratio syntax}
232 @section Ratio
233
234 A ratio can be expressed as an expression, or in the form
235 @var{numerator}:@var{denominator}.
236
237 Note that a ratio with infinite (1/0) or negative value is
238 considered valid, so you should check on the returned value if you
239 want to exclude those values.
240
241 The undefined value can be expressed using the "0:0" string.
242
243 @anchor{color syntax}
244 @section Color
245
246 It can be the name of a color (case insensitive match) or a
247 [0x|#]RRGGBB[AA] sequence, possibly followed by "@@" and a string
248 representing the alpha component.
249
250 The alpha component may be a string composed by "0x" followed by an
251 hexadecimal number or a decimal number between 0.0 and 1.0, which
252 represents the opacity value (0x00/0.0 means completely transparent,
253 0xff/1.0 completely opaque).
254 If the alpha component is not specified then 0xff is assumed.
255
256 The string "random" will result in a random color.
257
258 @c man end SYNTAX