ffplay 文件 - FFmpeg 多媒體框架

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 或 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]

符合具有給定 disposition(s) 的串流。dispositions 是以 '+' 連接的一個或多個 disposition（如 -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

顯示串流 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’: 表示重複的記錄輸出不應壓縮到第一行，並且將省略「最後訊息重複 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 選項。它們分為兩類

通用: 這些選項可以針對任何容器、編解碼器或裝置設定。通用選項列在容器/裝置的 AVFormatContext 選項和編解碼器的 AVCodecContext 選項下。
私有: 這些選項特定於給定的容器、裝置或編解碼器。私有選項列在其對應的容器/裝置/編解碼器下。

例如，若要將 ID3v2.3 標頭寫入 MP3 檔案而不是預設的 ID3v2.4，請使用 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，Windows SDL >= 2.0.6。

-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: 使用以 ":" 分隔的 key=value 配對列表進行 Vulkan 配置。
-hwaccel: 使用硬體加速解碼。啟用此選項將自動啟用 vulkan 渲染器。

3.6 播放期間

q, ESC

結束。

f

切換全螢幕。

p, SPC

暫停。

m

切換靜音。

9, 0

/, *

分別降低和提高音量。

a

在目前程式中循環切換音訊頻道。

v

循環切換視訊頻道。

t

在目前程式中循環切換字幕頻道。

c

循環切換程式。

w

循環切換視訊濾鏡或顯示模式。

s

步進到下一個影格。

如果串流尚未暫停，則暫停，步進到下一個視訊影格，然後暫停。

左/右

向後/向前搜尋 10 秒。

下/上

向後/向前搜尋 1 分鐘。

page down/page up

搜尋到上一個/下一個章節。或者，如果沒有章節，則向後/向前搜尋 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 提供託管服務