Playing videos

Godot supports video playback with the VideoPlayer node.

Supported playback formats

The only supported format in core is Ogg Theora (not to be confused with Ogg Vorbis audio). It's possible for extensions to bring support for additional formats, but no such extensions exist yet as of July 2022.

H.264 and H.265 cannot be supported in core Godot, as they are both encumbered by software patents. AV1 is royalty-free, but it remains slow to decode on the CPU and hardware decoding support isn't readily available on all GPUs in use yet.

WebM is supported in core in Godot 3.x, but support for it will be removed in 4.0 as it proved to be too buggy and difficult to maintain. Therefore, using WebM is not recommended.

Note

You may find videos with an .ogg or .ogx extensions, which are generic extensions for data within an Ogg container.

Renaming these file extensions to .ogv may allow the videos to be imported in Godot. However, not all files with .ogg or .ogx extensions are videos - some of them may only contain audio.

Setting up VideoPlayer

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

  2. Select the VideoPlayer 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 VideoPlayer node in a script to start playback when desired.

Handling resizing and different aspect ratios

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

To adjust how the VideoPlayer 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:

Add an AspectRatioContainer node. Make sure it is not a child of any other container node. Select the AspectRatioContainer node, then set its Layout at the top of the 2D editor to Full Rect. Set Ratio in the AspectRatioContainer node to match your video's aspect ratio. You can use math formulas in the inspector to help yourself. Remember to make one of the operands a float. Otherwise, the division's result will always be an integer.

AspectRatioContainer's Ratio property being modified in the editor inspector

This will evaluate to (approximately) 1.777778

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

See also

See Multiple resolutions for more tips on supporting multiple aspect ratios in your project.

Displaying a video on a 3D surface

Using a VideoPlayer node as a child of a Viewport 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.

This can be done with the following steps:

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

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

  3. Create a MeshInstance 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 SpatialMaterial resource in the Material Override property in the GeometryInstance section.

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

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

  7. Enable Albedo Tex Force sRGB in the SpatialMaterial to prevent colors from being washed out.

  8. If the billboard is supposed to emit its own light, enable Flags > Unshaded to improve rendering performance.

See Using Viewports and the GUI in 3D demo for more information on setting this up.

Playback limitations

There are several limitations with the current implementation of video playback in Godot:

  • Seeking a video to a certain point is not supported.

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

  • Looping is not supported, but you can connect a VideoPlayer's finished signal to a function that plays the video again. However, this will cause a black frame to be visible when the video restarts. This can be worked around by adding a fade to black in the video file before the video ends, or by hiding the video for one frame and displaying a TextureRect with a screenshot of the first frame of the video until the video is restarted.

  • Streaming a video from a URL is not supported.