utils.texi 22 KB

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