ffmpeg-command-syntax

关键：FFmpeg 选项顺序规则

FFmpeg 最常见的错误，就是把选项放错位置。 FFmpeg 选项对位置敏感，并会作用于其后指定的下一个文件。

黄金法则

ffmpeg [global_options] {[input_options] -i input}... {[output_options] output}...

关键原则：选项作用于下一个文件。不同文件之间的选项会重置。

---

选项类别一览

类别	放置位置	典型成员
全局	最前面，在任何 -i 之前	-y、-n、-v、-hide_banner、-filter_complex、-init_hw_device
输入	上一个输出（或命令开头）与下一个 -i 之间	-ss、-t、-to、-re、-stream_loop、-hwaccel、-itsoffset
输出	所有 -i 之后、对应输出文件之前	-c:v、-c:a、-crf、-preset、-vf、-af、-map、-movflags

按类别整理的完整目录（包含每个选项及其说明）见 references/complete-option-reference.md。

全局选项（常用子集）

ffmpeg -y -hide_banner -v warning -i input.mp4 output.mp4

常用全局标志：-y、-n、-v/-loglevel、-stats、-progress、-report、-hide_banner、-filter_complex、-filter_complex_threads、-init_hw_device、-filter_hw_device。

输入选项（常用子集）

放在其作用对象 -i 紧前面。这些选项会影响文件的读取/解码方式。

最常用的选项：-ss、-t、-to、-itsoffset、-itsscale、-re、-readrate、-stream_loop、-hwaccel、-hwaccel_device、-hwaccel_output_format、-c:v/-c:a（用作解码器）、-r/-s/-pix_fmt（用于原始输入）、-accurate_seek、-thread_queue_size。

# Correct: Input options before their -i
ffmpeg -ss 00:01:00 -t 30 -i input.mp4 output.mp4

# Wrong: -ss after -i becomes an OUTPUT (slow) seek
ffmpeg -i input.mp4 -ss 00:01:00 output.mp4

硬件加速选项必须始终放在 -i 之前：

ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 \
  -c:v h264_nvenc output.mp4

输出选项（常用子集）

放在所有输入之后、其作用对象的输出文件之前。这些选项会影响文件的编码/写入方式。

最常用的选项：-c:v/-c:a/-c:s（用作编码器）、-b:v/-b:a、-crf、-qp、-preset、-tune、-profile:v、-level、-r/-s/-aspect/-pix_fmt、-vf/-af、-map、-ss/-t/-to（输出形式）、-fs、-frames:v/-frames:a、-movflags、-metadata、-disposition、-shortest、-an/-vn/-sn。

ffmpeg -i input.mp4 -c:v libx264 -crf 23 -preset medium output.mp4

---

会因位置不同而改变行为的选项

某些选项出现在 -i 之前或之后时，含义完全不同。

-ss（查找/起始时间）——位置至关重要

# BEFORE -i (INPUT): Fast keyframe seek, then decode to exact position with -accurate_seek (default)
ffmpeg -ss 00:01:00 -i input.mp4 -t 30 -c copy output.mp4

# AFTER -i (OUTPUT): Frame-accurate but slow - decodes everything, discards until target
ffmpeg -i input.mp4 -ss 00:01:00 -t 30 -c:v libx264 output.mp4

# BOTH (recommended): coarse seek + fine seek
ffmpeg -ss 00:00:55 -i input.mp4 -ss 00:00:05 -t 30 -c:v libx264 output.mp4

注意：放在 -i 之前的 -ss 会将时间戳重置为 0。使用 -copyts 可保留原始时间戳。

-t 和 -to

# -t BEFORE -i: limits how much of input to READ
ffmpeg -t 60 -i input.mp4 -c copy output.mp4

# -t AFTER -i: limits output DURATION
ffmpeg -i input.mp4 -t 60 -c copy output.mp4

# -ss + -to: with timestamp reset, -to is relative to new zero
ffmpeg -ss 00:01:00 -i input.mp4 -to 00:00:30 output.mp4  # 30s clip
ffmpeg -ss 00:01:00 -copyts -i input.mp4 -to 00:01:30 output.mp4  # also 30s clip

-r（帧率）

# BEFORE -i: input frame rate (raw/image sequences)
ffmpeg -r 30 -i frame_%04d.png output.mp4

# AFTER -i: output frame rate (adds/drops frames)
ffmpeg -i input.mp4 -r 24 output.mp4

-s（尺寸）

# BEFORE -i: raw input size
ffmpeg -s 1920x1080 -pix_fmt yuv420p -i raw.yuv output.mp4

# AFTER -i: scales output (prefer -vf scale instead)
ffmpeg -i input.mp4 -s 1280x720 output.mp4

-c / -codec

# BEFORE -i: DECODER selection
ffmpeg -c:v h264_cuvid -i input.mp4 -c:v h264_nvenc output.mp4

# AFTER -i: ENCODER selection (common case)
ffmpeg -i input.mp4 -c:v libx264 -c:a aac output.mp4

---

流指定符（简明形式）

使用 -option[:specifier] 指定目标流：

ffmpeg -i input.mkv -c:v libx264 -c:a aac -c:s mov_text output.mp4
ffmpeg -i a.mp4 -i b.mp4 -map 1:0 -c copy output.mp4

常见指定符：:v、:V、:a、:s、:d、:t、:v:0、:a:1、:0、:m:key:value、:p:0。完整表格和针对各流的示例见 references/stream-specifiers.md。

---

多个输入和输出

# Per-input options
ffmpeg \
  -ss 10 -i first.mp4 \
  -ss 5 -i second.mp4 \
  -filter_complex "[0:v][1:v]overlay" output.mp4

