ffmpeg-utils.html 48 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  2. <html>
  3. <!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
  4. <head>
  5. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  6. <title>FFmpeg Utilities Documentation</title>
  7. <meta name="description" content="FFmpeg Utilities Documentation">
  8. <meta name="keywords" content="FFmpeg Utilities Documentation">
  9. <meta name="resource-type" content="document">
  10. <meta name="distribution" content="global">
  11. <meta name="Generator" content="makeinfo">
  12. <meta name="viewport" content="width=device-width,initial-scale=1">
  13. <link href="#SEC_Contents" rel="contents" title="Table of Contents">
  14. <style type="text/css">
  15. <!--
  16. a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
  17. a.summary-letter {text-decoration: none}
  18. blockquote.indentedblock {margin-right: 0em}
  19. div.display {margin-left: 3.2em}
  20. div.example {margin-left: 3.2em}
  21. kbd {font-style: oblique}
  22. pre.display {font-family: inherit}
  23. pre.format {font-family: inherit}
  24. pre.menu-comment {font-family: serif}
  25. pre.menu-preformatted {font-family: serif}
  26. span.nolinebreak {white-space: nowrap}
  27. span.roman {font-family: initial; font-weight: normal}
  28. span.sansserif {font-family: sans-serif; font-weight: normal}
  29. span:hover a.copiable-anchor {visibility: visible}
  30. ul.no-bullet {list-style: none}
  31. -->
  32. </style>
  33. </head>
  34. <body lang="en">
  35. <h1 class="settitle" align="center">FFmpeg Utilities Documentation</h1>
  36. <a name="SEC_Top"></a>
  37. <a name="Description"></a>
  38. <h2 class="chapter">1 Description<span class="pull-right"><a class="anchor hidden-xs" href="#Description" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Description" aria-hidden="true">TOC</a></span></h2>
  39. <p>This document describes some generic features and utilities provided
  40. by the libavutil library.
  41. </p>
  42. <a name="Syntax"></a>
  43. <h2 class="chapter">2 Syntax<span class="pull-right"><a class="anchor hidden-xs" href="#Syntax" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Syntax" aria-hidden="true">TOC</a></span></h2>
  44. <p>This section documents the syntax and formats employed by the FFmpeg
  45. libraries and tools.
  46. </p>
  47. <span id="quoting_005fand_005fescaping"></span><a name="Quoting-and-escaping"></a>
  48. <h3 class="section">2.1 Quoting and escaping<span class="pull-right"><a class="anchor hidden-xs" href="#Quoting-and-escaping" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Quoting-and-escaping" aria-hidden="true">TOC</a></span></h3>
  49. <p>FFmpeg adopts the following quoting and escaping mechanism, unless
  50. explicitly specified. The following rules are applied:
  51. </p>
  52. <ul>
  53. <li> &lsquo;<samp>'</samp>&rsquo; and &lsquo;<samp>\</samp>&rsquo; are special characters (respectively used for
  54. quoting and escaping). In addition to them, there might be other
  55. special characters depending on the specific syntax where the escaping
  56. and quoting are employed.
  57. </li><li> A special character is escaped by prefixing it with a &lsquo;<samp>\</samp>&rsquo;.
  58. </li><li> All characters enclosed between &lsquo;<samp>''</samp>&rsquo; are included literally in the
  59. parsed string. The quote character &lsquo;<samp>'</samp>&rsquo; itself cannot be quoted,
  60. so you may need to close the quote and escape it.
  61. </li><li> Leading and trailing whitespaces, unless escaped or quoted, are
  62. removed from the parsed string.
  63. </li></ul>
  64. <p>Note that you may need to add a second level of escaping when using
  65. the command line or a script, which depends on the syntax of the
  66. adopted shell language.
  67. </p>
  68. <p>The function <code>av_get_token</code> defined in
  69. <samp>libavutil/avstring.h</samp> can be used to parse a token quoted or
  70. escaped according to the rules defined above.
  71. </p>
  72. <p>The tool <samp>tools/ffescape</samp> in the FFmpeg source tree can be used
  73. to automatically quote or escape a string in a script.
  74. </p>
  75. <a name="Examples"></a>
  76. <h4 class="subsection">2.1.1 Examples<span class="pull-right"><a class="anchor hidden-xs" href="#Examples" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Examples" aria-hidden="true">TOC</a></span></h4>
  77. <ul>
  78. <li> Escape the string <code>Crime d'Amour</code> containing the <code>'</code> special
  79. character:
  80. <div class="example">
  81. <pre class="example">Crime d\'Amour
  82. </pre></div>
  83. </li><li> The string above contains a quote, so the <code>'</code> needs to be escaped
  84. when quoting it:
  85. <div class="example">
  86. <pre class="example">'Crime d'\''Amour'
  87. </pre></div>
  88. </li><li> Include leading or trailing whitespaces using quoting:
  89. <div class="example">
  90. <pre class="example">' this string starts and ends with whitespaces '
  91. </pre></div>
  92. </li><li> Escaping and quoting can be mixed together:
  93. <div class="example">
  94. <pre class="example">' The string '\'string\'' is a string '
  95. </pre></div>
  96. </li><li> To include a literal &lsquo;<samp>\</samp>&rsquo; you can use either escaping or quoting:
  97. <div class="example">
  98. <pre class="example">'c:\foo' can be written as c:\\foo
  99. </pre></div>
  100. </li></ul>
  101. <span id="date-syntax"></span><a name="Date"></a>
  102. <h3 class="section">2.2 Date<span class="pull-right"><a class="anchor hidden-xs" href="#Date" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Date" aria-hidden="true">TOC</a></span></h3>
  103. <p>The accepted syntax is:
  104. </p><div class="example">
  105. <pre class="example">[(YYYY-MM-DD|YYYYMMDD)[T|t| ]]((HH:MM:SS[.m...]]])|(HHMMSS[.m...]]]))[Z]
  106. now
  107. </pre></div>
  108. <p>If the value is &quot;now&quot; it takes the current time.
  109. </p>
  110. <p>Time is local time unless Z is appended, in which case it is
  111. interpreted as UTC.
  112. If the year-month-day part is not specified it takes the current
  113. year-month-day.
  114. </p>
  115. <span id="time-duration-syntax"></span><a name="Time-duration"></a>
  116. <h3 class="section">2.3 Time duration<span class="pull-right"><a class="anchor hidden-xs" href="#Time-duration" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Time-duration" aria-hidden="true">TOC</a></span></h3>
  117. <p>There are two accepted syntaxes for expressing time duration.
  118. </p>
  119. <div class="example">
  120. <pre class="example">[-][<var>HH</var>:]<var>MM</var>:<var>SS</var>[.<var>m</var>...]
  121. </pre></div>
  122. <p><var>HH</var> expresses the number of hours, <var>MM</var> the number of minutes
  123. for a maximum of 2 digits, and <var>SS</var> the number of seconds for a
  124. maximum of 2 digits. The <var>m</var> at the end expresses decimal value for
  125. <var>SS</var>.
  126. </p>
  127. <p><em>or</em>
  128. </p>
  129. <div class="example">
  130. <pre class="example">[-]<var>S</var>+[.<var>m</var>...][s|ms|us]
  131. </pre></div>
  132. <p><var>S</var> expresses the number of seconds, with the optional decimal part
  133. <var>m</var>. The optional literal suffixes &lsquo;<samp>s</samp>&rsquo;, &lsquo;<samp>ms</samp>&rsquo; or &lsquo;<samp>us</samp>&rsquo;
  134. indicate to interpret the value as seconds, milliseconds or microseconds,
  135. respectively.
  136. </p>
  137. <p>In both expressions, the optional &lsquo;<samp>-</samp>&rsquo; indicates negative duration.
  138. </p>
  139. <a name="Examples-1"></a>
  140. <h4 class="subsection">2.3.1 Examples<span class="pull-right"><a class="anchor hidden-xs" href="#Examples-1" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Examples-1" aria-hidden="true">TOC</a></span></h4>
  141. <p>The following examples are all valid time duration:
  142. </p>
  143. <dl compact="compact">
  144. <dt><span>&lsquo;<samp>55</samp>&rsquo;</span></dt>
  145. <dd><p>55 seconds
  146. </p>
  147. </dd>
  148. <dt><span>&lsquo;<samp>0.2</samp>&rsquo;</span></dt>
  149. <dd><p>0.2 seconds
  150. </p>
  151. </dd>
  152. <dt><span>&lsquo;<samp>200ms</samp>&rsquo;</span></dt>
  153. <dd><p>200 milliseconds, that&rsquo;s 0.2s
  154. </p>
  155. </dd>
  156. <dt><span>&lsquo;<samp>200000us</samp>&rsquo;</span></dt>
  157. <dd><p>200000 microseconds, that&rsquo;s 0.2s
  158. </p>
  159. </dd>
  160. <dt><span>&lsquo;<samp>12:03:45</samp>&rsquo;</span></dt>
  161. <dd><p>12 hours, 03 minutes and 45 seconds
  162. </p>
  163. </dd>
  164. <dt><span>&lsquo;<samp>23.189</samp>&rsquo;</span></dt>
  165. <dd><p>23.189 seconds
  166. </p></dd>
  167. </dl>
  168. <span id="video-size-syntax"></span><a name="Video-size"></a>
  169. <h3 class="section">2.4 Video size<span class="pull-right"><a class="anchor hidden-xs" href="#Video-size" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Video-size" aria-hidden="true">TOC</a></span></h3>
  170. <p>Specify the size of the sourced video, it may be a string of the form
  171. <var>width</var>x<var>height</var>, or the name of a size abbreviation.
  172. </p>
  173. <p>The following abbreviations are recognized:
  174. </p><dl compact="compact">
  175. <dt><span>&lsquo;<samp>ntsc</samp>&rsquo;</span></dt>
  176. <dd><p>720x480
  177. </p></dd>
  178. <dt><span>&lsquo;<samp>pal</samp>&rsquo;</span></dt>
  179. <dd><p>720x576
  180. </p></dd>
  181. <dt><span>&lsquo;<samp>qntsc</samp>&rsquo;</span></dt>
  182. <dd><p>352x240
  183. </p></dd>
  184. <dt><span>&lsquo;<samp>qpal</samp>&rsquo;</span></dt>
  185. <dd><p>352x288
  186. </p></dd>
  187. <dt><span>&lsquo;<samp>sntsc</samp>&rsquo;</span></dt>
  188. <dd><p>640x480
  189. </p></dd>
  190. <dt><span>&lsquo;<samp>spal</samp>&rsquo;</span></dt>
  191. <dd><p>768x576
  192. </p></dd>
  193. <dt><span>&lsquo;<samp>film</samp>&rsquo;</span></dt>
  194. <dd><p>352x240
  195. </p></dd>
  196. <dt><span>&lsquo;<samp>ntsc-film</samp>&rsquo;</span></dt>
  197. <dd><p>352x240
  198. </p></dd>
  199. <dt><span>&lsquo;<samp>sqcif</samp>&rsquo;</span></dt>
  200. <dd><p>128x96
  201. </p></dd>
  202. <dt><span>&lsquo;<samp>qcif</samp>&rsquo;</span></dt>
  203. <dd><p>176x144
  204. </p></dd>
  205. <dt><span>&lsquo;<samp>cif</samp>&rsquo;</span></dt>
  206. <dd><p>352x288
  207. </p></dd>
  208. <dt><span>&lsquo;<samp>4cif</samp>&rsquo;</span></dt>
  209. <dd><p>704x576
  210. </p></dd>
  211. <dt><span>&lsquo;<samp>16cif</samp>&rsquo;</span></dt>
  212. <dd><p>1408x1152
  213. </p></dd>
  214. <dt><span>&lsquo;<samp>qqvga</samp>&rsquo;</span></dt>
  215. <dd><p>160x120
  216. </p></dd>
  217. <dt><span>&lsquo;<samp>qvga</samp>&rsquo;</span></dt>
  218. <dd><p>320x240
  219. </p></dd>
  220. <dt><span>&lsquo;<samp>vga</samp>&rsquo;</span></dt>
  221. <dd><p>640x480
  222. </p></dd>
  223. <dt><span>&lsquo;<samp>svga</samp>&rsquo;</span></dt>
  224. <dd><p>800x600
  225. </p></dd>
  226. <dt><span>&lsquo;<samp>xga</samp>&rsquo;</span></dt>
  227. <dd><p>1024x768
  228. </p></dd>
  229. <dt><span>&lsquo;<samp>uxga</samp>&rsquo;</span></dt>
  230. <dd><p>1600x1200
  231. </p></dd>
  232. <dt><span>&lsquo;<samp>qxga</samp>&rsquo;</span></dt>
  233. <dd><p>2048x1536
  234. </p></dd>
  235. <dt><span>&lsquo;<samp>sxga</samp>&rsquo;</span></dt>
  236. <dd><p>1280x1024
  237. </p></dd>
  238. <dt><span>&lsquo;<samp>qsxga</samp>&rsquo;</span></dt>
  239. <dd><p>2560x2048
  240. </p></dd>
  241. <dt><span>&lsquo;<samp>hsxga</samp>&rsquo;</span></dt>
  242. <dd><p>5120x4096
  243. </p></dd>
  244. <dt><span>&lsquo;<samp>wvga</samp>&rsquo;</span></dt>
  245. <dd><p>852x480
  246. </p></dd>
  247. <dt><span>&lsquo;<samp>wxga</samp>&rsquo;</span></dt>
  248. <dd><p>1366x768
  249. </p></dd>
  250. <dt><span>&lsquo;<samp>wsxga</samp>&rsquo;</span></dt>
  251. <dd><p>1600x1024
  252. </p></dd>
  253. <dt><span>&lsquo;<samp>wuxga</samp>&rsquo;</span></dt>
  254. <dd><p>1920x1200
  255. </p></dd>
  256. <dt><span>&lsquo;<samp>woxga</samp>&rsquo;</span></dt>
  257. <dd><p>2560x1600
  258. </p></dd>
  259. <dt><span>&lsquo;<samp>wqsxga</samp>&rsquo;</span></dt>
  260. <dd><p>3200x2048
  261. </p></dd>
  262. <dt><span>&lsquo;<samp>wquxga</samp>&rsquo;</span></dt>
  263. <dd><p>3840x2400
  264. </p></dd>
  265. <dt><span>&lsquo;<samp>whsxga</samp>&rsquo;</span></dt>
  266. <dd><p>6400x4096
  267. </p></dd>
  268. <dt><span>&lsquo;<samp>whuxga</samp>&rsquo;</span></dt>
  269. <dd><p>7680x4800
  270. </p></dd>
  271. <dt><span>&lsquo;<samp>cga</samp>&rsquo;</span></dt>
  272. <dd><p>320x200
  273. </p></dd>
  274. <dt><span>&lsquo;<samp>ega</samp>&rsquo;</span></dt>
  275. <dd><p>640x350
  276. </p></dd>
  277. <dt><span>&lsquo;<samp>hd480</samp>&rsquo;</span></dt>
  278. <dd><p>852x480
  279. </p></dd>
  280. <dt><span>&lsquo;<samp>hd720</samp>&rsquo;</span></dt>
  281. <dd><p>1280x720
  282. </p></dd>
  283. <dt><span>&lsquo;<samp>hd1080</samp>&rsquo;</span></dt>
  284. <dd><p>1920x1080
  285. </p></dd>
  286. <dt><span>&lsquo;<samp>2k</samp>&rsquo;</span></dt>
  287. <dd><p>2048x1080
  288. </p></dd>
  289. <dt><span>&lsquo;<samp>2kflat</samp>&rsquo;</span></dt>
  290. <dd><p>1998x1080
  291. </p></dd>
  292. <dt><span>&lsquo;<samp>2kscope</samp>&rsquo;</span></dt>
  293. <dd><p>2048x858
  294. </p></dd>
  295. <dt><span>&lsquo;<samp>4k</samp>&rsquo;</span></dt>
  296. <dd><p>4096x2160
  297. </p></dd>
  298. <dt><span>&lsquo;<samp>4kflat</samp>&rsquo;</span></dt>
  299. <dd><p>3996x2160
  300. </p></dd>
  301. <dt><span>&lsquo;<samp>4kscope</samp>&rsquo;</span></dt>
  302. <dd><p>4096x1716
  303. </p></dd>
  304. <dt><span>&lsquo;<samp>nhd</samp>&rsquo;</span></dt>
  305. <dd><p>640x360
  306. </p></dd>
  307. <dt><span>&lsquo;<samp>hqvga</samp>&rsquo;</span></dt>
  308. <dd><p>240x160
  309. </p></dd>
  310. <dt><span>&lsquo;<samp>wqvga</samp>&rsquo;</span></dt>
  311. <dd><p>400x240
  312. </p></dd>
  313. <dt><span>&lsquo;<samp>fwqvga</samp>&rsquo;</span></dt>
  314. <dd><p>432x240
  315. </p></dd>
  316. <dt><span>&lsquo;<samp>hvga</samp>&rsquo;</span></dt>
  317. <dd><p>480x320
  318. </p></dd>
  319. <dt><span>&lsquo;<samp>qhd</samp>&rsquo;</span></dt>
  320. <dd><p>960x540
  321. </p></dd>
  322. <dt><span>&lsquo;<samp>2kdci</samp>&rsquo;</span></dt>
  323. <dd><p>2048x1080
  324. </p></dd>
  325. <dt><span>&lsquo;<samp>4kdci</samp>&rsquo;</span></dt>
  326. <dd><p>4096x2160
  327. </p></dd>
  328. <dt><span>&lsquo;<samp>uhd2160</samp>&rsquo;</span></dt>
  329. <dd><p>3840x2160
  330. </p></dd>
  331. <dt><span>&lsquo;<samp>uhd4320</samp>&rsquo;</span></dt>
  332. <dd><p>7680x4320
  333. </p></dd>
  334. </dl>
  335. <span id="video-rate-syntax"></span><a name="Video-rate"></a>
  336. <h3 class="section">2.5 Video rate<span class="pull-right"><a class="anchor hidden-xs" href="#Video-rate" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Video-rate" aria-hidden="true">TOC</a></span></h3>
  337. <p>Specify the frame rate of a video, expressed as the number of frames
  338. generated per second. It has to be a string in the format
  339. <var>frame_rate_num</var>/<var>frame_rate_den</var>, an integer number, a float
  340. number or a valid video frame rate abbreviation.
  341. </p>
  342. <p>The following abbreviations are recognized:
  343. </p><dl compact="compact">
  344. <dt><span>&lsquo;<samp>ntsc</samp>&rsquo;</span></dt>
  345. <dd><p>30000/1001
  346. </p></dd>
  347. <dt><span>&lsquo;<samp>pal</samp>&rsquo;</span></dt>
  348. <dd><p>25/1
  349. </p></dd>
  350. <dt><span>&lsquo;<samp>qntsc</samp>&rsquo;</span></dt>
  351. <dd><p>30000/1001
  352. </p></dd>
  353. <dt><span>&lsquo;<samp>qpal</samp>&rsquo;</span></dt>
  354. <dd><p>25/1
  355. </p></dd>
  356. <dt><span>&lsquo;<samp>sntsc</samp>&rsquo;</span></dt>
  357. <dd><p>30000/1001
  358. </p></dd>
  359. <dt><span>&lsquo;<samp>spal</samp>&rsquo;</span></dt>
  360. <dd><p>25/1
  361. </p></dd>
  362. <dt><span>&lsquo;<samp>film</samp>&rsquo;</span></dt>
  363. <dd><p>24/1
  364. </p></dd>
  365. <dt><span>&lsquo;<samp>ntsc-film</samp>&rsquo;</span></dt>
  366. <dd><p>24000/1001
  367. </p></dd>
  368. </dl>
  369. <span id="ratio-syntax"></span><a name="Ratio"></a>
  370. <h3 class="section">2.6 Ratio<span class="pull-right"><a class="anchor hidden-xs" href="#Ratio" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Ratio" aria-hidden="true">TOC</a></span></h3>
  371. <p>A ratio can be expressed as an expression, or in the form
  372. <var>numerator</var>:<var>denominator</var>.
  373. </p>
  374. <p>Note that a ratio with infinite (1/0) or negative value is
  375. considered valid, so you should check on the returned value if you
  376. want to exclude those values.
  377. </p>
  378. <p>The undefined value can be expressed using the &quot;0:0&quot; string.
  379. </p>
  380. <span id="color-syntax"></span><a name="Color"></a>
  381. <h3 class="section">2.7 Color<span class="pull-right"><a class="anchor hidden-xs" href="#Color" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Color" aria-hidden="true">TOC</a></span></h3>
  382. <p>It can be the name of a color as defined below (case insensitive match) or a
  383. <code>[0x|#]RRGGBB[AA]</code> sequence, possibly followed by @ and a string
  384. representing the alpha component.
  385. </p>
  386. <p>The alpha component may be a string composed by &quot;0x&quot; followed by an
  387. hexadecimal number or a decimal number between 0.0 and 1.0, which
  388. represents the opacity value (&lsquo;<samp>0x00</samp>&rsquo; or &lsquo;<samp>0.0</samp>&rsquo; means completely
  389. transparent, &lsquo;<samp>0xff</samp>&rsquo; or &lsquo;<samp>1.0</samp>&rsquo; completely opaque). If the alpha
  390. component is not specified then &lsquo;<samp>0xff</samp>&rsquo; is assumed.
  391. </p>
  392. <p>The string &lsquo;<samp>random</samp>&rsquo; will result in a random color.
  393. </p>
  394. <p>The following names of colors are recognized:
  395. </p><dl compact="compact">
  396. <dt><span>&lsquo;<samp>AliceBlue</samp>&rsquo;</span></dt>
  397. <dd><p>0xF0F8FF
  398. </p></dd>
  399. <dt><span>&lsquo;<samp>AntiqueWhite</samp>&rsquo;</span></dt>
  400. <dd><p>0xFAEBD7
  401. </p></dd>
  402. <dt><span>&lsquo;<samp>Aqua</samp>&rsquo;</span></dt>
  403. <dd><p>0x00FFFF
  404. </p></dd>
  405. <dt><span>&lsquo;<samp>Aquamarine</samp>&rsquo;</span></dt>
  406. <dd><p>0x7FFFD4
  407. </p></dd>
  408. <dt><span>&lsquo;<samp>Azure</samp>&rsquo;</span></dt>
  409. <dd><p>0xF0FFFF
  410. </p></dd>
  411. <dt><span>&lsquo;<samp>Beige</samp>&rsquo;</span></dt>
  412. <dd><p>0xF5F5DC
  413. </p></dd>
  414. <dt><span>&lsquo;<samp>Bisque</samp>&rsquo;</span></dt>
  415. <dd><p>0xFFE4C4
  416. </p></dd>
  417. <dt><span>&lsquo;<samp>Black</samp>&rsquo;</span></dt>
  418. <dd><p>0x000000
  419. </p></dd>
  420. <dt><span>&lsquo;<samp>BlanchedAlmond</samp>&rsquo;</span></dt>
  421. <dd><p>0xFFEBCD
  422. </p></dd>
  423. <dt><span>&lsquo;<samp>Blue</samp>&rsquo;</span></dt>
  424. <dd><p>0x0000FF
  425. </p></dd>
  426. <dt><span>&lsquo;<samp>BlueViolet</samp>&rsquo;</span></dt>
  427. <dd><p>0x8A2BE2
  428. </p></dd>
  429. <dt><span>&lsquo;<samp>Brown</samp>&rsquo;</span></dt>
  430. <dd><p>0xA52A2A
  431. </p></dd>
  432. <dt><span>&lsquo;<samp>BurlyWood</samp>&rsquo;</span></dt>
  433. <dd><p>0xDEB887
  434. </p></dd>
  435. <dt><span>&lsquo;<samp>CadetBlue</samp>&rsquo;</span></dt>
  436. <dd><p>0x5F9EA0
  437. </p></dd>
  438. <dt><span>&lsquo;<samp>Chartreuse</samp>&rsquo;</span></dt>
  439. <dd><p>0x7FFF00
  440. </p></dd>
  441. <dt><span>&lsquo;<samp>Chocolate</samp>&rsquo;</span></dt>
  442. <dd><p>0xD2691E
  443. </p></dd>
  444. <dt><span>&lsquo;<samp>Coral</samp>&rsquo;</span></dt>
  445. <dd><p>0xFF7F50
  446. </p></dd>
  447. <dt><span>&lsquo;<samp>CornflowerBlue</samp>&rsquo;</span></dt>
  448. <dd><p>0x6495ED
  449. </p></dd>
  450. <dt><span>&lsquo;<samp>Cornsilk</samp>&rsquo;</span></dt>
  451. <dd><p>0xFFF8DC
  452. </p></dd>
  453. <dt><span>&lsquo;<samp>Crimson</samp>&rsquo;</span></dt>
  454. <dd><p>0xDC143C
  455. </p></dd>
  456. <dt><span>&lsquo;<samp>Cyan</samp>&rsquo;</span></dt>
  457. <dd><p>0x00FFFF
  458. </p></dd>
  459. <dt><span>&lsquo;<samp>DarkBlue</samp>&rsquo;</span></dt>
  460. <dd><p>0x00008B
  461. </p></dd>
  462. <dt><span>&lsquo;<samp>DarkCyan</samp>&rsquo;</span></dt>
  463. <dd><p>0x008B8B
  464. </p></dd>
  465. <dt><span>&lsquo;<samp>DarkGoldenRod</samp>&rsquo;</span></dt>
  466. <dd><p>0xB8860B
  467. </p></dd>
  468. <dt><span>&lsquo;<samp>DarkGray</samp>&rsquo;</span></dt>
  469. <dd><p>0xA9A9A9
  470. </p></dd>
  471. <dt><span>&lsquo;<samp>DarkGreen</samp>&rsquo;</span></dt>
  472. <dd><p>0x006400
  473. </p></dd>
  474. <dt><span>&lsquo;<samp>DarkKhaki</samp>&rsquo;</span></dt>
  475. <dd><p>0xBDB76B
  476. </p></dd>
  477. <dt><span>&lsquo;<samp>DarkMagenta</samp>&rsquo;</span></dt>
  478. <dd><p>0x8B008B
  479. </p></dd>
  480. <dt><span>&lsquo;<samp>DarkOliveGreen</samp>&rsquo;</span></dt>
  481. <dd><p>0x556B2F
  482. </p></dd>
  483. <dt><span>&lsquo;<samp>Darkorange</samp>&rsquo;</span></dt>
  484. <dd><p>0xFF8C00
  485. </p></dd>
  486. <dt><span>&lsquo;<samp>DarkOrchid</samp>&rsquo;</span></dt>
  487. <dd><p>0x9932CC
  488. </p></dd>
  489. <dt><span>&lsquo;<samp>DarkRed</samp>&rsquo;</span></dt>
  490. <dd><p>0x8B0000
  491. </p></dd>
  492. <dt><span>&lsquo;<samp>DarkSalmon</samp>&rsquo;</span></dt>
  493. <dd><p>0xE9967A
  494. </p></dd>
  495. <dt><span>&lsquo;<samp>DarkSeaGreen</samp>&rsquo;</span></dt>
  496. <dd><p>0x8FBC8F
  497. </p></dd>
  498. <dt><span>&lsquo;<samp>DarkSlateBlue</samp>&rsquo;</span></dt>
  499. <dd><p>0x483D8B
  500. </p></dd>
  501. <dt><span>&lsquo;<samp>DarkSlateGray</samp>&rsquo;</span></dt>
  502. <dd><p>0x2F4F4F
  503. </p></dd>
  504. <dt><span>&lsquo;<samp>DarkTurquoise</samp>&rsquo;</span></dt>
  505. <dd><p>0x00CED1
  506. </p></dd>
  507. <dt><span>&lsquo;<samp>DarkViolet</samp>&rsquo;</span></dt>
  508. <dd><p>0x9400D3
  509. </p></dd>
  510. <dt><span>&lsquo;<samp>DeepPink</samp>&rsquo;</span></dt>
  511. <dd><p>0xFF1493
  512. </p></dd>
  513. <dt><span>&lsquo;<samp>DeepSkyBlue</samp>&rsquo;</span></dt>
  514. <dd><p>0x00BFFF
  515. </p></dd>
  516. <dt><span>&lsquo;<samp>DimGray</samp>&rsquo;</span></dt>
  517. <dd><p>0x696969
  518. </p></dd>
  519. <dt><span>&lsquo;<samp>DodgerBlue</samp>&rsquo;</span></dt>
  520. <dd><p>0x1E90FF
  521. </p></dd>
  522. <dt><span>&lsquo;<samp>FireBrick</samp>&rsquo;</span></dt>
  523. <dd><p>0xB22222
  524. </p></dd>
  525. <dt><span>&lsquo;<samp>FloralWhite</samp>&rsquo;</span></dt>
  526. <dd><p>0xFFFAF0
  527. </p></dd>
  528. <dt><span>&lsquo;<samp>ForestGreen</samp>&rsquo;</span></dt>
  529. <dd><p>0x228B22
  530. </p></dd>
  531. <dt><span>&lsquo;<samp>Fuchsia</samp>&rsquo;</span></dt>
  532. <dd><p>0xFF00FF
  533. </p></dd>
  534. <dt><span>&lsquo;<samp>Gainsboro</samp>&rsquo;</span></dt>
  535. <dd><p>0xDCDCDC
  536. </p></dd>
  537. <dt><span>&lsquo;<samp>GhostWhite</samp>&rsquo;</span></dt>
  538. <dd><p>0xF8F8FF
  539. </p></dd>
  540. <dt><span>&lsquo;<samp>Gold</samp>&rsquo;</span></dt>
  541. <dd><p>0xFFD700
  542. </p></dd>
  543. <dt><span>&lsquo;<samp>GoldenRod</samp>&rsquo;</span></dt>
  544. <dd><p>0xDAA520
  545. </p></dd>
  546. <dt><span>&lsquo;<samp>Gray</samp>&rsquo;</span></dt>
  547. <dd><p>0x808080
  548. </p></dd>
  549. <dt><span>&lsquo;<samp>Green</samp>&rsquo;</span></dt>
  550. <dd><p>0x008000
  551. </p></dd>
  552. <dt><span>&lsquo;<samp>GreenYellow</samp>&rsquo;</span></dt>
  553. <dd><p>0xADFF2F
  554. </p></dd>
  555. <dt><span>&lsquo;<samp>HoneyDew</samp>&rsquo;</span></dt>
  556. <dd><p>0xF0FFF0
  557. </p></dd>
  558. <dt><span>&lsquo;<samp>HotPink</samp>&rsquo;</span></dt>
  559. <dd><p>0xFF69B4
  560. </p></dd>
  561. <dt><span>&lsquo;<samp>IndianRed</samp>&rsquo;</span></dt>
  562. <dd><p>0xCD5C5C
  563. </p></dd>
  564. <dt><span>&lsquo;<samp>Indigo</samp>&rsquo;</span></dt>
  565. <dd><p>0x4B0082
  566. </p></dd>
  567. <dt><span>&lsquo;<samp>Ivory</samp>&rsquo;</span></dt>
  568. <dd><p>0xFFFFF0
  569. </p></dd>
  570. <dt><span>&lsquo;<samp>Khaki</samp>&rsquo;</span></dt>
  571. <dd><p>0xF0E68C
  572. </p></dd>
  573. <dt><span>&lsquo;<samp>Lavender</samp>&rsquo;</span></dt>
  574. <dd><p>0xE6E6FA
  575. </p></dd>
  576. <dt><span>&lsquo;<samp>LavenderBlush</samp>&rsquo;</span></dt>
  577. <dd><p>0xFFF0F5
  578. </p></dd>
  579. <dt><span>&lsquo;<samp>LawnGreen</samp>&rsquo;</span></dt>
  580. <dd><p>0x7CFC00
  581. </p></dd>
  582. <dt><span>&lsquo;<samp>LemonChiffon</samp>&rsquo;</span></dt>
  583. <dd><p>0xFFFACD
  584. </p></dd>
  585. <dt><span>&lsquo;<samp>LightBlue</samp>&rsquo;</span></dt>
  586. <dd><p>0xADD8E6
  587. </p></dd>
  588. <dt><span>&lsquo;<samp>LightCoral</samp>&rsquo;</span></dt>
  589. <dd><p>0xF08080
  590. </p></dd>
  591. <dt><span>&lsquo;<samp>LightCyan</samp>&rsquo;</span></dt>
  592. <dd><p>0xE0FFFF
  593. </p></dd>
  594. <dt><span>&lsquo;<samp>LightGoldenRodYellow</samp>&rsquo;</span></dt>
  595. <dd><p>0xFAFAD2
  596. </p></dd>
  597. <dt><span>&lsquo;<samp>LightGreen</samp>&rsquo;</span></dt>
  598. <dd><p>0x90EE90
  599. </p></dd>
  600. <dt><span>&lsquo;<samp>LightGrey</samp>&rsquo;</span></dt>
  601. <dd><p>0xD3D3D3
  602. </p></dd>
  603. <dt><span>&lsquo;<samp>LightPink</samp>&rsquo;</span></dt>
  604. <dd><p>0xFFB6C1
  605. </p></dd>
  606. <dt><span>&lsquo;<samp>LightSalmon</samp>&rsquo;</span></dt>
  607. <dd><p>0xFFA07A
  608. </p></dd>
  609. <dt><span>&lsquo;<samp>LightSeaGreen</samp>&rsquo;</span></dt>
  610. <dd><p>0x20B2AA
  611. </p></dd>
  612. <dt><span>&lsquo;<samp>LightSkyBlue</samp>&rsquo;</span></dt>
  613. <dd><p>0x87CEFA
  614. </p></dd>
  615. <dt><span>&lsquo;<samp>LightSlateGray</samp>&rsquo;</span></dt>
  616. <dd><p>0x778899
  617. </p></dd>
  618. <dt><span>&lsquo;<samp>LightSteelBlue</samp>&rsquo;</span></dt>
  619. <dd><p>0xB0C4DE
  620. </p></dd>
  621. <dt><span>&lsquo;<samp>LightYellow</samp>&rsquo;</span></dt>
  622. <dd><p>0xFFFFE0
  623. </p></dd>
  624. <dt><span>&lsquo;<samp>Lime</samp>&rsquo;</span></dt>
  625. <dd><p>0x00FF00
  626. </p></dd>
  627. <dt><span>&lsquo;<samp>LimeGreen</samp>&rsquo;</span></dt>
  628. <dd><p>0x32CD32
  629. </p></dd>
  630. <dt><span>&lsquo;<samp>Linen</samp>&rsquo;</span></dt>
  631. <dd><p>0xFAF0E6
  632. </p></dd>
  633. <dt><span>&lsquo;<samp>Magenta</samp>&rsquo;</span></dt>
  634. <dd><p>0xFF00FF
  635. </p></dd>
  636. <dt><span>&lsquo;<samp>Maroon</samp>&rsquo;</span></dt>
  637. <dd><p>0x800000
  638. </p></dd>
  639. <dt><span>&lsquo;<samp>MediumAquaMarine</samp>&rsquo;</span></dt>
  640. <dd><p>0x66CDAA
  641. </p></dd>
  642. <dt><span>&lsquo;<samp>MediumBlue</samp>&rsquo;</span></dt>
  643. <dd><p>0x0000CD
  644. </p></dd>
  645. <dt><span>&lsquo;<samp>MediumOrchid</samp>&rsquo;</span></dt>
  646. <dd><p>0xBA55D3
  647. </p></dd>
  648. <dt><span>&lsquo;<samp>MediumPurple</samp>&rsquo;</span></dt>
  649. <dd><p>0x9370D8
  650. </p></dd>
  651. <dt><span>&lsquo;<samp>MediumSeaGreen</samp>&rsquo;</span></dt>
  652. <dd><p>0x3CB371
  653. </p></dd>
  654. <dt><span>&lsquo;<samp>MediumSlateBlue</samp>&rsquo;</span></dt>
  655. <dd><p>0x7B68EE
  656. </p></dd>
  657. <dt><span>&lsquo;<samp>MediumSpringGreen</samp>&rsquo;</span></dt>
  658. <dd><p>0x00FA9A
  659. </p></dd>
  660. <dt><span>&lsquo;<samp>MediumTurquoise</samp>&rsquo;</span></dt>
  661. <dd><p>0x48D1CC
  662. </p></dd>
  663. <dt><span>&lsquo;<samp>MediumVioletRed</samp>&rsquo;</span></dt>
  664. <dd><p>0xC71585
  665. </p></dd>
  666. <dt><span>&lsquo;<samp>MidnightBlue</samp>&rsquo;</span></dt>
  667. <dd><p>0x191970
  668. </p></dd>
  669. <dt><span>&lsquo;<samp>MintCream</samp>&rsquo;</span></dt>
  670. <dd><p>0xF5FFFA
  671. </p></dd>
  672. <dt><span>&lsquo;<samp>MistyRose</samp>&rsquo;</span></dt>
  673. <dd><p>0xFFE4E1
  674. </p></dd>
  675. <dt><span>&lsquo;<samp>Moccasin</samp>&rsquo;</span></dt>
  676. <dd><p>0xFFE4B5
  677. </p></dd>
  678. <dt><span>&lsquo;<samp>NavajoWhite</samp>&rsquo;</span></dt>
  679. <dd><p>0xFFDEAD
  680. </p></dd>
  681. <dt><span>&lsquo;<samp>Navy</samp>&rsquo;</span></dt>
  682. <dd><p>0x000080
  683. </p></dd>
  684. <dt><span>&lsquo;<samp>OldLace</samp>&rsquo;</span></dt>
  685. <dd><p>0xFDF5E6
  686. </p></dd>
  687. <dt><span>&lsquo;<samp>Olive</samp>&rsquo;</span></dt>
  688. <dd><p>0x808000
  689. </p></dd>
  690. <dt><span>&lsquo;<samp>OliveDrab</samp>&rsquo;</span></dt>
  691. <dd><p>0x6B8E23
  692. </p></dd>
  693. <dt><span>&lsquo;<samp>Orange</samp>&rsquo;</span></dt>
  694. <dd><p>0xFFA500
  695. </p></dd>
  696. <dt><span>&lsquo;<samp>OrangeRed</samp>&rsquo;</span></dt>
  697. <dd><p>0xFF4500
  698. </p></dd>
  699. <dt><span>&lsquo;<samp>Orchid</samp>&rsquo;</span></dt>
  700. <dd><p>0xDA70D6
  701. </p></dd>
  702. <dt><span>&lsquo;<samp>PaleGoldenRod</samp>&rsquo;</span></dt>
  703. <dd><p>0xEEE8AA
  704. </p></dd>
  705. <dt><span>&lsquo;<samp>PaleGreen</samp>&rsquo;</span></dt>
  706. <dd><p>0x98FB98
  707. </p></dd>
  708. <dt><span>&lsquo;<samp>PaleTurquoise</samp>&rsquo;</span></dt>
  709. <dd><p>0xAFEEEE
  710. </p></dd>
  711. <dt><span>&lsquo;<samp>PaleVioletRed</samp>&rsquo;</span></dt>
  712. <dd><p>0xD87093
  713. </p></dd>
  714. <dt><span>&lsquo;<samp>PapayaWhip</samp>&rsquo;</span></dt>
  715. <dd><p>0xFFEFD5
  716. </p></dd>
  717. <dt><span>&lsquo;<samp>PeachPuff</samp>&rsquo;</span></dt>
  718. <dd><p>0xFFDAB9
  719. </p></dd>
  720. <dt><span>&lsquo;<samp>Peru</samp>&rsquo;</span></dt>
  721. <dd><p>0xCD853F
  722. </p></dd>
  723. <dt><span>&lsquo;<samp>Pink</samp>&rsquo;</span></dt>
  724. <dd><p>0xFFC0CB
  725. </p></dd>
  726. <dt><span>&lsquo;<samp>Plum</samp>&rsquo;</span></dt>
  727. <dd><p>0xDDA0DD
  728. </p></dd>
  729. <dt><span>&lsquo;<samp>PowderBlue</samp>&rsquo;</span></dt>
  730. <dd><p>0xB0E0E6
  731. </p></dd>
  732. <dt><span>&lsquo;<samp>Purple</samp>&rsquo;</span></dt>
  733. <dd><p>0x800080
  734. </p></dd>
  735. <dt><span>&lsquo;<samp>Red</samp>&rsquo;</span></dt>
  736. <dd><p>0xFF0000
  737. </p></dd>
  738. <dt><span>&lsquo;<samp>RosyBrown</samp>&rsquo;</span></dt>
  739. <dd><p>0xBC8F8F
  740. </p></dd>
  741. <dt><span>&lsquo;<samp>RoyalBlue</samp>&rsquo;</span></dt>
  742. <dd><p>0x4169E1
  743. </p></dd>
  744. <dt><span>&lsquo;<samp>SaddleBrown</samp>&rsquo;</span></dt>
  745. <dd><p>0x8B4513
  746. </p></dd>
  747. <dt><span>&lsquo;<samp>Salmon</samp>&rsquo;</span></dt>
  748. <dd><p>0xFA8072
  749. </p></dd>
  750. <dt><span>&lsquo;<samp>SandyBrown</samp>&rsquo;</span></dt>
  751. <dd><p>0xF4A460
  752. </p></dd>
  753. <dt><span>&lsquo;<samp>SeaGreen</samp>&rsquo;</span></dt>
  754. <dd><p>0x2E8B57
  755. </p></dd>
  756. <dt><span>&lsquo;<samp>SeaShell</samp>&rsquo;</span></dt>
  757. <dd><p>0xFFF5EE
  758. </p></dd>
  759. <dt><span>&lsquo;<samp>Sienna</samp>&rsquo;</span></dt>
  760. <dd><p>0xA0522D
  761. </p></dd>
  762. <dt><span>&lsquo;<samp>Silver</samp>&rsquo;</span></dt>
  763. <dd><p>0xC0C0C0
  764. </p></dd>
  765. <dt><span>&lsquo;<samp>SkyBlue</samp>&rsquo;</span></dt>
  766. <dd><p>0x87CEEB
  767. </p></dd>
  768. <dt><span>&lsquo;<samp>SlateBlue</samp>&rsquo;</span></dt>
  769. <dd><p>0x6A5ACD
  770. </p></dd>
  771. <dt><span>&lsquo;<samp>SlateGray</samp>&rsquo;</span></dt>
  772. <dd><p>0x708090
  773. </p></dd>
  774. <dt><span>&lsquo;<samp>Snow</samp>&rsquo;</span></dt>
  775. <dd><p>0xFFFAFA
  776. </p></dd>
  777. <dt><span>&lsquo;<samp>SpringGreen</samp>&rsquo;</span></dt>
  778. <dd><p>0x00FF7F
  779. </p></dd>
  780. <dt><span>&lsquo;<samp>SteelBlue</samp>&rsquo;</span></dt>
  781. <dd><p>0x4682B4
  782. </p></dd>
  783. <dt><span>&lsquo;<samp>Tan</samp>&rsquo;</span></dt>
  784. <dd><p>0xD2B48C
  785. </p></dd>
  786. <dt><span>&lsquo;<samp>Teal</samp>&rsquo;</span></dt>
  787. <dd><p>0x008080
  788. </p></dd>
  789. <dt><span>&lsquo;<samp>Thistle</samp>&rsquo;</span></dt>
  790. <dd><p>0xD8BFD8
  791. </p></dd>
  792. <dt><span>&lsquo;<samp>Tomato</samp>&rsquo;</span></dt>
  793. <dd><p>0xFF6347
  794. </p></dd>
  795. <dt><span>&lsquo;<samp>Turquoise</samp>&rsquo;</span></dt>
  796. <dd><p>0x40E0D0
  797. </p></dd>
  798. <dt><span>&lsquo;<samp>Violet</samp>&rsquo;</span></dt>
  799. <dd><p>0xEE82EE
  800. </p></dd>
  801. <dt><span>&lsquo;<samp>Wheat</samp>&rsquo;</span></dt>
  802. <dd><p>0xF5DEB3
  803. </p></dd>
  804. <dt><span>&lsquo;<samp>White</samp>&rsquo;</span></dt>
  805. <dd><p>0xFFFFFF
  806. </p></dd>
  807. <dt><span>&lsquo;<samp>WhiteSmoke</samp>&rsquo;</span></dt>
  808. <dd><p>0xF5F5F5
  809. </p></dd>
  810. <dt><span>&lsquo;<samp>Yellow</samp>&rsquo;</span></dt>
  811. <dd><p>0xFFFF00
  812. </p></dd>
  813. <dt><span>&lsquo;<samp>YellowGreen</samp>&rsquo;</span></dt>
  814. <dd><p>0x9ACD32
  815. </p></dd>
  816. </dl>
  817. <span id="channel-layout-syntax"></span><a name="Channel-Layout"></a>
  818. <h3 class="section">2.8 Channel Layout<span class="pull-right"><a class="anchor hidden-xs" href="#Channel-Layout" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Channel-Layout" aria-hidden="true">TOC</a></span></h3>
  819. <p>A channel layout specifies the spatial disposition of the channels in
  820. a multi-channel audio stream. To specify a channel layout, FFmpeg
  821. makes use of a special syntax.
  822. </p>
  823. <p>Individual channels are identified by an id, as given by the table
  824. below:
  825. </p><dl compact="compact">
  826. <dt><span>&lsquo;<samp>FL</samp>&rsquo;</span></dt>
  827. <dd><p>front left
  828. </p></dd>
  829. <dt><span>&lsquo;<samp>FR</samp>&rsquo;</span></dt>
  830. <dd><p>front right
  831. </p></dd>
  832. <dt><span>&lsquo;<samp>FC</samp>&rsquo;</span></dt>
  833. <dd><p>front center
  834. </p></dd>
  835. <dt><span>&lsquo;<samp>LFE</samp>&rsquo;</span></dt>
  836. <dd><p>low frequency
  837. </p></dd>
  838. <dt><span>&lsquo;<samp>BL</samp>&rsquo;</span></dt>
  839. <dd><p>back left
  840. </p></dd>
  841. <dt><span>&lsquo;<samp>BR</samp>&rsquo;</span></dt>
  842. <dd><p>back right
  843. </p></dd>
  844. <dt><span>&lsquo;<samp>FLC</samp>&rsquo;</span></dt>
  845. <dd><p>front left-of-center
  846. </p></dd>
  847. <dt><span>&lsquo;<samp>FRC</samp>&rsquo;</span></dt>
  848. <dd><p>front right-of-center
  849. </p></dd>
  850. <dt><span>&lsquo;<samp>BC</samp>&rsquo;</span></dt>
  851. <dd><p>back center
  852. </p></dd>
  853. <dt><span>&lsquo;<samp>SL</samp>&rsquo;</span></dt>
  854. <dd><p>side left
  855. </p></dd>
  856. <dt><span>&lsquo;<samp>SR</samp>&rsquo;</span></dt>
  857. <dd><p>side right
  858. </p></dd>
  859. <dt><span>&lsquo;<samp>TC</samp>&rsquo;</span></dt>
  860. <dd><p>top center
  861. </p></dd>
  862. <dt><span>&lsquo;<samp>TFL</samp>&rsquo;</span></dt>
  863. <dd><p>top front left
  864. </p></dd>
  865. <dt><span>&lsquo;<samp>TFC</samp>&rsquo;</span></dt>
  866. <dd><p>top front center
  867. </p></dd>
  868. <dt><span>&lsquo;<samp>TFR</samp>&rsquo;</span></dt>
  869. <dd><p>top front right
  870. </p></dd>
  871. <dt><span>&lsquo;<samp>TBL</samp>&rsquo;</span></dt>
  872. <dd><p>top back left
  873. </p></dd>
  874. <dt><span>&lsquo;<samp>TBC</samp>&rsquo;</span></dt>
  875. <dd><p>top back center
  876. </p></dd>
  877. <dt><span>&lsquo;<samp>TBR</samp>&rsquo;</span></dt>
  878. <dd><p>top back right
  879. </p></dd>
  880. <dt><span>&lsquo;<samp>DL</samp>&rsquo;</span></dt>
  881. <dd><p>downmix left
  882. </p></dd>
  883. <dt><span>&lsquo;<samp>DR</samp>&rsquo;</span></dt>
  884. <dd><p>downmix right
  885. </p></dd>
  886. <dt><span>&lsquo;<samp>WL</samp>&rsquo;</span></dt>
  887. <dd><p>wide left
  888. </p></dd>
  889. <dt><span>&lsquo;<samp>WR</samp>&rsquo;</span></dt>
  890. <dd><p>wide right
  891. </p></dd>
  892. <dt><span>&lsquo;<samp>SDL</samp>&rsquo;</span></dt>
  893. <dd><p>surround direct left
  894. </p></dd>
  895. <dt><span>&lsquo;<samp>SDR</samp>&rsquo;</span></dt>
  896. <dd><p>surround direct right
  897. </p></dd>
  898. <dt><span>&lsquo;<samp>LFE2</samp>&rsquo;</span></dt>
  899. <dd><p>low frequency 2
  900. </p></dd>
  901. </dl>
  902. <p>Standard channel layout compositions can be specified by using the
  903. following identifiers:
  904. </p><dl compact="compact">
  905. <dt><span>&lsquo;<samp>mono</samp>&rsquo;</span></dt>
  906. <dd><p>FC
  907. </p></dd>
  908. <dt><span>&lsquo;<samp>stereo</samp>&rsquo;</span></dt>
  909. <dd><p>FL+FR
  910. </p></dd>
  911. <dt><span>&lsquo;<samp>2.1</samp>&rsquo;</span></dt>
  912. <dd><p>FL+FR+LFE
  913. </p></dd>
  914. <dt><span>&lsquo;<samp>3.0</samp>&rsquo;</span></dt>
  915. <dd><p>FL+FR+FC
  916. </p></dd>
  917. <dt><span>&lsquo;<samp>3.0(back)</samp>&rsquo;</span></dt>
  918. <dd><p>FL+FR+BC
  919. </p></dd>
  920. <dt><span>&lsquo;<samp>4.0</samp>&rsquo;</span></dt>
  921. <dd><p>FL+FR+FC+BC
  922. </p></dd>
  923. <dt><span>&lsquo;<samp>quad</samp>&rsquo;</span></dt>
  924. <dd><p>FL+FR+BL+BR
  925. </p></dd>
  926. <dt><span>&lsquo;<samp>quad(side)</samp>&rsquo;</span></dt>
  927. <dd><p>FL+FR+SL+SR
  928. </p></dd>
  929. <dt><span>&lsquo;<samp>3.1</samp>&rsquo;</span></dt>
  930. <dd><p>FL+FR+FC+LFE
  931. </p></dd>
  932. <dt><span>&lsquo;<samp>5.0</samp>&rsquo;</span></dt>
  933. <dd><p>FL+FR+FC+BL+BR
  934. </p></dd>
  935. <dt><span>&lsquo;<samp>5.0(side)</samp>&rsquo;</span></dt>
  936. <dd><p>FL+FR+FC+SL+SR
  937. </p></dd>
  938. <dt><span>&lsquo;<samp>4.1</samp>&rsquo;</span></dt>
  939. <dd><p>FL+FR+FC+LFE+BC
  940. </p></dd>
  941. <dt><span>&lsquo;<samp>5.1</samp>&rsquo;</span></dt>
  942. <dd><p>FL+FR+FC+LFE+BL+BR
  943. </p></dd>
  944. <dt><span>&lsquo;<samp>5.1(side)</samp>&rsquo;</span></dt>
  945. <dd><p>FL+FR+FC+LFE+SL+SR
  946. </p></dd>
  947. <dt><span>&lsquo;<samp>6.0</samp>&rsquo;</span></dt>
  948. <dd><p>FL+FR+FC+BC+SL+SR
  949. </p></dd>
  950. <dt><span>&lsquo;<samp>6.0(front)</samp>&rsquo;</span></dt>
  951. <dd><p>FL+FR+FLC+FRC+SL+SR
  952. </p></dd>
  953. <dt><span>&lsquo;<samp>hexagonal</samp>&rsquo;</span></dt>
  954. <dd><p>FL+FR+FC+BL+BR+BC
  955. </p></dd>
  956. <dt><span>&lsquo;<samp>6.1</samp>&rsquo;</span></dt>
  957. <dd><p>FL+FR+FC+LFE+BC+SL+SR
  958. </p></dd>
  959. <dt><span>&lsquo;<samp>6.1</samp>&rsquo;</span></dt>
  960. <dd><p>FL+FR+FC+LFE+BL+BR+BC
  961. </p></dd>
  962. <dt><span>&lsquo;<samp>6.1(front)</samp>&rsquo;</span></dt>
  963. <dd><p>FL+FR+LFE+FLC+FRC+SL+SR
  964. </p></dd>
  965. <dt><span>&lsquo;<samp>7.0</samp>&rsquo;</span></dt>
  966. <dd><p>FL+FR+FC+BL+BR+SL+SR
  967. </p></dd>
  968. <dt><span>&lsquo;<samp>7.0(front)</samp>&rsquo;</span></dt>
  969. <dd><p>FL+FR+FC+FLC+FRC+SL+SR
  970. </p></dd>
  971. <dt><span>&lsquo;<samp>7.1</samp>&rsquo;</span></dt>
  972. <dd><p>FL+FR+FC+LFE+BL+BR+SL+SR
  973. </p></dd>
  974. <dt><span>&lsquo;<samp>7.1(wide)</samp>&rsquo;</span></dt>
  975. <dd><p>FL+FR+FC+LFE+BL+BR+FLC+FRC
  976. </p></dd>
  977. <dt><span>&lsquo;<samp>7.1(wide-side)</samp>&rsquo;</span></dt>
  978. <dd><p>FL+FR+FC+LFE+FLC+FRC+SL+SR
  979. </p></dd>
  980. <dt><span>&lsquo;<samp>octagonal</samp>&rsquo;</span></dt>
  981. <dd><p>FL+FR+FC+BL+BR+BC+SL+SR
  982. </p></dd>
  983. <dt><span>&lsquo;<samp>hexadecagonal</samp>&rsquo;</span></dt>
  984. <dd><p>FL+FR+FC+BL+BR+BC+SL+SR+WL+WR+TBL+TBR+TBC+TFC+TFL+TFR
  985. </p></dd>
  986. <dt><span>&lsquo;<samp>downmix</samp>&rsquo;</span></dt>
  987. <dd><p>DL+DR
  988. </p></dd>
  989. </dl>
  990. <p>A custom channel layout can be specified as a sequence of terms, separated by
  991. &rsquo;+&rsquo; or &rsquo;|&rsquo;. Each term can be:
  992. </p><ul>
  993. <li> the name of a standard channel layout (e.g. &lsquo;<samp>mono</samp>&rsquo;,
  994. &lsquo;<samp>stereo</samp>&rsquo;, &lsquo;<samp>4.0</samp>&rsquo;, &lsquo;<samp>quad</samp>&rsquo;, &lsquo;<samp>5.0</samp>&rsquo;, etc.)
  995. </li><li> the name of a single channel (e.g. &lsquo;<samp>FL</samp>&rsquo;, &lsquo;<samp>FR</samp>&rsquo;, &lsquo;<samp>FC</samp>&rsquo;, &lsquo;<samp>LFE</samp>&rsquo;, etc.)
  996. </li><li> a number of channels, in decimal, followed by &rsquo;c&rsquo;, yielding the default channel
  997. layout for that number of channels (see the function
  998. <code>av_get_default_channel_layout</code>). Note that not all channel counts have a
  999. default layout.
  1000. </li><li> a number of channels, in decimal, followed by &rsquo;C&rsquo;, yielding an unknown channel
  1001. layout with the specified number of channels. Note that not all channel layout
  1002. specification strings support unknown channel layouts.
  1003. </li><li> a channel layout mask, in hexadecimal starting with &quot;0x&quot; (see the
  1004. <code>AV_CH_*</code> macros in <samp>libavutil/channel_layout.h</samp>.
  1005. </li></ul>
  1006. <p>Before libavutil version 53 the trailing character &quot;c&quot; to specify a number of
  1007. channels was optional, but now it is required, while a channel layout mask can
  1008. also be specified as a decimal number (if and only if not followed by &quot;c&quot; or &quot;C&quot;).
  1009. </p>
  1010. <p>See also the function <code>av_get_channel_layout</code> defined in
  1011. <samp>libavutil/channel_layout.h</samp>.
  1012. </p>
  1013. <a name="Expression-Evaluation"></a>
  1014. <h2 class="chapter">3 Expression Evaluation<span class="pull-right"><a class="anchor hidden-xs" href="#Expression-Evaluation" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Expression-Evaluation" aria-hidden="true">TOC</a></span></h2>
  1015. <p>When evaluating an arithmetic expression, FFmpeg uses an internal
  1016. formula evaluator, implemented through the <samp>libavutil/eval.h</samp>
  1017. interface.
  1018. </p>
  1019. <p>An expression may contain unary, binary operators, constants, and
  1020. functions.
  1021. </p>
  1022. <p>Two expressions <var>expr1</var> and <var>expr2</var> can be combined to form
  1023. another expression &quot;<var>expr1</var>;<var>expr2</var>&quot;.
  1024. <var>expr1</var> and <var>expr2</var> are evaluated in turn, and the new
  1025. expression evaluates to the value of <var>expr2</var>.
  1026. </p>
  1027. <p>The following binary operators are available: <code>+</code>, <code>-</code>,
  1028. <code>*</code>, <code>/</code>, <code>^</code>.
  1029. </p>
  1030. <p>The following unary operators are available: <code>+</code>, <code>-</code>.
  1031. </p>
  1032. <p>The following functions are available:
  1033. </p><dl compact="compact">
  1034. <dt><span><samp>abs(x)</samp></span></dt>
  1035. <dd><p>Compute absolute value of <var>x</var>.
  1036. </p>
  1037. </dd>
  1038. <dt><span><samp>acos(x)</samp></span></dt>
  1039. <dd><p>Compute arccosine of <var>x</var>.
  1040. </p>
  1041. </dd>
  1042. <dt><span><samp>asin(x)</samp></span></dt>
  1043. <dd><p>Compute arcsine of <var>x</var>.
  1044. </p>
  1045. </dd>
  1046. <dt><span><samp>atan(x)</samp></span></dt>
  1047. <dd><p>Compute arctangent of <var>x</var>.
  1048. </p>
  1049. </dd>
  1050. <dt><span><samp>atan2(x, y)</samp></span></dt>
  1051. <dd><p>Compute principal value of the arc tangent of <var>y</var>/<var>x</var>.
  1052. </p>
  1053. </dd>
  1054. <dt><span><samp>between(x, min, max)</samp></span></dt>
  1055. <dd><p>Return 1 if <var>x</var> is greater than or equal to <var>min</var> and lesser than or
  1056. equal to <var>max</var>, 0 otherwise.
  1057. </p>
  1058. </dd>
  1059. <dt><span><samp>bitand(x, y)</samp></span></dt>
  1060. <dt><span><samp>bitor(x, y)</samp></span></dt>
  1061. <dd><p>Compute bitwise and/or operation on <var>x</var> and <var>y</var>.
  1062. </p>
  1063. <p>The results of the evaluation of <var>x</var> and <var>y</var> are converted to
  1064. integers before executing the bitwise operation.
  1065. </p>
  1066. <p>Note that both the conversion to integer and the conversion back to
  1067. floating point can lose precision. Beware of unexpected results for
  1068. large numbers (usually 2^53 and larger).
  1069. </p>
  1070. </dd>
  1071. <dt><span><samp>ceil(expr)</samp></span></dt>
  1072. <dd><p>Round the value of expression <var>expr</var> upwards to the nearest
  1073. integer. For example, &quot;ceil(1.5)&quot; is &quot;2.0&quot;.
  1074. </p>
  1075. </dd>
  1076. <dt><span><samp>clip(x, min, max)</samp></span></dt>
  1077. <dd><p>Return the value of <var>x</var> clipped between <var>min</var> and <var>max</var>.
  1078. </p>
  1079. </dd>
  1080. <dt><span><samp>cos(x)</samp></span></dt>
  1081. <dd><p>Compute cosine of <var>x</var>.
  1082. </p>
  1083. </dd>
  1084. <dt><span><samp>cosh(x)</samp></span></dt>
  1085. <dd><p>Compute hyperbolic cosine of <var>x</var>.
  1086. </p>
  1087. </dd>
  1088. <dt><span><samp>eq(x, y)</samp></span></dt>
  1089. <dd><p>Return 1 if <var>x</var> and <var>y</var> are equivalent, 0 otherwise.
  1090. </p>
  1091. </dd>
  1092. <dt><span><samp>exp(x)</samp></span></dt>
  1093. <dd><p>Compute exponential of <var>x</var> (with base <code>e</code>, the Euler&rsquo;s number).
  1094. </p>
  1095. </dd>
  1096. <dt><span><samp>floor(expr)</samp></span></dt>
  1097. <dd><p>Round the value of expression <var>expr</var> downwards to the nearest
  1098. integer. For example, &quot;floor(-1.5)&quot; is &quot;-2.0&quot;.
  1099. </p>
  1100. </dd>
  1101. <dt><span><samp>gauss(x)</samp></span></dt>
  1102. <dd><p>Compute Gauss function of <var>x</var>, corresponding to
  1103. <code>exp(-x*x/2) / sqrt(2*PI)</code>.
  1104. </p>
  1105. </dd>
  1106. <dt><span><samp>gcd(x, y)</samp></span></dt>
  1107. <dd><p>Return the greatest common divisor of <var>x</var> and <var>y</var>. If both <var>x</var> and
  1108. <var>y</var> are 0 or either or both are less than zero then behavior is undefined.
  1109. </p>
  1110. </dd>
  1111. <dt><span><samp>gt(x, y)</samp></span></dt>
  1112. <dd><p>Return 1 if <var>x</var> is greater than <var>y</var>, 0 otherwise.
  1113. </p>
  1114. </dd>
  1115. <dt><span><samp>gte(x, y)</samp></span></dt>
  1116. <dd><p>Return 1 if <var>x</var> is greater than or equal to <var>y</var>, 0 otherwise.
  1117. </p>
  1118. </dd>
  1119. <dt><span><samp>hypot(x, y)</samp></span></dt>
  1120. <dd><p>This function is similar to the C function with the same name; it returns
  1121. &quot;sqrt(<var>x</var>*<var>x</var> + <var>y</var>*<var>y</var>)&quot;, the length of the hypotenuse of a
  1122. right triangle with sides of length <var>x</var> and <var>y</var>, or the distance of the
  1123. point (<var>x</var>, <var>y</var>) from the origin.
  1124. </p>
  1125. </dd>
  1126. <dt><span><samp>if(x, y)</samp></span></dt>
  1127. <dd><p>Evaluate <var>x</var>, and if the result is non-zero return the result of
  1128. the evaluation of <var>y</var>, return 0 otherwise.
  1129. </p>
  1130. </dd>
  1131. <dt><span><samp>if(x, y, z)</samp></span></dt>
  1132. <dd><p>Evaluate <var>x</var>, and if the result is non-zero return the evaluation
  1133. result of <var>y</var>, otherwise the evaluation result of <var>z</var>.
  1134. </p>
  1135. </dd>
  1136. <dt><span><samp>ifnot(x, y)</samp></span></dt>
  1137. <dd><p>Evaluate <var>x</var>, and if the result is zero return the result of the
  1138. evaluation of <var>y</var>, return 0 otherwise.
  1139. </p>
  1140. </dd>
  1141. <dt><span><samp>ifnot(x, y, z)</samp></span></dt>
  1142. <dd><p>Evaluate <var>x</var>, and if the result is zero return the evaluation
  1143. result of <var>y</var>, otherwise the evaluation result of <var>z</var>.
  1144. </p>
  1145. </dd>
  1146. <dt><span><samp>isinf(x)</samp></span></dt>
  1147. <dd><p>Return 1.0 if <var>x</var> is +/-INFINITY, 0.0 otherwise.
  1148. </p>
  1149. </dd>
  1150. <dt><span><samp>isnan(x)</samp></span></dt>
  1151. <dd><p>Return 1.0 if <var>x</var> is NAN, 0.0 otherwise.
  1152. </p>
  1153. </dd>
  1154. <dt><span><samp>ld(var)</samp></span></dt>
  1155. <dd><p>Load the value of the internal variable with number
  1156. <var>var</var>, which was previously stored with st(<var>var</var>, <var>expr</var>).
  1157. The function returns the loaded value.
  1158. </p>
  1159. </dd>
  1160. <dt><span><samp>lerp(x, y, z)</samp></span></dt>
  1161. <dd><p>Return linear interpolation between <var>x</var> and <var>y</var> by amount of <var>z</var>.
  1162. </p>
  1163. </dd>
  1164. <dt><span><samp>log(x)</samp></span></dt>
  1165. <dd><p>Compute natural logarithm of <var>x</var>.
  1166. </p>
  1167. </dd>
  1168. <dt><span><samp>lt(x, y)</samp></span></dt>
  1169. <dd><p>Return 1 if <var>x</var> is lesser than <var>y</var>, 0 otherwise.
  1170. </p>
  1171. </dd>
  1172. <dt><span><samp>lte(x, y)</samp></span></dt>
  1173. <dd><p>Return 1 if <var>x</var> is lesser than or equal to <var>y</var>, 0 otherwise.
  1174. </p>
  1175. </dd>
  1176. <dt><span><samp>max(x, y)</samp></span></dt>
  1177. <dd><p>Return the maximum between <var>x</var> and <var>y</var>.
  1178. </p>
  1179. </dd>
  1180. <dt><span><samp>min(x, y)</samp></span></dt>
  1181. <dd><p>Return the minimum between <var>x</var> and <var>y</var>.
  1182. </p>
  1183. </dd>
  1184. <dt><span><samp>mod(x, y)</samp></span></dt>
  1185. <dd><p>Compute the remainder of division of <var>x</var> by <var>y</var>.
  1186. </p>
  1187. </dd>
  1188. <dt><span><samp>not(expr)</samp></span></dt>
  1189. <dd><p>Return 1.0 if <var>expr</var> is zero, 0.0 otherwise.
  1190. </p>
  1191. </dd>
  1192. <dt><span><samp>pow(x, y)</samp></span></dt>
  1193. <dd><p>Compute the power of <var>x</var> elevated <var>y</var>, it is equivalent to
  1194. &quot;(<var>x</var>)^(<var>y</var>)&quot;.
  1195. </p>
  1196. </dd>
  1197. <dt><span><samp>print(t)</samp></span></dt>
  1198. <dt><span><samp>print(t, l)</samp></span></dt>
  1199. <dd><p>Print the value of expression <var>t</var> with loglevel <var>l</var>. If
  1200. <var>l</var> is not specified then a default log level is used.
  1201. Returns the value of the expression printed.
  1202. </p>
  1203. <p>Prints t with loglevel l
  1204. </p>
  1205. </dd>
  1206. <dt><span><samp>random(x)</samp></span></dt>
  1207. <dd><p>Return a pseudo random value between 0.0 and 1.0. <var>x</var> is the index of the
  1208. internal variable which will be used to save the seed/state.
  1209. </p>
  1210. </dd>
  1211. <dt><span><samp>root(expr, max)</samp></span></dt>
  1212. <dd><p>Find an input value for which the function represented by <var>expr</var>
  1213. with argument <var>ld(0)</var> is 0 in the interval 0..<var>max</var>.
  1214. </p>
  1215. <p>The expression in <var>expr</var> must denote a continuous function or the
  1216. result is undefined.
  1217. </p>
  1218. <p><var>ld(0)</var> is used to represent the function input value, which means
  1219. that the given expression will be evaluated multiple times with
  1220. various input values that the expression can access through
  1221. <code>ld(0)</code>. When the expression evaluates to 0 then the
  1222. corresponding input value will be returned.
  1223. </p>
  1224. </dd>
  1225. <dt><span><samp>round(expr)</samp></span></dt>
  1226. <dd><p>Round the value of expression <var>expr</var> to the nearest integer. For example, &quot;round(1.5)&quot; is &quot;2.0&quot;.
  1227. </p>
  1228. </dd>
  1229. <dt><span><samp>sgn(x)</samp></span></dt>
  1230. <dd><p>Compute sign of <var>x</var>.
  1231. </p>
  1232. </dd>
  1233. <dt><span><samp>sin(x)</samp></span></dt>
  1234. <dd><p>Compute sine of <var>x</var>.
  1235. </p>
  1236. </dd>
  1237. <dt><span><samp>sinh(x)</samp></span></dt>
  1238. <dd><p>Compute hyperbolic sine of <var>x</var>.
  1239. </p>
  1240. </dd>
  1241. <dt><span><samp>sqrt(expr)</samp></span></dt>
  1242. <dd><p>Compute the square root of <var>expr</var>. This is equivalent to
  1243. &quot;(<var>expr</var>)^.5&quot;.
  1244. </p>
  1245. </dd>
  1246. <dt><span><samp>squish(x)</samp></span></dt>
  1247. <dd><p>Compute expression <code>1/(1 + exp(4*x))</code>.
  1248. </p>
  1249. </dd>
  1250. <dt><span><samp>st(var, expr)</samp></span></dt>
  1251. <dd><p>Store the value of the expression <var>expr</var> in an internal
  1252. variable. <var>var</var> specifies the number of the variable where to
  1253. store the value, and it is a value ranging from 0 to 9. The function
  1254. returns the value stored in the internal variable.
  1255. Note, Variables are currently not shared between expressions.
  1256. </p>
  1257. </dd>
  1258. <dt><span><samp>tan(x)</samp></span></dt>
  1259. <dd><p>Compute tangent of <var>x</var>.
  1260. </p>
  1261. </dd>
  1262. <dt><span><samp>tanh(x)</samp></span></dt>
  1263. <dd><p>Compute hyperbolic tangent of <var>x</var>.
  1264. </p>
  1265. </dd>
  1266. <dt><span><samp>taylor(expr, x)</samp></span></dt>
  1267. <dt><span><samp>taylor(expr, x, id)</samp></span></dt>
  1268. <dd><p>Evaluate a Taylor series at <var>x</var>, given an expression representing
  1269. the <code>ld(id)</code>-th derivative of a function at 0.
  1270. </p>
  1271. <p>When the series does not converge the result is undefined.
  1272. </p>
  1273. <p><var>ld(id)</var> is used to represent the derivative order in <var>expr</var>,
  1274. which means that the given expression will be evaluated multiple times
  1275. with various input values that the expression can access through
  1276. <code>ld(id)</code>. If <var>id</var> is not specified then 0 is assumed.
  1277. </p>
  1278. <p>Note, when you have the derivatives at y instead of 0,
  1279. <code>taylor(expr, x-y)</code> can be used.
  1280. </p>
  1281. </dd>
  1282. <dt><span><samp>time(0)</samp></span></dt>
  1283. <dd><p>Return the current (wallclock) time in seconds.
  1284. </p>
  1285. </dd>
  1286. <dt><span><samp>trunc(expr)</samp></span></dt>
  1287. <dd><p>Round the value of expression <var>expr</var> towards zero to the nearest
  1288. integer. For example, &quot;trunc(-1.5)&quot; is &quot;-1.0&quot;.
  1289. </p>
  1290. </dd>
  1291. <dt><span><samp>while(cond, expr)</samp></span></dt>
  1292. <dd><p>Evaluate expression <var>expr</var> while the expression <var>cond</var> is
  1293. non-zero, and returns the value of the last <var>expr</var> evaluation, or
  1294. NAN if <var>cond</var> was always false.
  1295. </p></dd>
  1296. </dl>
  1297. <p>The following constants are available:
  1298. </p><dl compact="compact">
  1299. <dt><span><samp>PI</samp></span></dt>
  1300. <dd><p>area of the unit disc, approximately 3.14
  1301. </p></dd>
  1302. <dt><span><samp>E</samp></span></dt>
  1303. <dd><p>exp(1) (Euler&rsquo;s number), approximately 2.718
  1304. </p></dd>
  1305. <dt><span><samp>PHI</samp></span></dt>
  1306. <dd><p>golden ratio (1+sqrt(5))/2, approximately 1.618
  1307. </p></dd>
  1308. </dl>
  1309. <p>Assuming that an expression is considered &quot;true&quot; if it has a non-zero
  1310. value, note that:
  1311. </p>
  1312. <p><code>*</code> works like AND
  1313. </p>
  1314. <p><code>+</code> works like OR
  1315. </p>
  1316. <p>For example the construct:
  1317. </p><div class="example">
  1318. <pre class="example">if (A AND B) then C
  1319. </pre></div>
  1320. <p>is equivalent to:
  1321. </p><div class="example">
  1322. <pre class="example">if(A*B, C)
  1323. </pre></div>
  1324. <p>In your C code, you can extend the list of unary and binary functions,
  1325. and define recognized constants, so that they are available for your
  1326. expressions.
  1327. </p>
  1328. <p>The evaluator also recognizes the International System unit prefixes.
  1329. If &rsquo;i&rsquo; is appended after the prefix, binary prefixes are used, which
  1330. are based on powers of 1024 instead of powers of 1000.
  1331. The &rsquo;B&rsquo; postfix multiplies the value by 8, and can be appended after a
  1332. unit prefix or used alone. This allows using for example &rsquo;KB&rsquo;, &rsquo;MiB&rsquo;,
  1333. &rsquo;G&rsquo; and &rsquo;B&rsquo; as number postfix.
  1334. </p>
  1335. <p>The list of available International System prefixes follows, with
  1336. indication of the corresponding powers of 10 and of 2.
  1337. </p><dl compact="compact">
  1338. <dt><span><samp>y</samp></span></dt>
  1339. <dd><p>10^-24 / 2^-80
  1340. </p></dd>
  1341. <dt><span><samp>z</samp></span></dt>
  1342. <dd><p>10^-21 / 2^-70
  1343. </p></dd>
  1344. <dt><span><samp>a</samp></span></dt>
  1345. <dd><p>10^-18 / 2^-60
  1346. </p></dd>
  1347. <dt><span><samp>f</samp></span></dt>
  1348. <dd><p>10^-15 / 2^-50
  1349. </p></dd>
  1350. <dt><span><samp>p</samp></span></dt>
  1351. <dd><p>10^-12 / 2^-40
  1352. </p></dd>
  1353. <dt><span><samp>n</samp></span></dt>
  1354. <dd><p>10^-9 / 2^-30
  1355. </p></dd>
  1356. <dt><span><samp>u</samp></span></dt>
  1357. <dd><p>10^-6 / 2^-20
  1358. </p></dd>
  1359. <dt><span><samp>m</samp></span></dt>
  1360. <dd><p>10^-3 / 2^-10
  1361. </p></dd>
  1362. <dt><span><samp>c</samp></span></dt>
  1363. <dd><p>10^-2
  1364. </p></dd>
  1365. <dt><span><samp>d</samp></span></dt>
  1366. <dd><p>10^-1
  1367. </p></dd>
  1368. <dt><span><samp>h</samp></span></dt>
  1369. <dd><p>10^2
  1370. </p></dd>
  1371. <dt><span><samp>k</samp></span></dt>
  1372. <dd><p>10^3 / 2^10
  1373. </p></dd>
  1374. <dt><span><samp>K</samp></span></dt>
  1375. <dd><p>10^3 / 2^10
  1376. </p></dd>
  1377. <dt><span><samp>M</samp></span></dt>
  1378. <dd><p>10^6 / 2^20
  1379. </p></dd>
  1380. <dt><span><samp>G</samp></span></dt>
  1381. <dd><p>10^9 / 2^30
  1382. </p></dd>
  1383. <dt><span><samp>T</samp></span></dt>
  1384. <dd><p>10^12 / 2^40
  1385. </p></dd>
  1386. <dt><span><samp>P</samp></span></dt>
  1387. <dd><p>10^15 / 2^40
  1388. </p></dd>
  1389. <dt><span><samp>E</samp></span></dt>
  1390. <dd><p>10^18 / 2^50
  1391. </p></dd>
  1392. <dt><span><samp>Z</samp></span></dt>
  1393. <dd><p>10^21 / 2^60
  1394. </p></dd>
  1395. <dt><span><samp>Y</samp></span></dt>
  1396. <dd><p>10^24 / 2^70
  1397. </p></dd>
  1398. </dl>
  1399. <a name="See-Also"></a>
  1400. <h2 class="chapter">4 See Also<span class="pull-right"><a class="anchor hidden-xs" href="#See-Also" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-See-Also" aria-hidden="true">TOC</a></span></h2>
  1401. <p><a href="ffmpeg.html">ffmpeg</a>, <a href="ffplay.html">ffplay</a>, <a href="ffprobe.html">ffprobe</a>,
  1402. <a href="libavutil.html">libavutil</a>
  1403. </p>
  1404. <a name="Authors"></a>
  1405. <h2 class="chapter">5 Authors<span class="pull-right"><a class="anchor hidden-xs" href="#Authors" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Authors" aria-hidden="true">TOC</a></span></h2>
  1406. <p>The FFmpeg developers.
  1407. </p>
  1408. <p>For details about the authorship, see the Git history of the project
  1409. (https://git.ffmpeg.org/ffmpeg), e.g. by typing the command
  1410. <code>git log</code> in the FFmpeg source directory, or browsing the
  1411. online repository at <a href="https://git.ffmpeg.org/ffmpeg">https://git.ffmpeg.org/ffmpeg</a>.
  1412. </p>
  1413. <p>Maintainers for the specific components are listed in the file
  1414. <samp>MAINTAINERS</samp> in the source code tree.
  1415. </p>
  1416. </body>
  1417. </html>