ffplay 文档

1 概要

ffplay [options] [input_url]

2 描述

FFplay 是一个非常简单、可移植的媒体播放器，使用了 FFmpeg 库和 SDL 库，主要用作各种 FFmpeg API 的测试平台。

3 选项

除非另有说明，所有数值选项都接受一个表示数字的字符串作为输入，其后可以跟随一个 SI 单位前缀，例如：’K’、’M’ 或 ’G’。

如果在 SI 单位前缀后面附加 ’i’，则整个前缀会被解释为二进制倍数的单位前缀，即以 1024 的幂而非 1000 的幂为基础。在 SI 单位前缀后附加 ’B’ 会使数值乘以 8。这样便可以使用例如 ’KB’、’MiB’、’G’ 和 ’B’ 之类的数字后缀。

不带参数的选项是布尔选项，会把对应的值设为 true。在选项名前加上 "no" 前缀可以将其设为 false。例如使用 "-nofoo" 会把名为 "foo" 的布尔选项设为 false。

带参数的选项支持一种特殊语法：命令行中给出的参数会被解释为一个文件路径，实际的参数值将从该文件中加载。要使用此功能，请在选项名之前（紧跟在前导短横线之后）加上一个正斜杠 ’/’。例如：

ffmpeg -i INPUT -/filter:v filter.script OUTPUT

这会从名为 filter.script 的文件中加载 filtergraph 描述。

3.1 流指定符

有些选项按流应用，例如 bitrate 或 codec。流指定符用于精确指定某个选项属于哪个（些）流。

流指定符通常是附加在选项名之后、以冒号分隔的字符串。例如 -codec:a:1 ac3 中包含 a:1 这个流指定符，它匹配第二个音频流。因此，这会为第二个音频流选择 ac3 codec。

流指定符可以匹配多个流，此时该选项会应用到所有这些流上。例如 -b:a 128k 中的流指定符匹配所有音频流。

空的流指定符匹配所有流。例如，-codec copy 或 -codec: copy 会在不重新编码的情况下复制所有流。

流指定符可能采用以下形式：

stream_index

匹配具有该索引的流。例如 -threads:1 4 会把第二个流的线程数设为 4。如果 stream_index 被用作附加流指定符（见下文），则会从匹配到的流中选择第 stream_index 个流。流的编号基于 libavformat 检测到的流顺序，但如果同时指定了流组指定符或节目 ID，则例外，此时基于流在组或节目内的顺序。

stream_type[:additional_stream_specifier]

stream_type 可以是下列值之一：’v’ 或 ’V’ 表示视频，’a’ 表示音频，’s’ 表示字幕，’d’ 表示数据，’t’ 表示附件。’v’ 匹配所有视频流，’V’ 只匹配非附属图片、视频缩略图或封面图的视频流。如果使用了 additional_stream_specifier，则匹配同时具有该类型且匹配 additional_stream_specifier 的流；否则匹配指定类型的所有流。

g:group_specifier[:additional_stream_specifier]

匹配属于指定符为 group_specifier 的组的流。如果使用了 additional_stream_specifier，则匹配既属于该组、又匹配 additional_stream_specifier 的流。group_specifier 可以是下列值之一：

group_index

匹配具有该组索引的流。

#group_id or i:group_id

匹配具有该组 ID 的流。

p:program_id[:additional_stream_specifier]

匹配属于 ID 为 program_id 的节目的流。如果使用了 additional_stream_specifier，则匹配既属于该节目、又匹配 additional_stream_specifier 的流。

#stream_id or i:stream_id

按流 ID（例如 MPEG-TS container 中的 PID）匹配流。

m:key[:value]

匹配元数据标签 key 具有指定 value 的流。如果没有给出 value，则匹配包含该标签（不论其值）的流。key 或 value 中的冒号字符 ’:’ 需要用反斜杠转义。

disp:dispositions[:additional_stream_specifier]

匹配具有给定 disposition 的流。dispositions 是一个或多个 disposition（形式与 -dispositions 选项输出的一致）用 ’+’ 连接而成的列表。

u

匹配具有可用配置的流：codec 必须已定义，且视频尺寸或音频采样率等必要信息必须存在。

请注意，在 ffmpeg 中，按元数据匹配只对输入文件正常起作用。

