ffplay：ffplay 工具 - FFmpeg中文文档

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的文件加载过滤器图描述。

3.1 流说明符

某些选项针对每个流应用，例如比特率或编解码器。流说明符用于精确指定给定选项属于哪个流。

流说明符是一个字符串，通常附加在选项名称后面，并用冒号分隔。例如 -codec:a:1 ac3 包含 a:1 流说明符，它与第二个音频流匹配。因此，它将为第二个音频流选择 ac3 编解码器。

流说明符可以匹配多个流，因此该选项将应用于所有流。例如 -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 容器中的 PID）。

m:key[:value]

匹配具有指定值的元数据标签键的流。如果未指定值，则匹配包含给定标签且具有任意值的流。

u

匹配具有可用配置的流，必须定义编解码器，并且必须存在视频尺寸或音频采样率等基本信息。

请注意，在 ffmpeg 中，通过元数据匹配仅适用于输入文件。

3.2 通用选项

这些选项在 ff* 工具之间共享。

-L

显示许可证。

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

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

arg 的可能值为：

long: 除了基本工具选项外，还打印高级工具选项。
full: 打印完整的选项列表，包括编码器、解码器、解复用器、复用器、过滤器等的共享和私有选项。
decoder=decoder_name: 打印有关名为decoder_name的解码器的详细信息。使用-decoders选项获取所有解码器的列表。
encoder=encoder_name: 打印有关名为encoder_name的编码器的详细信息。使用-encoders选项获取所有编码器的列表。
demuxer=demuxer_name: 打印有关名为demuxer_name的解复用器的详细信息。使用-formats选项获取所有解复用器和复用器的列表。
muxer=muxer_name: 打印有关名为 muxer_name 的复用器的详细信息。使用 -formats 选项获取所有复用器和解复用器的列表。
filter=filter_name: 打印有关名为 filter_name 的过滤器的详细信息。使用 -filters 选项获取所有过滤器的列表。
bsf=bitstream_filter_name: 打印有关名为 bitstream_filter_name 的比特流过滤器的详细信息。使用 -bsfs 选项获取所有比特流过滤器的列表。
protocol=protocol_name: 打印有关名为 protocol_name 的协议的详细信息。使用 -protocols 选项获取所有协议的列表。

-version

显示版本。

-buildconf

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

-formats

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

-demuxers

显示可用的解复用器。

-muxers

显示可用的复用器。

-devices

显示可用的设备。

-codecs

显示 libavcodec 已知的所有编解码器。

请注意，本文档中使用的术语“编解码器”是媒体比特流格式的缩写，更准确地说是媒体比特流格式。

-decoders

显示可用的解码器。

-encoders

显示所有可用的编码器。

-bsfs

显示可用的比特流过滤器。

-protocols

显示可用的协议。

-filters

显示可用的 libavfilter 过滤器。

-pix_fmts

显示可用的像素格式。

-sample_fmts

显示可用的样本格式。

-layouts

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

-dispositions

显示流配置。

-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

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

可选的标志前缀可以由以下值组成：

‘repeat’: 表示重复的日志输出不应压缩到第一行，并且将省略“最后一条消息重复 n 次”行。
‘level’: 表示日志输出应在每条消息行中添加 [level] 前缀。这可以用作日志着色的替代方法，例如在将日志转储到文件时。

也可以单独使用标志，方法是添加 '+'/'-' 前缀来设置/重置单个标志，而不会影响其他标志或更改日志级别。当同时设置标志和日志级别时，最后一个标志值和日志级别之前应有一个 '+' 分隔符。

日志级别是包含以下值之一的字符串或数字：

‘quiet, -8’: 什么也不显示；保持沉默。
‘panic, 0’: 仅显示可能导致进程崩溃的致命错误，例如断言失败。目前不用于任何用途。
‘fatal, 8’: 仅显示致命错误。这些错误会导致进程绝对无法继续。
‘error, 16’: 显示所有错误，包括可以恢复的错误。
‘warning, 24’: 显示所有警告和错误。任何与可能不正确或意外事件相关的消息都将显示。
‘info, 32’: 在处理过程中显示信息性消息。这是对警告和错误的补充。这是默认值。
‘verbose, 40’: 与信息相同，但更详细。
‘debug, 48’: 显示所有内容，包括调试信息。
‘trace, 56’

例如，要启用重复日志输出，请添加级别前缀，并将日志级别设置为详细：ffmpeg -loglevel repeat+level+verbose -i input output

另一个启用重复日志输出而不影响级别前缀标志或日志级别的当前状态的示例：ffmpeg [...] -loglevel +repeat

默认情况下，程序会将日志记录到 stderr。如果终端支持着色，则使用颜色标记错误和警告。可以通过设置环境变量 AV_LOG_FORCE_NOCOLOR 来禁用日志着色，也可以强制设置环境变量 AV_LOG_FORCE_COLOR。

-report

将完整的命令行和日志输出转储到当前目录中名为 program-YYYYMMDD-HHMMSS.log 的文件中。此文件可用于错误报告。它还暗示 -loglevel debug。

将环境变量 FFREPORT 设置为任何值具有相同的效果。如果值是以 ':' 分隔的 key=value 序列，则这些选项将影响报告；如果选项值包含特殊字符或选项分隔符 ':'，则必须对其进行转义（请参阅 ffmpeg-utils 手册中的“引用和转义”部分）。