# Per-output options (they RESET between outputs)
ffmpeg -i input.mp4 \
  -c:v libx264 -crf 23 output_h264.mp4 \
  -c:v libx265 -crf 28 output_h265.mp4

# WRONG: second output silently gets no encoding options
ffmpeg -i input.mp4 -c:v libx264 -crf 23 out1.mp4 out2.mp4

---

常见错误及修正方法

1. 输入选项放在 -i 之后

# WRONG: -hwaccel after -i has no effect
ffmpeg -i input.mp4 -hwaccel cuda -c:v h264_nvenc output.mp4
# CORRECT
ffmpeg -hwaccel cuda -i input.mp4 -c:v h264_nvenc output.mp4

2. 输出选项放在 -i 之前

# WRONG: -c:v before -i tries to choose a decoder
ffmpeg -c:v libx264 -i input.mp4 output.mp4
# CORRECT
ffmpeg -i input.mp4 -c:v libx264 output.mp4

3. 误以为选项会延续到后续输出

# WRONG
ffmpeg -i input.mp4 -c:v libx264 -crf 23 out1.mp4 out2.mp4
# CORRECT
ffmpeg -i input.mp4 \
  -c:v libx264 -crf 23 out1.mp4 \
  -c:v libx264 -crf 23 out2.mp4

4. 为保证精度而将 -ss 放在错误位置

# Fast but may snap to keyframe
ffmpeg -ss 00:05:00 -i input.mp4 -t 30 -c copy output.mp4
# Accurate but slow
ffmpeg -i input.mp4 -ss 00:05:00 -t 30 -c:v libx264 output.mp4
# Fast AND accurate
ffmpeg -ss 00:04:55 -i input.mp4 -ss 5 -t 30 -c:v libx264 output.mp4

5. 混淆输入和输出

# WRONG
ffmpeg -i input1.mp4 -c:v libx264 output1.mp4 -i input2.mp4 output2.mp4
# CORRECT
ffmpeg -i input1.mp4 -i input2.mp4 \
  -map 0 -c:v libx264 output1.mp4 \
  -map 1 -c:v libx264 output2.mp4

6. 时间戳重置时混淆 -t 和 -to

ffmpeg -ss 00:01:00 -i input.mp4 -to 00:00:30 output.mp4         # 30s clip
ffmpeg -ss 00:01:00 -copyts -i input.mp4 -to 00:01:30 output.mp4 # 30s clip
ffmpeg -ss 00:01:00 -i input.mp4 -t 00:00:30 output.mp4          # 30s clip

7. 混淆 -vf 和 -filter_complex

# Single-input filter (per-output)
ffmpeg -i input.mp4 -vf "scale=1280:720" output.mp4

# Multi-input filter (global)
ffmpeg -i video.mp4 -i overlay.png \
  -filter_complex "[0:v][1:v]overlay=10:10" output.mp4

# WRONG: -vf cannot reference multiple inputs
ffmpeg -i video.mp4 -i overlay.png -vf "overlay=10:10" output.mp4

---

命令结构示例

# Basic transcode
ffmpeg -i input.mp4 -c:v libx264 -crf 23 -c:a aac output.mp4

# With input seeking
ffmpeg -ss 60 -i input.mp4 -t 30 -c:v libx264 output.mp4

# Hardware acceleration
ffmpeg -hwaccel cuda -hwaccel_output_format cuda -i input.mp4 \
  -c:v h264_nvenc -preset p4 output.mp4

# Multiple inputs with filters
ffmpeg -i main.mp4 -i overlay.png \
  -filter_complex "[0:v][1:v]overlay=10:10[v]" \
  -map "[v]" -map 0:a -c:v libx264 -c:a copy output.mp4

# Real-time streaming
ffmpeg -re -i input.mp4 -c:v libx264 -f flv rtmp://server/live/stream

# Full structure
ffmpeg \
  -y -hide_banner \
  -hwaccel cuda -ss 10 -i input1.mp4 \
  -stream_loop -1 -i input2.mp4 \
  -filter_complex "[0:v][1:v]overlay[v]" \
  -map "[v]" -map 0:a \
  -c:v h264_nvenc -b:v 5M \
  -c:a aac -b:a 192k \
  -movflags +faststart \
  output.mp4

---

快速放置速查表

选项	-i 之前	-i 之后	备注
-ss	快速 seek	精确 seek	之前 = 关键帧，之后 = 解码
-t	输入限制	输出限制	读取与写入
-to	输入结束时间	输出结束时间	受时间戳重置影响
-r	输入 FPS	输出 FPS	原始 / 输出转换
-s	输入尺寸	输出尺寸	原始 / 缩放
-c:v/-c:a	解码器	编码器	之前 = 解码
-hwaccel、-re、-itsoffset、-stream_loop	必需	不适用	仅用于输入
-vf、-af、-map、-crf、-preset、-movflags	不适用	必需	仅用于输出
-y、-v、-filter_complex	全局	全局	放在最前面

---

扩展参考索引

如需全面查找，请参阅配套参考文件：

• 完整选项目录（所有全局 / 输入 / 输出 / 颜色 / 线程 / 格式标志表）：references/complete-option-reference.md
• 流指定符语法和示例：references/stream-specifiers.md
• 各后端硬件设备初始化（CUDA、VAAPI、QSV、Vulkan、D3D11VA、VideoToolbox）：references/hardware-device-init.md
• 格式 / 协议 / 复用器选项（HLS、DASH、segment、RTSP、RTMP、原始视频、movflags、MPEG-TS、Matroska）：references/format-specific-options.md
• 时间戳、比特流过滤器、元数据、附件、处置方式：references/timestamps-bitstream-metadata.md

---

外部参考

• FFmpeg 文档
• FFmpeg Wiki - Seeking
• 流指定符
• FFmpeg 格式文档
• FFmpeg 比特流过滤器