StreamingMediaEncoder¶
- class torio.io.StreamingMediaEncoder(dst: Union[str, Path, BinaryIO], format: Optional[str] = None, buffer_size: int = 4096)[source]¶
逐塊編碼並寫入音訊/視訊串流
- 參數:
dst (str, path-like 或 file-like object) –
編碼資料寫入的目的地。如果為字串類型，則必須是 FFmpeg 可以處理的資源指示器。支援的值取決於系統中找到的 FFmpeg。
如果為類檔案物件，則必須支援簽名為 write(data: bytes) -> int 的 write 方法。
有關 write 方法的預期簽名和行為，請參閱以下內容。
format (str 或 None, 可選) –
覆寫輸出格式，或指定輸出媒體裝置。預設值：
None(不覆寫也不輸出裝置)。此引數有兩種不同的使用情境。
覆寫輸出格式。當寫入原始資料或格式與副檔名不同時，此功能很有用。
指定輸出裝置。這允許將媒體串流輸出到硬體裝置，例如喇叭和視訊螢幕。
注意
此選項大致對應於
ffmpeg命令的-f選項。有關可能的值，請參閱 ffmpeg 文件。https://ffmpeg.dev.org.tw/ffmpeg-formats.html#Muxers
請使用
get_muxers()列出目前環境中可用的多工器。對於裝置存取，可用的值因硬體 (AV 裝置) 和軟體組態 (ffmpeg 建置) 而異。有關可能的值，請參閱 ffmpeg 文件。
https://ffmpeg.dev.org.tw/ffmpeg-devices.html#Output-Devices
請使用
get_output_devices()列出目前環境中可用的輸出裝置。buffer_size (int) –
內部緩衝區大小 (以位元組為單位)。僅在 dst 是類檔案物件時使用。
預設值：4096。
方法¶
add_audio_stream¶
- StreamingMediaEncoder.add_audio_stream(sample_rate: int, num_channels: int, format: str = 'flt', *, encoder: Optional[str] = None, encoder_option: Optional[Dict[str, str]] = None, encoder_sample_rate: Optional[int] = None, encoder_num_channels: Optional[int] = None, encoder_format: Optional[str] = None, codec_config: Optional[CodecConfig] = None, filter_desc: Optional[str] = None)[source]¶
新增輸出音訊串流。
- 參數:
sample_rate (int) – 取樣率。
num_channels (int) – 聲道數量。
format (str, 可選) –
輸入樣本格式，決定輸入張量的 dtype。
"u8"：輸入張量必須為torch.uint8類型。"s16"：輸入張量必須為torch.int16類型。"s32"：輸入張量必須為torch.int32類型。"s64"：輸入張量必須為torch.int64類型。"flt"：輸入張量必須為torch.float32類型。"dbl"：輸入張量必須為torch.float64類型。
預設值：
"flt"。encoder (str 或 None, 可選) –
要使用的編碼器名稱。如果提供，則使用指定的編碼器，而不是預設編碼器。
若要列出可用的編碼器，音訊請使用
get_audio_encoders()，視訊請使用get_video_encoders()。預設值：
None。encoder_option (dict 或 None, 可選) –
傳遞給編碼器的選項。從 str 到 str 的對應。
若要列出編碼器的選項，您可以使用
ffmpeg -h encoder=<ENCODER>命令。預設值：
None。除了編碼器特定的選項外，您還可以傳遞與多執行緒相關的選項。它們僅在編碼器支援時才有效。如果兩者都未提供，StreamReader 預設為單執行緒。
"threads"：執行緒數量 (以 str 表示)。提供值"0"將讓 FFmpeg 根據其啟發式方法決定。"thread_type"：要使用的多執行緒方法。有效值為"frame"或"slice"。請注意，每個編碼器支援不同的方法組合。如果未提供，則使用預設值。"frame"：一次編碼多個影格。每個執行緒處理一個影格。這會使每個執行緒的解碼延遲增加一個影格"slice"：一次編碼單個影格的多個部分。
encoder_sample_rate (int 或 None, 可選) –
覆寫用於編碼時間的取樣率。某些編碼器對用於編碼的取樣率施加限制。如果編碼器不支援來源取樣率，則使用來源取樣率，否則選擇預設取樣率。
例如，
"opus"編碼器僅支援 48k Hz，因此，當使用"opus"編碼器編碼波形時，它始終編碼為 48k Hz。同時，"mp3"("libmp3lame") 支援 44.1k、48k、32k、22.05k、24k、16k、11.025k、12k 和 8k Hz。如果原始取樣率是其中之一，則使用原始取樣率，否則將重新取樣為預設取樣率 (44.1k)。當編碼為 WAV 格式時，對取樣率沒有限制，因此將使用原始取樣率。提供
encoder_sample_rate將覆寫此行為，並使編碼器嘗試使用提供的取樣率。提供的值必須是編碼器支援的值之一。encoder_num_channels (int 或 None, 可選) –
覆寫用於編碼的聲道數量。
與取樣率類似，某些編碼器 (例如
"opus"、"vorbis"和"g722") 對可用於編碼的聲道數量施加限制。如果編碼器支援原始聲道數量，則將使用該數量，否則，編碼器會嘗試將聲道重新混合為其中一個支援的聲道數量。
提供
encoder_num_channels將覆寫此行為，並使編碼器嘗試使用提供的聲道數量。提供的值必須是編碼器支援的值之一。encoder_format (str 或 None, 可選) –
用於編碼媒體的格式。當編碼器支援多種格式時，傳遞此引數將覆寫用於編碼的格式。
若要列出編碼器支援的格式，您可以使用
ffmpeg -h encoder=<ENCODER>命令。預設值：
None。注意
當未提供
encoder_format選項時，編碼器會使用其預設格式。例如，當將音訊編碼為 wav 格式時，使用 16 位元帶正負號整數，而當將視訊編碼為 mp4 格式 (h264 編碼器) 時，使用其中一種 YUV 格式。
這是因為通常在音訊模型中使用 32 位元或 16 位元浮點數，但在音訊格式中並不常用。同樣地，RGB24 常在視覺模型中使用，但視訊格式通常 (且更好) 支援 YUV 格式。
codec_config (CodecConfig 或 None, 可選) –
編解碼器組態。有關組態選項，請參閱
CodecConfig。預設值：
None。filter_desc (str 或 None, 可選) – 在編碼輸入媒體之前套用的其他處理。
add_video_stream¶
- StreamingMediaEncoder.add_video_stream(frame_rate: float, width: int, height: int, format: str = 'rgb24', *, encoder: Optional[str] = None, encoder_option: Optional[Dict[str, str]] = None, encoder_frame_rate: Optional[float] = None, encoder_width: Optional[int] = None, encoder_height: Optional[int] = None, encoder_format: Optional[str] = None, codec_config: Optional[CodecConfig] = None, filter_desc: Optional[str] = None, hw_accel: Optional[str] = None)[source]¶
新增輸出視訊串流。
此方法必須在呼叫 open 之前呼叫。
- 參數:
frame_rate (float) – 視訊的影格率。
width (int) – 視訊影格的寬度。
height (int) – 視訊影格的高度。
format (str, 可選) –
輸入像素格式，決定輸入張量的色彩聲道順序。
"gray8"：單聲道，灰階。"rgb24"：三個聲道，順序為 RGB。"bgr24"：三個聲道，順序為 BGR。"yuv444p"：三個聲道，順序為 YUV。
預設值：
"rgb24"。在任一情況下，輸入張量都必須為
torch.uint8類型，且形狀必須為 (影格, 聲道, 高度, 寬度)。encoder (str 或 None, 可選) –
要使用的編碼器名稱。如果提供，則使用指定的編碼器，而不是預設編碼器。
若要列出可用的編碼器，音訊請使用
get_audio_encoders()，視訊請使用get_video_encoders()。預設值：
None。encoder_option (dict 或 None, 可選) –
傳遞給編碼器的選項。從 str 到 str 的對應。
若要列出編碼器的選項，您可以使用
ffmpeg -h encoder=<ENCODER>命令。預設值：
None。除了編碼器特定的選項外，您還可以傳遞與多執行緒相關的選項。它們僅在編碼器支援時才有效。如果兩者都未提供，StreamReader 預設為單執行緒。
"threads"：執行緒數量 (以 str 表示)。提供值"0"將讓 FFmpeg 根據其啟發式方法決定。"thread_type"：要使用的多執行緒方法。有效值為"frame"或"slice"。請注意，每個編碼器支援不同的方法組合。如果未提供，則使用預設值。"frame"：一次編碼多個影格。每個執行緒處理一個影格。這會使每個執行緒的解碼延遲增加一個影格"slice"：一次編碼單個影格的多個部分。
encoder_frame_rate (float 或 None, 可選) –
覆寫用於編碼的影格率。
某些編碼器 (例如
"mpeg1"和"mpeg2") 對可用於編碼的影格率施加限制。在這種情況下，如果來源影格率 (以frame_rate形式提供) 不是支援的影格率之一，則會選擇預設影格率，並即時變更影格率。否則，將使用來源影格率。提供
encoder_frame_rate將覆寫此行為，並使編碼器嘗試使用提供的取樣率。提供的值必須是編碼器支援的值之一。encoder_width (int 或 None, 選用) – 用於編碼的影像寬度。這允許在編碼期間變更影像大小。
encoder_height (int 或 None, 選用) – 用於編碼的影像高度。這允許在編碼期間變更影像大小。
encoder_format (str 或 None, 可選) –
用於編碼媒體的格式。當編碼器支援多種格式時，傳遞此引數將覆寫用於編碼的格式。
若要列出編碼器支援的格式，您可以使用
ffmpeg -h encoder=<ENCODER>命令。預設值：
None。注意
當未提供
encoder_format選項時，編碼器會使用其預設格式。例如，當將音訊編碼為 wav 格式時，使用 16 位元帶正負號整數，而當將視訊編碼為 mp4 格式 (h264 編碼器) 時，使用其中一種 YUV 格式。
這是因為通常在音訊模型中使用 32 位元或 16 位元浮點數，但在音訊格式中並不常用。同樣地，RGB24 常在視覺模型中使用，但視訊格式通常 (且更好) 支援 YUV 格式。
codec_config (CodecConfig 或 None, 可選) –
編解碼器組態。有關組態選項，請參閱
CodecConfig。預設值：
None。filter_desc (str 或 None, 可選) – 在編碼輸入媒體之前套用的其他處理。
hw_accel (str 或 None, 選用) –
啟用硬體加速。
當影片在 CUDA 硬體上編碼時，例如 encoder="h264_nvenc"，將 CUDA 裝置指示器傳遞給 hw_accel (即 hw_accel="cuda:0") 將使 StreamingMediaEncoder 預期視訊區塊為 CUDA Tensor。傳遞 CPU Tensor 將導致錯誤。
若為 None，則視訊區塊 Tensor 必須為 CPU Tensor。預設值：
None。
close¶
- StreamingMediaEncoder.close()[原始碼]¶
關閉輸出
StreamingMediaEncoder也是一個上下文管理器，因此支援with陳述式。建議使用上下文管理器，因為當從with子句退出時，檔案會自動關閉。請參閱
StreamingMediaEncoder.open()以取得更多詳細資訊。
flush¶
open¶
- StreamingMediaEncoder.open(option: Optional[Dict[str, str]] = None) StreamingMediaEncoder[原始碼]¶
開啟輸出檔案/裝置並寫入標頭。
StreamingMediaEncoder也是一個上下文管理器，因此支援with陳述式。此方法會傳回呼叫該方法的實例 (即 self)，以便可以在 with 陳述式中使用。建議使用上下文管理器，因為當從with子句退出時，檔案會自動關閉。- 參數:
option (dict 或 None, 選用) – 協定、裝置和多工器的私有選項。請參閱範例。
- 範例 - 協定選項
>>> s = StreamingMediaEncoder(dst="rtmp://127.0.0.1:1234/live/app", format="flv") >>> s.add_video_stream(...) >>> # Passing protocol option `listen=1` makes StreamingMediaEncoder act as RTMP server. >>> with s.open(option={"listen": "1"}) as f: >>> f.write_video_chunk(...)
- 範例 - 裝置選項
>>> s = StreamingMediaEncoder("-", format="sdl") >>> s.add_video_stream(..., encoder_format="rgb24") >>> # Open SDL video player with fullscreen >>> with s.open(option={"window_fullscreen": "1"}): >>> f.write_video_chunk(...)
- 範例 - 多工器選項
>>> s = StreamingMediaEncoder("foo.flac") >>> s.add_audio_stream(...) >>> s.set_metadata({"artist": "torio contributors"}) >>> # FLAC muxer has a private option to not write the header. >>> # The resulting file does not contain the above metadata. >>> with s.open(option={"write_header": "false"}) as f: >>> f.write_audio_chunk(...)
set_metadata¶
write_audio_chunk¶
write_video_chunk¶
- StreamingMediaEncoder.write_video_chunk(i: int, chunk: Tensor, pts: Optional[float] = None)[原始碼]¶
寫入視訊/影像資料
- 參數:
i (int) – 串流索引。
chunk (Tensor) – 視訊/影像張量。形狀：(時間, 通道, 高度, 寬度)。
dtype必須為torch.uint8。形狀 (高度、寬度和通道數) 必須與呼叫add_video_stream()時設定的內容相符pts (float, 選用 或 None) –
如果提供，則覆寫展示時間戳記。
注意
所提供的值會轉換為以影格率為基準的整數值。因此，它會截斷為最接近
n / frame_rate的值。
支援結構¶
CodecConfig¶
- class torio.io.CodecConfig(bit_rate: int = -1, compression_level: int = -1, qscale: Optional[int] = None, gop_size: int = -1, max_b_frames: int = -1)[原始碼]¶
Codec 組態。
- qscale: Optional[int] = None¶
全域品質因數。啟用可變位元率。有效值取決於編碼器。
例如：MP3 採用
0-9(https://trac.ffmpeg.org/wiki/Encode/MP3)，而 libvorbis 採用-1-10。
