Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

MovieWriter

繼承: Object

非即時影片錄製編碼器的抽象類別。

說明

Godot 能夠使用非即時模擬技術錄制影片。與 --fixed-fps 命令行參數類似,會強制讓 Node._process() 等函式每一影格都收到相同的 delta,無論實際渲染花費了多長的時間。這個技術可用於錄制高畫質的影片,無論你的硬體效能如何,影格率始終都是恆定的。

Godot 內建的 MovieWriter 有 3 個:

  • 使用 Theora 影片和 Vorbis 音訊的 OVG 容器(檔案副檔名為 .ogv)。有損壓縮、檔案大小中等、編碼速度快。有損壓縮品質可以通過修改 ProjectSettings.editor/movie_writer/video_quality 和 ProjectSettings.editor/movie_writer/ogv/audio_quality 來調整。生成的檔案在 Godot 中可以使用 VideoStreamPlayer 查看,也可以使用大多數影片播放器查看,但是無法在網頁瀏覽器中查看,因為它們不支援 Theora。

  • 使用 MJPEG 影片和未壓縮音訊的 AVI 容器(檔案副檔名為 .avi)。有損壓縮、檔案大小中等、編碼速度較快。有損壓縮品質可以通過修改 ProjectSettings.editor/movie_writer/video_quality 來調整。生成的檔案可以使用大多數影片播放器查看,但如果要在 Web 上查看或者用 Godot 的 VideoStreamPlayer 查看,則必須先進行格式的轉換。MJPEG 不支援透明度。AVI 輸出的檔案目前最多為 4 GB 大小。

  • 影片使用 PNG 影像序列、音訊使用 WAV(檔案副檔名為 .png)。無損壓縮、檔案大小較大、編碼速度較慢。旨在錄制後使用 FFmpeg 等其他工具編碼為影片檔案。目前不支援透明度,即便將根視埠設為透明。

如果你需要編碼為其他格式,或者將流匯入到第三方軟體中,你可以擴充 MovieWriter 類,建立自己的影片錄制器。出於效能考慮,一般應該使用 GDExtension 實現。

編輯器使用:預設影片檔案路徑可以在 ProjectSettings.editor/movie_writer/movie_file 指定。或者在執行單個場景時,也可以在根節點上新增中繼資料 movie_file,可以指定錄制該場景時所使用的影片檔案路徑。設定路徑後,請點選編輯器右上角的電影膠卷圖示,啟動 Movie Maker 模式,然後和平常一樣執行場景即可。引擎會在啟動畫面結束後開始錄制,只會在引擎退出時停止錄制。再次點選電影膠卷圖示可以停用 Movie Maker 模式。請注意,Movie Maker 模式的開關不會影響正在執行的專案實例。

注意:MovieWriter 既可以在編輯器中使用,也可以在匯出的專案中使用,但這個功能不應用來讓最終使用者錄制遊戲影片。希望錄制遊戲影片的玩家應該安裝 OBS Studio 或 SimpleScreenRecorder 等工具。

注意:MJPEG 支援((.avi 檔案副檔名)取決於 jpg 模組,需要在編譯時啟用(預設行為)。

注意:OGV 支援((.ogv 檔案副檔名)取決於 theora 模組,需要在編譯時啟用(預設行為)。Theora 壓縮僅在編輯器二進位檔案中可用。

方法

int

_get_audio_mix_rate() virtual required const

SpeakerMode

_get_audio_speaker_mode() virtual required const

PackedStringArray

_get_supported_extensions() virtual required const

bool

_handles_file(path: String) virtual required const

Error

_write_begin(movie_size: Vector2i, fps: int, base_path: String) virtual required

void

_write_end() virtual required

Error

_write_frame(frame_image: Image, audio_frame_block: const int32_t*) virtual required

void

add_writer(writer: MovieWriter) static


方法說明

int _get_audio_mix_rate() virtual required const 🔗

當引擎請求用於錄製音訊的音訊取樣速率時呼叫。返回的值必須以 Hz 為單位指定。如果 _get_audio_mix_rate() 未被重寫,則預設為 48000 Hz。


SpeakerMode _get_audio_speaker_mode() virtual required const 🔗

當引擎請求用於錄製音訊的音訊揚聲器模式時呼叫。這可能會影響生成的音訊檔/流中的輸出通道數。如果 _get_audio_speaker_mode() 未被重寫,則預設為 AudioServer.SPEAKER_MODE_STEREO。


PackedStringArray _get_supported_extensions() virtual required const 🔗

回傳此 MovieWriter 在生成(寫入)影片時所支援的檔名副檔名清單。


bool _handles_file(path: String) virtual required const 🔗

當引擎確定該 MovieWriter 是否能夠處理位於 path 的檔時呼叫。如果該 MovieWriter 能夠處理給定的檔路徑,則必須返回 true,否則返回 false。通常,_handles_file() 如下被重寫,以允許使用者使用給定檔副檔名,在任何路徑下記錄一個檔:

func _handles_file(path):
    # 允許指定一個帶有 `.mkv` 檔副檔名(不區分大小寫)的輸出檔,
    # 在專案設定中或使用 `--write-movie <path>` 命令列參數。
    return path.get_extension().to_lower() == "mkv"

Error _write_begin(movie_size: Vector2i, fps: int, base_path: String) virtual required 🔗

在引擎開始寫入影片和音訊資料之前呼叫一次。movie_size 是要保存的影片的寬度和高度。fps 是指定的每秒影格數,在專案設定中、或使用 --fixed-fps <fps>《命令列參數》指定。


void _write_end() virtual required 🔗

當引擎完成寫入時呼叫。當引擎通過按下視窗管理器的關閉按鈕退出時,或呼叫 SceneTree.quit() 時,會發生這種情況。

注意:在運作編輯器/專案的終端上,按 Ctrl + C,不會導致 _write_end() 被呼叫。


Error _write_frame(frame_image: Image, audio_frame_block: const int32_t*) virtual required 🔗

在每個渲染的影格結束時被呼叫。應寫入 frame_image 和 audio_frame_block 函式參數。


void add_writer(writer: MovieWriter) static 🔗

新增一個可供引擎使用的編寫器。可以通過重寫 _handles_file(),來設定支援的檔案副檔名。

注意:add_writer() 必須在引擎初始化期間儘早呼叫才能工作,因為電影編寫被設計為與引擎的其餘部分同時啟動。