ffmpeg.texi 100 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593
  1. \input texinfo @c -*- texinfo -*-
  2. @documentencoding UTF-8
  3. @settitle ffmpeg Documentation
  4. @titlepage
  5. @center @titlefont{ffmpeg Documentation}
  6. @end titlepage
  7. @top
  8. @contents
  9. @chapter Synopsis
  10. ffmpeg [@var{global_options}] @{[@var{input_file_options}] -i @file{input_url}@} ... @{[@var{output_file_options}] @file{output_url}@} ...
  11. @chapter Description
  12. @c man begin DESCRIPTION
  13. @command{ffmpeg} is a universal media converter. It can read a wide variety of
  14. inputs - including live grabbing/recording devices - filter, and transcode them
  15. into a plethora of output formats.
  16. @command{ffmpeg} reads from an arbitrary number of input "files" (which can be regular
  17. files, pipes, network streams, grabbing devices, etc.), specified by the
  18. @code{-i} option, and writes to an arbitrary number of output "files", which are
  19. specified by a plain output url. Anything found on the command line which
  20. cannot be interpreted as an option is considered to be an output url.
  21. Each input or output url can, in principle, contain any number of streams of
  22. different types (video/audio/subtitle/attachment/data). The allowed number and/or
  23. types of streams may be limited by the container format. Selecting which
  24. streams from which inputs will go into which output is either done automatically
  25. or with the @code{-map} option (see the Stream selection chapter).
  26. To refer to input files in options, you must use their indices (0-based). E.g.
  27. the first input file is @code{0}, the second is @code{1}, etc. Similarly, streams
  28. within a file are referred to by their indices. E.g. @code{2:3} refers to the
  29. fourth stream in the third input file. Also see the Stream specifiers chapter.
  30. As a general rule, options are applied to the next specified
  31. file. Therefore, order is important, and you can have the same
  32. option on the command line multiple times. Each occurrence is
  33. then applied to the next input or output file.
  34. Exceptions from this rule are the global options (e.g. verbosity level),
  35. which should be specified first.
  36. Do not mix input and output files -- first specify all input files, then all
  37. output files. Also do not mix options which belong to different files. All
  38. options apply ONLY to the next input or output file and are reset between files.
  39. Some simple examples follow.
  40. @itemize
  41. @item
  42. Convert an input media file to a different format, by re-encoding media streams:
  43. @example
  44. ffmpeg -i input.avi output.mp4
  45. @end example
  46. @item
  47. Set the video bitrate of the output file to 64 kbit/s:
  48. @example
  49. ffmpeg -i input.avi -b:v 64k -bufsize 64k output.mp4
  50. @end example
  51. @item
  52. Force the frame rate of the output file to 24 fps:
  53. @example
  54. ffmpeg -i input.avi -r 24 output.mp4
  55. @end example
  56. @item
  57. Force the frame rate of the input file (valid for raw formats only) to 1 fps and
  58. the frame rate of the output file to 24 fps:
  59. @example
  60. ffmpeg -r 1 -i input.m2v -r 24 output.mp4
  61. @end example
  62. @end itemize
  63. The format option may be needed for raw input files.
  64. @c man end DESCRIPTION
  65. @chapter Detailed description
  66. @c man begin DETAILED DESCRIPTION
  67. The transcoding process in @command{ffmpeg} for each output can be described by
  68. the following diagram:
  69. @verbatim
  70. _______ ______________
  71. | | | |
  72. | input | demuxer | encoded data | decoder
  73. | file | ---------> | packets | -----+
  74. |_______| |______________| |
  75. v
  76. _________
  77. | |
  78. | decoded |
  79. | frames |
  80. |_________|
  81. ________ ______________ |
  82. | | | | |
  83. | output | <-------- | encoded data | <----+
  84. | file | muxer | packets | encoder
  85. |________| |______________|
  86. @end verbatim
  87. @command{ffmpeg} calls the libavformat library (containing demuxers) to read
  88. input files and get packets containing encoded data from them. When there are
  89. multiple input files, @command{ffmpeg} tries to keep them synchronized by
  90. tracking lowest timestamp on any active input stream.
  91. Encoded packets are then passed to the decoder (unless streamcopy is selected
  92. for the stream, see further for a description). The decoder produces
  93. uncompressed frames (raw video/PCM audio/...) which can be processed further by
  94. filtering (see next section). After filtering, the frames are passed to the
  95. encoder, which encodes them and outputs encoded packets. Finally those are
  96. passed to the muxer, which writes the encoded packets to the output file.
  97. @section Filtering
  98. Before encoding, @command{ffmpeg} can process raw audio and video frames using
  99. filters from the libavfilter library. Several chained filters form a filter
  100. graph. @command{ffmpeg} distinguishes between two types of filtergraphs:
  101. simple and complex.
  102. @subsection Simple filtergraphs
  103. Simple filtergraphs are those that have exactly one input and output, both of
  104. the same type. In the above diagram they can be represented by simply inserting
  105. an additional step between decoding and encoding:
  106. @verbatim
  107. _________ ______________
  108. | | | |
  109. | decoded | | encoded data |
  110. | frames |\ _ | packets |
  111. |_________| \ /||______________|
  112. \ __________ /
  113. simple _\|| | / encoder
  114. filtergraph | filtered |/
  115. | frames |
  116. |__________|
  117. @end verbatim
  118. Simple filtergraphs are configured with the per-stream @option{-filter} option
  119. (with @option{-vf} and @option{-af} aliases for video and audio respectively).
  120. A simple filtergraph for video can look for example like this:
  121. @verbatim
  122. _______ _____________ _______ ________
  123. | | | | | | | |
  124. | input | ---> | deinterlace | ---> | scale | ---> | output |
  125. |_______| |_____________| |_______| |________|
  126. @end verbatim
  127. Note that some filters change frame properties but not frame contents. E.g. the
  128. @code{fps} filter in the example above changes number of frames, but does not
  129. touch the frame contents. Another example is the @code{setpts} filter, which
  130. only sets timestamps and otherwise passes the frames unchanged.
  131. @subsection Complex filtergraphs
  132. Complex filtergraphs are those which cannot be described as simply a linear
  133. processing chain applied to one stream. This is the case, for example, when the graph has
  134. more than one input and/or output, or when output stream type is different from
  135. input. They can be represented with the following diagram:
  136. @verbatim
  137. _________
  138. | |
  139. | input 0 |\ __________
  140. |_________| \ | |
  141. \ _________ /| output 0 |
  142. \ | | / |__________|
  143. _________ \| complex | /
  144. | | | |/
  145. | input 1 |---->| filter |\
  146. |_________| | | \ __________
  147. /| graph | \ | |
  148. / | | \| output 1 |
  149. _________ / |_________| |__________|
  150. | | /
  151. | input 2 |/
  152. |_________|
  153. @end verbatim
  154. Complex filtergraphs are configured with the @option{-filter_complex} option.
  155. Note that this option is global, since a complex filtergraph, by its nature,
  156. cannot be unambiguously associated with a single stream or file.
  157. The @option{-lavfi} option is equivalent to @option{-filter_complex}.
  158. A trivial example of a complex filtergraph is the @code{overlay} filter, which
  159. has two video inputs and one video output, containing one video overlaid on top
  160. of the other. Its audio counterpart is the @code{amix} filter.
  161. @section Stream copy
  162. Stream copy is a mode selected by supplying the @code{copy} parameter to the
  163. @option{-codec} option. It makes @command{ffmpeg} omit the decoding and encoding
  164. step for the specified stream, so it does only demuxing and muxing. It is useful
  165. for changing the container format or modifying container-level metadata. The
  166. diagram above will, in this case, simplify to this:
  167. @verbatim
  168. _______ ______________ ________
  169. | | | | | |
  170. | input | demuxer | encoded data | muxer | output |
  171. | file | ---------> | packets | -------> | file |
  172. |_______| |______________| |________|
  173. @end verbatim
  174. Since there is no decoding or encoding, it is very fast and there is no quality
  175. loss. However, it might not work in some cases because of many factors. Applying
  176. filters is obviously also impossible, since filters work on uncompressed data.
  177. @c man end DETAILED DESCRIPTION
  178. @chapter Stream selection
  179. @c man begin STREAM SELECTION
  180. @command{ffmpeg} provides the @code{-map} option for manual control of stream selection in each
  181. output file. Users can skip @code{-map} and let ffmpeg perform automatic stream selection as
  182. described below. The @code{-vn / -an / -sn / -dn} options can be used to skip inclusion of
  183. video, audio, subtitle and data streams respectively, whether manually mapped or automatically
  184. selected, except for those streams which are outputs of complex filtergraphs.
  185. @section Description
  186. The sub-sections that follow describe the various rules that are involved in stream selection.
  187. The examples that follow next show how these rules are applied in practice.
  188. While every effort is made to accurately reflect the behavior of the program, FFmpeg is under
  189. continuous development and the code may have changed since the time of this writing.
  190. @subsection Automatic stream selection
  191. In the absence of any map options for a particular output file, ffmpeg inspects the output
  192. format to check which type of streams can be included in it, viz. video, audio and/or
  193. subtitles. For each acceptable stream type, ffmpeg will pick one stream, when available,
  194. from among all the inputs.
  195. It will select that stream based upon the following criteria:
  196. @itemize
  197. @item
  198. for video, it is the stream with the highest resolution,
  199. @item
  200. for audio, it is the stream with the most channels,
  201. @item
  202. for subtitles, it is the first subtitle stream found but there's a caveat.
  203. The output format's default subtitle encoder can be either text-based or image-based,
  204. and only a subtitle stream of the same type will be chosen.
  205. @end itemize
  206. In the case where several streams of the same type rate equally, the stream with the lowest
  207. index is chosen.
  208. Data or attachment streams are not automatically selected and can only be included
  209. using @code{-map}.
  210. @subsection Manual stream selection
  211. When @code{-map} is used, only user-mapped streams are included in that output file,
  212. with one possible exception for filtergraph outputs described below.
  213. @subsection Complex filtergraphs
  214. If there are any complex filtergraph output streams with unlabeled pads, they will be added
  215. to the first output file. This will lead to a fatal error if the stream type is not supported
  216. by the output format. In the absence of the map option, the inclusion of these streams leads
  217. to the automatic stream selection of their types being skipped. If map options are present,
  218. these filtergraph streams are included in addition to the mapped streams.
  219. Complex filtergraph output streams with labeled pads must be mapped once and exactly once.
  220. @subsection Stream handling
  221. Stream handling is independent of stream selection, with an exception for subtitles described
  222. below. Stream handling is set via the @code{-codec} option addressed to streams within a
  223. specific @emph{output} file. In particular, codec options are applied by ffmpeg after the
  224. stream selection process and thus do not influence the latter. If no @code{-codec} option is
  225. specified for a stream type, ffmpeg will select the default encoder registered by the output
  226. file muxer.
  227. An exception exists for subtitles. If a subtitle encoder is specified for an output file, the
  228. first subtitle stream found of any type, text or image, will be included. ffmpeg does not validate
  229. if the specified encoder can convert the selected stream or if the converted stream is acceptable
  230. within the output format. This applies generally as well: when the user sets an encoder manually,
  231. the stream selection process cannot check if the encoded stream can be muxed into the output file.
  232. If it cannot, ffmpeg will abort and @emph{all} output files will fail to be processed.
  233. @section Examples
  234. The following examples illustrate the behavior, quirks and limitations of ffmpeg's stream
  235. selection methods.
  236. They assume the following three input files.
  237. @verbatim
  238. input file 'A.avi'
  239. stream 0: video 640x360
  240. stream 1: audio 2 channels
  241. input file 'B.mp4'
  242. stream 0: video 1920x1080
  243. stream 1: audio 2 channels
  244. stream 2: subtitles (text)
  245. stream 3: audio 5.1 channels
  246. stream 4: subtitles (text)
  247. input file 'C.mkv'
  248. stream 0: video 1280x720
  249. stream 1: audio 2 channels
  250. stream 2: subtitles (image)
  251. @end verbatim
  252. @subsubheading Example: automatic stream selection
  253. @example
  254. ffmpeg -i A.avi -i B.mp4 out1.mkv out2.wav -map 1:a -c:a copy out3.mov
  255. @end example
  256. There are three output files specified, and for the first two, no @code{-map} options
  257. are set, so ffmpeg will select streams for these two files automatically.
  258. @file{out1.mkv} is a Matroska container file and accepts video, audio and subtitle streams,
  259. so ffmpeg will try to select one of each type.@*
  260. For video, it will select @code{stream 0} from @file{B.mp4}, which has the highest
  261. resolution among all the input video streams.@*
  262. For audio, it will select @code{stream 3} from @file{B.mp4}, since it has the greatest
  263. number of channels.@*
  264. For subtitles, it will select @code{stream 2} from @file{B.mp4}, which is the first subtitle
  265. stream from among @file{A.avi} and @file{B.mp4}.
  266. @file{out2.wav} accepts only audio streams, so only @code{stream 3} from @file{B.mp4} is
  267. selected.
  268. For @file{out3.mov}, since a @code{-map} option is set, no automatic stream selection will
  269. occur. The @code{-map 1:a} option will select all audio streams from the second input
  270. @file{B.mp4}. No other streams will be included in this output file.
  271. For the first two outputs, all included streams will be transcoded. The encoders chosen will
  272. be the default ones registered by each output format, which may not match the codec of the
  273. selected input streams.
  274. For the third output, codec option for audio streams has been set
  275. to @code{copy}, so no decoding-filtering-encoding operations will occur, or @emph{can} occur.
  276. Packets of selected streams shall be conveyed from the input file and muxed within the output
  277. file.
  278. @subsubheading Example: automatic subtitles selection
  279. @example
  280. ffmpeg -i C.mkv out1.mkv -c:s dvdsub -an out2.mkv
  281. @end example
  282. Although @file{out1.mkv} is a Matroska container file which accepts subtitle streams, only a
  283. video and audio stream shall be selected. The subtitle stream of @file{C.mkv} is image-based
  284. and the default subtitle encoder of the Matroska muxer is text-based, so a transcode operation
  285. for the subtitles is expected to fail and hence the stream isn't selected. However, in
  286. @file{out2.mkv}, a subtitle encoder is specified in the command and so, the subtitle stream is
  287. selected, in addition to the video stream. The presence of @code{-an} disables audio stream
  288. selection for @file{out2.mkv}.
  289. @subsubheading Example: unlabeled filtergraph outputs
  290. @example
  291. ffmpeg -i A.avi -i C.mkv -i B.mp4 -filter_complex "overlay" out1.mp4 out2.srt
  292. @end example
  293. A filtergraph is setup here using the @code{-filter_complex} option and consists of a single
  294. video filter. The @code{overlay} filter requires exactly two video inputs, but none are
  295. specified, so the first two available video streams are used, those of @file{A.avi} and
  296. @file{C.mkv}. The output pad of the filter has no label and so is sent to the first output file
  297. @file{out1.mp4}. Due to this, automatic selection of the video stream is skipped, which would
  298. have selected the stream in @file{B.mp4}. The audio stream with most channels viz. @code{stream 3}
  299. in @file{B.mp4}, is chosen automatically. No subtitle stream is chosen however, since the MP4
  300. format has no default subtitle encoder registered, and the user hasn't specified a subtitle encoder.
  301. The 2nd output file, @file{out2.srt}, only accepts text-based subtitle streams. So, even though
  302. the first subtitle stream available belongs to @file{C.mkv}, it is image-based and hence skipped.
  303. The selected stream, @code{stream 2} in @file{B.mp4}, is the first text-based subtitle stream.
  304. @subsubheading Example: labeled filtergraph outputs
  305. @example
  306. ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
  307. -map '[outv]' -an out1.mp4 \
  308. out2.mkv \
  309. -map '[outv]' -map 1:a:0 out3.mkv
  310. @end example
  311. The above command will fail, as the output pad labelled @code{[outv]} has been mapped twice.
  312. None of the output files shall be processed.
  313. @example
  314. ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
  315. -an out1.mp4 \
  316. out2.mkv \
  317. -map 1:a:0 out3.mkv
  318. @end example
  319. This command above will also fail as the hue filter output has a label, @code{[outv]},
  320. and hasn't been mapped anywhere.
  321. The command should be modified as follows,
  322. @example
  323. ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0,split=2[outv1][outv2];overlay;aresample" \
  324. -map '[outv1]' -an out1.mp4 \
  325. out2.mkv \
  326. -map '[outv2]' -map 1:a:0 out3.mkv
  327. @end example
  328. The video stream from @file{B.mp4} is sent to the hue filter, whose output is cloned once using
  329. the split filter, and both outputs labelled. Then a copy each is mapped to the first and third
  330. output files.
  331. The overlay filter, requiring two video inputs, uses the first two unused video streams. Those
  332. are the streams from @file{A.avi} and @file{C.mkv}. The overlay output isn't labelled, so it is
  333. sent to the first output file @file{out1.mp4}, regardless of the presence of the @code{-map} option.
  334. The aresample filter is sent the first unused audio stream, that of @file{A.avi}. Since this filter
  335. output is also unlabelled, it too is mapped to the first output file. The presence of @code{-an}
  336. only suppresses automatic or manual stream selection of audio streams, not outputs sent from
  337. filtergraphs. Both these mapped streams shall be ordered before the mapped stream in @file{out1.mp4}.
  338. The video, audio and subtitle streams mapped to @code{out2.mkv} are entirely determined by
  339. automatic stream selection.
  340. @file{out3.mkv} consists of the cloned video output from the hue filter and the first audio
  341. stream from @file{B.mp4}.
  342. @*
  343. @c man end STREAM SELECTION
  344. @chapter Options
  345. @c man begin OPTIONS
  346. @include fftools-common-opts.texi
  347. @section Main options
  348. @table @option
  349. @item -f @var{fmt} (@emph{input/output})
  350. Force input or output file format. The format is normally auto detected for input
  351. files and guessed from the file extension for output files, so this option is not
  352. needed in most cases.
  353. @item -i @var{url} (@emph{input})
  354. input file url
  355. @item -y (@emph{global})
  356. Overwrite output files without asking.
  357. @item -n (@emph{global})
  358. Do not overwrite output files, and exit immediately if a specified
  359. output file already exists.
  360. @item -stream_loop @var{number} (@emph{input})
  361. Set number of times input stream shall be looped. Loop 0 means no loop,
  362. loop -1 means infinite loop.
  363. @item -recast_media (@emph{global})
  364. Allow forcing a decoder of a different media type than the one
  365. detected or designated by the demuxer. Useful for decoding media
  366. data muxed as data streams.
  367. @item -c[:@var{stream_specifier}] @var{codec} (@emph{input/output,per-stream})
  368. @itemx -codec[:@var{stream_specifier}] @var{codec} (@emph{input/output,per-stream})
  369. Select an encoder (when used before an output file) or a decoder (when used
  370. before an input file) for one or more streams. @var{codec} is the name of a
  371. decoder/encoder or a special value @code{copy} (output only) to indicate that
  372. the stream is not to be re-encoded.
  373. For example
  374. @example
  375. ffmpeg -i INPUT -map 0 -c:v libx264 -c:a copy OUTPUT
  376. @end example
  377. encodes all video streams with libx264 and copies all audio streams.
  378. For each stream, the last matching @code{c} option is applied, so
  379. @example
  380. ffmpeg -i INPUT -map 0 -c copy -c:v:1 libx264 -c:a:137 libvorbis OUTPUT
  381. @end example
  382. will copy all the streams except the second video, which will be encoded with
  383. libx264, and the 138th audio, which will be encoded with libvorbis.
  384. @item -t @var{duration} (@emph{input/output})
  385. When used as an input option (before @code{-i}), limit the @var{duration} of
  386. data read from the input file.
  387. When used as an output option (before an output url), stop writing the
  388. output after its duration reaches @var{duration}.
  389. @var{duration} must be a time duration specification,
  390. see @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
  391. -to and -t are mutually exclusive and -t has priority.
  392. @item -to @var{position} (@emph{input/output})
  393. Stop writing the output or reading the input at @var{position}.
  394. @var{position} must be a time duration specification,
  395. see @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
  396. -to and -t are mutually exclusive and -t has priority.
  397. @item -fs @var{limit_size} (@emph{output})
  398. Set the file size limit, expressed in bytes. No further chunk of bytes is written
  399. after the limit is exceeded. The size of the output file is slightly more than the
  400. requested file size.
  401. @item -ss @var{position} (@emph{input/output})
  402. When used as an input option (before @code{-i}), seeks in this input file to
  403. @var{position}. Note that in most formats it is not possible to seek exactly,
  404. so @command{ffmpeg} will seek to the closest seek point before @var{position}.
  405. When transcoding and @option{-accurate_seek} is enabled (the default), this
  406. extra segment between the seek point and @var{position} will be decoded and
  407. discarded. When doing stream copy or when @option{-noaccurate_seek} is used, it
  408. will be preserved.
  409. When used as an output option (before an output url), decodes but discards
  410. input until the timestamps reach @var{position}.
  411. @var{position} must be a time duration specification,
  412. see @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
  413. @item -sseof @var{position} (@emph{input})
  414. Like the @code{-ss} option but relative to the "end of file". That is negative
  415. values are earlier in the file, 0 is at EOF.
  416. @item -isync @var{input_index} (@emph{input})
  417. Assign an input as a sync source.
  418. This will take the difference between the start times of the target and reference inputs and
  419. offset the timestamps of the target file by that difference. The source timestamps of the two
  420. inputs should derive from the same clock source for expected results. If @code{copyts} is set
  421. then @code{start_at_zero} must also be set. If either of the inputs has no starting timestamp
  422. then no sync adjustment is made.
  423. Acceptable values are those that refer to a valid ffmpeg input index. If the sync reference is
  424. the target index itself or @var{-1}, then no adjustment is made to target timestamps. A sync
  425. reference may not itself be synced to any other input.
  426. Default value is @var{-1}.
  427. @item -itsoffset @var{offset} (@emph{input})
  428. Set the input time offset.
  429. @var{offset} must be a time duration specification,
  430. see @ref{time duration syntax,,the Time duration section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
  431. The offset is added to the timestamps of the input files. Specifying
  432. a positive offset means that the corresponding streams are delayed by
  433. the time duration specified in @var{offset}.
  434. @item -itsscale @var{scale} (@emph{input,per-stream})
  435. Rescale input timestamps. @var{scale} should be a floating point number.
  436. @item -timestamp @var{date} (@emph{output})
  437. Set the recording timestamp in the container.
  438. @var{date} must be a date specification,
  439. see @ref{date syntax,,the Date section in the ffmpeg-utils(1) manual,ffmpeg-utils}.
  440. @item -metadata[:metadata_specifier] @var{key}=@var{value} (@emph{output,per-metadata})
  441. Set a metadata key/value pair.
  442. An optional @var{metadata_specifier} may be given to set metadata
  443. on streams, chapters or programs. See @code{-map_metadata}
  444. documentation for details.
  445. This option overrides metadata set with @code{-map_metadata}. It is
  446. also possible to delete metadata by using an empty value.
  447. For example, for setting the title in the output file:
  448. @example
  449. ffmpeg -i in.avi -metadata title="my title" out.flv
  450. @end example
  451. To set the language of the first audio stream:
  452. @example
  453. ffmpeg -i INPUT -metadata:s:a:0 language=eng OUTPUT
  454. @end example
  455. @item -disposition[:stream_specifier] @var{value} (@emph{output,per-stream})
  456. Sets the disposition for a stream.
  457. By default, the disposition is copied from the input stream, unless the output
  458. stream this option applies to is fed by a complex filtergraph - in that case the
  459. disposition is unset by default.
  460. @var{value} is a sequence of items separated by '+' or '-'. The first item may
  461. also be prefixed with '+' or '-', in which case this option modifies the default
  462. value. Otherwise (the first item is not prefixed) this options overrides the
  463. default value. A '+' prefix adds the given disposition, '-' removes it. It is
  464. also possible to clear the disposition by setting it to 0.
  465. If no @code{-disposition} options were specified for an output file, ffmpeg will
  466. automatically set the 'default' disposition on the first stream of each type,
  467. when there are multiple streams of this type in the output file and no stream of
  468. that type is already marked as default.
  469. The @code{-dispositions} option lists the known dispositions.
  470. For example, to make the second audio stream the default stream:
  471. @example
  472. ffmpeg -i in.mkv -c copy -disposition:a:1 default out.mkv
  473. @end example
  474. To make the second subtitle stream the default stream and remove the default
  475. disposition from the first subtitle stream:
  476. @example
  477. ffmpeg -i in.mkv -c copy -disposition:s:0 0 -disposition:s:1 default out.mkv
  478. @end example
  479. To add an embedded cover/thumbnail:
  480. @example
  481. ffmpeg -i in.mp4 -i IMAGE -map 0 -map 1 -c copy -c:v:1 png -disposition:v:1 attached_pic out.mp4
  482. @end example
  483. Not all muxers support embedded thumbnails, and those who do, only support a few formats, like JPEG or PNG.
  484. @item -program [title=@var{title}:][program_num=@var{program_num}:]st=@var{stream}[:st=@var{stream}...] (@emph{output})
  485. Creates a program with the specified @var{title}, @var{program_num} and adds the specified
  486. @var{stream}(s) to it.
  487. @item -target @var{type} (@emph{output})
  488. Specify target file type (@code{vcd}, @code{svcd}, @code{dvd}, @code{dv},
  489. @code{dv50}). @var{type} may be prefixed with @code{pal-}, @code{ntsc-} or
  490. @code{film-} to use the corresponding standard. All the format options
  491. (bitrate, codecs, buffer sizes) are then set automatically. You can just type:
  492. @example
  493. ffmpeg -i myfile.avi -target vcd /tmp/vcd.mpg
  494. @end example
  495. Nevertheless you can specify additional options as long as you know
  496. they do not conflict with the standard, as in:
  497. @example
  498. ffmpeg -i myfile.avi -target vcd -bf 2 /tmp/vcd.mpg
  499. @end example
  500. The parameters set for each target are as follows.
  501. @strong{VCD}
  502. @example
  503. @var{pal}:
  504. -f vcd -muxrate 1411200 -muxpreload 0.44 -packetsize 2324
  505. -s 352x288 -r 25
  506. -codec:v mpeg1video -g 15 -b:v 1150k -maxrate:v 1150k -minrate:v 1150k -bufsize:v 327680
  507. -ar 44100 -ac 2
  508. -codec:a mp2 -b:a 224k
  509. @var{ntsc}:
  510. -f vcd -muxrate 1411200 -muxpreload 0.44 -packetsize 2324
  511. -s 352x240 -r 30000/1001
  512. -codec:v mpeg1video -g 18 -b:v 1150k -maxrate:v 1150k -minrate:v 1150k -bufsize:v 327680
  513. -ar 44100 -ac 2
  514. -codec:a mp2 -b:a 224k
  515. @var{film}:
  516. -f vcd -muxrate 1411200 -muxpreload 0.44 -packetsize 2324
  517. -s 352x240 -r 24000/1001
  518. -codec:v mpeg1video -g 18 -b:v 1150k -maxrate:v 1150k -minrate:v 1150k -bufsize:v 327680
  519. -ar 44100 -ac 2
  520. -codec:a mp2 -b:a 224k
  521. @end example
  522. @strong{SVCD}
  523. @example
  524. @var{pal}:
  525. -f svcd -packetsize 2324
  526. -s 480x576 -pix_fmt yuv420p -r 25
  527. -codec:v mpeg2video -g 15 -b:v 2040k -maxrate:v 2516k -minrate:v 0 -bufsize:v 1835008 -scan_offset 1
  528. -ar 44100
  529. -codec:a mp2 -b:a 224k
  530. @var{ntsc}:
  531. -f svcd -packetsize 2324
  532. -s 480x480 -pix_fmt yuv420p -r 30000/1001
  533. -codec:v mpeg2video -g 18 -b:v 2040k -maxrate:v 2516k -minrate:v 0 -bufsize:v 1835008 -scan_offset 1
  534. -ar 44100
  535. -codec:a mp2 -b:a 224k
  536. @var{film}:
  537. -f svcd -packetsize 2324
  538. -s 480x480 -pix_fmt yuv420p -r 24000/1001
  539. -codec:v mpeg2video -g 18 -b:v 2040k -maxrate:v 2516k -minrate:v 0 -bufsize:v 1835008 -scan_offset 1
  540. -ar 44100
  541. -codec:a mp2 -b:a 224k
  542. @end example
  543. @strong{DVD}
  544. @example
  545. @var{pal}:
  546. -f dvd -muxrate 10080k -packetsize 2048
  547. -s 720x576 -pix_fmt yuv420p -r 25
  548. -codec:v mpeg2video -g 15 -b:v 6000k -maxrate:v 9000k -minrate:v 0 -bufsize:v 1835008
  549. -ar 48000
  550. -codec:a ac3 -b:a 448k
  551. @var{ntsc}:
  552. -f dvd -muxrate 10080k -packetsize 2048
  553. -s 720x480 -pix_fmt yuv420p -r 30000/1001
  554. -codec:v mpeg2video -g 18 -b:v 6000k -maxrate:v 9000k -minrate:v 0 -bufsize:v 1835008
  555. -ar 48000
  556. -codec:a ac3 -b:a 448k
  557. @var{film}:
  558. -f dvd -muxrate 10080k -packetsize 2048
  559. -s 720x480 -pix_fmt yuv420p -r 24000/1001
  560. -codec:v mpeg2video -g 18 -b:v 6000k -maxrate:v 9000k -minrate:v 0 -bufsize:v 1835008
  561. -ar 48000
  562. -codec:a ac3 -b:a 448k
  563. @end example
  564. @strong{DV}
  565. @example
  566. @var{pal}:
  567. -f dv
  568. -s 720x576 -pix_fmt yuv420p -r 25
  569. -ar 48000 -ac 2
  570. @var{ntsc}:
  571. -f dv
  572. -s 720x480 -pix_fmt yuv411p -r 30000/1001
  573. -ar 48000 -ac 2
  574. @var{film}:
  575. -f dv
  576. -s 720x480 -pix_fmt yuv411p -r 24000/1001
  577. -ar 48000 -ac 2
  578. @end example
  579. The @code{dv50} target is identical to the @code{dv} target except that the pixel format set is @code{yuv422p} for all three standards.
  580. Any user-set value for a parameter above will override the target preset value. In that case, the output may
  581. not comply with the target standard.
  582. @item -dn (@emph{input/output})
  583. As an input option, blocks all data streams of a file from being filtered or
  584. being automatically selected or mapped for any output. See @code{-discard}
  585. option to disable streams individually.
  586. As an output option, disables data recording i.e. automatic selection or
  587. mapping of any data stream. For full manual control see the @code{-map}
  588. option.
  589. @item -dframes @var{number} (@emph{output})
  590. Set the number of data frames to output. This is an obsolete alias for
  591. @code{-frames:d}, which you should use instead.
  592. @item -frames[:@var{stream_specifier}] @var{framecount} (@emph{output,per-stream})
  593. Stop writing to the stream after @var{framecount} frames.
  594. @item -q[:@var{stream_specifier}] @var{q} (@emph{output,per-stream})
  595. @itemx -qscale[:@var{stream_specifier}] @var{q} (@emph{output,per-stream})
  596. Use fixed quality scale (VBR). The meaning of @var{q}/@var{qscale} is
  597. codec-dependent.
  598. If @var{qscale} is used without a @var{stream_specifier} then it applies only
  599. to the video stream, this is to maintain compatibility with previous behavior
  600. and as specifying the same codec specific value to 2 different codecs that is
  601. audio and video generally is not what is intended when no stream_specifier is
  602. used.
  603. @anchor{filter_option}
  604. @item -filter[:@var{stream_specifier}] @var{filtergraph} (@emph{output,per-stream})
  605. Create the filtergraph specified by @var{filtergraph} and use it to
  606. filter the stream.
  607. @var{filtergraph} is a description of the filtergraph to apply to
  608. the stream, and must have a single input and a single output of the
  609. same type of the stream. In the filtergraph, the input is associated
  610. to the label @code{in}, and the output to the label @code{out}. See
  611. the ffmpeg-filters manual for more information about the filtergraph
  612. syntax.
  613. See the @ref{filter_complex_option,,-filter_complex option} if you
  614. want to create filtergraphs with multiple inputs and/or outputs.
  615. @anchor{filter_script option}
  616. @item -filter_script[:@var{stream_specifier}] @var{filename} (@emph{output,per-stream})
  617. This option is similar to @option{-filter}, the only difference is that its
  618. argument is the name of the file from which a filtergraph description is to be
  619. read.
  620. @item -reinit_filter[:@var{stream_specifier}] @var{integer} (@emph{input,per-stream})
  621. This boolean option determines if the filtergraph(s) to which this stream is fed gets
  622. reinitialized when input frame parameters change mid-stream. This option is enabled by
  623. default as most video and all audio filters cannot handle deviation in input frame properties.
  624. Upon reinitialization, existing filter state is lost, like e.g. the frame count @code{n}
  625. reference available in some filters. Any frames buffered at time of reinitialization are lost.
  626. The properties where a change triggers reinitialization are,
  627. for video, frame resolution or pixel format;
  628. for audio, sample format, sample rate, channel count or channel layout.
  629. @item -filter_threads @var{nb_threads} (@emph{global})
  630. Defines how many threads are used to process a filter pipeline. Each pipeline
  631. will produce a thread pool with this many threads available for parallel processing.
  632. The default is the number of available CPUs.
  633. @item -pre[:@var{stream_specifier}] @var{preset_name} (@emph{output,per-stream})
  634. Specify the preset for matching stream(s).
  635. @item -stats (@emph{global})
  636. Print encoding progress/statistics. It is on by default, to explicitly
  637. disable it you need to specify @code{-nostats}.
  638. @item -stats_period @var{time} (@emph{global})
  639. Set period at which encoding progress/statistics are updated. Default is 0.5 seconds.
  640. @item -progress @var{url} (@emph{global})
  641. Send program-friendly progress information to @var{url}.
  642. Progress information is written periodically and at the end of
  643. the encoding process. It is made of "@var{key}=@var{value}" lines. @var{key}
  644. consists of only alphanumeric characters. The last key of a sequence of
  645. progress information is always "progress".
  646. The update period is set using @code{-stats_period}.
  647. @anchor{stdin option}
  648. @item -stdin
  649. Enable interaction on standard input. On by default unless standard input is
  650. used as an input. To explicitly disable interaction you need to specify
  651. @code{-nostdin}.
  652. Disabling interaction on standard input is useful, for example, if
  653. ffmpeg is in the background process group. Roughly the same result can
  654. be achieved with @code{ffmpeg ... < /dev/null} but it requires a
  655. shell.
  656. @item -debug_ts (@emph{global})
  657. Print timestamp information. It is off by default. This option is
  658. mostly useful for testing and debugging purposes, and the output
  659. format may change from one version to another, so it should not be
  660. employed by portable scripts.
  661. See also the option @code{-fdebug ts}.
  662. @item -attach @var{filename} (@emph{output})
  663. Add an attachment to the output file. This is supported by a few formats
  664. like Matroska for e.g. fonts used in rendering subtitles. Attachments
  665. are implemented as a specific type of stream, so this option will add
  666. a new stream to the file. It is then possible to use per-stream options
  667. on this stream in the usual way. Attachment streams created with this
  668. option will be created after all the other streams (i.e. those created
  669. with @code{-map} or automatic mappings).
  670. Note that for Matroska you also have to set the mimetype metadata tag:
  671. @example
  672. ffmpeg -i INPUT -attach DejaVuSans.ttf -metadata:s:2 mimetype=application/x-truetype-font out.mkv
  673. @end example
  674. (assuming that the attachment stream will be third in the output file).
  675. @item -dump_attachment[:@var{stream_specifier}] @var{filename} (@emph{input,per-stream})
  676. Extract the matching attachment stream into a file named @var{filename}. If
  677. @var{filename} is empty, then the value of the @code{filename} metadata tag
  678. will be used.
  679. E.g. to extract the first attachment to a file named 'out.ttf':
  680. @example
  681. ffmpeg -dump_attachment:t:0 out.ttf -i INPUT
  682. @end example
  683. To extract all attachments to files determined by the @code{filename} tag:
  684. @example
  685. ffmpeg -dump_attachment:t "" -i INPUT
  686. @end example
  687. Technical note -- attachments are implemented as codec extradata, so this
  688. option can actually be used to extract extradata from any stream, not just
  689. attachments.
  690. @end table
  691. @section Video Options
  692. @table @option
  693. @item -vframes @var{number} (@emph{output})
  694. Set the number of video frames to output. This is an obsolete alias for
  695. @code{-frames:v}, which you should use instead.
  696. @item -r[:@var{stream_specifier}] @var{fps} (@emph{input/output,per-stream})
  697. Set frame rate (Hz value, fraction or abbreviation).
  698. As an input option, ignore any timestamps stored in the file and instead
  699. generate timestamps assuming constant frame rate @var{fps}.
  700. This is not the same as the @option{-framerate} option used for some input formats
  701. like image2 or v4l2 (it used to be the same in older versions of FFmpeg).
  702. If in doubt use @option{-framerate} instead of the input option @option{-r}.
  703. As an output option:
  704. @table @option
  705. @item video encoding
  706. Duplicate or drop frames right before encoding them to achieve constant output
  707. frame rate @var{fps}.
  708. @item video streamcopy
  709. Indicate to the muxer that @var{fps} is the stream frame rate. No data is
  710. dropped or duplicated in this case. This may produce invalid files if @var{fps}
  711. does not match the actual stream frame rate as determined by packet timestamps.
  712. See also the @code{setts} bitstream filter.
  713. @end table
  714. @item -fpsmax[:@var{stream_specifier}] @var{fps} (@emph{output,per-stream})
  715. Set maximum frame rate (Hz value, fraction or abbreviation).
  716. Clamps output frame rate when output framerate is auto-set and is higher than this value.
  717. Useful in batch processing or when input framerate is wrongly detected as very high.
  718. It cannot be set together with @code{-r}. It is ignored during streamcopy.
  719. @item -s[:@var{stream_specifier}] @var{size} (@emph{input/output,per-stream})
  720. Set frame size.
  721. As an input option, this is a shortcut for the @option{video_size} private
  722. option, recognized by some demuxers for which the frame size is either not
  723. stored in the file or is configurable -- e.g. raw video or video grabbers.
  724. As an output option, this inserts the @code{scale} video filter to the
  725. @emph{end} of the corresponding filtergraph. Please use the @code{scale} filter
  726. directly to insert it at the beginning or some other place.
  727. The format is @samp{wxh} (default - same as source).
  728. @item -aspect[:@var{stream_specifier}] @var{aspect} (@emph{output,per-stream})
  729. Set the video display aspect ratio specified by @var{aspect}.
  730. @var{aspect} can be a floating point number string, or a string of the
  731. form @var{num}:@var{den}, where @var{num} and @var{den} are the
  732. numerator and denominator of the aspect ratio. For example "4:3",
  733. "16:9", "1.3333", and "1.7777" are valid argument values.
  734. If used together with @option{-vcodec copy}, it will affect the aspect ratio
  735. stored at container level, but not the aspect ratio stored in encoded
  736. frames, if it exists.
  737. @item -display_rotation[:@var{stream_specifier}] @var{rotation} (@emph{input,per-stream})
  738. Set video rotation metadata.
  739. @var{rotation} is a decimal number specifying the amount in degree by
  740. which the video should be rotated counter-clockwise before being
  741. displayed.
  742. This option overrides the rotation/display transform metadata stored in
  743. the file, if any. When the video is being transcoded (rather than
  744. copied) and @code{-autorotate} is enabled, the video will be rotated at
  745. the filtering stage. Otherwise, the metadata will be written into the
  746. output file if the muxer supports it.
  747. If the @code{-display_hflip} and/or @code{-display_vflip} options are
  748. given, they are applied after the rotation specified by this option.
  749. @item -display_hflip[:@var{stream_specifier}] (@emph{input,per-stream})
  750. Set whether on display the image should be horizontally flipped.
  751. See the @code{-display_rotation} option for more details.
  752. @item -display_vflip[:@var{stream_specifier}] (@emph{input,per-stream})
  753. Set whether on display the image should be vertically flipped.
  754. See the @code{-display_rotation} option for more details.
  755. @item -vn (@emph{input/output})
  756. As an input option, blocks all video streams of a file from being filtered or
  757. being automatically selected or mapped for any output. See @code{-discard}
  758. option to disable streams individually.
  759. As an output option, disables video recording i.e. automatic selection or
  760. mapping of any video stream. For full manual control see the @code{-map}
  761. option.
  762. @item -vcodec @var{codec} (@emph{output})
  763. Set the video codec. This is an alias for @code{-codec:v}.
  764. @item -pass[:@var{stream_specifier}] @var{n} (@emph{output,per-stream})
  765. Select the pass number (1 or 2). It is used to do two-pass
  766. video encoding. The statistics of the video are recorded in the first
  767. pass into a log file (see also the option -passlogfile),
  768. and in the second pass that log file is used to generate the video
  769. at the exact requested bitrate.
  770. On pass 1, you may just deactivate audio and set output to null,
  771. examples for Windows and Unix:
  772. @example
  773. ffmpeg -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y NUL
  774. ffmpeg -i foo.mov -c:v libxvid -pass 1 -an -f rawvideo -y /dev/null
  775. @end example
  776. @item -passlogfile[:@var{stream_specifier}] @var{prefix} (@emph{output,per-stream})
  777. Set two-pass log file name prefix to @var{prefix}, the default file name
  778. prefix is ``ffmpeg2pass''. The complete file name will be
  779. @file{PREFIX-N.log}, where N is a number specific to the output
  780. stream
  781. @item -vf @var{filtergraph} (@emph{output})
  782. Create the filtergraph specified by @var{filtergraph} and use it to
  783. filter the stream.
  784. This is an alias for @code{-filter:v}, see the @ref{filter_option,,-filter option}.
  785. @item -autorotate
  786. Automatically rotate the video according to file metadata. Enabled by
  787. default, use @option{-noautorotate} to disable it.
  788. @item -autoscale
  789. Automatically scale the video according to the resolution of first frame.
  790. Enabled by default, use @option{-noautoscale} to disable it. When autoscale is
  791. disabled, all output frames of filter graph might not be in the same resolution
  792. and may be inadequate for some encoder/muxer. Therefore, it is not recommended
  793. to disable it unless you really know what you are doing.
  794. Disable autoscale at your own risk.
  795. @end table
  796. @section Advanced Video options
  797. @table @option
  798. @item -pix_fmt[:@var{stream_specifier}] @var{format} (@emph{input/output,per-stream})
  799. Set pixel format. Use @code{-pix_fmts} to show all the supported
  800. pixel formats.
  801. If the selected pixel format can not be selected, ffmpeg will print a
  802. warning and select the best pixel format supported by the encoder.
  803. If @var{pix_fmt} is prefixed by a @code{+}, ffmpeg will exit with an error
  804. if the requested pixel format can not be selected, and automatic conversions
  805. inside filtergraphs are disabled.
  806. If @var{pix_fmt} is a single @code{+}, ffmpeg selects the same pixel format
  807. as the input (or graph output) and automatic conversions are disabled.
  808. @item -sws_flags @var{flags} (@emph{input/output})
  809. Set default flags for the libswscale library. These flags are used by
  810. automatically inserted @code{scale} filters and those within simple
  811. filtergraphs, if not overridden within the filtergraph definition.
  812. See the @ref{scaler_options,,ffmpeg-scaler manual,ffmpeg-scaler} for a list
  813. of scaler options.
  814. @item -rc_override[:@var{stream_specifier}] @var{override} (@emph{output,per-stream})
  815. Rate control override for specific intervals, formatted as "int,int,int"
  816. list separated with slashes. Two first values are the beginning and
  817. end frame numbers, last one is quantizer to use if positive, or quality
  818. factor if negative.
  819. @item -psnr
  820. Calculate PSNR of compressed frames. This option is deprecated, pass the
  821. PSNR flag to the encoder instead, using @code{-flags +psnr}.
  822. @item -vstats
  823. Dump video coding statistics to @file{vstats_HHMMSS.log}. See the
  824. @ref{vstats_file_format,,vstats file format} section for the format description.
  825. @item -vstats_file @var{file}
  826. Dump video coding statistics to @var{file}. See the
  827. @ref{vstats_file_format,,vstats file format} section for the format description.
  828. @item -vstats_version @var{file}
  829. Specify which version of the vstats format to use. Default is @code{2}. See the
  830. @ref{vstats_file_format,,vstats file format} section for the format description.
  831. @item -vtag @var{fourcc/tag} (@emph{output})
  832. Force video tag/fourcc. This is an alias for @code{-tag:v}.
  833. @item -vbsf @var{bitstream_filter}
  834. Deprecated see -bsf
  835. @item -force_key_frames[:@var{stream_specifier}] @var{time}[,@var{time}...] (@emph{output,per-stream})
  836. @item -force_key_frames[:@var{stream_specifier}] expr:@var{expr} (@emph{output,per-stream})
  837. @item -force_key_frames[:@var{stream_specifier}] source (@emph{output,per-stream})
  838. @var{force_key_frames} can take arguments of the following form:
  839. @table @option
  840. @item @var{time}[,@var{time}...]
  841. If the argument consists of timestamps, ffmpeg will round the specified times to the nearest
  842. output timestamp as per the encoder time base and force a keyframe at the first frame having
  843. timestamp equal or greater than the computed timestamp. Note that if the encoder time base is too
  844. coarse, then the keyframes may be forced on frames with timestamps lower than the specified time.
  845. The default encoder time base is the inverse of the output framerate but may be set otherwise
  846. via @code{-enc_time_base}.
  847. If one of the times is "@code{chapters}[@var{delta}]", it is expanded into
  848. the time of the beginning of all chapters in the file, shifted by
  849. @var{delta}, expressed as a time in seconds.
  850. This option can be useful to ensure that a seek point is present at a
  851. chapter mark or any other designated place in the output file.
  852. For example, to insert a key frame at 5 minutes, plus key frames 0.1 second
  853. before the beginning of every chapter:
  854. @example
  855. -force_key_frames 0:05:00,chapters-0.1
  856. @end example
  857. @item expr:@var{expr}
  858. If the argument is prefixed with @code{expr:}, the string @var{expr}
  859. is interpreted like an expression and is evaluated for each frame. A
  860. key frame is forced in case the evaluation is non-zero.
  861. The expression in @var{expr} can contain the following constants:
  862. @table @option
  863. @item n
  864. the number of current processed frame, starting from 0
  865. @item n_forced
  866. the number of forced frames
  867. @item prev_forced_n
  868. the number of the previous forced frame, it is @code{NAN} when no
  869. keyframe was forced yet
  870. @item prev_forced_t
  871. the time of the previous forced frame, it is @code{NAN} when no
  872. keyframe was forced yet
  873. @item t
  874. the time of the current processed frame
  875. @end table
  876. For example to force a key frame every 5 seconds, you can specify:
  877. @example
  878. -force_key_frames expr:gte(t,n_forced*5)
  879. @end example
  880. To force a key frame 5 seconds after the time of the last forced one,
  881. starting from second 13:
  882. @example
  883. -force_key_frames expr:if(isnan(prev_forced_t),gte(t,13),gte(t,prev_forced_t+5))
  884. @end example
  885. @item source
  886. If the argument is @code{source}, ffmpeg will force a key frame if
  887. the current frame being encoded is marked as a key frame in its source.
  888. In cases where this particular source frame has to be dropped,
  889. enforce the next available frame to become a key frame instead.
  890. @end table
  891. Note that forcing too many keyframes is very harmful for the lookahead
  892. algorithms of certain encoders: using fixed-GOP options or similar
  893. would be more efficient.
  894. @item -copyinkf[:@var{stream_specifier}] (@emph{output,per-stream})
  895. When doing stream copy, copy also non-key frames found at the
  896. beginning.
  897. @item -init_hw_device @var{type}[=@var{name}][:@var{device}[,@var{key=value}...]]
  898. Initialise a new hardware device of type @var{type} called @var{name}, using the
  899. given device parameters.
  900. If no name is specified it will receive a default name of the form "@var{type}%d".
  901. The meaning of @var{device} and the following arguments depends on the
  902. device type:
  903. @table @option
  904. @item cuda
  905. @var{device} is the number of the CUDA device.
  906. The following options are recognized:
  907. @table @option
  908. @item primary_ctx
  909. If set to 1, uses the primary device context instead of creating a new one.
  910. @end table
  911. Examples:
  912. @table @emph
  913. @item -init_hw_device cuda:1
  914. Choose the second device on the system.
  915. @item -init_hw_device cuda:0,primary_ctx=1
  916. Choose the first device and use the primary device context.
  917. @end table
  918. @item dxva2
  919. @var{device} is the number of the Direct3D 9 display adapter.
  920. @item d3d11va
  921. @var{device} is the number of the Direct3D 11 display adapter.
  922. @item vaapi
  923. @var{device} is either an X11 display name, a DRM render node or a DirectX adapter index.
  924. If not specified, it will attempt to open the default X11 display (@emph{$DISPLAY})
  925. and then the first DRM render node (@emph{/dev/dri/renderD128}), or the default
  926. DirectX adapter on Windows.
  927. @item vdpau
  928. @var{device} is an X11 display name.
  929. If not specified, it will attempt to open the default X11 display (@emph{$DISPLAY}).
  930. @item qsv
  931. @var{device} selects a value in @samp{MFX_IMPL_*}. Allowed values are:
  932. @table @option
  933. @item auto
  934. @item sw
  935. @item hw
  936. @item auto_any
  937. @item hw_any
  938. @item hw2
  939. @item hw3
  940. @item hw4
  941. @end table
  942. If not specified, @samp{auto_any} is used.
  943. (Note that it may be easier to achieve the desired result for QSV by creating the
  944. platform-appropriate subdevice (@samp{dxva2} or @samp{d3d11va} or @samp{vaapi}) and then deriving a
  945. QSV device from that.)
  946. Alternatively, @samp{child_device_type} helps to choose platform-appropriate subdevice type.
  947. On Windows @samp{d3d11va} is used as default subdevice type.
  948. Examples:
  949. @table @emph
  950. @item -init_hw_device qsv:hw,child_device_type=d3d11va
  951. Choose the GPU subdevice with type @samp{d3d11va} and create QSV device with @samp{MFX_IMPL_HARDWARE}.
  952. @item -init_hw_device qsv:hw,child_device_type=dxva2
  953. Choose the GPU subdevice with type @samp{dxva2} and create QSV device with @samp{MFX_IMPL_HARDWARE}.
  954. @end table
  955. @item opencl
  956. @var{device} selects the platform and device as @emph{platform_index.device_index}.
  957. The set of devices can also be filtered using the key-value pairs to find only
  958. devices matching particular platform or device strings.
  959. The strings usable as filters are:
  960. @table @option
  961. @item platform_profile
  962. @item platform_version
  963. @item platform_name
  964. @item platform_vendor
  965. @item platform_extensions
  966. @item device_name
  967. @item device_vendor
  968. @item driver_version
  969. @item device_version
  970. @item device_profile
  971. @item device_extensions
  972. @item device_type
  973. @end table
  974. The indices and filters must together uniquely select a device.
  975. Examples:
  976. @table @emph
  977. @item -init_hw_device opencl:0.1
  978. Choose the second device on the first platform.
  979. @item -init_hw_device opencl:,device_name=Foo9000
  980. Choose the device with a name containing the string @emph{Foo9000}.
  981. @item -init_hw_device opencl:1,device_type=gpu,device_extensions=cl_khr_fp16
  982. Choose the GPU device on the second platform supporting the @emph{cl_khr_fp16}
  983. extension.
  984. @end table
  985. @item vulkan
  986. If @var{device} is an integer, it selects the device by its index in a
  987. system-dependent list of devices. If @var{device} is any other string, it
  988. selects the first device with a name containing that string as a substring.
  989. The following options are recognized:
  990. @table @option
  991. @item debug
  992. If set to 1, enables the validation layer, if installed.
  993. @item linear_images
  994. If set to 1, images allocated by the hwcontext will be linear and locally mappable.
  995. @item instance_extensions
  996. A plus separated list of additional instance extensions to enable.
  997. @item device_extensions
  998. A plus separated list of additional device extensions to enable.
  999. @end table
  1000. Examples:
  1001. @table @emph
  1002. @item -init_hw_device vulkan:1
  1003. Choose the second device on the system.
  1004. @item -init_hw_device vulkan:RADV
  1005. Choose the first device with a name containing the string @emph{RADV}.
  1006. @item -init_hw_device vulkan:0,instance_extensions=VK_KHR_wayland_surface+VK_KHR_xcb_surface
  1007. Choose the first device and enable the Wayland and XCB instance extensions.
  1008. @end table
  1009. @end table
  1010. @item -init_hw_device @var{type}[=@var{name}]@@@var{source}
  1011. Initialise a new hardware device of type @var{type} called @var{name},
  1012. deriving it from the existing device with the name @var{source}.
  1013. @item -init_hw_device list
  1014. List all hardware device types supported in this build of ffmpeg.
  1015. @item -filter_hw_device @var{name}
  1016. Pass the hardware device called @var{name} to all filters in any filter graph.
  1017. This can be used to set the device to upload to with the @code{hwupload} filter,
  1018. or the device to map to with the @code{hwmap} filter. Other filters may also
  1019. make use of this parameter when they require a hardware device. Note that this
  1020. is typically only required when the input is not already in hardware frames -
  1021. when it is, filters will derive the device they require from the context of the
  1022. frames they receive as input.
  1023. This is a global setting, so all filters will receive the same device.
  1024. @item -hwaccel[:@var{stream_specifier}] @var{hwaccel} (@emph{input,per-stream})
  1025. Use hardware acceleration to decode the matching stream(s). The allowed values
  1026. of @var{hwaccel} are:
  1027. @table @option
  1028. @item none
  1029. Do not use any hardware acceleration (the default).
  1030. @item auto
  1031. Automatically select the hardware acceleration method.
  1032. @item vdpau
  1033. Use VDPAU (Video Decode and Presentation API for Unix) hardware acceleration.
  1034. @item dxva2
  1035. Use DXVA2 (DirectX Video Acceleration) hardware acceleration.
  1036. @item d3d11va
  1037. Use D3D11VA (DirectX Video Acceleration) hardware acceleration.
  1038. @item vaapi
  1039. Use VAAPI (Video Acceleration API) hardware acceleration.
  1040. @item qsv
  1041. Use the Intel QuickSync Video acceleration for video transcoding.
  1042. Unlike most other values, this option does not enable accelerated decoding (that
  1043. is used automatically whenever a qsv decoder is selected), but accelerated
  1044. transcoding, without copying the frames into the system memory.
  1045. For it to work, both the decoder and the encoder must support QSV acceleration
  1046. and no filters must be used.
  1047. @end table
  1048. This option has no effect if the selected hwaccel is not available or not
  1049. supported by the chosen decoder.
  1050. Note that most acceleration methods are intended for playback and will not be
  1051. faster than software decoding on modern CPUs. Additionally, @command{ffmpeg}
  1052. will usually need to copy the decoded frames from the GPU memory into the system
  1053. memory, resulting in further performance loss. This option is thus mainly
  1054. useful for testing.
  1055. @item -hwaccel_device[:@var{stream_specifier}] @var{hwaccel_device} (@emph{input,per-stream})
  1056. Select a device to use for hardware acceleration.
  1057. This option only makes sense when the @option{-hwaccel} option is also specified.
  1058. It can either refer to an existing device created with @option{-init_hw_device}
  1059. by name, or it can create a new device as if
  1060. @samp{-init_hw_device} @var{type}:@var{hwaccel_device}
  1061. were called immediately before.
  1062. @item -hwaccels
  1063. List all hardware acceleration components enabled in this build of ffmpeg.
  1064. Actual runtime availability depends on the hardware and its suitable driver
  1065. being installed.
  1066. @item -fix_sub_duration_heartbeat[:@var{stream_specifier}]
  1067. Set a specific output video stream as the heartbeat stream according to which
  1068. to split and push through currently in-progress subtitle upon receipt of a
  1069. random access packet.
  1070. This lowers the latency of subtitles for which the end packet or the following
  1071. subtitle has not yet been received. As a drawback, this will most likely lead
  1072. to duplication of subtitle events in order to cover the full duration, so
  1073. when dealing with use cases where latency of when the subtitle event is passed
  1074. on to output is not relevant this option should not be utilized.
  1075. Requires @option{-fix_sub_duration} to be set for the relevant input subtitle
  1076. stream for this to have any effect, as well as for the input subtitle stream
  1077. having to be directly mapped to the same output in which the heartbeat stream
  1078. resides.
  1079. @end table
  1080. @section Audio Options
  1081. @table @option
  1082. @item -aframes @var{number} (@emph{output})
  1083. Set the number of audio frames to output. This is an obsolete alias for
  1084. @code{-frames:a}, which you should use instead.
  1085. @item -ar[:@var{stream_specifier}] @var{freq} (@emph{input/output,per-stream})
  1086. Set the audio sampling frequency. For output streams it is set by
  1087. default to the frequency of the corresponding input stream. For input
  1088. streams this option only makes sense for audio grabbing devices and raw
  1089. demuxers and is mapped to the corresponding demuxer options.
  1090. @item -aq @var{q} (@emph{output})
  1091. Set the audio quality (codec-specific, VBR). This is an alias for -q:a.
  1092. @item -ac[:@var{stream_specifier}] @var{channels} (@emph{input/output,per-stream})
  1093. Set the number of audio channels. For output streams it is set by
  1094. default to the number of input audio channels. For input streams
  1095. this option only makes sense for audio grabbing devices and raw demuxers
  1096. and is mapped to the corresponding demuxer options.
  1097. @item -an (@emph{input/output})
  1098. As an input option, blocks all audio streams of a file from being filtered or
  1099. being automatically selected or mapped for any output. See @code{-discard}
  1100. option to disable streams individually.
  1101. As an output option, disables audio recording i.e. automatic selection or
  1102. mapping of any audio stream. For full manual control see the @code{-map}
  1103. option.
  1104. @item -acodec @var{codec} (@emph{input/output})
  1105. Set the audio codec. This is an alias for @code{-codec:a}.
  1106. @item -sample_fmt[:@var{stream_specifier}] @var{sample_fmt} (@emph{output,per-stream})
  1107. Set the audio sample format. Use @code{-sample_fmts} to get a list
  1108. of supported sample formats.
  1109. @item -af @var{filtergraph} (@emph{output})
  1110. Create the filtergraph specified by @var{filtergraph} and use it to
  1111. filter the stream.
  1112. This is an alias for @code{-filter:a}, see the @ref{filter_option,,-filter option}.
  1113. @end table
  1114. @section Advanced Audio options
  1115. @table @option
  1116. @item -atag @var{fourcc/tag} (@emph{output})
  1117. Force audio tag/fourcc. This is an alias for @code{-tag:a}.
  1118. @item -absf @var{bitstream_filter}
  1119. Deprecated, see -bsf
  1120. @item -guess_layout_max @var{channels} (@emph{input,per-stream})
  1121. If some input channel layout is not known, try to guess only if it
  1122. corresponds to at most the specified number of channels. For example, 2
  1123. tells to @command{ffmpeg} to recognize 1 channel as mono and 2 channels as
  1124. stereo but not 6 channels as 5.1. The default is to always try to guess. Use
  1125. 0 to disable all guessing.
  1126. @end table
  1127. @section Subtitle options
  1128. @table @option
  1129. @item -scodec @var{codec} (@emph{input/output})
  1130. Set the subtitle codec. This is an alias for @code{-codec:s}.
  1131. @item -sn (@emph{input/output})
  1132. As an input option, blocks all subtitle streams of a file from being filtered or
  1133. being automatically selected or mapped for any output. See @code{-discard}
  1134. option to disable streams individually.
  1135. As an output option, disables subtitle recording i.e. automatic selection or
  1136. mapping of any subtitle stream. For full manual control see the @code{-map}
  1137. option.
  1138. @item -sbsf @var{bitstream_filter}
  1139. Deprecated, see -bsf
  1140. @end table
  1141. @section Advanced Subtitle options
  1142. @table @option
  1143. @item -fix_sub_duration
  1144. Fix subtitles durations. For each subtitle, wait for the next packet in the
  1145. same stream and adjust the duration of the first to avoid overlap. This is
  1146. necessary with some subtitles codecs, especially DVB subtitles, because the
  1147. duration in the original packet is only a rough estimate and the end is
  1148. actually marked by an empty subtitle frame. Failing to use this option when
  1149. necessary can result in exaggerated durations or muxing failures due to
  1150. non-monotonic timestamps.
  1151. Note that this option will delay the output of all data until the next
  1152. subtitle packet is decoded: it may increase memory consumption and latency a
  1153. lot.
  1154. @item -canvas_size @var{size}
  1155. Set the size of the canvas used to render subtitles.
  1156. @end table
  1157. @section Advanced options
  1158. @table @option
  1159. @item -map [-]@var{input_file_id}[:@var{stream_specifier}][?] | @var{[linklabel]} (@emph{output})
  1160. Create one or more streams in the output file. This option has two forms for
  1161. specifying the data source(s): the first selects one or more streams from some
  1162. input file (specified with @code{-i}), the second takes an output from some
  1163. complex filtergraph (specified with @code{-filter_complex} or
  1164. @code{-filter_complex_script}).
  1165. In the first form, an output stream is created for every stream from the input
  1166. file with the index @var{input_file_id}. If @var{stream_specifier} is given,
  1167. only those streams that match the specifier are used (see the
  1168. @ref{Stream specifiers} section for the @var{stream_specifier} syntax).
  1169. A @code{-} character before the stream identifier creates a "negative" mapping.
  1170. It disables matching streams from already created mappings.
  1171. A trailing @code{?} after the stream index will allow the map to be
  1172. optional: if the map matches no streams the map will be ignored instead
  1173. of failing. Note the map will still fail if an invalid input file index
  1174. is used; such as if the map refers to a non-existent input.
  1175. An alternative @var{[linklabel]} form will map outputs from complex filter
  1176. graphs (see the @option{-filter_complex} option) to the output file.
  1177. @var{linklabel} must correspond to a defined output link label in the graph.
  1178. This option may be specified multiple times, each adding more streams to the
  1179. output file. Any given input stream may also be mapped any number of times as a
  1180. source for different output streams, e.g. in order to use different encoding
  1181. options and/or filters. The streams are created in the output in the same order
  1182. in which the @code{-map} options are given on the commandline.
  1183. Using this option disables the default mappings for this output file.
  1184. Examples:
  1185. @table @emph
  1186. @item map everything
  1187. To map ALL streams from the first input file to output
  1188. @example
  1189. ffmpeg -i INPUT -map 0 output
  1190. @end example
  1191. @item select specific stream
  1192. If you have two audio streams in the first input file, these streams are
  1193. identified by @var{0:0} and @var{0:1}. You can use @code{-map} to select which
  1194. streams to place in an output file. For example:
  1195. @example
  1196. ffmpeg -i INPUT -map 0:1 out.wav
  1197. @end example
  1198. will map the second input stream in @file{INPUT} to the (single) output stream
  1199. in @file{out.wav}.
  1200. @item create multiple streams
  1201. To select the stream with index 2 from input file @file{a.mov} (specified by the
  1202. identifier @var{0:2}), and stream with index 6 from input @file{b.mov}
  1203. (specified by the identifier @var{1:6}), and copy them to the output file
  1204. @file{out.mov}:
  1205. @example
  1206. ffmpeg -i a.mov -i b.mov -c copy -map 0:2 -map 1:6 out.mov
  1207. @end example
  1208. @item create multiple streams 2
  1209. To select all video and the third audio stream from an input file:
  1210. @example
  1211. ffmpeg -i INPUT -map 0:v -map 0:a:2 OUTPUT
  1212. @end example
  1213. @item negative map
  1214. To map all the streams except the second audio, use negative mappings
  1215. @example
  1216. ffmpeg -i INPUT -map 0 -map -0:a:1 OUTPUT
  1217. @end example
  1218. @item optional map
  1219. To map the video and audio streams from the first input, and using the
  1220. trailing @code{?}, ignore the audio mapping if no audio streams exist in
  1221. the first input:
  1222. @example
  1223. ffmpeg -i INPUT -map 0:v -map 0:a? OUTPUT
  1224. @end example
  1225. @item map by language
  1226. To pick the English audio stream:
  1227. @example
  1228. ffmpeg -i INPUT -map 0:m:language:eng OUTPUT
  1229. @end example
  1230. @end table
  1231. @item -ignore_unknown
  1232. Ignore input streams with unknown type instead of failing if copying
  1233. such streams is attempted.
  1234. @item -copy_unknown
  1235. Allow input streams with unknown type to be copied instead of failing if copying
  1236. such streams is attempted.
  1237. @item -map_channel [@var{input_file_id}.@var{stream_specifier}.@var{channel_id}|-1][?][:@var{output_file_id}.@var{stream_specifier}]
  1238. This option is deprecated and will be removed. It can be replaced by the
  1239. @var{pan} filter. In some cases it may be easier to use some combination of the
  1240. @var{channelsplit}, @var{channelmap}, or @var{amerge} filters.
  1241. Map an audio channel from a given input to an output. If
  1242. @var{output_file_id}.@var{stream_specifier} is not set, the audio channel will
  1243. be mapped on all the audio streams.
  1244. Using "-1" instead of
  1245. @var{input_file_id}.@var{stream_specifier}.@var{channel_id} will map a muted
  1246. channel.
  1247. A trailing @code{?} will allow the map_channel to be
  1248. optional: if the map_channel matches no channel the map_channel will be ignored instead
  1249. of failing.
  1250. For example, assuming @var{INPUT} is a stereo audio file, you can switch the
  1251. two audio channels with the following command:
  1252. @example
  1253. ffmpeg -i INPUT -map_channel 0.0.1 -map_channel 0.0.0 OUTPUT
  1254. @end example
  1255. If you want to mute the first channel and keep the second:
  1256. @example
  1257. ffmpeg -i INPUT -map_channel -1 -map_channel 0.0.1 OUTPUT
  1258. @end example
  1259. The order of the "-map_channel" option specifies the order of the channels in
  1260. the output stream. The output channel layout is guessed from the number of
  1261. channels mapped (mono if one "-map_channel", stereo if two, etc.). Using "-ac"
  1262. in combination of "-map_channel" makes the channel gain levels to be updated if
  1263. input and output channel layouts don't match (for instance two "-map_channel"
  1264. options and "-ac 6").
  1265. You can also extract each channel of an input to specific outputs; the following
  1266. command extracts two channels of the @var{INPUT} audio stream (file 0, stream 0)
  1267. to the respective @var{OUTPUT_CH0} and @var{OUTPUT_CH1} outputs:
  1268. @example
  1269. ffmpeg -i INPUT -map_channel 0.0.0 OUTPUT_CH0 -map_channel 0.0.1 OUTPUT_CH1
  1270. @end example
  1271. The following example splits the channels of a stereo input into two separate
  1272. streams, which are put into the same output file:
  1273. @example
  1274. ffmpeg -i stereo.wav -map 0:0 -map 0:0 -map_channel 0.0.0:0.0 -map_channel 0.0.1:0.1 -y out.ogg
  1275. @end example
  1276. Note that currently each output stream can only contain channels from a single
  1277. input stream; you can't for example use "-map_channel" to pick multiple input
  1278. audio channels contained in different streams (from the same or different files)
  1279. and merge them into a single output stream. It is therefore not currently
  1280. possible, for example, to turn two separate mono streams into a single stereo
  1281. stream. However splitting a stereo stream into two single channel mono streams
  1282. is possible.
  1283. If you need this feature, a possible workaround is to use the @emph{amerge}
  1284. filter. For example, if you need to merge a media (here @file{input.mkv}) with 2
  1285. mono audio streams into one single stereo channel audio stream (and keep the
  1286. video stream), you can use the following command:
  1287. @example
  1288. ffmpeg -i input.mkv -filter_complex "[0:1] [0:2] amerge" -c:a pcm_s16le -c:v copy output.mkv
  1289. @end example
  1290. To map the first two audio channels from the first input, and using the
  1291. trailing @code{?}, ignore the audio channel mapping if the first input is
  1292. mono instead of stereo:
  1293. @example
  1294. ffmpeg -i INPUT -map_channel 0.0.0 -map_channel 0.0.1? OUTPUT
  1295. @end example
  1296. @item -map_metadata[:@var{metadata_spec_out}] @var{infile}[:@var{metadata_spec_in}] (@emph{output,per-metadata})
  1297. Set metadata information of the next output file from @var{infile}. Note that
  1298. those are file indices (zero-based), not filenames.
  1299. Optional @var{metadata_spec_in/out} parameters specify, which metadata to copy.
  1300. A metadata specifier can have the following forms:
  1301. @table @option
  1302. @item @var{g}
  1303. global metadata, i.e. metadata that applies to the whole file
  1304. @item @var{s}[:@var{stream_spec}]
  1305. per-stream metadata. @var{stream_spec} is a stream specifier as described
  1306. in the @ref{Stream specifiers} chapter. In an input metadata specifier, the first
  1307. matching stream is copied from. In an output metadata specifier, all matching
  1308. streams are copied to.
  1309. @item @var{c}:@var{chapter_index}
  1310. per-chapter metadata. @var{chapter_index} is the zero-based chapter index.
  1311. @item @var{p}:@var{program_index}
  1312. per-program metadata. @var{program_index} is the zero-based program index.
  1313. @end table
  1314. If metadata specifier is omitted, it defaults to global.
  1315. By default, global metadata is copied from the first input file,
  1316. per-stream and per-chapter metadata is copied along with streams/chapters. These
  1317. default mappings are disabled by creating any mapping of the relevant type. A negative
  1318. file index can be used to create a dummy mapping that just disables automatic copying.
  1319. For example to copy metadata from the first stream of the input file to global metadata
  1320. of the output file:
  1321. @example
  1322. ffmpeg -i in.ogg -map_metadata 0:s:0 out.mp3
  1323. @end example
  1324. To do the reverse, i.e. copy global metadata to all audio streams:
  1325. @example
  1326. ffmpeg -i in.mkv -map_metadata:s:a 0:g out.mkv
  1327. @end example
  1328. Note that simple @code{0} would work as well in this example, since global
  1329. metadata is assumed by default.
  1330. @item -map_chapters @var{input_file_index} (@emph{output})
  1331. Copy chapters from input file with index @var{input_file_index} to the next
  1332. output file. If no chapter mapping is specified, then chapters are copied from
  1333. the first input file with at least one chapter. Use a negative file index to
  1334. disable any chapter copying.
  1335. @item -benchmark (@emph{global})
  1336. Show benchmarking information at the end of an encode.
  1337. Shows real, system and user time used and maximum memory consumption.
  1338. Maximum memory consumption is not supported on all systems,
  1339. it will usually display as 0 if not supported.
  1340. @item -benchmark_all (@emph{global})
  1341. Show benchmarking information during the encode.
  1342. Shows real, system and user time used in various steps (audio/video encode/decode).
  1343. @item -timelimit @var{duration} (@emph{global})
  1344. Exit after ffmpeg has been running for @var{duration} seconds in CPU user time.
  1345. @item -dump (@emph{global})
  1346. Dump each input packet to stderr.
  1347. @item -hex (@emph{global})
  1348. When dumping packets, also dump the payload.
  1349. @item -readrate @var{speed} (@emph{input})
  1350. Limit input read speed.
  1351. Its value is a floating-point positive number which represents the maximum duration of
  1352. media, in seconds, that should be ingested in one second of wallclock time.
  1353. Default value is zero and represents no imposed limitation on speed of ingestion.
  1354. Value @code{1} represents real-time speed and is equivalent to @code{-re}.
  1355. Mainly used to simulate a capture device or live input stream (e.g. when reading from a file).
  1356. Should not be used with a low value when input is an actual capture device or live stream as
  1357. it may cause packet loss.
  1358. It is useful for when flow speed of output packets is important, such as live streaming.
  1359. @item -re (@emph{input})
  1360. Read input at native frame rate. This is equivalent to setting @code{-readrate 1}.
  1361. @item -readrate_initial_burst @var{seconds}
  1362. Set an initial read burst time, in seconds, after which @option{-re/-readrate}
  1363. will be enforced.
  1364. @item -vsync @var{parameter} (@emph{global})
  1365. @itemx -fps_mode[:@var{stream_specifier}] @var{parameter} (@emph{output,per-stream})
  1366. Set video sync method / framerate mode. vsync is applied to all output video streams
  1367. but can be overridden for a stream by setting fps_mode. vsync is deprecated and will be
  1368. removed in the future.
  1369. For compatibility reasons some of the values for vsync can be specified as numbers (shown
  1370. in parentheses in the following table).
  1371. @table @option
  1372. @item passthrough (0)
  1373. Each frame is passed with its timestamp from the demuxer to the muxer.
  1374. @item cfr (1)
  1375. Frames will be duplicated and dropped to achieve exactly the requested
  1376. constant frame rate.
  1377. @item vfr (2)
  1378. Frames are passed through with their timestamp or dropped so as to
  1379. prevent 2 frames from having the same timestamp.
  1380. @item drop
  1381. As passthrough but destroys all timestamps, making the muxer generate
  1382. fresh timestamps based on frame-rate.
  1383. @item auto (-1)
  1384. Chooses between cfr and vfr depending on muxer capabilities. This is the
  1385. default method.
  1386. @end table
  1387. Note that the timestamps may be further modified by the muxer, after this.
  1388. For example, in the case that the format option @option{avoid_negative_ts}
  1389. is enabled.
  1390. With -map you can select from which stream the timestamps should be
  1391. taken. You can leave either video or audio unchanged and sync the
  1392. remaining stream(s) to the unchanged one.
  1393. @item -frame_drop_threshold @var{parameter}
  1394. Frame drop threshold, which specifies how much behind video frames can
  1395. be before they are dropped. In frame rate units, so 1.0 is one frame.
  1396. The default is -1.1. One possible usecase is to avoid framedrops in case
  1397. of noisy timestamps or to increase frame drop precision in case of exact
  1398. timestamps.
  1399. @item -apad @var{parameters} (@emph{output,per-stream})
  1400. Pad the output audio stream(s). This is the same as applying @code{-af apad}.
  1401. Argument is a string of filter parameters composed the same as with the @code{apad} filter.
  1402. @code{-shortest} must be set for this output for the option to take effect.
  1403. @item -copyts
  1404. Do not process input timestamps, but keep their values without trying
  1405. to sanitize them. In particular, do not remove the initial start time
  1406. offset value.
  1407. Note that, depending on the @option{vsync} option or on specific muxer
  1408. processing (e.g. in case the format option @option{avoid_negative_ts}
  1409. is enabled) the output timestamps may mismatch with the input
  1410. timestamps even when this option is selected.
  1411. @item -start_at_zero
  1412. When used with @option{copyts}, shift input timestamps so they start at zero.
  1413. This means that using e.g. @code{-ss 50} will make output timestamps start at
  1414. 50 seconds, regardless of what timestamp the input file started at.
  1415. @item -copytb @var{mode}
  1416. Specify how to set the encoder timebase when stream copying. @var{mode} is an
  1417. integer numeric value, and can assume one of the following values:
  1418. @table @option
  1419. @item 1
  1420. Use the demuxer timebase.
  1421. The time base is copied to the output encoder from the corresponding input
  1422. demuxer. This is sometimes required to avoid non monotonically increasing
  1423. timestamps when copying video streams with variable frame rate.
  1424. @item 0
  1425. Use the decoder timebase.
  1426. The time base is copied to the output encoder from the corresponding input
  1427. decoder.
  1428. @item -1
  1429. Try to make the choice automatically, in order to generate a sane output.
  1430. @end table
  1431. Default value is -1.
  1432. @item -enc_time_base[:@var{stream_specifier}] @var{timebase} (@emph{output,per-stream})
  1433. Set the encoder timebase. @var{timebase} can assume one of the following values:
  1434. @table @option
  1435. @item 0
  1436. Assign a default value according to the media type.
  1437. For video - use 1/framerate, for audio - use 1/samplerate.
  1438. @item demux
  1439. Use the timebase from the demuxer.
  1440. @item filter
  1441. Use the timebase from the filtergraph.
  1442. @item a positive number
  1443. Use the provided number as the timebase.
  1444. This field can be provided as a ratio of two integers (e.g. 1:24, 1:48000)
  1445. or as a decimal number (e.g. 0.04166, 2.0833e-5)
  1446. @end table
  1447. Default value is 0.
  1448. @item -bitexact (@emph{input/output})
  1449. Enable bitexact mode for (de)muxer and (de/en)coder
  1450. @item -shortest (@emph{output})
  1451. Finish encoding when the shortest output stream ends.
  1452. Note that this option may require buffering frames, which introduces extra
  1453. latency. The maximum amount of this latency may be controlled with the
  1454. @code{-shortest_buf_duration} option.
  1455. @item -shortest_buf_duration @var{duration} (@emph{output})
  1456. The @code{-shortest} option may require buffering potentially large amounts
  1457. of data when at least one of the streams is "sparse" (i.e. has large gaps
  1458. between frames – this is typically the case for subtitles).
  1459. This option controls the maximum duration of buffered frames in seconds.
  1460. Larger values may allow the @code{-shortest} option to produce more accurate
  1461. results, but increase memory use and latency.
  1462. The default value is 10 seconds.
  1463. @item -dts_delta_threshold @var{threshold}
  1464. Timestamp discontinuity delta threshold, expressed as a decimal number
  1465. of seconds.
  1466. The timestamp discontinuity correction enabled by this option is only
  1467. applied to input formats accepting timestamp discontinuity (for which
  1468. the @code{AV_FMT_DISCONT} flag is enabled), e.g. MPEG-TS and HLS, and
  1469. is automatically disabled when employing the @code{-copy_ts} option
  1470. (unless wrapping is detected).
  1471. If a timestamp discontinuity is detected whose absolute value is
  1472. greater than @var{threshold}, ffmpeg will remove the discontinuity by
  1473. decreasing/increasing the current DTS and PTS by the corresponding
  1474. delta value.
  1475. The default value is 10.
  1476. @item -dts_error_threshold @var{threshold}
  1477. Timestamp error delta threshold, expressed as a decimal number of
  1478. seconds.
  1479. The timestamp correction enabled by this option is only applied to
  1480. input formats not accepting timestamp discontinuity (for which the
  1481. @code{AV_FMT_DISCONT} flag is not enabled).
  1482. If a timestamp discontinuity is detected whose absolute value is
  1483. greater than @var{threshold}, ffmpeg will drop the PTS/DTS timestamp
  1484. value.
  1485. The default value is @code{3600*30} (30 hours), which is arbitrarily
  1486. picked and quite conservative.
  1487. @item -muxdelay @var{seconds} (@emph{output})
  1488. Set the maximum demux-decode delay.
  1489. @item -muxpreload @var{seconds} (@emph{output})
  1490. Set the initial demux-decode delay.
  1491. @item -streamid @var{output-stream-index}:@var{new-value} (@emph{output})
  1492. Assign a new stream-id value to an output stream. This option should be
  1493. specified prior to the output filename to which it applies.
  1494. For the situation where multiple output files exist, a streamid
  1495. may be reassigned to a different value.
  1496. For example, to set the stream 0 PID to 33 and the stream 1 PID to 36 for
  1497. an output mpegts file:
  1498. @example
  1499. ffmpeg -i inurl -streamid 0:33 -streamid 1:36 out.ts
  1500. @end example
  1501. @item -bsf[:@var{stream_specifier}] @var{bitstream_filters} (@emph{output,per-stream})
  1502. Set bitstream filters for matching streams. @var{bitstream_filters} is
  1503. a comma-separated list of bitstream filters. Use the @code{-bsfs} option
  1504. to get the list of bitstream filters.
  1505. @example
  1506. ffmpeg -i h264.mp4 -c:v copy -bsf:v h264_mp4toannexb -an out.h264
  1507. @end example
  1508. @example
  1509. ffmpeg -i file.mov -an -vn -bsf:s mov2textsub -c:s copy -f rawvideo sub.txt
  1510. @end example
  1511. @item -tag[:@var{stream_specifier}] @var{codec_tag} (@emph{input/output,per-stream})
  1512. Force a tag/fourcc for matching streams.
  1513. @item -timecode @var{hh}:@var{mm}:@var{ss}SEP@var{ff}
  1514. Specify Timecode for writing. @var{SEP} is ':' for non drop timecode and ';'
  1515. (or '.') for drop.
  1516. @example
  1517. ffmpeg -i input.mpg -timecode 01:02:03.04 -r 30000/1001 -s ntsc output.mpg
  1518. @end example
  1519. @anchor{filter_complex_option}
  1520. @item -filter_complex @var{filtergraph} (@emph{global})
  1521. Define a complex filtergraph, i.e. one with arbitrary number of inputs and/or
  1522. outputs. For simple graphs -- those with one input and one output of the same
  1523. type -- see the @option{-filter} options. @var{filtergraph} is a description of
  1524. the filtergraph, as described in the ``Filtergraph syntax'' section of the
  1525. ffmpeg-filters manual.
  1526. Input link labels must refer to input streams using the
  1527. @code{[file_index:stream_specifier]} syntax (i.e. the same as @option{-map}
  1528. uses). If @var{stream_specifier} matches multiple streams, the first one will be
  1529. used. An unlabeled input will be connected to the first unused input stream of
  1530. the matching type.
  1531. Output link labels are referred to with @option{-map}. Unlabeled outputs are
  1532. added to the first output file.
  1533. Note that with this option it is possible to use only lavfi sources without
  1534. normal input files.
  1535. For example, to overlay an image over video
  1536. @example
  1537. ffmpeg -i video.mkv -i image.png -filter_complex '[0:v][1:v]overlay[out]' -map
  1538. '[out]' out.mkv
  1539. @end example
  1540. Here @code{[0:v]} refers to the first video stream in the first input file,
  1541. which is linked to the first (main) input of the overlay filter. Similarly the
  1542. first video stream in the second input is linked to the second (overlay) input
  1543. of overlay.
  1544. Assuming there is only one video stream in each input file, we can omit input
  1545. labels, so the above is equivalent to
  1546. @example
  1547. ffmpeg -i video.mkv -i image.png -filter_complex 'overlay[out]' -map
  1548. '[out]' out.mkv
  1549. @end example
  1550. Furthermore we can omit the output label and the single output from the filter
  1551. graph will be added to the output file automatically, so we can simply write
  1552. @example
  1553. ffmpeg -i video.mkv -i image.png -filter_complex 'overlay' out.mkv
  1554. @end example
  1555. As a special exception, you can use a bitmap subtitle stream as input: it
  1556. will be converted into a video with the same size as the largest video in
  1557. the file, or 720x576 if no video is present. Note that this is an
  1558. experimental and temporary solution. It will be removed once libavfilter has
  1559. proper support for subtitles.
  1560. For example, to hardcode subtitles on top of a DVB-T recording stored in
  1561. MPEG-TS format, delaying the subtitles by 1 second:
  1562. @example
  1563. ffmpeg -i input.ts -filter_complex \
  1564. '[#0x2ef] setpts=PTS+1/TB [sub] ; [#0x2d0] [sub] overlay' \
  1565. -sn -map '#0x2dc' output.mkv
  1566. @end example
  1567. (0x2d0, 0x2dc and 0x2ef are the MPEG-TS PIDs of respectively the video,
  1568. audio and subtitles streams; 0:0, 0:3 and 0:7 would have worked too)
  1569. To generate 5 seconds of pure red video using lavfi @code{color} source:
  1570. @example
  1571. ffmpeg -filter_complex 'color=c=red' -t 5 out.mkv
  1572. @end example
  1573. @item -filter_complex_threads @var{nb_threads} (@emph{global})
  1574. Defines how many threads are used to process a filter_complex graph.
  1575. Similar to filter_threads but used for @code{-filter_complex} graphs only.
  1576. The default is the number of available CPUs.
  1577. @item -lavfi @var{filtergraph} (@emph{global})
  1578. Define a complex filtergraph, i.e. one with arbitrary number of inputs and/or
  1579. outputs. Equivalent to @option{-filter_complex}.
  1580. @anchor{filter_complex_script option}
  1581. @item -filter_complex_script @var{filename} (@emph{global})
  1582. This option is similar to @option{-filter_complex}, the only difference is that
  1583. its argument is the name of the file from which a complex filtergraph
  1584. description is to be read.
  1585. @item -accurate_seek (@emph{input})
  1586. This option enables or disables accurate seeking in input files with the
  1587. @option{-ss} option. It is enabled by default, so seeking is accurate when
  1588. transcoding. Use @option{-noaccurate_seek} to disable it, which may be useful
  1589. e.g. when copying some streams and transcoding the others.
  1590. @item -seek_timestamp (@emph{input})
  1591. This option enables or disables seeking by timestamp in input files with the
  1592. @option{-ss} option. It is disabled by default. If enabled, the argument
  1593. to the @option{-ss} option is considered an actual timestamp, and is not
  1594. offset by the start time of the file. This matters only for files which do
  1595. not start from timestamp 0, such as transport streams.
  1596. @item -thread_queue_size @var{size} (@emph{input/output})
  1597. For input, this option sets the maximum number of queued packets when reading
  1598. from the file or device. With low latency / high rate live streams, packets may
  1599. be discarded if they are not read in a timely manner; setting this value can
  1600. force ffmpeg to use a separate input thread and read packets as soon as they
  1601. arrive. By default ffmpeg only does this if multiple inputs are specified.
  1602. For output, this option specified the maximum number of packets that may be
  1603. queued to each muxing thread.
  1604. @item -sdp_file @var{file} (@emph{global})
  1605. Print sdp information for an output stream to @var{file}.
  1606. This allows dumping sdp information when at least one output isn't an
  1607. rtp stream. (Requires at least one of the output formats to be rtp).
  1608. @item -discard (@emph{input})
  1609. Allows discarding specific streams or frames from streams.
  1610. Any input stream can be fully discarded, using value @code{all} whereas
  1611. selective discarding of frames from a stream occurs at the demuxer
  1612. and is not supported by all demuxers.
  1613. @table @option
  1614. @item none
  1615. Discard no frame.
  1616. @item default
  1617. Default, which discards no frames.
  1618. @item noref
  1619. Discard all non-reference frames.
  1620. @item bidir
  1621. Discard all bidirectional frames.
  1622. @item nokey
  1623. Discard all frames excepts keyframes.
  1624. @item all
  1625. Discard all frames.
  1626. @end table
  1627. @item -abort_on @var{flags} (@emph{global})
  1628. Stop and abort on various conditions. The following flags are available:
  1629. @table @option
  1630. @item empty_output
  1631. No packets were passed to the muxer, the output is empty.
  1632. @item empty_output_stream
  1633. No packets were passed to the muxer in some of the output streams.
  1634. @end table
  1635. @item -max_error_rate (@emph{global})
  1636. Set fraction of decoding frame failures across all inputs which when crossed
  1637. ffmpeg will return exit code 69. Crossing this threshold does not terminate
  1638. processing. Range is a floating-point number between 0 to 1. Default is 2/3.
  1639. @item -xerror (@emph{global})
  1640. Stop and exit on error
  1641. @item -max_muxing_queue_size @var{packets} (@emph{output,per-stream})
  1642. When transcoding audio and/or video streams, ffmpeg will not begin writing into
  1643. the output until it has one packet for each such stream. While waiting for that
  1644. to happen, packets for other streams are buffered. This option sets the size of
  1645. this buffer, in packets, for the matching output stream.
  1646. The default value of this option should be high enough for most uses, so only
  1647. touch this option if you are sure that you need it.
  1648. @item -muxing_queue_data_threshold @var{bytes} (@emph{output,per-stream})
  1649. This is a minimum threshold until which the muxing queue size is not taken into
  1650. account. Defaults to 50 megabytes per stream, and is based on the overall size
  1651. of packets passed to the muxer.
  1652. @item -auto_conversion_filters (@emph{global})
  1653. Enable automatically inserting format conversion filters in all filter
  1654. graphs, including those defined by @option{-vf}, @option{-af},
  1655. @option{-filter_complex} and @option{-lavfi}. If filter format negotiation
  1656. requires a conversion, the initialization of the filters will fail.
  1657. Conversions can still be performed by inserting the relevant conversion
  1658. filter (scale, aresample) in the graph.
  1659. On by default, to explicitly disable it you need to specify
  1660. @code{-noauto_conversion_filters}.
  1661. @item -bits_per_raw_sample[:@var{stream_specifier}] @var{value} (@emph{output,per-stream})
  1662. Declare the number of bits per raw sample in the given output stream to be
  1663. @var{value}. Note that this option sets the information provided to the
  1664. encoder/muxer, it does not change the stream to conform to this value. Setting
  1665. values that do not match the stream properties may result in encoding failures
  1666. or invalid output files.
  1667. @anchor{stats_enc_options}
  1668. @item -stats_enc_pre[:@var{stream_specifier}] @var{path} (@emph{output,per-stream})
  1669. @item -stats_enc_post[:@var{stream_specifier}] @var{path} (@emph{output,per-stream})
  1670. @item -stats_mux_pre[:@var{stream_specifier}] @var{path} (@emph{output,per-stream})
  1671. Write per-frame encoding information about the matching streams into the file
  1672. given by @var{path}.
  1673. @option{-stats_enc_pre} writes information about raw video or audio frames right
  1674. before they are sent for encoding, while @option{-stats_enc_post} writes
  1675. information about encoded packets as they are received from the encoder.
  1676. @option{-stats_mux_pre} writes information about packets just as they are about to
  1677. be sent to the muxer. Every frame or packet produces one line in the specified
  1678. file. The format of this line is controlled by @option{-stats_enc_pre_fmt} /
  1679. @option{-stats_enc_post_fmt} / @option{-stats_mux_pre_fmt}.
  1680. When stats for multiple streams are written into a single file, the lines
  1681. corresponding to different streams will be interleaved. The precise order of
  1682. this interleaving is not specified and not guaranteed to remain stable between
  1683. different invocations of the program, even with the same options.
  1684. @item -stats_enc_pre_fmt[:@var{stream_specifier}] @var{format_spec} (@emph{output,per-stream})
  1685. @item -stats_enc_post_fmt[:@var{stream_specifier}] @var{format_spec} (@emph{output,per-stream})
  1686. @item -stats_mux_pre_fmt[:@var{stream_specifier}] @var{format_spec} (@emph{output,per-stream})
  1687. Specify the format for the lines written with @option{-stats_enc_pre} /
  1688. @option{-stats_enc_post} / @option{-stats_mux_pre}.
  1689. @var{format_spec} is a string that may contain directives of the form
  1690. @var{@{fmt@}}. @var{format_spec} is backslash-escaped --- use \@{, \@}, and \\
  1691. to write a literal @{, @}, or \, respectively, into the output.
  1692. The directives given with @var{fmt} may be one of the following:
  1693. @table @option
  1694. @item fidx
  1695. Index of the output file.
  1696. @item sidx
  1697. Index of the output stream in the file.
  1698. @item n
  1699. Frame number. Pre-encoding: number of frames sent to the encoder so far.
  1700. Post-encoding: number of packets received from the encoder so far.
  1701. Muxing: number of packets submitted to the muxer for this stream so far.
  1702. @item ni
  1703. Input frame number. Index of the input frame (i.e. output by a decoder) that
  1704. corresponds to this output frame or packet. -1 if unavailable.
  1705. @item tb
  1706. Timebase in which this frame/packet's timestamps are expressed, as a rational
  1707. number @var{num/den}. Note that encoder and muxer may use different timebases.
  1708. @item tbi
  1709. Timebase for @var{ptsi}, as a rational number @var{num/den}. Available when
  1710. @var{ptsi} is available, @var{0/1} otherwise.
  1711. @item pts
  1712. Presentation timestamp of the frame or packet, as an integer. Should be
  1713. multiplied by the timebase to compute presentation time.
  1714. @item ptsi
  1715. Presentation timestamp of the input frame (see @var{ni}), as an integer. Should
  1716. be multiplied by @var{tbi} to compute presentation time. Printed as
  1717. (2^63 - 1 = 9223372036854775807) when not available.
  1718. @item t
  1719. Presentation time of the frame or packet, as a decimal number. Equal to
  1720. @var{pts} multiplied by @var{tb}.
  1721. @item ti
  1722. Presentation time of the input frame (see @var{ni}), as a decimal number. Equal
  1723. to @var{ptsi} multiplied by @var{tbi}. Printed as inf when not available.
  1724. @item dts (@emph{packet})
  1725. Decoding timestamp of the packet, as an integer. Should be multiplied by the
  1726. timebase to compute presentation time.
  1727. @item dt (@emph{packet})
  1728. Decoding time of the frame or packet, as a decimal number. Equal to
  1729. @var{dts} multiplied by @var{tb}.
  1730. @item sn (@emph{frame,audio})
  1731. Number of audio samples sent to the encoder so far.
  1732. @item samp (@emph{frame,audio})
  1733. Number of audio samples in the frame.
  1734. @item size (@emph{packet})
  1735. Size of the encoded packet in bytes.
  1736. @item br (@emph{packet})
  1737. Current bitrate in bits per second. Post-encoding only.
  1738. @item abr (@emph{packet})
  1739. Average bitrate for the whole stream so far, in bits per second, -1 if it cannot
  1740. be determined at this point. Post-encoding only.
  1741. @end table
  1742. Directives tagged with @emph{packet} may only be used with
  1743. @option{-stats_enc_post_fmt} and @option{-stats_mux_pre_fmt}.
  1744. Directives tagged with @emph{frame} may only be used with
  1745. @option{-stats_enc_pre_fmt}.
  1746. Directives tagged with @emph{audio} may only be used with audio streams.
  1747. The default format strings are:
  1748. @table @option
  1749. @item pre-encoding
  1750. @{fidx@} @{sidx@} @{n@} @{t@}
  1751. @item post-encoding
  1752. @{fidx@} @{sidx@} @{n@} @{t@}
  1753. @end table
  1754. In the future, new items may be added to the end of the default formatting
  1755. strings. Users who depend on the format staying exactly the same, should
  1756. prescribe it manually.
  1757. Note that stats for different streams written into the same file may have
  1758. different formats.
  1759. @end table
  1760. @section Preset files
  1761. A preset file contains a sequence of @var{option}=@var{value} pairs,
  1762. one for each line, specifying a sequence of options which would be
  1763. awkward to specify on the command line. Lines starting with the hash
  1764. ('#') character are ignored and are used to provide comments. Check
  1765. the @file{presets} directory in the FFmpeg source tree for examples.
  1766. There are two types of preset files: ffpreset and avpreset files.
  1767. @subsection ffpreset files
  1768. ffpreset files are specified with the @code{vpre}, @code{apre},
  1769. @code{spre}, and @code{fpre} options. The @code{fpre} option takes the
  1770. filename of the preset instead of a preset name as input and can be
  1771. used for any kind of codec. For the @code{vpre}, @code{apre}, and
  1772. @code{spre} options, the options specified in a preset file are
  1773. applied to the currently selected codec of the same type as the preset
  1774. option.
  1775. The argument passed to the @code{vpre}, @code{apre}, and @code{spre}
  1776. preset options identifies the preset file to use according to the
  1777. following rules:
  1778. First ffmpeg searches for a file named @var{arg}.ffpreset in the
  1779. directories @file{$FFMPEG_DATADIR} (if set), and @file{$HOME/.ffmpeg}, and in
  1780. the datadir defined at configuration time (usually @file{PREFIX/share/ffmpeg})
  1781. or in a @file{ffpresets} folder along the executable on win32,
  1782. in that order. For example, if the argument is @code{libvpx-1080p}, it will
  1783. search for the file @file{libvpx-1080p.ffpreset}.
  1784. If no such file is found, then ffmpeg will search for a file named
  1785. @var{codec_name}-@var{arg}.ffpreset in the above-mentioned
  1786. directories, where @var{codec_name} is the name of the codec to which
  1787. the preset file options will be applied. For example, if you select
  1788. the video codec with @code{-vcodec libvpx} and use @code{-vpre 1080p},
  1789. then it will search for the file @file{libvpx-1080p.ffpreset}.
  1790. @subsection avpreset files
  1791. avpreset files are specified with the @code{pre} option. They work similar to
  1792. ffpreset files, but they only allow encoder- specific options. Therefore, an
  1793. @var{option}=@var{value} pair specifying an encoder cannot be used.
  1794. When the @code{pre} option is specified, ffmpeg will look for files with the
  1795. suffix .avpreset in the directories @file{$AVCONV_DATADIR} (if set), and
  1796. @file{$HOME/.avconv}, and in the datadir defined at configuration time (usually
  1797. @file{PREFIX/share/ffmpeg}), in that order.
  1798. First ffmpeg searches for a file named @var{codec_name}-@var{arg}.avpreset in
  1799. the above-mentioned directories, where @var{codec_name} is the name of the codec
  1800. to which the preset file options will be applied. For example, if you select the
  1801. video codec with @code{-vcodec libvpx} and use @code{-pre 1080p}, then it will
  1802. search for the file @file{libvpx-1080p.avpreset}.
  1803. If no such file is found, then ffmpeg will search for a file named
  1804. @var{arg}.avpreset in the same directories.
  1805. @anchor{vstats_file_format}
  1806. @section vstats file format
  1807. The @code{-vstats} and @code{-vstats_file} options enable generation of a file
  1808. containing statistics about the generated video outputs.
  1809. The @code{-vstats_version} option controls the format version of the generated
  1810. file.
  1811. With version @code{1} the format is:
  1812. @example
  1813. frame= @var{FRAME} q= @var{FRAME_QUALITY} PSNR= @var{PSNR} f_size= @var{FRAME_SIZE} s_size= @var{STREAM_SIZE}kB time= @var{TIMESTAMP} br= @var{BITRATE}kbits/s avg_br= @var{AVERAGE_BITRATE}kbits/s
  1814. @end example
  1815. With version @code{2} the format is:
  1816. @example
  1817. out= @var{OUT_FILE_INDEX} st= @var{OUT_FILE_STREAM_INDEX} frame= @var{FRAME_NUMBER} q= @var{FRAME_QUALITY}f PSNR= @var{PSNR} f_size= @var{FRAME_SIZE} s_size= @var{STREAM_SIZE}kB time= @var{TIMESTAMP} br= @var{BITRATE}kbits/s avg_br= @var{AVERAGE_BITRATE}kbits/s
  1818. @end example
  1819. The value corresponding to each key is described below:
  1820. @table @option
  1821. @item avg_br
  1822. average bitrate expressed in Kbits/s
  1823. @item br
  1824. bitrate expressed in Kbits/s
  1825. @item frame
  1826. number of encoded frame
  1827. @item out
  1828. out file index
  1829. @item PSNR
  1830. Peak Signal to Noise Ratio
  1831. @item q
  1832. quality of the frame
  1833. @item f_size
  1834. encoded packet size expressed as number of bytes
  1835. @item s_size
  1836. stream size expressed in KiB
  1837. @item st
  1838. out file stream index
  1839. @item time
  1840. time of the packet
  1841. @item type
  1842. picture type
  1843. @end table
  1844. See also the @ref{stats_enc_options,,-stats_enc options} for an alternative way
  1845. to show encoding statistics.
  1846. @c man end OPTIONS
  1847. @chapter Examples
  1848. @c man begin EXAMPLES
  1849. @section Video and Audio grabbing
  1850. If you specify the input format and device then ffmpeg can grab video
  1851. and audio directly.
  1852. @example
  1853. ffmpeg -f oss -i /dev/dsp -f video4linux2 -i /dev/video0 /tmp/out.mpg
  1854. @end example
  1855. Or with an ALSA audio source (mono input, card id 1) instead of OSS:
  1856. @example
  1857. ffmpeg -f alsa -ac 1 -i hw:1 -f video4linux2 -i /dev/video0 /tmp/out.mpg
  1858. @end example
  1859. Note that you must activate the right video source and channel before
  1860. launching ffmpeg with any TV viewer such as
  1861. @uref{http://linux.bytesex.org/xawtv/, xawtv} by Gerd Knorr. You also
  1862. have to set the audio recording levels correctly with a
  1863. standard mixer.
  1864. @section X11 grabbing
  1865. Grab the X11 display with ffmpeg via
  1866. @example
  1867. ffmpeg -f x11grab -video_size cif -framerate 25 -i :0.0 /tmp/out.mpg
  1868. @end example
  1869. 0.0 is display.screen number of your X11 server, same as
  1870. the DISPLAY environment variable.
  1871. @example
  1872. ffmpeg -f x11grab -video_size cif -framerate 25 -i :0.0+10,20 /tmp/out.mpg
  1873. @end example
  1874. 0.0 is display.screen number of your X11 server, same as the DISPLAY environment
  1875. variable. 10 is the x-offset and 20 the y-offset for the grabbing.
  1876. @section Video and Audio file format conversion
  1877. Any supported file format and protocol can serve as input to ffmpeg:
  1878. Examples:
  1879. @itemize
  1880. @item
  1881. You can use YUV files as input:
  1882. @example
  1883. ffmpeg -i /tmp/test%d.Y /tmp/out.mpg
  1884. @end example
  1885. It will use the files:
  1886. @example
  1887. /tmp/test0.Y, /tmp/test0.U, /tmp/test0.V,
  1888. /tmp/test1.Y, /tmp/test1.U, /tmp/test1.V, etc...
  1889. @end example
  1890. The Y files use twice the resolution of the U and V files. They are
  1891. raw files, without header. They can be generated by all decent video
  1892. decoders. You must specify the size of the image with the @option{-s} option
  1893. if ffmpeg cannot guess it.
  1894. @item
  1895. You can input from a raw YUV420P file:
  1896. @example
  1897. ffmpeg -i /tmp/test.yuv /tmp/out.avi
  1898. @end example
  1899. test.yuv is a file containing raw YUV planar data. Each frame is composed
  1900. of the Y plane followed by the U and V planes at half vertical and
  1901. horizontal resolution.
  1902. @item
  1903. You can output to a raw YUV420P file:
  1904. @example
  1905. ffmpeg -i mydivx.avi hugefile.yuv
  1906. @end example
  1907. @item
  1908. You can set several input files and output files:
  1909. @example
  1910. ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
  1911. @end example
  1912. Converts the audio file a.wav and the raw YUV video file a.yuv
  1913. to MPEG file a.mpg.
  1914. @item
  1915. You can also do audio and video conversions at the same time:
  1916. @example
  1917. ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
  1918. @end example
  1919. Converts a.wav to MPEG audio at 22050 Hz sample rate.
  1920. @item
  1921. You can encode to several formats at the same time and define a
  1922. mapping from input stream to output streams:
  1923. @example
  1924. ffmpeg -i /tmp/a.wav -map 0:a -b:a 64k /tmp/a.mp2 -map 0:a -b:a 128k /tmp/b.mp2
  1925. @end example
  1926. Converts a.wav to a.mp2 at 64 kbits and to b.mp2 at 128 kbits. '-map
  1927. file:index' specifies which input stream is used for each output
  1928. stream, in the order of the definition of output streams.
  1929. @item
  1930. You can transcode decrypted VOBs:
  1931. @example
  1932. ffmpeg -i snatch_1.vob -f avi -c:v mpeg4 -b:v 800k -g 300 -bf 2 -c:a libmp3lame -b:a 128k snatch.avi
  1933. @end example
  1934. This is a typical DVD ripping example; the input is a VOB file, the
  1935. output an AVI file with MPEG-4 video and MP3 audio. Note that in this
  1936. command we use B-frames so the MPEG-4 stream is DivX5 compatible, and
  1937. GOP size is 300 which means one intra frame every 10 seconds for 29.97fps
  1938. input video. Furthermore, the audio stream is MP3-encoded so you need
  1939. to enable LAME support by passing @code{--enable-libmp3lame} to configure.
  1940. The mapping is particularly useful for DVD transcoding
  1941. to get the desired audio language.
  1942. NOTE: To see the supported input formats, use @code{ffmpeg -demuxers}.
  1943. @item
  1944. You can extract images from a video, or create a video from many images:
  1945. For extracting images from a video:
  1946. @example
  1947. ffmpeg -i foo.avi -r 1 -s WxH -f image2 foo-%03d.jpeg
  1948. @end example
  1949. This will extract one video frame per second from the video and will
  1950. output them in files named @file{foo-001.jpeg}, @file{foo-002.jpeg},
  1951. etc. Images will be rescaled to fit the new WxH values.
  1952. If you want to extract just a limited number of frames, you can use the
  1953. above command in combination with the @code{-frames:v} or @code{-t} option,
  1954. or in combination with -ss to start extracting from a certain point in time.
  1955. For creating a video from many images:
  1956. @example
  1957. ffmpeg -f image2 -framerate 12 -i foo-%03d.jpeg -s WxH foo.avi
  1958. @end example
  1959. The syntax @code{foo-%03d.jpeg} specifies to use a decimal number
  1960. composed of three digits padded with zeroes to express the sequence
  1961. number. It is the same syntax supported by the C printf function, but
  1962. only formats accepting a normal integer are suitable.
  1963. When importing an image sequence, -i also supports expanding
  1964. shell-like wildcard patterns (globbing) internally, by selecting the
  1965. image2-specific @code{-pattern_type glob} option.
  1966. For example, for creating a video from filenames matching the glob pattern
  1967. @code{foo-*.jpeg}:
  1968. @example
  1969. ffmpeg -f image2 -pattern_type glob -framerate 12 -i 'foo-*.jpeg' -s WxH foo.avi
  1970. @end example
  1971. @item
  1972. You can put many streams of the same type in the output:
  1973. @example
  1974. ffmpeg -i test1.avi -i test2.avi -map 1:1 -map 1:0 -map 0:1 -map 0:0 -c copy -y test12.nut
  1975. @end example
  1976. The resulting output file @file{test12.nut} will contain the first four streams
  1977. from the input files in reverse order.
  1978. @item
  1979. To force CBR video output:
  1980. @example
  1981. ffmpeg -i myfile.avi -b 4000k -minrate 4000k -maxrate 4000k -bufsize 1835k out.m2v
  1982. @end example
  1983. @item
  1984. The four options lmin, lmax, mblmin and mblmax use 'lambda' units,
  1985. but you may use the QP2LAMBDA constant to easily convert from 'q' units:
  1986. @example
  1987. ffmpeg -i src.ext -lmax 21*QP2LAMBDA dst.ext
  1988. @end example
  1989. @end itemize
  1990. @c man end EXAMPLES
  1991. @include config.texi
  1992. @ifset config-all
  1993. @ifset config-avutil
  1994. @include utils.texi
  1995. @end ifset
  1996. @ifset config-avcodec
  1997. @include codecs.texi
  1998. @include bitstream_filters.texi
  1999. @end ifset
  2000. @ifset config-avformat
  2001. @include formats.texi
  2002. @include protocols.texi
  2003. @end ifset
  2004. @ifset config-avdevice
  2005. @include devices.texi
  2006. @end ifset
  2007. @ifset config-swresample
  2008. @include resampler.texi
  2009. @end ifset
  2010. @ifset config-swscale
  2011. @include scaler.texi
  2012. @end ifset
  2013. @ifset config-avfilter
  2014. @include filters.texi
  2015. @end ifset
  2016. @include general_contents.texi
  2017. @end ifset
  2018. @chapter See Also
  2019. @ifhtml
  2020. @ifset config-all
  2021. @url{ffmpeg.html,ffmpeg}
  2022. @end ifset
  2023. @ifset config-not-all
  2024. @url{ffmpeg-all.html,ffmpeg-all},
  2025. @end ifset
  2026. @url{ffplay.html,ffplay}, @url{ffprobe.html,ffprobe},
  2027. @url{ffmpeg-utils.html,ffmpeg-utils},
  2028. @url{ffmpeg-scaler.html,ffmpeg-scaler},
  2029. @url{ffmpeg-resampler.html,ffmpeg-resampler},
  2030. @url{ffmpeg-codecs.html,ffmpeg-codecs},
  2031. @url{ffmpeg-bitstream-filters.html,ffmpeg-bitstream-filters},
  2032. @url{ffmpeg-formats.html,ffmpeg-formats},
  2033. @url{ffmpeg-devices.html,ffmpeg-devices},
  2034. @url{ffmpeg-protocols.html,ffmpeg-protocols},
  2035. @url{ffmpeg-filters.html,ffmpeg-filters}
  2036. @end ifhtml
  2037. @ifnothtml
  2038. @ifset config-all
  2039. ffmpeg(1),
  2040. @end ifset
  2041. @ifset config-not-all
  2042. ffmpeg-all(1),
  2043. @end ifset
  2044. ffplay(1), ffprobe(1),
  2045. ffmpeg-utils(1), ffmpeg-scaler(1), ffmpeg-resampler(1),
  2046. ffmpeg-codecs(1), ffmpeg-bitstream-filters(1), ffmpeg-formats(1),
  2047. ffmpeg-devices(1), ffmpeg-protocols(1), ffmpeg-filters(1)
  2048. @end ifnothtml
  2049. @include authors.texi
  2050. @ignore
  2051. @setfilename ffmpeg
  2052. @settitle ffmpeg media converter
  2053. @end ignore
  2054. @bye