可识别以下选项：

file: 设置用于报告的文件名； %p 扩展为程序名称，%t 扩展为时间戳，%% 扩展为纯 %
level: 使用数值设置日志详细程度（请参阅 -loglevel）。

例如，要使用日志级别 32（日志级别信息的别名）将报告输出到名为 ffreport.log 的文件：FFREPORT=file=ffreport.log:level=32 ffmpeg -i input output

解析环境变量时的错误并不严重，不会出现在报告中。

-hide_banner

禁止打印横幅。

-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’
‘<11 8>’
‘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: 可以为任何容器、编解码器或设备设置这些选项。通用选项列在容器/设备的 AVFormatContext 选项下，以及编解码器的 AVCodecContext 选项下。
private: 这些选项特定于给定的容器、设备或编解码器。私有选项列在其相应的容器/设备/编解码器下。

例如，要将 ID3v2.3 标头（而不是默认的 ID3v2.4）写入 MP3 文件，请使用id3v2_versionMP3 复用器的私有选项：

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

所有编解码器 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

在上面的示例中，多通道音频流被映射两次以进行输出。第一个实例使用编解码器 ac3 和比特率 640k 进行编码。第二个实例被混音为 2 个通道并使用编解码器 aac 进行编码。使用输出流的绝对索引为其指定 128k 的比特率。

注意：-nooption 语法不能用于布尔 AVOptions，请使用 -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 必须是时间持续时间规范，请参阅 (ffmpeg-utils)ffmpeg-utils(1) 手册中的时间持续时间部分。

-bytes

按字节查找。

-seek_interval

设置使用左/右键搜索的自定义间隔（以秒为单位）。默认值为 10 秒。

-nodisp

禁用图形显示。

-noborder

无边框窗口。

-alwaysontop

窗口始终位于最前面。可用：X11 SDL >= 2.0.5，Windows SDL >= 2.0.6。

-volume

设置启动音量。0 表示静音，100 表示不降低或放大音量。负值被视为 0，大于 100 的值被视为 100。

-f fmt

强制格式化。

-window_title title

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

-left title

设置窗口左侧的 x 位置（默认为居中窗口）。

-top title

设置窗口顶部的 y 位置（默认为居中窗口）。

-loop number

循环播放电影次。0 表示永远播放。

-showmode mode

设置要使用的放映模式。模式的可用值为：

‘0, video’: 显示视频
‘1, waves’: 显示音频波
‘2, rdft’: 使用 RDFT（（逆）实离散傅立叶变换）显示音频频带

默认值为“视频”，如果视频不存在或无法播放，则自动选择“rdft”。

您可以通过按键以交互方式循环浏览可用的显示模式。

-vf filtergraph

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

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

您可以多次指定此参数，并通过按下键循环显示指定的过滤器图和显示模式。

-af filtergraph

filtergraph 是应用于输入音频的过滤器图的描述。使用选项“-filters”显示所有可用的过滤器（包括源和接收器）。

-i input_url

读取 input_url。

3.5 高级选项

-stats: 打印多个播放统计信息，特别是显示流持续时间、编解码器参数、流中的当前位置和音频/视频同步漂移。默认情况下显示，除非日志级别低于 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 标识的流的特定解码器实现，该实现可以采用值 a（音频）、v（视频）和 s 字幕。
-acodec codec_name: 强制使用特定的音频解码器。
-vcodec codec_name: 强制使用特定的视频解码器。
-scodec codec_name: 强制使用特定的字幕解码器。
-autorotate: 根据文件元数据自动旋转视频。默认启用，使用 -noautorotate 禁用。
-framedrop: 如果视频不同步，则丢弃视频帧。如果主时钟未设置为视频，则默认启用。使用此选项为所有主时钟源启用帧丢弃，使用 -noframedrop 禁用。
-infbuf: 不限制输入缓冲区大小，尽快从输入中读取尽可能多的数据。对于实时流，默认启用，如果未及时读取，数据可能会丢失。使用此选项为所有输入启用无限缓冲区，使用 -noinfbuf 禁用它。
-filter_threads nb_threads: 定义使用多少个线程来处理过滤器管道。每个管道将生成一个线程池，其中有这么多线程可用于并行处理。默认值为 0，这意味着线程数将由可用 CPU 的数量决定。
-enable_vulkan: 使用 Vulkan 渲染器而不是 SDL 内置渲染器。取决于 libplacebo。
-vulkan_params: 使用以“:”分隔的键=值对列表的 Vulkan 配置。
-hwaccel: 使用硬件加速解码。启用此选项将自动启用 Vulkan 渲染器。

3.6 播放时

q，ESC

退出。

f

切换全屏。

p，SPC

暂停。

m

切换静音。

9, 0

/, *

分别降低和增加音量。

a

循环当前节目中的音频通道。

v

循环视频通道。

t

循环当前节目中的字幕通道。

c

循环节目。

w

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

s

步进到下一帧。

如果流尚未暂停，则暂停，步进到下一个视频帧，然后暂停。

左/右

向后/向前搜索 10 秒。

向下/向上

向后/向前搜索 1 分钟。

向下翻页/向上翻页

搜索上一章/下一章。如果没有章节，则向后/向前搜索 10 分钟。

右键单击

查找文件中与宽度分数对应的百分比。

鼠标左键双击

切换全屏。