Go to most recent revision | Details | Last modification | View Log | RSS feed
Rev | Author | Line No. | Line |
---|---|---|---|
4349 | Serge | 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 | There are two accepted syntaxes for expressing time duration. |
||
100 | |||
101 | @example |
||
102 | [-][@var{HH}:]@var{MM}:@var{SS}[.@var{m}...] |
||
103 | @end example |
||
104 | |||
105 | @var{HH} expresses the number of hours, @var{MM} the number of minutes |
||
106 | for a maximum of 2 digits, and @var{SS} the number of seconds for a |
||
107 | maximum of 2 digits. The @var{m} at the end expresses decimal value for |
||
108 | @var{SS}. |
||
109 | |||
110 | @emph{or} |
||
111 | |||
112 | @example |
||
113 | [-]@var{S}+[.@var{m}...] |
||
114 | @end example |
||
115 | |||
116 | @var{S} expresses the number of seconds, with the optional decimal part |
||
117 | @var{m}. |
||
118 | |||
119 | In both expressions, the optional @samp{-} indicates negative duration. |
||
120 | |||
121 | @subsection Examples |
||
122 | |||
123 | The following examples are all valid time duration: |
||
124 | |||
125 | @table @samp |
||
126 | @item 55 |
||
127 | 55 seconds |
||
128 | |||
129 | @item 12:03:45 |
||
130 | 12 hours, 03 minutes and 45 seconds |
||
131 | |||
132 | @item 23.189 |
||
133 | 23.189 seconds |
||
134 | @end table |
||
135 | |||
136 | @anchor{video size syntax} |
||
137 | @section Video size |
||
138 | Specify the size of the sourced video, it may be a string of the form |
||
139 | @var{width}x@var{height}, or the name of a size abbreviation. |
||
140 | |||
141 | The following abbreviations are recognized: |
||
142 | @table @samp |
||
143 | @item ntsc |
||
144 | 720x480 |
||
145 | @item pal |
||
146 | 720x576 |
||
147 | @item qntsc |
||
148 | 352x240 |
||
149 | @item qpal |
||
150 | 352x288 |
||
151 | @item sntsc |
||
152 | 640x480 |
||
153 | @item spal |
||
154 | 768x576 |
||
155 | @item film |
||
156 | 352x240 |
||
157 | @item ntsc-film |
||
158 | 352x240 |
||
159 | @item sqcif |
||
160 | 128x96 |
||
161 | @item qcif |
||
162 | 176x144 |
||
163 | @item cif |
||
164 | 352x288 |
||
165 | @item 4cif |
||
166 | 704x576 |
||
167 | @item 16cif |
||
168 | 1408x1152 |
||
169 | @item qqvga |
||
170 | 160x120 |
||
171 | @item qvga |
||
172 | 320x240 |
||
173 | @item vga |
||
174 | 640x480 |
||
175 | @item svga |
||
176 | 800x600 |
||
177 | @item xga |
||
178 | 1024x768 |
||
179 | @item uxga |
||
180 | 1600x1200 |
||
181 | @item qxga |
||
182 | 2048x1536 |
||
183 | @item sxga |
||
184 | 1280x1024 |
||
185 | @item qsxga |
||
186 | 2560x2048 |
||
187 | @item hsxga |
||
188 | 5120x4096 |
||
189 | @item wvga |
||
190 | 852x480 |
||
191 | @item wxga |
||
192 | 1366x768 |
||
193 | @item wsxga |
||
194 | 1600x1024 |
||
195 | @item wuxga |
||
196 | 1920x1200 |
||
197 | @item woxga |
||
198 | 2560x1600 |
||
199 | @item wqsxga |
||
200 | 3200x2048 |
||
201 | @item wquxga |
||
202 | 3840x2400 |
||
203 | @item whsxga |
||
204 | 6400x4096 |
||
205 | @item whuxga |
||
206 | 7680x4800 |
||
207 | @item cga |
||
208 | 320x200 |
||
209 | @item ega |
||
210 | 640x350 |
||
211 | @item hd480 |
||
212 | 852x480 |
||
213 | @item hd720 |
||
214 | 1280x720 |
||
215 | @item hd1080 |
||
216 | 1920x1080 |
||
217 | @item 2k |
||
218 | 2048x1080 |
||
219 | @item 2kflat |
||
220 | 1998x1080 |
||
221 | @item 2kscope |
||
222 | 2048x858 |
||
223 | @item 4k |
||
224 | 4096x2160 |
||
225 | @item 4kflat |
||
226 | 3996x2160 |
||
227 | @item 4kscope |
||
228 | 4096x1716 |
||
229 | @item nhd |
||
230 | 640x360 |
||
231 | @item hqvga |
||
232 | 240x160 |
||
233 | @item wqvga |
||
234 | 400x240 |
||
235 | @item fwqvga |
||
236 | 432x240 |
||
237 | @item hvga |
||
238 | 480x320 |
||
239 | @item qhd |
||
240 | 960x540 |
||
241 | @end table |
||
242 | |||
243 | @anchor{video rate syntax} |
||
244 | @section Video rate |
||
245 | |||
246 | Specify the frame rate of a video, expressed as the number of frames |
||
247 | generated per second. It has to be a string in the format |
||
248 | @var{frame_rate_num}/@var{frame_rate_den}, an integer number, a float |
||
249 | number or a valid video frame rate abbreviation. |
||
250 | |||
251 | The following abbreviations are recognized: |
||
252 | @table @samp |
||
253 | @item ntsc |
||
254 | 30000/1001 |
||
255 | @item pal |
||
256 | 25/1 |
||
257 | @item qntsc |
||
258 | 30000/1001 |
||
259 | @item qpal |
||
260 | 25/1 |
||
261 | @item sntsc |
||
262 | 30000/1001 |
||
263 | @item spal |
||
264 | 25/1 |
||
265 | @item film |
||
266 | 24/1 |
||
267 | @item ntsc-film |
||
268 | 24000/1001 |
||
269 | @end table |
||
270 | |||
271 | @anchor{ratio syntax} |
||
272 | @section Ratio |
||
273 | |||
274 | A ratio can be expressed as an expression, or in the form |
||
275 | @var{numerator}:@var{denominator}. |
||
276 | |||
277 | Note that a ratio with infinite (1/0) or negative value is |
||
278 | considered valid, so you should check on the returned value if you |
||
279 | want to exclude those values. |
||
280 | |||
281 | The undefined value can be expressed using the "0:0" string. |
||
282 | |||
283 | @anchor{color syntax} |
||
284 | @section Color |
||
285 | |||
286 | It can be the name of a color as defined below (case insensitive match) or a |
||
287 | @code{[0x|#]RRGGBB[AA]} sequence, possibly followed by @@ and a string |
||
288 | representing the alpha component. |
||
289 | |||
290 | The alpha component may be a string composed by "0x" followed by an |
||
291 | hexadecimal number or a decimal number between 0.0 and 1.0, which |
||
292 | represents the opacity value (@samp{0x00} or @samp{0.0} means completely |
||
293 | transparent, @samp{0xff} or @samp{1.0} completely opaque). If the alpha |
||
294 | component is not specified then @samp{0xff} is assumed. |
||
295 | |||
296 | The string @samp{random} will result in a random color. |
||
297 | |||
298 | The following names of colors are recognized: |
||
299 | @table @samp |
||
300 | @item AliceBlue |
||
301 | 0xF0F8FF |
||
302 | @item AntiqueWhite |
||
303 | 0xFAEBD7 |
||
304 | @item Aqua |
||
305 | 0x00FFFF |
||
306 | @item Aquamarine |
||
307 | 0x7FFFD4 |
||
308 | @item Azure |
||
309 | 0xF0FFFF |
||
310 | @item Beige |
||
311 | 0xF5F5DC |
||
312 | @item Bisque |
||
313 | 0xFFE4C4 |
||
314 | @item Black |
||
315 | 0x000000 |
||
316 | @item BlanchedAlmond |
||
317 | 0xFFEBCD |
||
318 | @item Blue |
||
319 | 0x0000FF |
||
320 | @item BlueViolet |
||
321 | 0x8A2BE2 |
||
322 | @item Brown |
||
323 | 0xA52A2A |
||
324 | @item BurlyWood |
||
325 | 0xDEB887 |
||
326 | @item CadetBlue |
||
327 | 0x5F9EA0 |
||
328 | @item Chartreuse |
||
329 | 0x7FFF00 |
||
330 | @item Chocolate |
||
331 | 0xD2691E |
||
332 | @item Coral |
||
333 | 0xFF7F50 |
||
334 | @item CornflowerBlue |
||
335 | 0x6495ED |
||
336 | @item Cornsilk |
||
337 | 0xFFF8DC |
||
338 | @item Crimson |
||
339 | 0xDC143C |
||
340 | @item Cyan |
||
341 | 0x00FFFF |
||
342 | @item DarkBlue |
||
343 | 0x00008B |
||
344 | @item DarkCyan |
||
345 | 0x008B8B |
||
346 | @item DarkGoldenRod |
||
347 | 0xB8860B |
||
348 | @item DarkGray |
||
349 | 0xA9A9A9 |
||
350 | @item DarkGreen |
||
351 | 0x006400 |
||
352 | @item DarkKhaki |
||
353 | 0xBDB76B |
||
354 | @item DarkMagenta |
||
355 | 0x8B008B |
||
356 | @item DarkOliveGreen |
||
357 | 0x556B2F |
||
358 | @item Darkorange |
||
359 | 0xFF8C00 |
||
360 | @item DarkOrchid |
||
361 | 0x9932CC |
||
362 | @item DarkRed |
||
363 | 0x8B0000 |
||
364 | @item DarkSalmon |
||
365 | 0xE9967A |
||
366 | @item DarkSeaGreen |
||
367 | 0x8FBC8F |
||
368 | @item DarkSlateBlue |
||
369 | 0x483D8B |
||
370 | @item DarkSlateGray |
||
371 | 0x2F4F4F |
||
372 | @item DarkTurquoise |
||
373 | 0x00CED1 |
||
374 | @item DarkViolet |
||
375 | 0x9400D3 |
||
376 | @item DeepPink |
||
377 | 0xFF1493 |
||
378 | @item DeepSkyBlue |
||
379 | 0x00BFFF |
||
380 | @item DimGray |
||
381 | 0x696969 |
||
382 | @item DodgerBlue |
||
383 | 0x1E90FF |
||
384 | @item FireBrick |
||
385 | 0xB22222 |
||
386 | @item FloralWhite |
||
387 | 0xFFFAF0 |
||
388 | @item ForestGreen |
||
389 | 0x228B22 |
||
390 | @item Fuchsia |
||
391 | 0xFF00FF |
||
392 | @item Gainsboro |
||
393 | 0xDCDCDC |
||
394 | @item GhostWhite |
||
395 | 0xF8F8FF |
||
396 | @item Gold |
||
397 | 0xFFD700 |
||
398 | @item GoldenRod |
||
399 | 0xDAA520 |
||
400 | @item Gray |
||
401 | 0x808080 |
||
402 | @item Green |
||
403 | 0x008000 |
||
404 | @item GreenYellow |
||
405 | 0xADFF2F |
||
406 | @item HoneyDew |
||
407 | 0xF0FFF0 |
||
408 | @item HotPink |
||
409 | 0xFF69B4 |
||
410 | @item IndianRed |
||
411 | 0xCD5C5C |
||
412 | @item Indigo |
||
413 | 0x4B0082 |
||
414 | @item Ivory |
||
415 | 0xFFFFF0 |
||
416 | @item Khaki |
||
417 | 0xF0E68C |
||
418 | @item Lavender |
||
419 | 0xE6E6FA |
||
420 | @item LavenderBlush |
||
421 | 0xFFF0F5 |
||
422 | @item LawnGreen |
||
423 | 0x7CFC00 |
||
424 | @item LemonChiffon |
||
425 | 0xFFFACD |
||
426 | @item LightBlue |
||
427 | 0xADD8E6 |
||
428 | @item LightCoral |
||
429 | 0xF08080 |
||
430 | @item LightCyan |
||
431 | 0xE0FFFF |
||
432 | @item LightGoldenRodYellow |
||
433 | 0xFAFAD2 |
||
434 | @item LightGreen |
||
435 | 0x90EE90 |
||
436 | @item LightGrey |
||
437 | 0xD3D3D3 |
||
438 | @item LightPink |
||
439 | 0xFFB6C1 |
||
440 | @item LightSalmon |
||
441 | 0xFFA07A |
||
442 | @item LightSeaGreen |
||
443 | 0x20B2AA |
||
444 | @item LightSkyBlue |
||
445 | 0x87CEFA |
||
446 | @item LightSlateGray |
||
447 | 0x778899 |
||
448 | @item LightSteelBlue |
||
449 | 0xB0C4DE |
||
450 | @item LightYellow |
||
451 | 0xFFFFE0 |
||
452 | @item Lime |
||
453 | 0x00FF00 |
||
454 | @item LimeGreen |
||
455 | 0x32CD32 |
||
456 | @item Linen |
||
457 | 0xFAF0E6 |
||
458 | @item Magenta |
||
459 | 0xFF00FF |
||
460 | @item Maroon |
||
461 | 0x800000 |
||
462 | @item MediumAquaMarine |
||
463 | 0x66CDAA |
||
464 | @item MediumBlue |
||
465 | 0x0000CD |
||
466 | @item MediumOrchid |
||
467 | 0xBA55D3 |
||
468 | @item MediumPurple |
||
469 | 0x9370D8 |
||
470 | @item MediumSeaGreen |
||
471 | 0x3CB371 |
||
472 | @item MediumSlateBlue |
||
473 | 0x7B68EE |
||
474 | @item MediumSpringGreen |
||
475 | 0x00FA9A |
||
476 | @item MediumTurquoise |
||
477 | 0x48D1CC |
||
478 | @item MediumVioletRed |
||
479 | 0xC71585 |
||
480 | @item MidnightBlue |
||
481 | 0x191970 |
||
482 | @item MintCream |
||
483 | 0xF5FFFA |
||
484 | @item MistyRose |
||
485 | 0xFFE4E1 |
||
486 | @item Moccasin |
||
487 | 0xFFE4B5 |
||
488 | @item NavajoWhite |
||
489 | 0xFFDEAD |
||
490 | @item Navy |
||
491 | 0x000080 |
||
492 | @item OldLace |
||
493 | 0xFDF5E6 |
||
494 | @item Olive |
||
495 | 0x808000 |
||
496 | @item OliveDrab |
||
497 | 0x6B8E23 |
||
498 | @item Orange |
||
499 | 0xFFA500 |
||
500 | @item OrangeRed |
||
501 | 0xFF4500 |
||
502 | @item Orchid |
||
503 | 0xDA70D6 |
||
504 | @item PaleGoldenRod |
||
505 | 0xEEE8AA |
||
506 | @item PaleGreen |
||
507 | 0x98FB98 |
||
508 | @item PaleTurquoise |
||
509 | 0xAFEEEE |
||
510 | @item PaleVioletRed |
||
511 | 0xD87093 |
||
512 | @item PapayaWhip |
||
513 | 0xFFEFD5 |
||
514 | @item PeachPuff |
||
515 | 0xFFDAB9 |
||
516 | @item Peru |
||
517 | 0xCD853F |
||
518 | @item Pink |
||
519 | 0xFFC0CB |
||
520 | @item Plum |
||
521 | 0xDDA0DD |
||
522 | @item PowderBlue |
||
523 | 0xB0E0E6 |
||
524 | @item Purple |
||
525 | 0x800080 |
||
526 | @item Red |
||
527 | 0xFF0000 |
||
528 | @item RosyBrown |
||
529 | 0xBC8F8F |
||
530 | @item RoyalBlue |
||
531 | 0x4169E1 |
||
532 | @item SaddleBrown |
||
533 | 0x8B4513 |
||
534 | @item Salmon |
||
535 | 0xFA8072 |
||
536 | @item SandyBrown |
||
537 | 0xF4A460 |
||
538 | @item SeaGreen |
||
539 | 0x2E8B57 |
||
540 | @item SeaShell |
||
541 | 0xFFF5EE |
||
542 | @item Sienna |
||
543 | 0xA0522D |
||
544 | @item Silver |
||
545 | 0xC0C0C0 |
||
546 | @item SkyBlue |
||
547 | 0x87CEEB |
||
548 | @item SlateBlue |
||
549 | 0x6A5ACD |
||
550 | @item SlateGray |
||
551 | 0x708090 |
||
552 | @item Snow |
||
553 | 0xFFFAFA |
||
554 | @item SpringGreen |
||
555 | 0x00FF7F |
||
556 | @item SteelBlue |
||
557 | 0x4682B4 |
||
558 | @item Tan |
||
559 | 0xD2B48C |
||
560 | @item Teal |
||
561 | 0x008080 |
||
562 | @item Thistle |
||
563 | 0xD8BFD8 |
||
564 | @item Tomato |
||
565 | 0xFF6347 |
||
566 | @item Turquoise |
||
567 | 0x40E0D0 |
||
568 | @item Violet |
||
569 | 0xEE82EE |
||
570 | @item Wheat |
||
571 | 0xF5DEB3 |
||
572 | @item White |
||
573 | 0xFFFFFF |
||
574 | @item WhiteSmoke |
||
575 | 0xF5F5F5 |
||
576 | @item Yellow |
||
577 | 0xFFFF00 |
||
578 | @item YellowGreen |
||
579 | 0x9ACD32 |
||
580 | @end table |
||
581 | |||
582 | @anchor{channel layout syntax} |
||
583 | @section Channel Layout |
||
584 | |||
585 | A channel layout specifies the spatial disposition of the channels in |
||
586 | a multi-channel audio stream. To specify a channel layout, FFmpeg |
||
587 | makes use of a special syntax. |
||
588 | |||
589 | Individual channels are identified by an id, as given by the table |
||
590 | below: |
||
591 | @table @samp |
||
592 | @item FL |
||
593 | front left |
||
594 | @item FR |
||
595 | front right |
||
596 | @item FC |
||
597 | front center |
||
598 | @item LFE |
||
599 | low frequency |
||
600 | @item BL |
||
601 | back left |
||
602 | @item BR |
||
603 | back right |
||
604 | @item FLC |
||
605 | front left-of-center |
||
606 | @item FRC |
||
607 | front right-of-center |
||
608 | @item BC |
||
609 | back center |
||
610 | @item SL |
||
611 | side left |
||
612 | @item SR |
||
613 | side right |
||
614 | @item TC |
||
615 | top center |
||
616 | @item TFL |
||
617 | top front left |
||
618 | @item TFC |
||
619 | top front center |
||
620 | @item TFR |
||
621 | top front right |
||
622 | @item TBL |
||
623 | top back left |
||
624 | @item TBC |
||
625 | top back center |
||
626 | @item TBR |
||
627 | top back right |
||
628 | @item DL |
||
629 | downmix left |
||
630 | @item DR |
||
631 | downmix right |
||
632 | @item WL |
||
633 | wide left |
||
634 | @item WR |
||
635 | wide right |
||
636 | @item SDL |
||
637 | surround direct left |
||
638 | @item SDR |
||
639 | surround direct right |
||
640 | @item LFE2 |
||
641 | low frequency 2 |
||
642 | @end table |
||
643 | |||
644 | Standard channel layout compositions can be specified by using the |
||
645 | following identifiers: |
||
646 | @table @samp |
||
647 | @item mono |
||
648 | FC |
||
649 | @item stereo |
||
650 | FL+FR |
||
651 | @item 2.1 |
||
652 | FL+FR+LFE |
||
653 | @item 3.0 |
||
654 | FL+FR+FC |
||
655 | @item 3.0(back) |
||
656 | FL+FR+BC |
||
657 | @item 4.0 |
||
658 | FL+FR+FC+BC |
||
659 | @item quad |
||
660 | FL+FR+BL+BR |
||
661 | @item quad(side) |
||
662 | FL+FR+SL+SR |
||
663 | @item 3.1 |
||
664 | FL+FR+FC+LFE |
||
665 | @item 5.0 |
||
666 | FL+FR+FC+BL+BR |
||
667 | @item 5.0(side) |
||
668 | FL+FR+FC+SL+SR |
||
669 | @item 4.1 |
||
670 | FL+FR+FC+LFE+BC |
||
671 | @item 5.1 |
||
672 | FL+FR+FC+LFE+BL+BR |
||
673 | @item 5.1(side) |
||
674 | FL+FR+FC+LFE+SL+SR |
||
675 | @item 6.0 |
||
676 | FL+FR+FC+BC+SL+SR |
||
677 | @item 6.0(front) |
||
678 | FL+FR+FLC+FRC+SL+SR |
||
679 | @item hexagonal |
||
680 | FL+FR+FC+BL+BR+BC |
||
681 | @item 6.1 |
||
682 | FL+FR+FC+LFE+BC+SL+SR |
||
683 | @item 6.1 |
||
684 | FL+FR+FC+LFE+BL+BR+BC |
||
685 | @item 6.1(front) |
||
686 | FL+FR+LFE+FLC+FRC+SL+SR |
||
687 | @item 7.0 |
||
688 | FL+FR+FC+BL+BR+SL+SR |
||
689 | @item 7.0(front) |
||
690 | FL+FR+FC+FLC+FRC+SL+SR |
||
691 | @item 7.1 |
||
692 | FL+FR+FC+LFE+BL+BR+SL+SR |
||
693 | @item 7.1(wide) |
||
694 | FL+FR+FC+LFE+BL+BR+FLC+FRC |
||
695 | @item 7.1(wide-side) |
||
696 | FL+FR+FC+LFE+FLC+FRC+SL+SR |
||
697 | @item octagonal |
||
698 | FL+FR+FC+BL+BR+BC+SL+SR |
||
699 | @item downmix |
||
700 | DL+DR |
||
701 | @end table |
||
702 | |||
703 | A custom channel layout can be specified as a sequence of terms, separated by |
||
704 | '+' or '|'. Each term can be: |
||
705 | @itemize |
||
706 | @item |
||
707 | the name of a standard channel layout (e.g. @samp{mono}, |
||
708 | @samp{stereo}, @samp{4.0}, @samp{quad}, @samp{5.0}, etc.) |
||
709 | |||
710 | @item |
||
711 | the name of a single channel (e.g. @samp{FL}, @samp{FR}, @samp{FC}, @samp{LFE}, etc.) |
||
712 | |||
713 | @item |
||
714 | a number of channels, in decimal, optionally followed by 'c', yielding |
||
715 | the default channel layout for that number of channels (see the |
||
716 | function @code{av_get_default_channel_layout}) |
||
717 | |||
718 | @item |
||
719 | a channel layout mask, in hexadecimal starting with "0x" (see the |
||
720 | @code{AV_CH_*} macros in @file{libavutil/channel_layout.h}. |
||
721 | @end itemize |
||
722 | |||
723 | Starting from libavutil version 53 the trailing character "c" to |
||
724 | specify a number of channels will be required, while a channel layout |
||
725 | mask could also be specified as a decimal number (if and only if not |
||
726 | followed by "c"). |
||
727 | |||
728 | See also the function @code{av_get_channel_layout} defined in |
||
729 | @file{libavutil/channel_layout.h}. |
||
730 | @c man end SYNTAX |
||
731 | |||
732 | @chapter Expression Evaluation |
||
733 | @c man begin EXPRESSION EVALUATION |
||
734 | |||
735 | When evaluating an arithmetic expression, FFmpeg uses an internal |
||
736 | formula evaluator, implemented through the @file{libavutil/eval.h} |
||
737 | interface. |
||
738 | |||
739 | An expression may contain unary, binary operators, constants, and |
||
740 | functions. |
||
741 | |||
742 | Two expressions @var{expr1} and @var{expr2} can be combined to form |
||
743 | another expression "@var{expr1};@var{expr2}". |
||
744 | @var{expr1} and @var{expr2} are evaluated in turn, and the new |
||
745 | expression evaluates to the value of @var{expr2}. |
||
746 | |||
747 | The following binary operators are available: @code{+}, @code{-}, |
||
748 | @code{*}, @code{/}, @code{^}. |
||
749 | |||
750 | The following unary operators are available: @code{+}, @code{-}. |
||
751 | |||
752 | The following functions are available: |
||
753 | @table @option |
||
754 | @item abs(x) |
||
755 | Compute absolute value of @var{x}. |
||
756 | |||
757 | @item acos(x) |
||
758 | Compute arccosine of @var{x}. |
||
759 | |||
760 | @item asin(x) |
||
761 | Compute arcsine of @var{x}. |
||
762 | |||
763 | @item atan(x) |
||
764 | Compute arctangent of @var{x}. |
||
765 | |||
766 | @item between(x, min, max) |
||
767 | Return 1 if @var{x} is greater than or equal to @var{min} and lesser than or |
||
768 | equal to @var{max}, 0 otherwise. |
||
769 | |||
770 | @item bitand(x, y) |
||
771 | @item bitor(x, y) |
||
772 | Compute bitwise and/or operation on @var{x} and @var{y}. |
||
773 | |||
774 | The results of the evaluation of @var{x} and @var{y} are converted to |
||
775 | integers before executing the bitwise operation. |
||
776 | |||
777 | Note that both the conversion to integer and the conversion back to |
||
778 | floating point can lose precision. Beware of unexpected results for |
||
779 | large numbers (usually 2^53 and larger). |
||
780 | |||
781 | @item ceil(expr) |
||
782 | Round the value of expression @var{expr} upwards to the nearest |
||
783 | integer. For example, "ceil(1.5)" is "2.0". |
||
784 | |||
785 | @item cos(x) |
||
786 | Compute cosine of @var{x}. |
||
787 | |||
788 | @item cosh(x) |
||
789 | Compute hyperbolic cosine of @var{x}. |
||
790 | |||
791 | @item eq(x, y) |
||
792 | Return 1 if @var{x} and @var{y} are equivalent, 0 otherwise. |
||
793 | |||
794 | @item exp(x) |
||
795 | Compute exponential of @var{x} (with base @code{e}, the Euler's number). |
||
796 | |||
797 | @item floor(expr) |
||
798 | Round the value of expression @var{expr} downwards to the nearest |
||
799 | integer. For example, "floor(-1.5)" is "-2.0". |
||
800 | |||
801 | @item gauss(x) |
||
802 | Compute Gauss function of @var{x}, corresponding to |
||
803 | @code{exp(-x*x/2) / sqrt(2*PI)}. |
||
804 | |||
805 | @item gcd(x, y) |
||
806 | Return the greatest common divisor of @var{x} and @var{y}. If both @var{x} and |
||
807 | @var{y} are 0 or either or both are less than zero then behavior is undefined. |
||
808 | |||
809 | @item gt(x, y) |
||
810 | Return 1 if @var{x} is greater than @var{y}, 0 otherwise. |
||
811 | |||
812 | @item gte(x, y) |
||
813 | Return 1 if @var{x} is greater than or equal to @var{y}, 0 otherwise. |
||
814 | |||
815 | @item hypot(x, y) |
||
816 | This function is similar to the C function with the same name; it returns |
||
817 | "sqrt(@var{x}*@var{x} + @var{y}*@var{y})", the length of the hypotenuse of a |
||
818 | right triangle with sides of length @var{x} and @var{y}, or the distance of the |
||
819 | point (@var{x}, @var{y}) from the origin. |
||
820 | |||
821 | @item if(x, y) |
||
822 | Evaluate @var{x}, and if the result is non-zero return the result of |
||
823 | the evaluation of @var{y}, return 0 otherwise. |
||
824 | |||
825 | @item if(x, y, z) |
||
826 | Evaluate @var{x}, and if the result is non-zero return the evaluation |
||
827 | result of @var{y}, otherwise the evaluation result of @var{z}. |
||
828 | |||
829 | @item ifnot(x, y) |
||
830 | Evaluate @var{x}, and if the result is zero return the result of the |
||
831 | evaluation of @var{y}, return 0 otherwise. |
||
832 | |||
833 | @item ifnot(x, y, z) |
||
834 | Evaluate @var{x}, and if the result is zero return the evaluation |
||
835 | result of @var{y}, otherwise the evaluation result of @var{z}. |
||
836 | |||
837 | @item isinf(x) |
||
838 | Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise. |
||
839 | |||
840 | @item isnan(x) |
||
841 | Return 1.0 if @var{x} is NAN, 0.0 otherwise. |
||
842 | |||
843 | @item ld(var) |
||
844 | Allow to load the value of the internal variable with number |
||
845 | @var{var}, which was previously stored with st(@var{var}, @var{expr}). |
||
846 | The function returns the loaded value. |
||
847 | |||
848 | @item log(x) |
||
849 | Compute natural logarithm of @var{x}. |
||
850 | |||
851 | @item lt(x, y) |
||
852 | Return 1 if @var{x} is lesser than @var{y}, 0 otherwise. |
||
853 | |||
854 | @item lte(x, y) |
||
855 | Return 1 if @var{x} is lesser than or equal to @var{y}, 0 otherwise. |
||
856 | |||
857 | @item max(x, y) |
||
858 | Return the maximum between @var{x} and @var{y}. |
||
859 | |||
860 | @item min(x, y) |
||
861 | Return the maximum between @var{x} and @var{y}. |
||
862 | |||
863 | @item mod(x, y) |
||
864 | Compute the remainder of division of @var{x} by @var{y}. |
||
865 | |||
866 | @item not(expr) |
||
867 | Return 1.0 if @var{expr} is zero, 0.0 otherwise. |
||
868 | |||
869 | @item pow(x, y) |
||
870 | Compute the power of @var{x} elevated @var{y}, it is equivalent to |
||
871 | "(@var{x})^(@var{y})". |
||
872 | |||
873 | @item print(t) |
||
874 | @item print(t, l) |
||
875 | Print the value of expression @var{t} with loglevel @var{l}. If |
||
876 | @var{l} is not specified then a default log level is used. |
||
877 | Returns the value of the expression printed. |
||
878 | |||
879 | Prints t with loglevel l |
||
880 | |||
881 | @item random(x) |
||
882 | Return a pseudo random value between 0.0 and 1.0. @var{x} is the index of the |
||
883 | internal variable which will be used to save the seed/state. |
||
884 | |||
885 | @item root(expr, max) |
||
886 | Find an input value for which the function represented by @var{expr} |
||
887 | with argument @var{ld(0)} is 0 in the interval 0..@var{max}. |
||
888 | |||
889 | The expression in @var{expr} must denote a continuous function or the |
||
890 | result is undefined. |
||
891 | |||
892 | @var{ld(0)} is used to represent the function input value, which means |
||
893 | that the given expression will be evaluated multiple times with |
||
894 | various input values that the expression can access through |
||
895 | @code{ld(0)}. When the expression evaluates to 0 then the |
||
896 | corresponding input value will be returned. |
||
897 | |||
898 | @item sin(x) |
||
899 | Compute sine of @var{x}. |
||
900 | |||
901 | @item sinh(x) |
||
902 | Compute hyperbolic sine of @var{x}. |
||
903 | |||
904 | @item sqrt(expr) |
||
905 | Compute the square root of @var{expr}. This is equivalent to |
||
906 | "(@var{expr})^.5". |
||
907 | |||
908 | @item squish(x) |
||
909 | Compute expression @code{1/(1 + exp(4*x))}. |
||
910 | |||
911 | @item st(var, expr) |
||
912 | Allow to store the value of the expression @var{expr} in an internal |
||
913 | variable. @var{var} specifies the number of the variable where to |
||
914 | store the value, and it is a value ranging from 0 to 9. The function |
||
915 | returns the value stored in the internal variable. |
||
916 | Note, Variables are currently not shared between expressions. |
||
917 | |||
918 | @item tan(x) |
||
919 | Compute tangent of @var{x}. |
||
920 | |||
921 | @item tanh(x) |
||
922 | Compute hyperbolic tangent of @var{x}. |
||
923 | |||
924 | @item taylor(expr, x) |
||
925 | @item taylor(expr, x, id) |
||
926 | Evaluate a Taylor series at @var{x}, given an expression representing |
||
927 | the @code{ld(id)}-th derivative of a function at 0. |
||
928 | |||
929 | When the series does not converge the result is undefined. |
||
930 | |||
931 | @var{ld(id)} is used to represent the derivative order in @var{expr}, |
||
932 | which means that the given expression will be evaluated multiple times |
||
933 | with various input values that the expression can access through |
||
934 | @code{ld(id)}. If @var{id} is not specified then 0 is assumed. |
||
935 | |||
936 | Note, when you have the derivatives at y instead of 0, |
||
937 | @code{taylor(expr, x-y)} can be used. |
||
938 | |||
939 | @item time(0) |
||
940 | Return the current (wallclock) time in seconds. |
||
941 | |||
942 | @item trunc(expr) |
||
943 | Round the value of expression @var{expr} towards zero to the nearest |
||
944 | integer. For example, "trunc(-1.5)" is "-1.0". |
||
945 | |||
946 | @item while(cond, expr) |
||
947 | Evaluate expression @var{expr} while the expression @var{cond} is |
||
948 | non-zero, and returns the value of the last @var{expr} evaluation, or |
||
949 | NAN if @var{cond} was always false. |
||
950 | @end table |
||
951 | |||
952 | The following constants are available: |
||
953 | @table @option |
||
954 | @item PI |
||
955 | area of the unit disc, approximately 3.14 |
||
956 | @item E |
||
957 | exp(1) (Euler's number), approximately 2.718 |
||
958 | @item PHI |
||
959 | golden ratio (1+sqrt(5))/2, approximately 1.618 |
||
960 | @end table |
||
961 | |||
962 | Assuming that an expression is considered "true" if it has a non-zero |
||
963 | value, note that: |
||
964 | |||
965 | @code{*} works like AND |
||
966 | |||
967 | @code{+} works like OR |
||
968 | |||
969 | For example the construct: |
||
970 | @example |
||
971 | if (A AND B) then C |
||
972 | @end example |
||
973 | is equivalent to: |
||
974 | @example |
||
975 | if(A*B, C) |
||
976 | @end example |
||
977 | |||
978 | In your C code, you can extend the list of unary and binary functions, |
||
979 | and define recognized constants, so that they are available for your |
||
980 | expressions. |
||
981 | |||
982 | The evaluator also recognizes the International System unit prefixes. |
||
983 | If 'i' is appended after the prefix, binary prefixes are used, which |
||
984 | are based on powers of 1024 instead of powers of 1000. |
||
985 | The 'B' postfix multiplies the value by 8, and can be appended after a |
||
986 | unit prefix or used alone. This allows using for example 'KB', 'MiB', |
||
987 | 'G' and 'B' as number postfix. |
||
988 | |||
989 | The list of available International System prefixes follows, with |
||
990 | indication of the corresponding powers of 10 and of 2. |
||
991 | @table @option |
||
992 | @item y |
||
993 | 10^-24 / 2^-80 |
||
994 | @item z |
||
995 | 10^-21 / 2^-70 |
||
996 | @item a |
||
997 | 10^-18 / 2^-60 |
||
998 | @item f |
||
999 | 10^-15 / 2^-50 |
||
1000 | @item p |
||
1001 | 10^-12 / 2^-40 |
||
1002 | @item n |
||
1003 | 10^-9 / 2^-30 |
||
1004 | @item u |
||
1005 | 10^-6 / 2^-20 |
||
1006 | @item m |
||
1007 | 10^-3 / 2^-10 |
||
1008 | @item c |
||
1009 | 10^-2 |
||
1010 | @item d |
||
1011 | 10^-1 |
||
1012 | @item h |
||
1013 | 10^2 |
||
1014 | @item k |
||
1015 | 10^3 / 2^10 |
||
1016 | @item K |
||
1017 | 10^3 / 2^10 |
||
1018 | @item M |
||
1019 | 10^6 / 2^20 |
||
1020 | @item G |
||
1021 | 10^9 / 2^30 |
||
1022 | @item T |
||
1023 | 10^12 / 2^40 |
||
1024 | @item P |
||
1025 | 10^15 / 2^40 |
||
1026 | @item E |
||
1027 | 10^18 / 2^50 |
||
1028 | @item Z |
||
1029 | 10^21 / 2^60 |
||
1030 | @item Y |
||
1031 | 10^24 / 2^70 |
||
1032 | @end table |
||
1033 | |||
1034 | @c man end |
||
1035 | |||
1036 | @chapter OpenCL Options |
||
1037 | @c man begin OPENCL OPTIONS |
||
1038 | |||
1039 | When FFmpeg is configured with @code{--enable-opencl}, it is possible |
||
1040 | to set the options for the global OpenCL context. |
||
1041 | |||
1042 | The list of supported options follows: |
||
1043 | |||
1044 | @table @option |
||
1045 | @item build_options |
||
1046 | Set build options used to compile the registered kernels. |
||
1047 | |||
1048 | See reference "OpenCL Specification Version: 1.2 chapter 5.6.4". |
||
1049 | |||
1050 | @item platform_idx |
||
1051 | Select the index of the platform to run OpenCL code. |
||
1052 | |||
1053 | The specified index must be one of the indexes in the device list |
||
1054 | which can be obtained with @code{av_opencl_get_device_list()}. |
||
1055 | |||
1056 | @item device_idx |
||
1057 | Select the index of the device used to run OpenCL code. |
||
1058 | |||
1059 | The specifed index must be one of the indexes in the device list which |
||
1060 | can be obtained with @code{av_opencl_get_device_list()}. |
||
1061 | |||
1062 | @end table |
||
1063 | |||
1064 | @c man end OPENCL OPTIONS |