StreamingMediaDecoder¶
- class torio.io.StreamingMediaDecoder(src: Union[str, Path, BinaryIO], format: Optional[str] = None, option: Optional[Dict] = None, buffer_size: int = 4096)[來源]¶
逐塊提取和解碼音訊/視訊串流。
有關此類別的詳細用法,請參閱教學。
- 參數:
src (str, path-like, bytes 或 類檔案物件) –
媒體來源。如果為字串類型,則必須是 FFmpeg 可以處理的資源指示符。這包括檔案路徑、URL、裝置識別碼或篩選器表達式。支援的值取決於系統中找到的 FFmpeg。
如果為 bytes,則必須是連續記憶體中編碼的媒體資料。
如果為類檔案物件,則必須支援具有簽名 read(size: int) -> bytes 的 read 方法。此外,如果類檔案物件具有 seek 方法,則在剖析媒體元資料時會使用該方法。這提高了編解碼器偵測的可靠性。seek 方法的簽名必須為 seek(offset: int, whence: int) -> int。
請參閱以下內容,了解 read 和 seek 方法的預期簽名和行為。
format (str 或 None, 可選) –
覆寫輸入格式,或指定來源聲音裝置。預設值:
None
(不覆寫也不裝置輸入)。此引數有兩種不同的用例。
覆寫來源格式。當輸入資料不包含標頭時,這非常有用。
指定輸入來源裝置。這允許從硬體裝置 (例如麥克風、攝影機和螢幕) 或虛擬裝置載入媒體串流。
注意
此選項大致對應於
ffmpeg
命令的-f
選項。有關可能的值,請參閱 ffmpeg 文件。https://ffmpeg.dev.org.tw/ffmpeg-formats.html#Demuxers
請使用
get_demuxers()
列出目前環境中可用的解多工器。對於裝置存取,可用值因硬體 (AV 裝置) 和軟體組態 (ffmpeg 建置) 而異。
https://ffmpeg.dev.org.tw/ffmpeg-devices.html#Input-Devices
請使用
get_input_devices()
列出目前環境中可用的輸入裝置。option (str 到 str 的字典, 可選) –
初始化格式內容 (開啟來源) 時傳遞的自訂選項。
您可以使用此引數在輸入來源傳遞至解碼器之前變更輸入來源。
預設值:
None
。buffer_size (int) –
以位元組為單位的內部緩衝區大小。僅在 src 為類檔案物件時使用。
預設值:4096。
屬性¶
default_audio_stream¶
default_video_stream¶
num_out_streams¶
num_src_streams¶
方法¶
add_audio_stream¶
- StreamingMediaDecoder.add_audio_stream(frames_per_chunk: int, buffer_chunk_size: int = 3, *, stream_index: Optional[int] = None, decoder: Optional[str] = None, decoder_option: Optional[Dict] = None, filter_desc: Optional[str] = None)[來源]¶
新增輸出音訊串流
- 參數:
frames_per_chunk (int) –
作為一個區塊傳回的影格數。如果在緩衝足夠的影格之前來源串流已耗盡,則區塊會按原樣傳回。
提供
-1
會停用分塊,而pop_chunks()
方法將會串連所有緩衝的影格並傳回。buffer_chunk_size (int, 可選) –
內部緩衝區大小。當緩衝的區塊數超過此數字時,會捨棄舊的影格。例如,如果
frames_per_chunk
為 5 且buffer_chunk_size
為 3,則會捨棄早於15
的影格。提供-1
會停用此行為。預設值:
3
。stream_index (int 或 None, 可選) – 來源音訊串流索引。如果省略,則會使用
default_audio_stream
。decoder (str 或 None, 可選) –
要使用的解碼器名稱。如果提供,則使用指定的解碼器而不是預設解碼器。
若要列出可用的解碼器,請針對音訊使用
get_audio_decoders()
,針對視訊使用get_video_decoders()
。預設值:
None
。decoder_option (dict 或 None, 可選) –
傳遞至解碼器的選項。從 str 到 str 的對應。(預設值:
None
)若要列出解碼器的解碼器選項,您可以使用
ffmpeg -h decoder=<DECODER>
命令。除了解碼器特定的選項外,您還可以傳遞與多執行緒相關的選項。它們僅在解碼器支援它們時才有效。如果兩者都未提供,StreamingMediaDecoder 預設為單執行緒。
"threads"
:執行緒數 (以 str 表示)。提供值"0"
將讓 FFmpeg 根據其啟發法來決定。"thread_type"
:要使用的多執行緒方法。有效值為"frame"
或"slice"
。請注意,每個解碼器都支援不同的方法集。如果未提供,則使用預設值。"frame"
:一次解碼多個影格。每個執行緒處理一個影格。這會將每個執行緒的解碼延遲增加一個影格"slice"
:一次解碼單個影格的多個部分。
filter_desc (str 或 None, 可選) – 篩選器描述。可在 https://ffmpeg.dev.org.tw/ffmpeg-filters.html 找到可用篩選器的清單。請注意,不支援複雜的篩選器。
add_basic_audio_stream¶
- StreamingMediaDecoder.add_basic_audio_stream(frames_per_chunk: int, buffer_chunk_size: int = 3, *, stream_index: Optional[int] = None, decoder: Optional[str] = None, decoder_option: Optional[Dict] = None, format: Optional[str] = 'fltp', sample_rate: Optional[int] = None, num_channels: Optional[int] = None)[來源]¶
新增輸出音訊串流
- 參數:
frames_per_chunk (int) –
作為一個區塊傳回的影格數。如果在緩衝足夠的影格之前來源串流已耗盡,則區塊會按原樣傳回。
提供
-1
會停用分塊,而pop_chunks()
方法將會串連所有緩衝的影格並傳回。buffer_chunk_size (int, 可選) –
內部緩衝區大小。當緩衝的區塊數超過此數字時,會捨棄舊的影格。例如,如果
frames_per_chunk
為 5 且buffer_chunk_size
為 3,則會捨棄早於15
的影格。提供-1
會停用此行為。預設值:
3
。stream_index (int 或 None, 可選) – 來源音訊串流索引。如果省略,則會使用
default_audio_stream
。decoder (str 或 None, 可選) –
要使用的解碼器名稱。如果提供,則使用指定的解碼器而不是預設解碼器。
若要列出可用的解碼器,請針對音訊使用
get_audio_decoders()
,針對視訊使用get_video_decoders()
。預設值:
None
。decoder_option (dict 或 None, 可選) –
傳遞至解碼器的選項。從 str 到 str 的對應。(預設值:
None
)若要列出解碼器的解碼器選項,您可以使用
ffmpeg -h decoder=<DECODER>
命令。除了解碼器特定的選項外,您還可以傳遞與多執行緒相關的選項。它們僅在解碼器支援它們時才有效。如果兩者都未提供,StreamingMediaDecoder 預設為單執行緒。
"threads"
:執行緒數 (以 str 表示)。提供值"0"
將讓 FFmpeg 根據其啟發法來決定。"thread_type"
:要使用的多執行緒方法。有效值為"frame"
或"slice"
。請注意,每個解碼器都支援不同的方法集。如果未提供,則使用預設值。"frame"
:一次解碼多個影格。每個執行緒處理一個影格。這會將每個執行緒的解碼延遲增加一個影格"slice"
:一次解碼單個影格的多個部分。
format (str, 可選) –
輸出取樣格式 (精確度)。
如果
None
,則輸出區塊的 dtype 對應於來源音訊的精確度。否則,會轉換取樣,並且輸出 dtype 會變更如下。
"u8p"
:輸出為torch.uint8
類型。"s16p"
:輸出為torch.int16
類型。"s32p"
:輸出為torch.int32
類型。"s64p"
:輸出為torch.int64
類型。"fltp"
:輸出為torch.float32
類型。"dblp"
:輸出為torch.float64
類型。
預設值:
"fltp"
。sample_rate (int 或 None, 可選) – 如果提供,則重新取樣音訊。
num_channels (int, 或 None, 可選) – 如果提供,則變更通道數。
add_basic_video_stream¶
- StreamingMediaDecoder.add_basic_video_stream(frames_per_chunk: int, buffer_chunk_size: int = 3, *, stream_index: Optional[int] = None, decoder: Optional[str] = None, decoder_option: Optional[Dict] = None, format: Optional[str] = 'rgb24', frame_rate: Optional[int] = None, width: Optional[int] = None, height: Optional[int] = None, hw_accel: Optional[str] = None)[來源]¶
新增輸出視訊串流
- 參數:
frames_per_chunk (int) –
作為一個區塊傳回的影格數。如果在緩衝足夠的影格之前來源串流已耗盡,則區塊會按原樣傳回。
提供
-1
會停用分塊,而pop_chunks()
方法將會串連所有緩衝的影格並傳回。buffer_chunk_size (int, 可選) –
內部緩衝區大小。當緩衝的區塊數超過此數字時,會捨棄舊的影格。例如,如果
frames_per_chunk
為 5 且buffer_chunk_size
為 3,則會捨棄早於15
的影格。提供-1
會停用此行為。預設值:
3
。stream_index (int 或 None, 可選) – 來源視訊串流索引。如果省略,則會使用
default_video_stream
。decoder (str 或 None, 可選) –
要使用的解碼器名稱。如果提供,則使用指定的解碼器而不是預設解碼器。
若要列出可用的解碼器,請針對音訊使用
get_audio_decoders()
,針對視訊使用get_video_decoders()
。預設值:
None
。decoder_option (dict 或 None, 可選) –
傳遞至解碼器的選項。從 str 到 str 的對應。(預設值:
None
)若要列出解碼器的解碼器選項,您可以使用
ffmpeg -h decoder=<DECODER>
命令。除了解碼器特定的選項外,您還可以傳遞與多執行緒相關的選項。它們僅在解碼器支援它們時才有效。如果兩者都未提供,StreamingMediaDecoder 預設為單執行緒。
"threads"
:執行緒數 (以 str 表示)。提供值"0"
將讓 FFmpeg 根據其啟發法來決定。"thread_type"
:要使用的多執行緒方法。有效值為"frame"
或"slice"
。請注意,每個解碼器都支援不同的方法集。如果未提供,則使用預設值。"frame"
:一次解碼多個影格。每個執行緒處理一個影格。這會將每個執行緒的解碼延遲增加一個影格"slice"
:一次解碼單個影格的多個部分。
format (str, 可選) –
變更影像通道的格式。有效值為,
"rgb24"
:8 位元 * 3 個通道 (R、G、B)"bgr24"
:8 位元 * 3 個通道 (B、G、R)"yuv420p"
:8 位元 * 3 個通道 (Y、U、V)"gray"
:8 位元 * 1 個通道
預設值:
"rgb24"
。frame_rate (int 或 None, 可選) – 如果提供,則變更影格速率。
width (int 或 None, 可選) – 如果提供,則變更影像寬度。單位:像素。
height (int 或 None, 可選) – 如果提供,則變更影像高度。單位:像素。
hw_accel (str 或 None, 可選) –
啟用硬體加速。
當在 CUDA 硬體上解碼影片時,例如 decoder=”h264_cuvid”,將 CUDA 裝置指示器傳遞給 hw_accel (即 hw_accel=”cuda:0”) 將使 StreamingMediaDecoder 將產生的影格直接放置在指定的 CUDA 裝置上作為 CUDA 張量。
如果為 None,影格將被移動到 CPU 記憶體。預設值:
None
。
add_video_stream¶
- StreamingMediaDecoder.add_video_stream(frames_per_chunk: int, buffer_chunk_size: int = 3, *, stream_index: Optional[int] = None, decoder: Optional[str] = None, decoder_option: Optional[Dict[str, str]] = None, filter_desc: Optional[str] = None, hw_accel: Optional[str] = None)[原始碼]¶
新增輸出視訊串流
- 參數:
frames_per_chunk (int) –
作為一個區塊傳回的影格數。如果在緩衝足夠的影格之前來源串流已耗盡,則區塊會按原樣傳回。
提供
-1
會停用分塊,而pop_chunks()
方法將會串連所有緩衝的影格並傳回。buffer_chunk_size (int, 可選) –
內部緩衝區大小。當緩衝的區塊數超過此數字時,會捨棄舊的影格。例如,如果
frames_per_chunk
為 5 且buffer_chunk_size
為 3,則會捨棄早於15
的影格。提供-1
會停用此行為。預設值:
3
。stream_index (int 或 None, 可選) – 來源視訊串流索引。如果省略,則會使用
default_video_stream
。decoder (str 或 None, 可選) –
要使用的解碼器名稱。如果提供,則使用指定的解碼器而不是預設解碼器。
若要列出可用的解碼器,請針對音訊使用
get_audio_decoders()
,針對視訊使用get_video_decoders()
。預設值:
None
。decoder_option (dict 或 None, 可選) –
傳遞至解碼器的選項。從 str 到 str 的對應。(預設值:
None
)若要列出解碼器的解碼器選項,您可以使用
ffmpeg -h decoder=<DECODER>
命令。除了解碼器特定的選項外,您還可以傳遞與多執行緒相關的選項。它們僅在解碼器支援它們時才有效。如果兩者都未提供,StreamingMediaDecoder 預設為單執行緒。
"threads"
:執行緒數 (以 str 表示)。提供值"0"
將讓 FFmpeg 根據其啟發法來決定。"thread_type"
:要使用的多執行緒方法。有效值為"frame"
或"slice"
。請注意,每個解碼器都支援不同的方法集。如果未提供,則使用預設值。"frame"
:一次解碼多個影格。每個執行緒處理一個影格。這會將每個執行緒的解碼延遲增加一個影格"slice"
:一次解碼單個影格的多個部分。
hw_accel (str 或 None, 可選) –
啟用硬體加速。
當在 CUDA 硬體上解碼影片時,例如 decoder=”h264_cuvid”,將 CUDA 裝置指示器傳遞給 hw_accel (即 hw_accel=”cuda:0”) 將使 StreamingMediaDecoder 將產生的影格直接放置在指定的 CUDA 裝置上作為 CUDA 張量。
如果為 None,影格將被移動到 CPU 記憶體。預設值:
None
。filter_desc (str 或 None, 可選) – 篩選器描述。可在 https://ffmpeg.dev.org.tw/ffmpeg-filters.html 找到可用篩選器的清單。請注意,不支援複雜的篩選器。
fill_buffer¶
- StreamingMediaDecoder.fill_buffer(timeout: Optional[float] = None, backoff: float = 10.0) int [原始碼]¶
持續處理封包直到所有緩衝區至少有一個區塊。
- 參數:
timeout (float 或 None, 選用) – 請參閱
process_packet()
。(預設值:None
)backoff (float, 選用) – 請參閱
process_packet()
。(預設值:10.0
)
- 返回:
0
封包已正確處理,且緩衝區已準備好被彈出一次。1
串流器已到達 EOF。所有輸出串流處理器都刷新了待處理的影格。呼叫者應停止呼叫此方法。- 返回類型:
get_metadata¶
get_out_stream_info¶
- StreamingMediaDecoder.get_out_stream_info(i: int) OutputStream [原始碼]¶
取得輸出串流的元數據
- 參數:
i (int) – 串流索引。
- 返回:
- OutputStreamTypes
關於輸出串流的資訊。如果輸出串流是音訊類型,則會返回
OutputAudioStream
。如果是影片類型,則會返回OutputVideoStream
。
get_src_stream_info¶
is_buffer_ready¶
pop_chunks¶
- StreamingMediaDecoder.pop_chunks() Tuple[Optional[ChunkTensor]] [原始碼]¶
從所有輸出串流緩衝區彈出一個區塊。
- 返回:
緩衝區內容。如果緩衝區不包含任何影格,則會返回 None。
- 返回類型:
Tuple[Optional[ChunkTensor]]
process_all_packets¶
process_packet¶
- StreamingMediaDecoder.process_packet(timeout: Optional[float] = None, backoff: float = 10.0) int [原始碼]¶
讀取來源媒體並處理一個封包。
如果成功讀取封包,則封包中的資料將被解碼並傳遞到相應的輸出串流處理器。
如果封包屬於未連接到輸出串流的來源串流,則資料將被丟棄。
當來源到達 EOF 時,它會觸發所有輸出串流處理器進入排空模式。所有輸出串流處理器都會刷新待處理的影格。
- 參數:
timeout (float 或 None, 選用) –
逾時時間,以毫秒為單位。
當由於底層媒體資源暫時不可用而導致處理封包失敗時,此參數會變更重試行為。
當使用媒體裝置(例如麥克風)時,在某些情況下,底層緩衝區尚未準備就緒。在這種情況下呼叫此函數會導致系統報告 EAGAIN (resource temporarily unavailable)。
>=0
:持續重試直到經過給定的時間。0<
:持續無限重試。None
:不重試並立即引發例外。
預設值:
None
。注意
重試行為僅適用於原因是資源不可用的情況。如果失敗的原因是其他原因,則不會調用它。
backoff (float, 選用) –
重試前等待的時間,以毫秒為單位。
僅當 timeout 生效時,此選項才有效。(非
None
)當 timeout 生效時,此 backoff 控制函數在重試之前應等待多久。預設值:
10.0
。
- 返回:
0
封包已正確處理。呼叫者可以繼續呼叫此函數以緩衝更多影格。1
串流器已到達 EOF。所有輸出串流處理器都刷新了待處理的影格。呼叫者應停止呼叫此方法。- 返回類型:
remove_stream¶
seek¶
stream¶
- StreamingMediaDecoder.stream(timeout: Optional[float] = None, backoff: float = 10.0) Iterator[Tuple[Optional[ChunkTensor], ...]] [原始碼]¶
返回產生輸出張量的迭代器
- 參數:
timeout (float 或 None, 選用) – 請參閱
process_packet()
。(預設值:None
)backoff (float, 選用) – 請參閱
process_packet()
。(預設值:10.0
)
- 返回:
迭代器,產生與客戶端程式碼定義的輸出串流相對應的區塊元組。如果輸出串流已耗盡,則區塊張量將替換為
None
。如果所有輸出串流都已耗盡,則迭代器停止。- 返回類型:
Iterator[Tuple[Optional[ChunkTensor], …]]
支援結構¶
ChunkTensor¶
- class torio.io._streaming_media_decoder.ChunkTensor[原始碼]¶
具有元數據的已解碼媒體影格。
此類別的實例表示具有元數據的已解碼影片/音訊影格,且實例本身的作用類似於
Tensor
。客戶端程式碼可以將此類別的實例作為
Tensor
類別來傳遞,或呼叫在Tensor
類別上定義的方法。範例
>>> # Define input streams >>> reader = StreamingMediaDecoder(...) >>> reader.add_audio_stream(frames_per_chunk=4000, sample_rate=8000) >>> reader.add_video_stream(frames_per_chunk=7, frame_rate=28) >>> # Decode the streams and fetch frames >>> reader.fill_buffer() >>> audio_chunk, video_chunk = reader.pop_chunks()
>>> # Access metadata >>> (audio_chunk.pts, video_chunks.pts) (0.0, 0.0) >>> >>> # The second time the PTS is different >>> reader.fill_buffer() >>> audio_chunk, video_chunk = reader.pop_chunks() >>> (audio_chunk.pts, video_chunks.pts) (0.5, 0.25)
>>> # Call PyTorch ops on chunk >>> audio_chunk.shape torch.Size([4000, 2] >>> power = torch.pow(video_chunk, 2) >>> >>> # the result is a plain torch.Tensor class >>> type(power) <class 'torch.Tensor'> >>> >>> # Metadata is not available on the result >>> power.pts AttributeError: 'Tensor' object has no attribute 'pts'
SourceStream¶
- class torio.io._streaming_media_decoder.SourceStream[原始碼]¶
來源串流的元數據,由
get_src_stream_info()
返回。當表示 audio 或 video 以外的媒體類型串流時,會使用此類別。
當來源串流為 audio 或 video 類型時,分別使用
SourceAudioStream
和SourceVideoStream
,它們會報告其他媒體特定的屬性。- media_type: str¶
串流的類型。為
"audio"
、"video"
、"data"
、"subtitle"
、"attachment"
和空字串之一。注意
輸出僅支援音訊和影片串流。
注意
靜態影像(例如 PNG 和 JPEG 格式)會報告為影片。
- codec_long_name: str¶
編解碼器的詳細名稱。
例如 “PCM signed 16-bit little-endian” 和 “H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10”。
SourceAudioStream¶
- class torio.io._streaming_media_decoder.SourceAudioStream[原始碼]¶
音訊來源串流的元數據,由
get_src_stream_info()
返回。當表示音訊串流時,會使用此類別。
除了
SourceStream
報告的屬性之外,還會報告以下屬性。
SourceVideoStream¶
- class torio.io._streaming_media_decoder.SourceVideoStream[原始碼]¶
影片來源串流的元數據,由
get_src_stream_info()
返回。當表示影片串流時,會使用此類別。
除了
SourceStream
報告的屬性之外,還會報告以下屬性。
OutputStream¶
- class torio.io._streaming_media_decoder.OutputStream[原始碼]¶
輸出串流已在
StreamingMediaDecoder
上配置,由get_out_stream_info()
傳回。
OutputAudioStream¶
- class torio.io._streaming_media_decoder.OutputAudioStream[source]¶
關於使用
add_audio_stream()
或add_basic_audio_stream()
配置的音訊輸出串流的資訊。除了
OutputStream
報告的屬性之外,還報告以下屬性。
OutputVideoStream¶
- class torio.io._streaming_media_decoder.OutputVideoStream[source]¶
關於使用
add_video_stream()
或add_basic_video_stream()
配置的視訊輸出串流的資訊。除了
OutputStream
報告的屬性之外,還報告以下屬性。