FFmpeg

文档命令行工具

文档目录命令行工具

ffmpeg 命令行工具

用法总览

ffmpeg [global_options] {[input_file_options] -i input_url} ... {[output_file_options] output_url} ...

简介

ffmpeg 是通用媒体转换器：读取各种输入（含采集/录制设备），滤镜处理后转码输出。输入用 -i 指定，输出以裸 URL 给出，无法解释为选项的内容都视为输出 URL。每个输入/输出可含多路视频/音频/字幕/附件/数据流（受封装格式限制），哪些流进哪个输出自动选择或用 -map 指定；引用流用 0 起索引（2:3 即第 3 输入第 4 路流）。

通例：选项作用于紧随其后的文件、顺序重要、可多次出现；全局选项（如日志级别）最先写、先输入后输出。

示例（转码；视频码率 64 kbit/s；强制输出帧率；强制输入帧率、输出 24 fps）：

ffmpeg -i input.avi output.mp4
ffmpeg -i input.avi -b:v 64k -bufsize 64k output.mp4
ffmpeg -i input.avi -r 24 output.mp4
ffmpeg -r 1 -i input.m2v -r 24 output.mp4

详细说明

ffmpeg 用下列组件搭建转码管线，数据块从源流向宿、途中被加工：

  • 解流器（demuxer）读取输入、提取全局属性与各基本流；每 -i 一实例，编码包发给解码器或混流器。
  • 解码器把编码包解码为原始帧（视频像素数组、音频 PCM），编码器再把原始帧编码为包（多有损；字幕编码器直取解码器输出，字幕滤镜尚不支持）。
  • 滤镜图处理原始帧：简单图一进一出同类型、绑定输出流（如 yadif 接 scale）用 -filter；复杂图独立于流、可多进多出（如 overlay，音频 amix）用 -filter_complex。
  • 混流器（muxer）接收各路编码包，交错后写入输出。

流复制（Streamcopy）

最简管线：只复制包，不解码、不滤镜、不编码。三条命令依次：取第 2 路流、合并两输入、拆到两输出：

ffmpeg -i INPUT.mkv -map 0:1 -c copy OUTPUT.mp4
ffmpeg -i INPUT0.mkv -i INPUT1.aac -map 0:0 -map 1:0 -c copy OUTPUT.mp4
ffmpeg -i INPUT.mkv -map 0:0 -c copy OUTPUT0.mp4 -map 0:1 -c copy OUTPUT1.mp4

-map 用几次建几路流；非全局选项只对其后文件生效，每个输出需各自写 -c。流复制适合改流数量、换封装、改容器元数据：极快零损失，但可能因目标容器信息缺失失败、也无法用滤镜。

转码（Transcoding）

转码即解码后再编码，开销大且多有损，仅在需滤镜或目标解不了原编解码器时用；未指定 -c copy 的流默认转码。下例 :v/:a 各指定转码与复制：

ffmpeg -i INPUT.mkv -map 0:v -map 0:a -c:v libx264 -c:a copy OUTPUT.mp4

滤镜（Filtering）

简单滤镜图用 -filter（别名 -vf/-af）按输出流配置，多路音频各建一图。复杂图即无法描述为单流线性链的图，用全局 -filter_complex、每用一次新建一图。

环回解码器（Loopback decoders）

环回解码器解码某编码器输出并送回复杂滤镜图：-dec 输出流索引 创建、标签中引用，解码侧 AVOptions 写在 -dec 前。下例低质量编码、环回解码后与原输入并排、无损输出：

ffmpeg -i INPUT                                        \
  -map 0:v:0 -c:v libx264 -crf 45 -f null -            \
  -threads 3 -dec 0:0                                  \
  -filter_complex '[0:v][dec:0]hstack[stack]'          \
  -map '[stack]' -c:v ffv1 OUTPUT

流选择

-map 手动选择每个输出的流，不写则自动选择；-vn/-an/-sn/-dn 分别跳过视频/音频/字幕/数据流（复杂滤镜图输出除外）。

自动流选择

无 map 时按输出格式可容纳的类型各选一路：视频取分辨率最高、音频取声道最多、字幕取第一个（编码器分文本/图像、只选同类）；同条件取最小索引；数据/附件流仅靠 -map。

