codekingpro/portable-devtools
114k
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 7.1.1 -->4 <head>5 <meta charset="utf-8">6 <title>7 ffmpeg Documentation8 </title>9 <meta name="viewport" content="width=device-width,initial-scale=1.0">10 <link rel="stylesheet" type="text/css" href="bootstrap.min.css">11 <link rel="stylesheet" type="text/css" href="style.min.css">12 </head>13 <body>14 <div class="container">15 <h1>16 ffmpeg Documentation17 </h1>18 19 20<a name="SEC_Top"></a>21 22<div class="element-contents" id="SEC_Contents">23<h2 class="contents-heading">Table of Contents</h2>24 25<div class="contents">26 27<ul class="toc-numbered-mark">28 <li><a id="toc-Synopsis" href="#Synopsis">1 Synopsis</a></li>29 <li><a id="toc-Description" href="#Description">2 Description</a></li>30 <li><a id="toc-Detailed-description" href="#Detailed-description">3 Detailed description</a>31 <ul class="toc-numbered-mark">32 <li><a id="toc-Streamcopy" href="#Streamcopy">3.1 Streamcopy</a></li>33 <li><a id="toc-Transcoding" href="#Transcoding">3.2 Transcoding</a></li>34 <li><a id="toc-Filtering" href="#Filtering">3.3 Filtering</a>35 <ul class="toc-numbered-mark">36 <li><a id="toc-Simple-filtergraphs" href="#Simple-filtergraphs">3.3.1 Simple filtergraphs</a></li>37 <li><a id="toc-Complex-filtergraphs" href="#Complex-filtergraphs">3.3.2 Complex filtergraphs</a></li>38 </ul></li>39 <li><a id="toc-Loopback-decoders-1" href="#Loopback-decoders-1">3.4 Loopback decoders</a></li>40 </ul></li>41 <li><a id="toc-Stream-selection-1" href="#Stream-selection-1">4 Stream selection</a>42 <ul class="toc-numbered-mark">43 <li><a id="toc-Description-1" href="#Description-1">4.1 Description</a>44 <ul class="toc-numbered-mark">45 <li><a id="toc-Automatic-stream-selection" href="#Automatic-stream-selection">4.1.1 Automatic stream selection</a></li>46 <li><a id="toc-Manual-stream-selection" href="#Manual-stream-selection">4.1.2 Manual stream selection</a></li>47 <li><a id="toc-Complex-filtergraphs-1" href="#Complex-filtergraphs-1">4.1.3 Complex filtergraphs</a></li>48 <li><a id="toc-Stream-handling" href="#Stream-handling">4.1.4 Stream handling</a></li>49 </ul></li>50 <li><a id="toc-Examples" href="#Examples">4.2 Examples</a></li>51 </ul></li>52 <li><a id="toc-Options" href="#Options">5 Options</a>53 <ul class="toc-numbered-mark">54 <li><a id="toc-Stream-specifiers-1" href="#Stream-specifiers-1">5.1 Stream specifiers</a></li>55 <li><a id="toc-Generic-options" href="#Generic-options">5.2 Generic options</a></li>56 <li><a id="toc-AVOptions" href="#AVOptions">5.3 AVOptions</a></li>57 <li><a id="toc-Main-options" href="#Main-options">5.4 Main options</a></li>58 <li><a id="toc-Video-Options" href="#Video-Options">5.5 Video Options</a></li>59 <li><a id="toc-Advanced-Video-options" href="#Advanced-Video-options">5.6 Advanced Video options</a></li>60 <li><a id="toc-Audio-Options" href="#Audio-Options">5.7 Audio Options</a></li>61 <li><a id="toc-Advanced-Audio-options" href="#Advanced-Audio-options">5.8 Advanced Audio options</a></li>62 <li><a id="toc-Subtitle-options" href="#Subtitle-options">5.9 Subtitle options</a></li>63 <li><a id="toc-Advanced-Subtitle-options" href="#Advanced-Subtitle-options">5.10 Advanced Subtitle options</a></li>64 <li><a id="toc-Advanced-options" href="#Advanced-options">5.11 Advanced options</a></li>65 <li><a id="toc-Preset-files" href="#Preset-files">5.12 Preset files</a>66 <ul class="toc-numbered-mark">67 <li><a id="toc-ffpreset-files" href="#ffpreset-files">5.12.1 ffpreset files</a></li>68 <li><a id="toc-avpreset-files" href="#avpreset-files">5.12.2 avpreset files</a></li>69 </ul></li>70 <li><a id="toc-vstats-file-format" href="#vstats-file-format">5.13 vstats file format</a></li>71 </ul></li>72 <li><a id="toc-Examples-1" href="#Examples-1">6 Examples</a>73 <ul class="toc-numbered-mark">74 <li><a id="toc-Video-and-Audio-grabbing" href="#Video-and-Audio-grabbing">6.1 Video and Audio grabbing</a></li>75 <li><a id="toc-X11-grabbing" href="#X11-grabbing">6.2 X11 grabbing</a></li>76 <li><a id="toc-Video-and-Audio-file-format-conversion" href="#Video-and-Audio-file-format-conversion">6.3 Video and Audio file format conversion</a></li>77 </ul></li>78 <li><a id="toc-See-Also" href="#See-Also">7 See Also</a></li>79 <li><a id="toc-Authors" href="#Authors">8 Authors</a></li>80</ul>81</div>82</div>83 84<a name="Synopsis"></a>85<h2 class="chapter">1 Synopsis<span class="pull-right"><a class="anchor hidden-xs" href="#Synopsis" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Synopsis" aria-hidden="true">TOC</a></span></h2>86 87<p>ffmpeg [<var class="var">global_options</var>] {[<var class="var">input_file_options</var>] -i <samp class="file">input_url</samp>} ... {[<var class="var">output_file_options</var>] <samp class="file">output_url</samp>} ...88</p>89<a name="Description"></a>90<h2 class="chapter">2 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>91 92<p><code class="command">ffmpeg</code> is a universal media converter. It can read a wide variety of93inputs - including live grabbing/recording devices - filter, and transcode them94into a plethora of output formats.95</p>96<p><code class="command">ffmpeg</code> reads from an arbitrary number of inputs (which can be regular97files, pipes, network streams, grabbing devices, etc.), specified by the98<code class="code">-i</code> option, and writes to an arbitrary number of outputs, which are99specified by a plain output url. Anything found on the command line which cannot100be interpreted as an option is considered to be an output url.101</p>102<p>Each input or output can, in principle, contain any number of elementary streams103of different types (video/audio/subtitle/attachment/data), though the allowed104stream counts and/or types may be limited by the container format. Selecting105which streams from which inputs will go into which output is either done106automatically or with the <code class="code">-map</code> option (see the <a class="ref" href="#Stream-selection">Stream selection</a>107chapter).108</p>109<p>To refer to inputs/outputs in options, you must use their indices (0-based).110E.g. the first input is <code class="code">0</code>, the second is <code class="code">1</code>, etc. Similarly,111streams within an input/output are referred to by their indices. E.g. <code class="code">2:3</code>112refers to the fourth stream in the third input or output. Also see the113<a class="ref" href="#Stream-specifiers">Stream specifiers</a> chapter.114</p>115<p>As a general rule, options are applied to the next specified116file. Therefore, order is important, and you can have the same117option on the command line multiple times. Each occurrence is118then applied to the next input or output file.119Exceptions from this rule are the global options (e.g. verbosity level),120which should be specified first.121</p>122<p>Do not mix input and output files – first specify all input files, then all123output files. Also do not mix options which belong to different files. All124options apply ONLY to the next input or output file and are reset between files.125</p>126<p>Some simple examples follow.127</p>128<ul class="itemize mark-bullet">129<li>Convert an input media file to a different format, by re-encoding media streams:130<div class="example">131<pre class="example-preformatted">ffmpeg -i input.avi output.mp4132</pre></div>133 134</li><li>Set the video bitrate of the output file to 64 kbit/s:135<div class="example">136<pre class="example-preformatted">ffmpeg -i input.avi -b:v 64k -bufsize 64k output.mp4137</pre></div>138 139</li><li>Force the frame rate of the output file to 24 fps:140<div class="example">141<pre class="example-preformatted">ffmpeg -i input.avi -r 24 output.mp4142</pre></div>143 144</li><li>Force the frame rate of the input file (valid for raw formats only) to 1 fps and145the frame rate of the output file to 24 fps:146<div class="example">147<pre class="example-preformatted">ffmpeg -r 1 -i input.m2v -r 24 output.mp4148</pre></div>149</li></ul>150 151<p>The format option may be needed for raw input files.152</p>153 154<a name="Detailed-description"></a>155<h2 class="chapter">3 Detailed description<span class="pull-right"><a class="anchor hidden-xs" href="#Detailed-description" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Detailed-description" aria-hidden="true">TOC</a></span></h2>156 157<p><code class="command">ffmpeg</code> builds a transcoding pipeline out of the components listed158below. The program’s operation then consists of input data chunks flowing from159the sources down the pipes towards the sinks, while being transformed by the160components they encounter along the way.161</p>162<p>The following kinds of components are available:163</p><ul class="itemize mark-bullet">164<li><em class="emph">Demuxers</em> (short for "demultiplexers") read an input source in order to165extract166 167<ul class="itemize mark-bullet">168<li>global properties such as metadata or chapters;169</li><li>list of input elementary streams and their properties170</li></ul>171 172<p>One demuxer instance is created for each <samp class="option">-i</samp> option, and sends encoded173<em class="emph">packets</em> to <em class="emph">decoders</em> or <em class="emph">muxers</em>.174</p>175<p>In other literature, demuxers are sometimes called <em class="emph">splitters</em>, because176their main function is splitting a file into elementary streams (though some177files only contain one elementary stream).178</p>179<p>A schematic representation of a demuxer looks like this:180</p><pre class="verbatim">┌──────────┬───────────────────────┐181│ demuxer │ │ packets for stream 0182╞══════════╡ elementary stream 0 ├──────────────────────►183│ │ │184│ global ├───────────────────────┤185│properties│ │ packets for stream 1186│ and │ elementary stream 1 ├──────────────────────►187│ metadata │ │188│ ├───────────────────────┤189│ │ │190│ │ ........... │191│ │ │192│ ├───────────────────────┤193│ │ │ packets for stream N194│ │ elementary stream N ├──────────────────────►195│ │ │196└──────────┴───────────────────────┘197 ▲198 │199 │ read from file, network stream,200 │ grabbing device, etc.201 │202</pre>203</li><li><em class="emph">Decoders</em> receive encoded (compressed) <em class="emph">packets</em> for an audio, video,204or subtitle elementary stream, and decode them into raw <em class="emph">frames</em> (arrays of205pixels for video, PCM for audio). A decoder is typically associated with (and206receives its input from) an elementary stream in a <em class="emph">demuxer</em>, but sometimes207may also exist on its own (see <a class="ref" href="#Loopback-decoders">Loopback decoders</a>).208 209<p>A schematic representation of a decoder looks like this:210</p><pre class="verbatim"> ┌─────────┐211 packets │ │ raw frames212─────────►│ decoder ├────────────►213 │ │214 └─────────┘215</pre>216</li><li><em class="emph">Filtergraphs</em> process and transform raw audio or video <em class="emph">frames</em>. A217filtergraph consists of one or more individual <em class="emph">filters</em> linked into a218graph. Filtergraphs come in two flavors - <em class="emph">simple</em> and <em class="emph">complex</em>,219configured with the <samp class="option">-filter</samp> and <samp class="option">-filter_complex</samp> options,220respectively.221 222<p>A simple filtergraph is associated with an <em class="emph">output elementary stream</em>; it223receives the input to be filtered from a <em class="emph">decoder</em> and sends filtered224output to that output stream’s <em class="emph">encoder</em>.225</p>226<p>A simple video filtergraph that performs deinterlacing (using the <code class="code">yadif</code>227deinterlacer) followed by resizing (using the <code class="code">scale</code> filter) can look like228this:229</p><pre class="verbatim">230 ┌────────────────────────┐231 │ simple filtergraph │232 frames from ╞════════════════════════╡ frames for233 a decoder │ ┌───────┐ ┌───────┐ │ an encoder234────────────►├─►│ yadif ├─►│ scale ├─►│────────────►235 │ └───────┘ └───────┘ │236 └────────────────────────┘237</pre>238<p>A complex filtergraph is standalone and not associated with any specific stream.239It may have multiple (or zero) inputs, potentially of different types (audio or240video), each of which receiving data either from a decoder or another complex241filtergraph’s output. It also has one or more outputs that feed either an242encoder or another complex filtergraph’s input.243</p>244<p>The following example diagram represents a complex filtergraph with 3 inputs and2452 outputs (all video):246</p><pre class="verbatim"> ┌─────────────────────────────────────────────────┐247 │ complex filtergraph │248 ╞═════════════════════════════════════════════════╡249 frames ├───────┐ ┌─────────┐ ┌─────────┐ ┌────────┤ frames250─────────►│input 0├─►│ overlay ├─────►│ overlay ├─►│output 0├────────►251 ├───────┘ │ │ │ │ └────────┤252 frames ├───────┐╭►│ │ ╭►│ │ │253─────────►│input 1├╯ └─────────┘ │ └─────────┘ │254 ├───────┘ │ │255 frames ├───────┐ ┌─────┐ ┌─────┬─╯ ┌────────┤ frames256─────────►│input 2├►│scale├►│split├───────────────►│output 1├────────►257 ├───────┘ └─────┘ └─────┘ └────────┤258 └─────────────────────────────────────────────────┘259</pre><p>Frames from second input are overlaid over those from the first. Frames from the260third input are rescaled, then the duplicated into two identical streams. One of261them is overlaid over the combined first two inputs, with the result exposed as262the filtergraph’s first output. The other duplicate ends up being the263filtergraph’s second output.264</p>265</li><li><em class="emph">Encoders</em> receive raw audio, video, or subtitle <em class="emph">frames</em> and encode266them into encoded <em class="emph">packets</em>. The encoding (compression) process is267typically <em class="emph">lossy</em> - it degrades stream quality to make the output smaller;268some encoders are <em class="emph">lossless</em>, but at the cost of much higher output size. A269video or audio encoder receives its input from some filtergraph’s output,270subtitle encoders receive input from a decoder (since subtitle filtering is not271supported yet). Every encoder is associated with some muxer’s <em class="emph">output272elementary stream</em> and sends its output to that muxer.273 274<p>A schematic representation of an encoder looks like this:275</p><pre class="verbatim"> ┌─────────┐276 raw frames │ │ packets277────────────►│ encoder ├─────────►278 │ │279 └─────────┘280</pre>281</li><li><em class="emph">Muxers</em> (short for "multiplexers") receive encoded <em class="emph">packets</em> for282their elementary streams from encoders (the <em class="emph">transcoding</em> path) or directly283from demuxers (the <em class="emph">streamcopy</em> path), interleave them (when there is more284than one elementary stream), and write the resulting bytes into the output file285(or pipe, network stream, etc.).286 287<p>A schematic representation of a muxer looks like this:288</p><pre class="verbatim"> ┌──────────────────────┬───────────┐289 packets for stream 0 │ │ muxer │290──────────────────────►│ elementary stream 0 ╞═══════════╡291 │ │ │292 ├──────────────────────┤ global │293 packets for stream 1 │ │properties │294──────────────────────►│ elementary stream 1 │ and │295 │ │ metadata │296 ├──────────────────────┤ │297 │ │ │298 │ ........... │ │299 │ │ │300 ├──────────────────────┤ │301 packets for stream N │ │ │302──────────────────────►│ elementary stream N │ │303 │ │ │304 └──────────────────────┴─────┬─────┘305 │306 write to file, network stream, │307 grabbing device, etc. │308 │309 ▼310</pre>311</li></ul>312 313<a name="Streamcopy"></a>314<h3 class="section">3.1 Streamcopy<span class="pull-right"><a class="anchor hidden-xs" href="#Streamcopy" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Streamcopy" aria-hidden="true">TOC</a></span></h3>315<p>The simplest pipeline in <code class="command">ffmpeg</code> is single-stream316<em class="emph">streamcopy</em>, that is copying one <em class="emph">input elementary stream</em>’s packets317without decoding, filtering, or encoding them. As an example, consider an input318file called <samp class="file">INPUT.mkv</samp> with 3 elementary streams, from which we take the319second and write it to file <samp class="file">OUTPUT.mp4</samp>. A schematic representation of320such a pipeline looks like this:321</p><pre class="verbatim">┌──────────┬─────────────────────┐322│ demuxer │ │ unused323╞══════════╡ elementary stream 0 ├────────╳324│ │ │325│INPUT.mkv ├─────────────────────┤ ┌──────────────────────┬───────────┐326│ │ │ packets │ │ muxer │327│ │ elementary stream 1 ├─────────►│ elementary stream 0 ╞═══════════╡328│ │ │ │ │OUTPUT.mp4 │329│ ├─────────────────────┤ └──────────────────────┴───────────┘330│ │ │ unused331│ │ elementary stream 2 ├────────╳332│ │ │333└──────────┴─────────────────────┘334</pre>335<p>The above pipeline can be constructed with the following commandline:336</p><div class="example">337<pre class="example-preformatted">ffmpeg -i INPUT.mkv -map 0:1 -c copy OUTPUT.mp4338</pre></div>339 340<p>In this commandline341</p><ul class="itemize mark-bullet">342<li>there is a single input <samp class="file">INPUT.mkv</samp>;343 344</li><li>there are no input options for this input;345 346</li><li>there is a single output <samp class="file">OUTPUT.mp4</samp>;347 348</li><li>there are two output options for this output:349 350<ul class="itemize mark-bullet">351<li><code class="code">-map 0:1</code> selects the input stream to be used - from input with index 0352(i.e. the first one) the stream with index 1 (i.e. the second one);353 354</li><li><code class="code">-c copy</code> selects the <code class="code">copy</code> encoder, i.e. streamcopy with no decoding355or encoding.356</li></ul>357 358</li></ul>359 360<p>Streamcopy is useful for changing the elementary stream count, container format,361or modifying container-level metadata. Since there is no decoding or encoding,362it is very fast and there is no quality loss. However, it might not work in some363cases because of a variety of factors (e.g. certain information required by the364target container is not available in the source). Applying filters is obviously365also impossible, since filters work on decoded frames.366</p>367<p>More complex streamcopy scenarios can be constructed - e.g. combining streams368from two input files into a single output:369</p><pre class="verbatim">┌──────────┬────────────────────┐ ┌────────────────────┬───────────┐370│ demuxer 0│ │ packets │ │ muxer │371╞══════════╡elementary stream 0 ├────────►│elementary stream 0 ╞═══════════╡372│INPUT0.mkv│ │ │ │OUTPUT.mp4 │373└──────────┴────────────────────┘ ├────────────────────┤ │374┌──────────┬────────────────────┐ │ │ │375│ demuxer 1│ │ packets │elementary stream 1 │ │376╞══════════╡elementary stream 0 ├────────►│ │ │377│INPUT1.aac│ │ └────────────────────┴───────────┘378└──────────┴────────────────────┘379</pre><p>that can be built by the commandline380</p><div class="example">381<pre class="example-preformatted">ffmpeg -i INPUT0.mkv -i INPUT1.aac -map 0:0 -map 1:0 -c copy OUTPUT.mp4382</pre></div>383 384<p>The output <samp class="option">-map</samp> option is used twice here, creating two streams in the385output file - one fed by the first input and one by the second. The single386instance of the <samp class="option">-c</samp> option selects streamcopy for both of those streams.387You could also use multiple instances of this option together with388<a class="ref" href="#Stream-specifiers">Stream specifiers</a> to apply different values to each stream, as will be389demonstrated in following sections.390</p>391<p>A converse scenario is splitting multiple streams from a single input into392multiple outputs:393</p><pre class="verbatim">┌──────────┬─────────────────────┐ ┌───────────────────┬───────────┐394│ demuxer │ │ packets │ │ muxer 0 │395╞══════════╡ elementary stream 0 ├─────────►│elementary stream 0╞═══════════╡396│ │ │ │ │OUTPUT0.mp4│397│INPUT.mkv ├─────────────────────┤ └───────────────────┴───────────┘398│ │ │ packets ┌───────────────────┬───────────┐399│ │ elementary stream 1 ├─────────►│ │ muxer 1 │400│ │ │ │elementary stream 0╞═══════════╡401└──────────┴─────────────────────┘ │ │OUTPUT1.mp4│402 └───────────────────┴───────────┘403</pre><p>built with404</p><div class="example">405<pre class="example-preformatted">ffmpeg -i INPUT.mkv -map 0:0 -c copy OUTPUT0.mp4 -map 0:1 -c copy OUTPUT1.mp4406</pre></div>407<p>Note how a separate instance of the <samp class="option">-c</samp> option is needed for every408output file even though their values are the same. This is because non-global409options (which is most of them) only apply in the context of the file before410which they are placed.411</p>412<p>These examples can of course be further generalized into arbitrary remappings413of any number of inputs into any number of outputs.414</p>415<a name="Transcoding"></a>416<h3 class="section">3.2 Transcoding<span class="pull-right"><a class="anchor hidden-xs" href="#Transcoding" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Transcoding" aria-hidden="true">TOC</a></span></h3>417<p><em class="emph">Transcoding</em> is the process of decoding a stream and then encoding it418again. Since encoding tends to be computationally expensive and in most cases419degrades the stream quality (i.e. it is <em class="emph">lossy</em>), you should only transcode420when you need to and perform streamcopy otherwise. Typical reasons to transcode421are:422</p>423<ul class="itemize mark-bullet">424<li>applying filters - e.g. resizing, deinterlacing, or overlaying video; resampling425or mixing audio;426 427</li><li>you want to feed the stream to something that cannot decode the original codec.428</li></ul>429<p>Note that <code class="command">ffmpeg</code> will transcode all audio, video, and subtitle streams430unless you specify <samp class="option">-c copy</samp> for them.431</p>432<p>Consider an example pipeline that reads an input file with one audio and one433video stream, transcodes the video and copies the audio into a single output434file. This can be schematically represented as follows435</p><pre class="verbatim">┌──────────┬─────────────────────┐436│ demuxer │ │ audio packets437╞══════════╡ stream 0 (audio) ├─────────────────────────────────────╮438│ │ │ │439│INPUT.mkv ├─────────────────────┤ video ┌─────────┐ raw │440│ │ │ packets │ video │ video frames │441│ │ stream 1 (video) ├─────────►│ decoder ├──────────────╮ │442│ │ │ │ │ │ │443└──────────┴─────────────────────┘ └─────────┘ │ │444 ▼ ▼445 │ │446┌──────────┬─────────────────────┐ video ┌─────────┐ │ │447│ muxer │ │ packets │ video │ │ │448╞══════════╡ stream 0 (video) │◄─────────┤ encoder ├──────────────╯ │449│ │ │ │(libx264)│ │450│OUTPUT.mp4├─────────────────────┤ └─────────┘ │451│ │ │ │452│ │ stream 1 (audio) │◄────────────────────────────────────╯453│ │ │454└──────────┴─────────────────────┘455</pre><p>and implemented with the following commandline:456</p><div class="example">457<pre class="example-preformatted">ffmpeg -i INPUT.mkv -map 0:v -map 0:a -c:v libx264 -c:a copy OUTPUT.mp4458</pre></div>459<p>Note how it uses stream specifiers <code class="code">:v</code> and <code class="code">:a</code> to select input460streams and apply different values of the <samp class="option">-c</samp> option to them; see the461<a class="ref" href="#Stream-specifiers">Stream specifiers</a> section for more details.462</p>463 464<a name="Filtering"></a>465<h3 class="section">3.3 Filtering<span class="pull-right"><a class="anchor hidden-xs" href="#Filtering" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Filtering" aria-hidden="true">TOC</a></span></h3>466 467<p>When transcoding, audio and video streams can be filtered before encoding, with468either a <em class="emph">simple</em> or <em class="emph">complex</em> filtergraph.469</p>470<a name="Simple-filtergraphs"></a>471<h4 class="subsection">3.3.1 Simple filtergraphs<span class="pull-right"><a class="anchor hidden-xs" href="#Simple-filtergraphs" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Simple-filtergraphs" aria-hidden="true">TOC</a></span></h4>472 473<p>Simple filtergraphs are those that have exactly one input and output, both of474the same type (audio or video). They are configured with the per-stream475<samp class="option">-filter</samp> option (with <samp class="option">-vf</samp> and <samp class="option">-af</samp> aliases for476<samp class="option">-filter:v</samp> (video) and <samp class="option">-filter:a</samp> (audio) respectively). Note477that simple filtergraphs are tied to their output stream, so e.g. if you have478multiple audio streams, <samp class="option">-af</samp> will create a separate filtergraph for each479one.480</p>481<p>Taking the transcoding example from above, adding filtering (and omitting audio,482for clarity) makes it look like this:483</p><pre class="verbatim">┌──────────┬───────────────┐484│ demuxer │ │ ┌─────────┐485╞══════════╡ video stream │ packets │ video │ frames486│INPUT.mkv │ ├─────────►│ decoder ├─────►───╮487│ │ │ └─────────┘ │488└──────────┴───────────────┘ │489 ╭───────────◄───────────╯490 │ ┌────────────────────────┐491 │ │ simple filtergraph │492 │ ╞════════════════════════╡493 │ │ ┌───────┐ ┌───────┐ │494 ╰──►├─►│ yadif ├─►│ scale ├─►├╮495 │ └───────┘ └───────┘ ││496 └────────────────────────┘│497 │498 │499┌──────────┬───────────────┐ video ┌─────────┐ │500│ muxer │ │ packets │ video │ │501╞══════════╡ video stream │◄─────────┤ encoder ├───────◄───────╯502│OUTPUT.mp4│ │ │ │503│ │ │ └─────────┘504└──────────┴───────────────┘505</pre>506<a name="Complex-filtergraphs"></a>507<h4 class="subsection">3.3.2 Complex filtergraphs<span class="pull-right"><a class="anchor hidden-xs" href="#Complex-filtergraphs" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Complex-filtergraphs" aria-hidden="true">TOC</a></span></h4>508 509<p>Complex filtergraphs are those which cannot be described as simply a linear510processing chain applied to one stream. This is the case, for example, when the511graph has more than one input and/or output, or when output stream type is512different from input. Complex filtergraphs are configured with the513<samp class="option">-filter_complex</samp> option. Note that this option is global, since a514complex filtergraph, by its nature, cannot be unambiguously associated with a515single stream or file. Each instance of <samp class="option">-filter_complex</samp> creates a new516complex filtergraph, and there can be any number of them.517</p>518<p>A trivial example of a complex filtergraph is the <code class="code">overlay</code> filter, which519has two video inputs and one video output, containing one video overlaid on top520of the other. Its audio counterpart is the <code class="code">amix</code> filter.521</p>522<a class="anchor" id="Loopback-decoders"></a><a name="Loopback-decoders-1"></a>523<h3 class="section">3.4 Loopback decoders<span class="pull-right"><a class="anchor hidden-xs" href="#Loopback-decoders-1" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Loopback-decoders-1" aria-hidden="true">TOC</a></span></h3>524<p>While decoders are normally associated with demuxer streams, it is also possible525to create "loopback" decoders that decode the output from some encoder and allow526it to be fed back to complex filtergraphs. This is done with the <code class="code">-dec</code>527directive, which takes as a parameter the index of the output stream that should528be decoded. Every such directive creates a new loopback decoder, indexed with529successive integers starting at zero. These indices should then be used to refer530to loopback decoders in complex filtergraph link labels, as described in the531documentation for <samp class="option">-filter_complex</samp>.532</p>533<p>Decoding AVOptions can be passed to loopback decoders by placing them before534<code class="code">-dec</code>, analogously to input/output options.535</p>536<p>E.g. the following example:537</p>538<div class="example">539<pre class="example-preformatted">ffmpeg -i INPUT \540 -map 0:v:0 -c:v libx264 -crf 45 -f null - \541 -threads 3 -dec 0:0 \542 -filter_complex '[0:v][dec:0]hstack[stack]' \543 -map '[stack]' -c:v ffv1 OUTPUT544</pre></div>545 546<p>reads an input video and547</p><ul class="itemize mark-bullet">548<li>(line 2) encodes it with <code class="code">libx264</code> at low quality;549 550</li><li>(line 3) decodes this encoded stream using 3 threads;551 552</li><li>(line 4) places decoded video side by side with the original input video;553 554</li><li>(line 5) combined video is then losslessly encoded and written into555<samp class="file">OUTPUT</samp>.556 557</li></ul>558 559<p>Such a transcoding pipeline can be represented with the following diagram:560</p><pre class="verbatim">┌──────────┬───────────────┐561│ demuxer │ │ ┌─────────┐ ┌─────────┐ ┌────────────────────┐562╞══════════╡ video stream │ │ video │ │ video │ │ null muxer │563│ INPUT │ ├──►│ decoder ├──┬────────►│ encoder ├─┬─►│(discards its input)│564│ │ │ └─────────┘ │ │(libx264)│ │ └────────────────────┘565└──────────┴───────────────┘ │ └─────────┘ │566 ╭───────◄──╯ ┌─────────┐ │567 │ │loopback │ │568 │ ╭─────◄──────┤ decoder ├────◄──╯569 │ │ └─────────┘570 │ │571 │ │572 │ │ ┌───────────────────┐573 │ │ │complex filtergraph│574 │ │ ╞═══════════════════╡575 │ │ │ ┌─────────────┐ │576 ╰─╫─►├─►│ hstack ├─►├╮577 ╰─►├─►│ │ ││578 │ └─────────────┘ ││579 └───────────────────┘│580 │581┌──────────┬───────────────┐ ┌─────────┐ │582│ muxer │ │ │ video │ │583╞══════════╡ video stream │◄─┤ encoder ├───────◄──────────╯584│ OUTPUT │ │ │ (ffv1) │585│ │ │ └─────────┘586└──────────┴───────────────┘587</pre>588 589 590<a class="anchor" id="Stream-selection"></a><a name="Stream-selection-1"></a>591<h2 class="chapter">4 Stream selection<span class="pull-right"><a class="anchor hidden-xs" href="#Stream-selection-1" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Stream-selection-1" aria-hidden="true">TOC</a></span></h2>592 593<p><code class="command">ffmpeg</code> provides the <code class="code">-map</code> option for manual control of stream selection in each594output file. Users can skip <code class="code">-map</code> and let ffmpeg perform automatic stream selection as595described below. The <code class="code">-vn / -an / -sn / -dn</code> options can be used to skip inclusion of596video, audio, subtitle and data streams respectively, whether manually mapped or automatically597selected, except for those streams which are outputs of complex filtergraphs.598</p>599<a name="Description-1"></a>600<h3 class="section">4.1 Description<span class="pull-right"><a class="anchor hidden-xs" href="#Description-1" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Description-1" aria-hidden="true">TOC</a></span></h3>601<p>The sub-sections that follow describe the various rules that are involved in stream selection.602The examples that follow next show how these rules are applied in practice.603</p>604<p>While every effort is made to accurately reflect the behavior of the program, FFmpeg is under605continuous development and the code may have changed since the time of this writing.606</p>607<a name="Automatic-stream-selection"></a>608<h4 class="subsection">4.1.1 Automatic stream selection<span class="pull-right"><a class="anchor hidden-xs" href="#Automatic-stream-selection" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Automatic-stream-selection" aria-hidden="true">TOC</a></span></h4>609 610<p>In the absence of any map options for a particular output file, ffmpeg inspects the output611format to check which type of streams can be included in it, viz. video, audio and/or612subtitles. For each acceptable stream type, ffmpeg will pick one stream, when available,613from among all the inputs.614</p>615<p>It will select that stream based upon the following criteria:616</p><ul class="itemize mark-bullet">617<li>for video, it is the stream with the highest resolution,618</li><li>for audio, it is the stream with the most channels,619</li><li>for subtitles, it is the first subtitle stream found but there’s a caveat.620The output format’s default subtitle encoder can be either text-based or image-based,621and only a subtitle stream of the same type will be chosen.622</li></ul>623 624<p>In the case where several streams of the same type rate equally, the stream with the lowest625index is chosen.626</p>627<p>Data or attachment streams are not automatically selected and can only be included628using <code class="code">-map</code>.629</p><a name="Manual-stream-selection"></a>630<h4 class="subsection">4.1.2 Manual stream selection<span class="pull-right"><a class="anchor hidden-xs" href="#Manual-stream-selection" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Manual-stream-selection" aria-hidden="true">TOC</a></span></h4>631 632<p>When <code class="code">-map</code> is used, only user-mapped streams are included in that output file,633with one possible exception for filtergraph outputs described below.634</p>635<a name="Complex-filtergraphs-1"></a>636<h4 class="subsection">4.1.3 Complex filtergraphs<span class="pull-right"><a class="anchor hidden-xs" href="#Complex-filtergraphs-1" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Complex-filtergraphs-1" aria-hidden="true">TOC</a></span></h4>637 638<p>If there are any complex filtergraph output streams with unlabeled pads, they will be added639to the first output file. This will lead to a fatal error if the stream type is not supported640by the output format. In the absence of the map option, the inclusion of these streams leads641to the automatic stream selection of their types being skipped. If map options are present,642these filtergraph streams are included in addition to the mapped streams.643</p>644<p>Complex filtergraph output streams with labeled pads must be mapped once and exactly once.645</p>646<a name="Stream-handling"></a>647<h4 class="subsection">4.1.4 Stream handling<span class="pull-right"><a class="anchor hidden-xs" href="#Stream-handling" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Stream-handling" aria-hidden="true">TOC</a></span></h4>648 649<p>Stream handling is independent of stream selection, with an exception for subtitles described650below. Stream handling is set via the <code class="code">-codec</code> option addressed to streams within a651specific <em class="emph">output</em> file. In particular, codec options are applied by ffmpeg after the652stream selection process and thus do not influence the latter. If no <code class="code">-codec</code> option is653specified for a stream type, ffmpeg will select the default encoder registered by the output654file muxer.655</p>656<p>An exception exists for subtitles. If a subtitle encoder is specified for an output file, the657first subtitle stream found of any type, text or image, will be included. ffmpeg does not validate658if the specified encoder can convert the selected stream or if the converted stream is acceptable659within the output format. This applies generally as well: when the user sets an encoder manually,660the stream selection process cannot check if the encoded stream can be muxed into the output file.661If it cannot, ffmpeg will abort and <em class="emph">all</em> output files will fail to be processed.662</p>663<a name="Examples"></a>664<h3 class="section">4.2 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></h3>665 666<p>The following examples illustrate the behavior, quirks and limitations of ffmpeg’s stream667selection methods.668</p>669<p>They assume the following three input files.670</p>671<pre class="verbatim">672input file 'A.avi'673 stream 0: video 640x360674 stream 1: audio 2 channels675 676input file 'B.mp4'677 stream 0: video 1920x1080678 stream 1: audio 2 channels679 stream 2: subtitles (text)680 stream 3: audio 5.1 channels681 stream 4: subtitles (text)682 683input file 'C.mkv'684 stream 0: video 1280x720685 stream 1: audio 2 channels686 stream 2: subtitles (image)687</pre>688<a name="Example_003a-automatic-stream-selection"></a>689<div class="example">690<pre class="example-preformatted">ffmpeg -i A.avi -i B.mp4 out1.mkv out2.wav -map 1:a -c:a copy out3.mov691</pre></div>692<p>There are three output files specified, and for the first two, no <code class="code">-map</code> options693are set, so ffmpeg will select streams for these two files automatically.694</p>695<p><samp class="file">out1.mkv</samp> is a Matroska container file and accepts video, audio and subtitle streams,696so ffmpeg will try to select one of each type.<br>697For video, it will select <code class="code">stream 0</code> from <samp class="file">B.mp4</samp>, which has the highest698resolution among all the input video streams.<br>699For audio, it will select <code class="code">stream 3</code> from <samp class="file">B.mp4</samp>, since it has the greatest700number of channels.<br>701For subtitles, it will select <code class="code">stream 2</code> from <samp class="file">B.mp4</samp>, which is the first subtitle702stream from among <samp class="file">A.avi</samp> and <samp class="file">B.mp4</samp>.703</p>704<p><samp class="file">out2.wav</samp> accepts only audio streams, so only <code class="code">stream 3</code> from <samp class="file">B.mp4</samp> is705selected.706</p>707<p>For <samp class="file">out3.mov</samp>, since a <code class="code">-map</code> option is set, no automatic stream selection will708occur. The <code class="code">-map 1:a</code> option will select all audio streams from the second input709<samp class="file">B.mp4</samp>. No other streams will be included in this output file.710</p>711<p>For the first two outputs, all included streams will be transcoded. The encoders chosen will712be the default ones registered by each output format, which may not match the codec of the713selected input streams.714</p>715<p>For the third output, codec option for audio streams has been set716to <code class="code">copy</code>, so no decoding-filtering-encoding operations will occur, or <em class="emph">can</em> occur.717Packets of selected streams shall be conveyed from the input file and muxed within the output718file.719</p>720<a name="Example_003a-automatic-subtitles-selection"></a>721<div class="example">722<pre class="example-preformatted">ffmpeg -i C.mkv out1.mkv -c:s dvdsub -an out2.mkv723</pre></div>724<p>Although <samp class="file">out1.mkv</samp> is a Matroska container file which accepts subtitle streams, only a725video and audio stream shall be selected. The subtitle stream of <samp class="file">C.mkv</samp> is image-based726and the default subtitle encoder of the Matroska muxer is text-based, so a transcode operation727for the subtitles is expected to fail and hence the stream isn’t selected. However, in728<samp class="file">out2.mkv</samp>, a subtitle encoder is specified in the command and so, the subtitle stream is729selected, in addition to the video stream. The presence of <code class="code">-an</code> disables audio stream730selection for <samp class="file">out2.mkv</samp>.731</p>732<a name="Example_003a-unlabeled-filtergraph-outputs"></a>733<div class="example">734<pre class="example-preformatted">ffmpeg -i A.avi -i C.mkv -i B.mp4 -filter_complex "overlay" out1.mp4 out2.srt735</pre></div>736<p>A filtergraph is setup here using the <code class="code">-filter_complex</code> option and consists of a single737video filter. The <code class="code">overlay</code> filter requires exactly two video inputs, but none are738specified, so the first two available video streams are used, those of <samp class="file">A.avi</samp> and739<samp class="file">C.mkv</samp>. The output pad of the filter has no label and so is sent to the first output file740<samp class="file">out1.mp4</samp>. Due to this, automatic selection of the video stream is skipped, which would741have selected the stream in <samp class="file">B.mp4</samp>. The audio stream with most channels viz. <code class="code">stream 3</code>742in <samp class="file">B.mp4</samp>, is chosen automatically. No subtitle stream is chosen however, since the MP4743format has no default subtitle encoder registered, and the user hasn’t specified a subtitle encoder.744</p>745<p>The 2nd output file, <samp class="file">out2.srt</samp>, only accepts text-based subtitle streams. So, even though746the first subtitle stream available belongs to <samp class="file">C.mkv</samp>, it is image-based and hence skipped.747The selected stream, <code class="code">stream 2</code> in <samp class="file">B.mp4</samp>, is the first text-based subtitle stream.748</p>749<a name="Example_003a-labeled-filtergraph-outputs"></a>750<div class="example">751<pre class="example-preformatted">ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \752 -map '[outv]' -an out1.mp4 \753 out2.mkv \754 -map '[outv]' -map 1:a:0 out3.mkv755</pre></div>756 757<p>The above command will fail, as the output pad labelled <code class="code">[outv]</code> has been mapped twice.758None of the output files shall be processed.759</p>760<div class="example">761<pre class="example-preformatted">ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \762 -an out1.mp4 \763 out2.mkv \764 -map 1:a:0 out3.mkv765</pre></div>766 767<p>This command above will also fail as the hue filter output has a label, <code class="code">[outv]</code>,768and hasn’t been mapped anywhere.769</p>770<p>The command should be modified as follows,771</p><div class="example">772<pre class="example-preformatted">ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0,split=2[outv1][outv2];overlay;aresample" \773 -map '[outv1]' -an out1.mp4 \774 out2.mkv \775 -map '[outv2]' -map 1:a:0 out3.mkv776</pre></div>777<p>The video stream from <samp class="file">B.mp4</samp> is sent to the hue filter, whose output is cloned once using778the split filter, and both outputs labelled. Then a copy each is mapped to the first and third779output files.780</p>781<p>The overlay filter, requiring two video inputs, uses the first two unused video streams. Those782are the streams from <samp class="file">A.avi</samp> and <samp class="file">C.mkv</samp>. The overlay output isn’t labelled, so it is783sent to the first output file <samp class="file">out1.mp4</samp>, regardless of the presence of the <code class="code">-map</code> option.784</p>785<p>The aresample filter is sent the first unused audio stream, that of <samp class="file">A.avi</samp>. Since this filter786output is also unlabelled, it too is mapped to the first output file. The presence of <code class="code">-an</code>787only suppresses automatic or manual stream selection of audio streams, not outputs sent from788filtergraphs. Both these mapped streams shall be ordered before the mapped stream in <samp class="file">out1.mp4</samp>.789</p>790<p>The video, audio and subtitle streams mapped to <code class="code">out2.mkv</code> are entirely determined by791automatic stream selection.792</p>793<p><samp class="file">out3.mkv</samp> consists of the cloned video output from the hue filter and the first audio794stream from <samp class="file">B.mp4</samp>.795<br>796</p>797 798<a name="Options"></a>799<h2 class="chapter">5 Options<span class="pull-right"><a class="anchor hidden-xs" href="#Options" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Options" aria-hidden="true">TOC</a></span></h2>800 801<p>All the numerical options, if not specified otherwise, accept a string802representing a number as input, which may be followed by one of the SI803unit prefixes, for example: ’K’, ’M’, or ’G’.804</p>805<p>If ’i’ is appended to the SI unit prefix, the complete prefix will be806interpreted as a unit prefix for binary multiples, which are based on807powers of 1024 instead of powers of 1000. Appending ’B’ to the SI unit808prefix multiplies the value by 8. This allows using, for example:809’KB’, ’MiB’, ’G’ and ’B’ as number suffixes.810</p>811<p>Options which do not take arguments are boolean options, and set the812corresponding value to true. They can be set to false by prefixing813the option name with "no". For example using "-nofoo"814will set the boolean option with name "foo" to false.815</p>816<p>Options that take arguments support a special syntax where the argument given on817the command line is interpreted as a path to the file from which the actual818argument value is loaded. To use this feature, add a forward slash ’/’819immediately before the option name (after the leading dash). E.g.820</p><div class="example">821<pre class="example-preformatted">ffmpeg -i INPUT -/filter:v filter.script OUTPUT822</pre></div>823<p>will load a filtergraph description from the file named <samp class="file">filter.script</samp>.824</p>825<a class="anchor" id="Stream-specifiers"></a><a name="Stream-specifiers-1"></a>826<h3 class="section">5.1 Stream specifiers<span class="pull-right"><a class="anchor hidden-xs" href="#Stream-specifiers-1" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Stream-specifiers-1" aria-hidden="true">TOC</a></span></h3>827<p>Some options are applied per-stream, e.g. bitrate or codec. Stream specifiers828are used to precisely specify which stream(s) a given option belongs to.829</p>830<p>A stream specifier is a string generally appended to the option name and831separated from it by a colon. E.g. <code class="code">-codec:a:1 ac3</code> contains the832<code class="code">a:1</code> stream specifier, which matches the second audio stream. Therefore, it833would select the ac3 codec for the second audio stream.834</p>835<p>A stream specifier can match several streams, so that the option is applied to all836of them. E.g. the stream specifier in <code class="code">-b:a 128k</code> matches all audio837streams.838</p>839<p>An empty stream specifier matches all streams. For example, <code class="code">-codec copy</code>840or <code class="code">-codec: copy</code> would copy all the streams without reencoding.841</p>842<p>Possible forms of stream specifiers are:843</p><dl class="table">844<dt><samp class="option"><var class="var">stream_index</var></samp></dt>845<dd><p>Matches the stream with this index. E.g. <code class="code">-threads:1 4</code> would set the846thread count for the second stream to 4. If <var class="var">stream_index</var> is used as an847additional stream specifier (see below), then it selects stream number848<var class="var">stream_index</var> from the matching streams. Stream numbering is based on the849order of the streams as detected by libavformat except when a stream group850specifier or program ID is also specified. In this case it is based on the851ordering of the streams in the group or program.852</p></dd>853<dt><samp class="option"><var class="var">stream_type</var>[:<var class="var">additional_stream_specifier</var>]</samp></dt>854<dd><p><var class="var">stream_type</var> is one of following: ’v’ or ’V’ for video, ’a’ for audio, ’s’855for subtitle, ’d’ for data, and ’t’ for attachments. ’v’ matches all video856streams, ’V’ only matches video streams which are not attached pictures, video857thumbnails or cover arts. If <var class="var">additional_stream_specifier</var> is used, then858it matches streams which both have this type and match the859<var class="var">additional_stream_specifier</var>. Otherwise, it matches all streams of the860specified type.861</p></dd>862<dt><samp class="option">g:<var class="var">group_specifier</var>[:<var class="var">additional_stream_specifier</var>]</samp></dt>863<dd><p>Matches streams which are in the group with the specifier <var class="var">group_specifier</var>.864if <var class="var">additional_stream_specifier</var> is used, then it matches streams which both865are part of the group and match the <var class="var">additional_stream_specifier</var>.866<var class="var">group_specifier</var> may be one of the following:867</p><dl class="table">868<dt><samp class="option"><var class="var">group_index</var></samp></dt>869<dd><p>Match the stream with this group index.870</p></dd>871<dt><samp class="option">#<var class="var">group_id</var> or i:<var class="var">group_id</var></samp></dt>872<dd><p>Match the stream with this group id.873</p></dd>874</dl>875</dd>876<dt><samp class="option">p:<var class="var">program_id</var>[:<var class="var">additional_stream_specifier</var>]</samp></dt>877<dd><p>Matches streams which are in the program with the id <var class="var">program_id</var>. If878<var class="var">additional_stream_specifier</var> is used, then it matches streams which both879are part of the program and match the <var class="var">additional_stream_specifier</var>.880</p>881</dd>882<dt><samp class="option">#<var class="var">stream_id</var> or i:<var class="var">stream_id</var></samp></dt>883<dd><p>Match the stream by stream id (e.g. PID in MPEG-TS container).884</p></dd>885<dt><samp class="option">m:<var class="var">key</var>[:<var class="var">value</var>]</samp></dt>886<dd><p>Matches streams with the metadata tag <var class="var">key</var> having the specified value. If887<var class="var">value</var> is not given, matches streams that contain the given tag with any888value. The colon character ’:’ in <var class="var">key</var> or <var class="var">value</var> needs to be889backslash-escaped.890</p></dd>891<dt><samp class="option">disp:<var class="var">dispositions</var>[:<var class="var">additional_stream_specifier</var>]</samp></dt>892<dd><p>Matches streams with the given disposition(s). <var class="var">dispositions</var> is a list of893one or more dispositions (as printed by the <samp class="option">-dispositions</samp> option)894joined with ’+’.895</p></dd>896<dt><samp class="option">u</samp></dt>897<dd><p>Matches streams with usable configuration, the codec must be defined and the898essential information such as video dimension or audio sample rate must be present.899</p>900<p>Note that in <code class="command">ffmpeg</code>, matching by metadata will only work properly for901input files.902</p></dd>903</dl>904 905<a name="Generic-options"></a>906<h3 class="section">5.2 Generic options<span class="pull-right"><a class="anchor hidden-xs" href="#Generic-options" aria-hidden="true">#</a> <a class="anchor hidden-xs"href="#toc-Generic-options" aria-hidden="true">TOC</a></span></h3>907 908<p>These options are shared amongst the ff* tools.909</p>910<dl class="table">911<dt><samp class="option">-L, -license</samp></dt>912<dd><p>Show license.913</p>914</dd>915<dt><samp class="option">-h, -?, -help, --help [<var class="var">arg</var>]</samp></dt>916<dd><p>Show help. An optional parameter may be specified to print help about a specific917item. If no argument is specified, only basic (non advanced) tool918options are shown.919</p>920<p>Possible values of <var class="var">arg</var> are:921</p><dl class="table">922<dt><samp class="option">long</samp></dt>923<dd><p>Print advanced tool options in addition to the basic tool options.924</p>925</dd>926<dt><samp class="option">full</samp></dt>927<dd><p>Print complete list of options, including shared and private options928for encoders, decoders, demuxers, muxers, filters, etc.929</p>930</dd>931<dt><samp class="option">decoder=<var class="var">decoder_name</var></samp></dt>932<dd><p>Print detailed information about the decoder named <var class="var">decoder_name</var>. Use the933<samp class="option">-decoders</samp> option to get a list of all decoders.934</p>935</dd>936<dt><samp class="option">encoder=<var class="var">encoder_name</var></samp></dt>937<dd><p>Print detailed information about the encoder named <var class="var">encoder_name</var>. Use the938<samp class="option">-encoders</samp> option to get a list of all encoders.939</p>940</dd>941<dt><samp class="option">demuxer=<var class="var">demuxer_name</var></samp></dt>942<dd><p>Print detailed information about the demuxer named <var class="var">demuxer_name</var>. Use the943<samp class="option">-formats</samp> option to get a list of all demuxers and muxers.944</p>945</dd>946<dt><samp class="option">muxer=<var class="var">muxer_name</var></samp></dt>947<dd><p>Print detailed information about the muxer named <var class="var">muxer_name</var>. Use the948<samp class="option">-formats</samp> option to get a list of all muxers and demuxers.949</p>950</dd>951<dt><samp class="option">filter=<var class="var">filter_name</var></samp></dt>952<dd><p>Print detailed information about the filter named <var class="var">filter_name</var>. Use the953<samp class="option">-filters</samp> option to get a list of all filters.954</p>955</dd>956<dt><samp class="option">bsf=<var class="var">bitstream_filter_name</var></samp></dt>957<dd><p>Print detailed information about the bitstream filter named <var class="var">bitstream_filter_name</var>.958Use the <samp class="option">-bsfs</samp> option to get a list of all bitstream filters.959</p>960</dd>961<dt><samp class="option">protocol=<var class="var">protocol_name</var></samp></dt>962<dd><p>Print detailed information about the protocol named <var class="var">protocol_name</var>.963Use the <samp class="option">-protocols</samp> option to get a list of all protocols.964</p></dd>965</dl>966 967</dd>968<dt><samp class="option">-version</samp></dt>969<dd><p>Show version.970</p>971</dd>972<dt><samp class="option">-buildconf</samp></dt>973<dd><p>Show the build configuration, one option per line.974</p>975</dd>976<dt><samp class="option">-formats</samp></dt>977<dd><p>Show available formats (including devices).978</p>979</dd>980<dt><samp class="option">-demuxers</samp></dt>981<dd><p>Show available demuxers.982</p>983</dd>984<dt><samp class="option">-muxers</samp></dt>985<dd><p>Show available muxers.986</p>987</dd>988<dt><samp class="option">-devices</samp></dt>989<dd><p>Show available devices.990</p>991</dd>992<dt><samp class="option">-codecs</samp></dt>993<dd><p>Show all codecs known to libavcodec.994</p>995<p>Note that the term ’codec’ is used throughout this documentation as a shortcut996for what is more correctly called a media bitstream format.997</p>998</dd>999<dt><samp class="option">-decoders</samp></dt>1000<dd><p>Show available decoders.1001</p>1002</dd>1003<dt><samp class="option">-encoders</samp></dt>1004<dd><p>Show all available encoders.1005</p>1006</dd>1007<dt><samp class="option">-bsfs</samp></dt>1008<dd><p>Show available bitstream filters.1009</p>1010</dd>1011<dt><samp class="option">-protocols</samp></dt>1012<dd><p>Show available protocols.1013</p>1014</dd>1015<dt><samp class="option">-filters</samp></dt>1016<dd><p>Show available libavfilter filters.1017</p>1018</dd>1019<dt><samp class="option">-pix_fmts</samp></dt>1020<dd><p>Show available pixel formats.1021</p>1022</dd>1023<dt><samp class="option">-sample_fmts</samp></dt>1024<dd><p>Show available sample formats.1025</p>1026</dd>1027<dt><samp class="option">-layouts</samp></dt>1028<dd><p>Show channel names and standard channel layouts.1029</p>1030</dd>1031<dt><samp class="option">-dispositions</samp></dt>1032<dd><p>Show stream dispositions.1033</p>1034</dd>1035<dt><samp class="option">-colors</samp></dt>1036<dd><p>Show recognized color names.1037</p>1038</dd>1039<dt><samp class="option">-sources <var class="var">device</var>[,<var class="var">opt1</var>=<var class="var">val1</var>[,<var class="var">opt2</var>=<var class="var">val2</var>]...]</samp></dt>1040<dd><p>Show autodetected sources of the input device.1041Some devices may provide system-dependent source names that cannot be autodetected.1042The returned list cannot be assumed to be always complete.1043</p><div class="example">1044<pre class="example-preformatted">ffmpeg -sources pulse,server=192.168.0.41045</pre></div>1046 1047</dd>1048<dt><samp class="option">-sinks <var class="var">device</var>[,<var class="var">opt1</var>=<var class="var">val1</var>[,<var class="var">opt2</var>=<var class="var">val2</var>]...]</samp></dt>1049<dd><p>Show autodetected sinks of the output device.1050Some devices may provide system-dependent sink names that cannot be autodetected.1051The returned list cannot be assumed to be always complete.1052</p><div class="example">1053<pre class="example-preformatted">ffmpeg -sinks pulse,server=192.168.0.41054</pre></div>1055 1056</dd>1057<dt><samp class="option">-loglevel [<var class="var">flags</var>+]<var class="var">loglevel</var> | -v [<var class="var">flags</var>+]<var class="var">loglevel</var></samp></dt>1058<dd><p>Set logging level and flags used by the library.1059</p>1060<p>The optional <var class="var">flags</var> prefix can consist of the following values:1061</p><dl class="table">1062<dt>‘<samp class="samp">repeat</samp>’</dt>1063<dd><p>Indicates that repeated log output should not be compressed to the first line1064and the "Last message repeated n times" line will be omitted.1065</p></dd>1066<dt>‘<samp class="samp">level</samp>’</dt>1067<dd><p>Indicates that log output should add a <code class="code">[level]</code> prefix to each message1068line. This can be used as an alternative to log coloring, e.g. when dumping the1069log to file.1070</p></dd>1071<dt>‘<samp class="samp">time</samp>’</dt>1072<dd><p>Indicates that log lines should be prefixed with time information.1073</p></dd>1074<dt>‘<samp class="samp">datetime</samp>’</dt>1075<dd><p>Indicates that log lines should be prefixed with date and time information.1076</p></dd>1077</dl>1078<p>Flags can also be used alone by adding a ’+’/’-’ prefix to set/reset a single1079flag without affecting other <var class="var">flags</var> or changing <var class="var">loglevel</var>. When1080setting both <var class="var">flags</var> and <var class="var">loglevel</var>, a ’+’ separator is expected1081between the last <var class="var">flags</var> value and before <var class="var">loglevel</var>.1082</p>1083<p><var class="var">loglevel</var> is a string or a number containing one of the following values:1084</p><dl class="table">1085<dt>‘<samp class="samp">quiet, -8</samp>’</dt>1086<dd><p>Show nothing at all; be silent.1087</p></dd>1088<dt>‘<samp class="samp">panic, 0</samp>’</dt>1089<dd><p>Only show fatal errors which could lead the process to crash, such as1090an assertion failure. This is not currently used for anything.1091</p></dd>1092<dt>‘<samp class="samp">fatal, 8</samp>’</dt>1093<dd><p>Only show fatal errors. These are errors after which the process absolutely1094cannot continue.1095</p></dd>1096<dt>‘<samp class="samp">error, 16</samp>’</dt>1097<dd><p>Show all errors, including ones which can be recovered from.1098</p></dd>1099<dt>‘<samp class="samp">warning, 24</samp>’</dt>1100<dd><p>Show all warnings and errors. Any message related to possibly1101incorrect or unexpected events will be shown.1102</p></dd>1103<dt>‘<samp class="samp">info, 32</samp>’</dt>1104<dd><p>Show informative messages during processing. This is in addition to1105warnings and errors. This is the default value.1106</p></dd>1107<dt>‘<samp class="samp">verbose, 40</samp>’</dt>1108<dd><p>Same as <code class="code">info</code>, except more verbose.1109</p></dd>1110<dt>‘<samp class="samp">debug, 48</samp>’</dt>1111<dd><p>Show everything, including debugging information.1112</p></dd>1113<dt>‘<samp class="samp">trace, 56</samp>’</dt>1114</dl>1115 1116<p>For example to enable repeated log output, add the <code class="code">level</code> prefix, and set1117<var class="var">loglevel</var> to <code class="code">verbose</code>:1118</p><div class="example">1119<pre class="example-preformatted">ffmpeg -loglevel repeat+level+verbose -i input output1120</pre></div>1121<p>Another example that enables repeated log output without affecting current1122state of <code class="code">level</code> prefix flag or <var class="var">loglevel</var>:1123</p><div class="example">1124<pre class="example-preformatted">ffmpeg [...] -loglevel +repeat1125</pre></div>1126 1127<p>By default the program logs to stderr. If coloring is supported by the1128terminal, colors are used to mark errors and warnings. Log coloring1129can be disabled setting the environment variable1130<code class="env">AV_LOG_FORCE_NOCOLOR</code>, or can be forced setting1131the environment variable <code class="env">AV_LOG_FORCE_COLOR</code>.1132</p>1133</dd>1134<dt><samp class="option">-report</samp></dt>1135<dd><p>Dump full command line and log output to a file named1136<code class="code"><var class="var">program</var>-<var class="var">YYYYMMDD</var>-<var class="var">HHMMSS</var>.log</code> in the current1137directory.1138This file can be useful for bug reports.1139It also implies <code class="code">-loglevel debug</code>.1140</p>1141<p>Setting the environment variable <code class="env">FFREPORT</code> to any value has the1142same effect. If the value is a ’:’-separated key=value sequence, these1143options will affect the report; option values must be escaped if they1144contain special characters or the options delimiter ’:’ (see the1145“Quoting and escaping” section in the ffmpeg-utils manual).1146</p>1147<p>The following options are recognized:1148</p><dl class="table">1149<dt><samp class="option">file</samp></dt>1150<dd><p>set the file name to use for the report; <code class="code">%p</code> is expanded to the name1151of the program, <code class="code">%t</code> is expanded to a timestamp, <code class="code">%%</code> is expanded1152to a plain <code class="code">%</code>1153</p></dd>1154<dt><samp class="option">level</samp></dt>1155<dd><p>set the log verbosity level using a numerical value (see <code class="code">-loglevel</code>).1156</p></dd>1157</dl>1158 1159<p>For example, to output a report to a file named <samp class="file">ffreport.log</samp>1160using a log level of <code class="code">32</code> (alias for log level <code class="code">info</code>):1161</p>1162<div class="example">1163<pre class="example-preformatted">FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output1164</pre></div>1165 1166<p>Errors in parsing the environment variable are not fatal, and will not1167appear in the report.1168</p>1169</dd>1170<dt><samp class="option">-hide_banner</samp></dt>1171<dd><p>Suppress printing banner.1172</p>1173<p>All FFmpeg tools will normally show a copyright notice, build options1174and library versions. This option can be used to suppress printing1175this information.1176</p>1177</dd>1178<dt><samp class="option">-cpuflags flags (<em class="emph">global</em>)</samp></dt>1179<dd><p>Allows setting and clearing cpu flags. This option is intended1180for testing. Do not use it unless you know what you’re doing.1181</p><div class="example">1182<pre class="example-preformatted">ffmpeg -cpuflags -sse+mmx ...1183ffmpeg -cpuflags mmx ...1184ffmpeg -cpuflags 0 ...1185</pre></div>1186<p>Possible flags for this option are:1187</p><dl class="table">1188<dt>‘<samp class="samp">x86</samp>’</dt>1189<dd><dl class="table">1190<dt>‘<samp class="samp">mmx</samp>’</dt>1191<dt>‘<samp class="samp">mmxext</samp>’</dt>1192<dt>‘<samp class="samp">sse</samp>’</dt>1193<dt>‘<samp class="samp">sse2</samp>’</dt>1194<dt>‘<samp class="samp">sse2slow</samp>’</dt>1195<dt>‘<samp class="samp">sse3</samp>’</dt>1196<dt>‘<samp class="samp">sse3slow</samp>’</dt>1197<dt>‘<samp class="samp">ssse3</samp>’</dt>1198<dt>‘<samp class="samp">atom</samp>’</dt>1199<dt>‘<samp class="samp">sse4.1</samp>’</dt>1200<dt>‘<samp class="samp">sse4.2</samp>’</dt>