3.2 通用选项

这些选项在各个 ff* 工具之间是共用的。

-L, -license

显示许可证。

-h, -?, -help, --help [arg]

显示帮助。可以指定一个可选参数，用于打印关于特定项目的帮助。如果未指定参数，则只显示基本（非高级）工具选项。

arg 可以取下列值：

long

除基本工具选项外，还打印高级工具选项。

full

打印选项的完整列表，包括 encoder、decoder、demuxer、muxer、滤镜等的共用选项和私有选项。

decoder=decoder_name

打印名为 decoder_name 的 decoder 的详细信息。可以用 -decoders 选项获取所有 decoder 的列表。

encoder=encoder_name

打印名为 encoder_name 的 encoder 的详细信息。可以用 -encoders 选项获取所有 encoder 的列表。

demuxer=demuxer_name

打印名为 demuxer_name 的 demuxer 的详细信息。可以用 -formats 选项获取所有 demuxer 和 muxer 的列表。

muxer=muxer_name

打印名为 muxer_name 的 muxer 的详细信息。可以用 -formats 选项获取所有 muxer 和 demuxer 的列表。

filter=filter_name

打印名为 filter_name 的滤镜的详细信息。可以用 -filters 选项获取所有滤镜的列表。

bsf=bitstream_filter_name

打印名为 bitstream_filter_name 的 bitstream 过滤器的详细信息。可以用 -bsfs 选项获取所有 bitstream 过滤器的列表。

protocol=protocol_name

打印名为 protocol_name 的协议的详细信息。可以用 -protocols 选项获取所有协议的列表。

-version

显示版本。

-buildconf

显示构建配置，每行一个选项。

-formats

显示可用的格式（包括设备）。

-demuxers

显示可用的 demuxer。

-muxers

显示可用的 muxer。

-devices

显示可用的设备。

-codecs

显示 libavcodec 已知的所有 codec。

请注意，本文档通篇将 ’codec’ 一词用作媒体 bitstream 格式这一更准确说法的简称。

-decoders

显示可用的 decoder。

-encoders

显示所有可用的 encoder。

-bsfs

显示可用的 bitstream 过滤器。

-protocols

显示可用的协议。

-filters

显示可用的 libavfilter 滤镜。

-pix_fmts

显示可用的 pixel format。

-sample_fmts

显示可用的 sample format。

-layouts

显示声道名称和标准声道布局。

-dispositions

显示流的 disposition。

-colors

显示可识别的颜色名称。

-sources device[,opt1=val1[,opt2=val2]...]

显示输入设备自动检测到的源。有些设备可能提供无法自动检测的系统相关源名称。不能假定返回的列表总是完整的。

ffmpeg -sources pulse,server=192.168.0.4

-sinks device[,opt1=val1[,opt2=val2]...]

显示输出设备自动检测到的汇。有些设备可能提供无法自动检测的系统相关汇名称。不能假定返回的列表总是完整的。

ffmpeg -sinks pulse,server=192.168.0.4

-loglevel [flags+]loglevel | -v [flags+]loglevel

设置库使用的日志级别和标志。

可选的 flags 前缀可以由下列值组成：

‘repeat’

表示重复的日志输出不应压缩到第一行，且 "Last message repeated n times" 这一行会被省略。

‘level’

表示应在每条消息行前添加 [level] 前缀。这可用作日志着色的替代方案，例如在把日志转储到文件时。

‘time’

表示日志行前应加上时间信息。

‘datetime’

表示日志行前应加上日期和时间信息。

flags 也可以通过添加 ’+’/’-’ 前缀单独使用，在不影响其他标志或不改变 loglevel 的情况下设置/重置单个标志。同时设置 flags 和 loglevel 时，最后一个 flags 值和 loglevel 之间需要有 ’+’ 分隔符。

loglevel 是一个字符串或数字，取值为下列之一：

‘quiet, -8’

什么都不显示，保持静默。

‘panic, 0’

只显示可能导致进程崩溃的致命错误，例如断言失败。目前尚未在任何地方使用。

‘fatal, 8’

只显示致命错误。这些是使进程绝对无法继续运行的错误。

‘error, 16’

显示所有错误，包括可以恢复的错误。

‘warning, 24’