手动流选择

-map 后输出只含映射的流（下节例外）。

复杂滤镜图

无标签图输出 pad 进第一个输出文件（跳过同类型自动选择、类型不支持则致命）；带标签输出须恰好映射一次。

流处理

流处理经指向输出内流的 -codec 设置、选择之后应用；未指定时用混流器默认编码器。字幕例外：指定字幕编码器时任意类型第一路字幕都入选，不校验转换与混流可行性、失败即中止全部输出。

示例

假定 A.avi（640x360 视频+2ch 音频）、B.mp4（1080p 视频、2ch/5.1 音频、两路文本字幕）、C.mkv（720p 视频+2ch 音频、图像字幕）。

ffmpeg -i A.avi -i B.mp4 out1.mkv out2.wav -map 1:a -c:a copy out3.mov

out1 自动选 B 的视频/5.1 音频/第一路文本字幕；out2 只装音频；out3 仅含 B 音频。前两者转码、第三个直通。

ffmpeg -i C.mkv out1.mkv -c:s dvdsub -an out2.mkv

out1 不选字幕（图像类与默认文本编码器不匹配）；out2 因显式 -c:s 才选入。

ffmpeg -i A.avi -i C.mkv -i B.mp4 -filter_complex "overlay" out1.mp4 out2.srt

overlay 自动取前两路视频、无标签输出进 out1 并跳过视频自动选择；out2 只收文本字幕，选 B 流 2。

ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0[outv];overlay;aresample" \
       -map '[outv]' -an        out1.mp4 \
                                out2.mkv \
       -map '[outv]' -map 1:a:0 out3.mkv

失败：[outv] 映射两次；若删去两处 -map '[outv]' 则带标签输出未被映射、同样失败。应改为：

ffmpeg -i A.avi -i B.mp4 -i C.mkv -filter_complex "[1:v]hue=s=0,split=2[outv1][outv2];overlay;aresample" \
        -map '[outv1]' -an        out1.mp4 \
                                  out2.mkv \
        -map '[outv2]' -map 1:a:0 out3.mkv

split 把 hue 输出映射给 out1/out3；overlay、aresample 的无标签输出仍进 out1（-an 不拦滤镜图输出）。

选项

数值选项可跟 SI 前缀 K/M/G（i 按 1024 为底、B 乘 8）；布尔选项名前加 no 置 false；短横线后加 / 从文件加载参数值（例 ffmpeg -i INPUT -/filter:v filter.script OUTPUT）。

流说明符

冒号附于选项名后指定作用流：-codec:a:1 ac3、-b:a 128k（全部音频）、空说明符匹配所有流。形式：

  • stream_index：按索引（-threads:1 4）。
  • stream_type[:附加说明符]：v/V（V 排除附件图片/封面）、a、s、d、t。
  • g:... 流组；p:program_id:...；#stream_id/i:stream_id（如 MPEG-TS 的 PID）；m:key[:value] 按元数据（冒号转义，仅输入可靠）；disp:... 按 disposition；u 匹配配置可用的流。

通用选项

ff* 工具共享，完整列表见官方手册：

  • -L、-h/-help [arg]（arg：long、full、decoder=名 等）、-version、-buildconf；查询：-formats、-demuxers、-muxers、-devices、-codecs、-decoders、-encoders、-bsfs、-protocols、-filters、-pix_fmts、-sample_fmts、-layouts、-dispositions、-colors、-sources/-sinks。
  • -loglevel [flags+]级别：quiet/panic/fatal/error/warning/info（默认）/verbose/debug/trace，对应数字 -8 至 56；flags repeat/level/time/datetime 用 +/- 开关；-report（转储日志，FFREPORT 等效）、-hide_banner、-cpuflags/-cpucount（仅测试）、-max_alloc（堆上限）。

AVOptions

由 libavformat/libavdevice/libavcodec 提供：generic 适用任何容器/编解码器/设备（-b、-threads 即属此类），private 为特定对象专有；编解码器 AVOptions 逐流、应附流说明符；布尔项写 -option 0/-option 1。例（id3v2_version 私有选项写 ID3v2.3 头）：

ffmpeg -i input.flac -id3v2_version 3 out.mp3

