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.

Checking the stable version of the documentation...

播放视频

Godot supports video playback with the VideoStreamPlayer node.

支持的播放格式

核心中仅支持 Ogg Theora 格式（请勿与 Ogg Vorbis 音频混淆）。扩展可以支持额外的格式，但是截止到 2022 年 7 月，还没有这种扩展存在。

Godot 核心无法支持 H.264 和 H.265，因为它们都被软件专利所限。AV1 不需要授权，但 CPU 解码仍然很慢，也不是所有 GPU 都已支持硬件解码。

WebM was supported in core in Godot 3.x, but support for it was removed in 4.0 as it was too buggy and difficult to maintain.

备注

你的视频可能使用的是 .ogg 或者 .ogx 扩展名，这是带有数据的 Ogg 容器的通用扩展名。

将这些文件扩展名修改为 .ogv可能可以让视频在 Godot 中导入。不过，并不是所有 .ogg 或 .ogx 扩展名的文件都是视频——有些可能只包含音频。

Setting up VideoStreamPlayer

  1. Create a VideoStreamPlayer node using the Create New Node dialog.

  2. Select the VideoStreamPlayer node in the scene tree dock, go to the inspector and load an .ogv file in the Stream property.

  3. If you want the video to play as soon as the scene is loaded, check Autoplay in the inspector. If not, leave Autoplay disabled and call play() on the VideoStreamPlayer node in a script to start playback when desired.

处理大小变化及不同的纵横比

By default in Godot 4.0, the VideoStreamPlayer will automatically be resized to match the video's resolution. You can make it follow usual Control sizing by enabling Expand on the VideoStreamPlayer node.

To adjust how the VideoStreamPlayer node resizes depending on window size, adjust the anchors using the Layout menu at the top of the 2D editor viewport. However, this setup may not be powerful enough to handle all use cases, such as playing fullscreen videos without distorting the video (but with empty space on the edges instead). For more control, you can use an AspectRatioContainer node, which is designed to handle this kind of use case:

添加一个 AspectRatioContainer 节点。请确保它不是任何其他容器节点的子节点。选中该 AspectRatioContainer 节点，然后在 2D 编辑器的顶部将布局设置为整个矩形。将 AspectRatioContainer 节点的 Ratio（比例）设置为与你的视频的长宽比匹配的比例。你可以在检查器里直接输入数学公式。请记住要将其中的一个操作数写成浮点形式，否则会得到整数的商。

在编辑器检查器中修改 AspectRatioContainer 的 Ratio 属性

求值会得到（大约）1.777778

Once you've configured the AspectRatioContainer, reparent your VideoStreamPlayer node to be a child of the AspectRatioContainer node. Make sure Expand is enabled on the VideoStreamPlayer. Your video should now scale automatically to fit the whole screen while avoiding distortion.

参见

更多在项目中支持不同的长宽比的技巧，请参阅 多分辨率。

在 3D 表面上显示视频

Using a VideoStreamPlayer node as a child of a SubViewport node, it's possible to display any 2D node on a 3D surface. For example, this can be used to display animated billboards when frame-by-frame animation would require too much memory.

可以使用以下步骤实现：

  1. Create a SubViewport node. Set its size to match your video's size in pixels.

  2. Create a VideoStreamPlayer node as a child of the SubViewport node and specify a video path in it. Make sure Expand is disabled, and enable Autoplay if needed.

  3. Create a MeshInstance3D node with a PlaneMesh or QuadMesh resource in its Mesh property. Resize the mesh to match the video's aspect ratio (otherwise, it will appear distorted).

  4. Create a new StandardMaterial3D resource in the Material Override property in the GeometryInstance3D section.

  5. Enable Local To Scene in the StandardMaterial3D's Resource section (at the bottom). This is required before you can use a ViewportTexture in its Albedo Texture property.

  6. In the StandardMaterial3D, set the Albedo > Texture property to New ViewportTexture. Edit the new resource by clicking it, then specify the path to the SubViewport node in the Viewport Path property.

  7. Enable Albedo Texture Force sRGB in the StandardMaterial3D to prevent colors from being washed out.

  8. If the billboard is supposed to emit its own light, set Shading Mode to Unshaded to improve rendering performance.

更多关于设置的信息，请参阅 使用 Viewport 和 3D GUI 演示。

播放限制

Godot 中目前的视频播放实现有一些限制：

  • 不支持将视频跳跃到特定的时间点。

  • Changing playback speed is not supported. VideoStreamPlayer also won't follow Engine.time_scale.

  • Looping is not supported, but you can connect a VideoStreamPlayer's finished signal to a function that plays the video again.

  • 不支持从 URL 播放视频流。