显示所有警告和错误。任何与可能不正确或意外事件相关的消息都会显示。

‘info, 32’

在处理过程中显示信息性消息。这是在警告和错误之外附加显示的。这是默认值。

‘verbose, 40’

与 info 相同，只是更详细。

‘debug, 48’

显示一切内容，包括调试信息。

‘trace, 56’

例如，要启用重复日志输出、添加 level 前缀，并把 loglevel 设为 verbose：

ffmpeg -loglevel repeat+level+verbose -i input output

另一个例子：在不影响 level 前缀标志或 loglevel 当前状态的情况下启用重复日志输出：

ffmpeg [...] -loglevel +repeat

默认情况下，程序会把日志输出到标准错误。如果终端支持着色，会用颜色标出错误和警告。设置环境变量 AV_LOG_FORCE_NOCOLOR 可以禁用日志着色，设置环境变量 AV_LOG_FORCE_COLOR 可以强制启用。

-report

把完整的命令行和日志输出转储到当前目录下一个名为 program-YYYYMMDD-HHMMSS.log 的文件中。这个文件对错误报告很有用。它还隐含指定了 -loglevel debug。

把环境变量 FFREPORT 设为任意值也有相同的效果。如果该值是以 ’:’ 分隔的 key=value 序列，这些选项会影响报告；如果选项值中包含特殊字符或选项分隔符 ’:’，则必须进行转义（参见 ffmpeg-utils 手册中的 “Quoting and escaping” 小节）。

可识别以下选项：

file

设置用于报告的文件名；%p 会展开为程序名，%t 会展开为时间戳，%% 会展开为一个纯粹的 %

level

用数值设置日志的详细级别（参见 -loglevel）。

例如，要以日志级别 32（日志级别 info 的别名）把报告输出到名为 ffreport.log 的文件：

FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output

解析环境变量时发生的错误不是致命的，也不会出现在报告中。

-hide_banner

禁止打印横幅信息。

所有 FFmpeg 工具通常都会显示版权声明、构建选项和库版本。这个选项可用于禁止打印这些信息。

-cpuflags flags (global)

允许设置和清除 CPU 标志。这个选项用于测试。除非你清楚自己在做什么，否则请勿使用。

ffmpeg -cpuflags -sse+mmx ...
ffmpeg -cpuflags mmx ...
ffmpeg -cpuflags 0 ...

此选项可用的标志如下：

‘x86’

‘mmx’ ‘mmxext’ ‘sse’ ‘sse2’ ‘sse2slow’ ‘sse3’ ‘sse3slow’ ‘ssse3’ ‘atom’ ‘sse4.1’ ‘sse4.2’ ‘avx’ ‘avx2’ ‘xop’ ‘fma3’ ‘fma4’ ‘3dnow’ ‘3dnowext’ ‘bmi1’ ‘bmi2’ ‘cmov’ ‘ARM’

‘armv5te’ ‘armv6’ ‘armv6t2’ ‘vfp’ ‘vfpv3’ ‘neon’ ‘setend’ ‘AArch64’

‘armv8’ ‘vfp’ ‘neon’ ‘PowerPC’

‘altivec’ ‘Specific Processors’

‘pentium2’ ‘pentium3’ ‘pentium4’ ‘k6’ ‘k62’ ‘athlon’ ‘athlonxp’ ‘k8’ -cpucount count (global)

覆盖对 CPU 数量的检测。这个选项用于测试。除非你清楚自己在做什么，否则请勿使用。

ffmpeg -cpucount 2

-max_alloc bytes

为 ffmpeg 的 malloc 系列函数在堆上分配的块设置最大大小上限。使用此选项时请格外小心。如果你不完全理解这样做的后果，请勿使用。默认值为 INT_MAX。

3.3 AVOptions

这些选项由 libavformat、libavdevice 和 libavcodec 库直接提供。要查看可用 AVOptions 的列表，请使用 -help 选项。它们分为两类：

generic

这些选项可以为任意 container、codec 或设备设置。generic 选项在 container/设备下列在 AVFormatContext options 中，在 codec 下列在 AVCodecContext options 中。

private

这些选项是给定 container、设备或 codec 特有的。private 选项列在其对应的 container/设备/codec 之下。