主要选项

完整列表见官方手册：

  • -f fmt 强制格式；-i url 输入 URL；-y/-n 覆盖/不覆盖输出；-stream_loop n 循环输入（-1 无限）。
  • -c[:spec] codec（即 -codec）：选编码器（输出前）/解码器（输入前），copy 不重编码；同一流取最后匹配的 -c。
  • -t/-to 限时长/到点停止（互斥，-t 优先）；-fs 限输出字节数。
  • -ss position 输入侧 seek（转码丢弃多余段、流复制保留）/输出侧解码丢弃到该点；-sseof 相对 EOF；-itsoffset 加偏移。
  • -metadata[:spec] k=v 设元数据（可及流/章节/program，空值删除）；-frames[:spec] n 限帧数；-q[:spec] 固定质量 VBR；-filter[:spec] 滤镜图；-pre[:spec] 预设。
  • 其他：-stats 进度统计、-progress url、-nostdin、-attach 附件、-target vcd|svcd|dvd|dv|dv50（自动套用全套参数）。

视频选项

  • -r[:spec] fps：输入侧忽略时间戳按恒定 fps 生成（异于 image2/v4l2 的 -framerate）；输出侧补/丢帧至恒定帧率，流复制仅告知混流器；-fpsmax 限上限。
  • -s[:spec] wxh：输入侧为裸视频/采集设备 video_size 快捷写法，输出侧在滤镜图末尾插 scale；-aspect[:spec] 设显示宽高比（配 -vcodec copy 只改容器记录）。
  • -vn 屏蔽/禁用视频流；-vcodec、-vf 为 -codec:v、-filter:v 别名；-pass 1|2 两遍编码；-autorotate/-autoscale 默认开。
  • 高级：-pix_fmt[:spec]（前缀 + 则选不到即报错）、-sws_flags、-force_key_frames（时间点/expr:/source）、-vtag、-vstats、-hwaccel 系列、-display_* 三选项、-stereo3d。

音频选项

-ar[:spec] freq 采样率、-ac[:spec] channels 声道数（输入侧仅对采集设备与裸解流器有意义）；-an 屏蔽/禁用音频流；-acodec、-af 为 -codec:a、-filter:a 别名；-aq 即 -q:a；-sample_fmt[:spec] 采样格式；高级：-ch_layout/-channel_layout、-guess_layout_max、-atag。

字幕选项

-scodec 为 -codec:s 别名；-sn 屏蔽/禁用字幕流；-fix_sub_duration 修正字幕时长（DVB 字幕需要，增延迟与内存）；-canvas_size 渲染画布。

高级选项

  • -map [-]input_file_id[:stream_specifier][:view_specifier][:?] | [linklabel]：创建输出流；- 负映射剔除、? 可选、[linklabel] 映射复杂图输出；可多次使用、按序建流，写了即关闭默认映射，如 -map 0（全部流）、-map -0:a:1（除第二路音频）、-map 0:m:language:eng（按语言）：

  • -map_metadata[:spec_out] infile[:spec_in] 复制元数据（说明符 g/s:/c:/p:，如 ffmpeg -i in.mkv -map_metadata:s:a 0:g out.mkv）；-map_chapters 复制章节（负值禁用）；-ignore_unknown/-copy_unknown。

  • -filter_complex filtergraph（全局）：复杂图，可多次。输入标签 [file_index:stream_specifier]、[dec:dec_idx] 或另一图输出标签；未加标签输入自动接第一路未用同类型流；无标签输出进第一个输出。位图字幕流可作输入转视频（实验性）；lavfi 源无需输入文件：

    ffmpeg -i video.mkv -i image.png -filter_complex 'overlay' out.mkv
ffmpeg -filter_complex 'color=c=red' -t 5 out.mkv

  • 时间戳、速度与输出控制：-copyts、-start_at_zero、-copytb、-readrate/-re（-re=-readrate 1）、-fps_mode（cfr/avr/vfr）、-apad、-shortest、-muxdelay/-muxpreload、-streamid、-bsf[:spec]（如 -c copy -bsf:v h264_mp4toannexb）、-tag、-timecode。

  • 调试与稳健性：-benchmark、-timelimit、-dump/-hex、-discard、-xerror、-bitexact、-thread_queue_size、-stats_enc_pre/-stats_enc_post/-stats_mux_pre、-stream_group（IAMF）、-program 等。

