ffplay 文档 - FFmpeg 多媒体框架

1 概要

ffplay [选项] [输入_url]

2 描述

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

3 选项

所有数值选项（如果没有另外指定）都接受表示数字的字符串作为输入，该字符串后面可以跟一个 SI 单位前缀，例如：“K”、“M”或“G”。

如果将“i”附加到 SI 单位前缀，则整个前缀将被解释为二进制倍数的单位前缀，它基于 1024 的幂而不是 1000 的幂。将“B”附加到 SI 单位前缀会将值乘以 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 或 i:group_id: 匹配具有此组 ID 的流。

p:program_id[:additional_stream_specifier]

匹配 ID 为 program_id 的程序中的流。如果使用 additional_stream_specifier，则它匹配既是程序的一部分又匹配 additional_stream_specifier 的流。

#stream_id 或 i:stream_id

通过流 ID 匹配流（例如，MPEG-TS 容器中的 PID）。

m:key[:value]

匹配具有元数据标签 key 且具有指定值的流。如果未给出 value，则匹配包含给定标签且具有任何值的流。key 或 value 中的冒号字符“:”需要使用反斜杠转义。

disp:dispositions[:additional_stream_specifier]

匹配具有给定处置的流。dispositions 是一个或多个处置（由 -dispositions 选项打印）的列表，并用“+”连接。

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

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

可选的 flags 前缀可以包含以下值

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

标志也可以单独使用，只需添加“+”/“-”前缀即可设置/重置单个标志，而不会影响其他 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

默认情况下，程序将日志记录到 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（日志级别 info 的别名）将报告输出到名为 ffreport.log 的文件中

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

解析环境变量中的错误不是致命的，并且不会出现在报告中。

-hide_banner

禁止打印横幅。

-cpuflags flags (全局)

允许设置和清除 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 (全局)

覆盖对 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 文件，请使用 MP3 复用器的 id3v2_version 私有选项

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 秒的音频/视频。

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

循环播放电影 <number> 次。0 表示无限循环。

-showmode mode

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

‘0, video’: 显示视频
‘1, waves’: 显示音频波形
‘2, rdft’: 使用 RDFT（（反）实数离散傅里叶变换）显示音频频段

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

您可以通过按键循环切换可用的显示模式w.

-vf filtergraph

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

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

您可以多次指定此参数，并通过按键循环切换指定的滤镜图以及显示模式w.

-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 标识的流使用特定的解码器实现，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 配置，使用以 ":" 分隔的 key=value 对列表。
-hwaccel: 使用硬件加速解码。启用此选项将自动启用 Vulkan 渲染器。

3.6 播放时

q, ESC

退出。

f

切换全屏。

p, SPC

暂停。

m

切换静音。

9, 0

/, *

分别减小和增大音量。

a

在当前程序中循环切换音频声道。

v

循环切换视频声道。

t

在当前程序中循环切换字幕声道。

c

循环切换节目。

w

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

s

步进到下一帧。

如果流未处于暂停状态，则暂停，步进到下一视频帧，并暂停。

左/右

后退/前进 10 秒。

下/上

后退/前进 1 分钟。

向下翻页/向上翻页

跳转到上一章/下一章。如果没有章节，则后退/前进 10 分钟。

鼠标右键单击

跳转到文件中与宽度比例对应的百分比位置。

鼠标左键双击

切换全屏。

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 中。

本文档于 2025 年 1 月 21 日 使用 makeinfo 生成。

由 telepoint.bg 提供托管