例如，要给 MP3 文件写入 ID3v2.3 头而不是默认的 ID3v2.4 头，请使用 MP3 muxer 的 id3v2_version private 选项：

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

所有 codec 的 AVOptions 都是按流应用的，因此应该为它们附加一个流指定符：

ffmpeg -i multichannel.mxf -map 0:v:0 -map 0:a:0 -map 0:a:0 -c:a:0 ac3 -b:a:0 640k -ac:a:1 2 -c:a:1 aac -b:2 128k out.mp4

在上面的例子中，一个多声道音频流被映射了两次以供输出。第一个实例用 codec ac3 和比特率 640k 编码。第二个实例被下混为 2 声道，并用 codec aac 编码。这里使用输出流的绝对索引为它指定了比特率 128k。

注意：布尔类型的 AVOptions 不能使用 -nooption 语法，请使用 -option 0/-option 1。

注意：通过在选项名前加上 v/a/s 来指定按流 AVOptions 的旧式未文档化方式现已过时，即将被移除。

3.4 主要选项

-x width

强制指定显示宽度。

-y height

强制指定显示高度。

-fs

以全屏模式启动。

-an

禁用音频。

-vn

禁用视频。

-sn

禁用字幕。

-ss pos

定位到 pos。注意，大多数格式无法精确定位，因此 ffplay 会定位到最接近 pos 的定位点。

pos 必须是一个时间长度规范，参见 (ffmpeg-utils)ffmpeg-utils(1) 手册中的时间长度一节。

-t duration

播放 duration 秒的音频/视频。

duration 必须是一个时间长度规范，参见 (ffmpeg-utils)ffmpeg-utils(1) 手册中的时间长度一节。

-bytes

按字节定位。

-seek_interval

设置使用左右方向键定位时的自定义间隔（单位为秒）。默认值为 10 秒。

-nodisp

禁用图形显示。

-noborder

无边框窗口。

-alwaysontop

窗口始终置顶。可用于：SDL >= 2.0.5 的 X11、SDL >= 2.0.6 的 Windows。

-volume

设置启动音量。0 表示静音，100 表示不增大也不减小音量。负值会被视为 0，大于 100 的值会被视为 100。

-f fmt

强制指定格式。

-window_title title

设置窗口标题（默认使用输入文件名）。

-left title

设置窗口左边缘的 x 坐标（默认窗口居中）。

-top title

设置窗口上边缘的 y 坐标（默认窗口居中）。

-loop number

将影片循环播放 次。0 表示无限循环。

-showmode mode

设置要使用的显示模式。mode 可用的值有：

‘0, video’

显示视频

‘1, waves’

显示音频波形

‘2, rdft’

使用 RDFT（（逆）实离散傅里叶变换）显示音频频段

默认值为 "video"；如果没有视频或无法播放视频，则会自动选择 "rdft"。

按下按键 w 可以在可用的显示模式之间交互式切换。

-vf filtergraph

创建由 filtergraph 指定的 filtergraph，并使用它来过滤视频流。

filtergraph 是要应用于该流的 filtergraph 描述，必须只有一个视频输入和一个视频输出。在 filtergraph 中，输入关联到标签 in，输出关联到标签 out。关于 filtergraph 语法的更多信息，请参阅 ffmpeg-filters 手册。

可以多次指定该参数，按下按键 w 即可在指定的 filtergraph 和显示模式之间依次切换。

-af filtergraph

filtergraph 是要应用于输入音频的 filtergraph 描述。使用 "-filters" 选项可显示所有可用的滤镜（包括源和汇）。

-i input_url

读取 input_url。

3.5 高级选项

-stats

打印若干播放统计信息，具体包括流的时长、codec 参数、流中的当前位置以及音画同步的偏差。默认会显示这些信息，除非日志级别低于 info。可以通过手动指定该选项来强制显示。要禁用它，需要指定 -nostats。

-fast

不符合规范的优化。

-genpts

生成 pts。

-sync type

将主时钟设置为音频（type=audio）、视频（type=video）或外部（type=ext）。默认值为音频。主时钟用于控制音画同步。大多数媒体播放器使用音频作为主时钟，但在某些情况下（例如流媒体或高质量广播）需要更改这一设置。该选项主要用于调试目的。

-ast audio_stream_specifier