预设文件

预设文件每行一个 option=value、# 注释，见源码树 presets。ffpreset 用 vpre/apre/spre/fpre 指定（fpre 给文件名），在 $FFMPEG_DATADIR、$HOME/.ffmpeg、datadir 依次找 arg.ffpreset、codec_name-arg.ffpreset；avpreset 用 pre 指定、两名称顺序相反。

vstats 文件格式

-vstats/-vstats_file 逐帧输出帧号、q、PSNR、大小、码率等，格式见官方手册。

示例

视频与音频采集

指定格式与设备直接采集（第二条以 ALSA 单声道、1 号声卡替代 OSS）；启动前用 xawtv 等选对视频源与频道、设好录音电平：

ffmpeg -f oss -i /dev/dsp -f video4linux2 -i /dev/video0 /tmp/out.mpg
ffmpeg -f alsa -ac 1 -i hw:1 -f video4linux2 -i /dev/video0 /tmp/out.mpg

X11 采集

0.0 为 display.screen 号（同 DISPLAY），第二例 10、20 为 x、y 偏移：

ffmpeg -f x11grab -video_size cif -framerate 25 -i :0.0 /tmp/out.mpg
ffmpeg -f x11grab -video_size cif -framerate 25 -i :0.0+10,20 /tmp/out.mpg

视频与音频格式转换

任何支持的格式与协议都可作输入。依次：YUV 文件输入（Y 平面加半分辨率 U、V，尺寸不明用 -s）；读写裸 YUV420P；多输入合一输出；转 22050 Hz MPEG 音频；一次输出两路不同码率 MP2：

ffmpeg -i /tmp/test%d.Y /tmp/out.mpg
ffmpeg -i /tmp/test.yuv /tmp/out.avi
ffmpeg -i mydivx.avi hugefile.yuv
ffmpeg -i /tmp/a.wav -s 640x480 -i /tmp/a.yuv /tmp/a.mpg
ffmpeg -i /tmp/a.wav -ar 22050 /tmp/a.mp2
ffmpeg -i /tmp/a.wav -map 0:a -b:a 64k /tmp/a.mp2 -map 0:a -b:a 128k /tmp/b.mp2

典型 DVD 抓取（VOB 转 MPEG-4+MP3 AVI；B 帧兼容 DivX5；GOP 300 即 29.97fps 每 10 秒一个帧内帧；MP3 需以 --enable-libmp3lame 编译）：

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

抽帧与合成（foo-%03d.jpeg 序号按 C printf 补零；-pattern_type glob 展开通配符；限量配 -frames:v/-t、起点 -ss）：

ffmpeg -i foo.avi -r 1 -s WxH -f image2 foo-%03d.jpeg
ffmpeg -f image2 -framerate 12 -i foo-%03d.jpeg -s WxH foo.avi
ffmpeg -f image2 -pattern_type glob -framerate 12 -i 'foo-*.jpeg' -s WxH foo.avi

输出多路同类型流（逆序含两输入前四路流）；强制 CBR；lmin/lmax 等用 lambda 单位（QP2LAMBDA 自 q 换算）：

ffmpeg -i test1.avi -i test2.avi -map 1:1 -map 1:0 -map 0:1 -map 0:0 -c copy -y test12.nut
ffmpeg -i myfile.avi -b 4000k -minrate 4000k -maxrate 4000k -bufsize 1835k out.m2v
ffmpeg -i src.ext -lmax 21*QP2LAMBDA dst.ext

参见

ffmpeg-all、ffplay、ffprobe，以及 ffmpeg-utils、ffmpeg-scaler、ffmpeg-resampler、ffmpeg-codecs、ffmpeg-bitstream-filters、ffmpeg-formats、ffmpeg-devices、ffmpeg-protocols、ffmpeg-filters 各手册（https://ffmpeg.org/<名称>.html）

作者

FFmpeg 开发者，详见 Git 历史；维护者列在源码树 MAINTAINERS。

对照官方英文原文疑难杂症查 FFmpeg Wiki