Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

MovieWriter

继承： Object

非实时视频录制编码器的抽象类。

描述

Godot 能够使用非实时模拟技术录制视频。与 --fixed-fps 命令行参数类似，会强制让 Node._process 等函数每一帧都收到相同的 delta，无论实际渲染花费了多长的时间。这个技术可用于录制高画质的视频，无论你的硬件性能如何，帧率始终都是恒定的。

Godot 内置的 MovieWriter 有两个：

  • 使用 MJPEG 视频和未压缩音频的 AVI 容器（文件扩展名为 .avi）。有损压缩、文件大小中等、编码速度较快。有损压缩质量可以通过修改 ProjectSettings.editor/movie_writer/mjpeg_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 等工具。

方法

int

_get_audio_mix_rate ( ) virtual const

SpeakerMode

_get_audio_speaker_mode ( ) virtual const

bool

_handles_file ( String path ) virtual const

Error

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

void

_write_end ( ) virtual

Error

_write_frame ( Image frame_image, const void* audio_frame_block ) virtual

void

add_writer ( MovieWriter writer ) static

方法说明

int _get_audio_mix_rate ( ) virtual const

当引擎请求用于录制音频的音频采样率时调用。返回的值必须以 Hz 为单位指定。如果 _get_audio_mix_rate 未被重写，则默认为 48000 Hz。

SpeakerMode _get_audio_speaker_mode ( ) virtual const

当引擎请求用于录制音频的音频扬声器模式时调用。这可能会影响生成的音频文件/流中的输出通道数。如果 _get_audio_speaker_mode 未被重写，则默认为 AudioServer.SPEAKER_MODE_STEREO。

bool _handles_file ( String path ) virtual 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 ( Vector2i movie_size, int fps, String base_path ) virtual

在引擎开始写入视频和音频数据之前调用一次。movie_size 是要保存的视频的宽度和高度。fps 是指定的每秒帧数，在项目设置中、或使用 --fixed-fps <fps>《命令行参数》指定。

void _write_end ( ) virtual

当引擎完成写入时调用。当引擎通过按下窗口管理器的关闭按钮退出时，或调用 SceneTree.quit 时，会发生这种情况。

注意：在运行编辑器/项目的终端上，按 Ctrl + C，不会导致 _write_end 被调用。

Error _write_frame ( Image frame_image, const void* audio_frame_block ) virtual

在每个渲染的帧结束时被调用。应写入 frame_image 和 audio_frame_block 函数参数。

void add_writer ( MovieWriter writer ) static

添加一个可供引擎使用的编写器。可以通过重写 _handles_file，来设置支持的文件扩展名。

注意：add_writer 必须在引擎初始化期间尽早调用才能工作，因为电影编写被设计为与引擎的其余部分同时启动。