使用给定的流指定符选择所需的音频流。流指定符在“流指定符”一章中说明。如果未指定该选项，则会在已选中视频流所在节目中选择“最佳”音频流。

-vst video_stream_specifier

使用给定的流指定符选择所需的视频流。流指定符在“流指定符”一章中说明。如果未指定该选项，则会选择“最佳”视频流。

-sst subtitle_stream_specifier

使用给定的流指定符选择所需的字幕流。流指定符在“流指定符”一章中说明。如果未指定该选项，则会在已选中视频流或音频流所在节目中选择“最佳”字幕流。

-autoexit

视频播放完毕后退出。

-exitonkeydown

按下任意键时退出。

-exitonmousedown

按下任意鼠标按钮时退出。

-codec:media_specifier codec_name

为 media_specifier 标识的流强制指定特定的 decoder 实现，media_specifier 可以取值 a（音频）、v（视频）和 s（字幕）。

-acodec codec_name

强制指定特定的音频 decoder。

-vcodec codec_name

强制指定特定的视频 decoder。

-scodec codec_name

强制指定特定的字幕 decoder。

-autorotate

根据文件元数据自动旋转视频。默认启用，使用 -noautorotate 可禁用该功能。

-framedrop

视频不同步时丢弃视频帧。当主时钟未设置为视频时，默认启用。使用该选项可对所有主时钟来源启用丢帧，使用 -noframedrop 可禁用该功能。

-infbuf

不限制输入缓冲区大小，尽可能快地从输入中读取尽可能多的数据。对于实时流，默认启用该选项，因为如果不及时读取，数据可能会被丢弃。使用该选项可对所有输入启用无限缓冲区，使用 -noinfbuf 可禁用该功能。

-filter_threads nb_threads

定义处理滤镜管道所用的线程数。每条管道都会创建一个线程池，其中包含这么多可用于并行处理的线程。默认值为 0，表示线程数将由可用 CPU 的数量决定。

-enable_vulkan

使用 vulkan 渲染器而非 SDL 内置渲染器。依赖于 libplacebo。

-vulkan_params

使用以 ":" 分隔的 key=value 列表配置 Vulkan。

-hwaccel

使用硬件加速解码。启用该选项会自动启用 vulkan 渲染器。

-video_bg pattern

设置用于透明视频的视频背景图案。对于纯色图案，可以使用(ffmpeg-utils)ffmpeg-utils(1) 手册中的 Color 一节所定义的颜色名称或颜色代码。也可以使用特殊关键字 tiles 得到棋盘格样式的图案，这也是默认值。none 图案在渲染时不进行 alpha 混合，相当于忽略 alpha 通道。

3.6 播放时的按键操作

q, ESC

退出。

f

切换全屏。

p, SPC

暂停。

m

切换静音。

9, 0 /, *

分别用于降低和提高音量。

a

在当前节目中循环切换音频流。

v

循环切换视频流。

t

在当前节目中循环切换字幕流。

c

循环切换节目。

w

循环切换视频滤镜或显示模式。

s

单步前进到下一帧。

如果流尚未暂停，则先暂停，然后前进到下一视频帧，再次暂停。

left/right

向后/向前定位 10 秒；如果设置了 -seek_interval，则按该自定义间隔定位。

down/up

向后/向前定位 1 分钟。

page down/page up

定位到上一章/下一章；如果没有章节，则向后/向前定位 10 分钟。

right mouse click

定位到文件中与窗口宽度比例相对应的百分比位置。

left mouse double-click

切换全屏。

4 参见

ffmpeg-all, ffmpeg, ffprobe, ffmpeg-utils, ffmpeg-scaler, ffmpeg-resampler, ffmpeg-codecs, ffmpeg-bitstream-filters, ffmpeg-formats, ffmpeg-devices, ffmpeg-protocols, ffmpeg-filters

5 作者

FFmpeg 的开发者们。

关于作者身份的详细信息，请参见项目的 Git 历史（https://git.ffmpeg.org/ffmpeg），例如在 FFmpeg 源代码目录中输入 git log 命令，或浏览在线仓库 https://git.ffmpeg.org/ffmpeg。

各组件的维护者列在源代码树中的 MAINTAINERS 文件里。

主机托管由 telepoint.bg 提供