VideoStreamPlayer in Godot – Complete Guide

Video games are not just about interactive mechanics and mesmerizing graphics. Sometimes, they’re about telling a story, and one powerful medium for narrative is video. In our ever-evolving world of game design, Godot Engine stands as a herald of accessibility and power, and the VideoStreamPlayer class is a testament to this. It offers developers the capability to incorporate video content seamlessly into their games, providing the potential to create immersive cinematic experiences in Godot 4. Whether you’re looking to add cutscenes, instructional content, or just set the mood with a video background, understanding how to use VideoStreamPlayer will enhance your game development toolkit.

What is VideoStreamPlayer?

VideoStreamPlayer is a Control node in Godot 4, which provides functionality for video playback within your games or applications. It’s the bridge between raw video content and the Godot Engine, capable of playing VideoStream resources such as Ogg Theora (.ogv) files.

What is VideoStreamPlayer Used For?

This class is used to integrate video content into your projects. With VideoStreamPlayer, you can introduce video cutscenes, tutorials, credits, or even live backgrounds into your game world. It’s an enriching feature that can serve many purposes, both aesthetic and functional, enhancing the player’s experience.

Why Should I Learn to Use VideoStreamPlayer?

By mastering VideoStreamPlayer, you can:
– Expand the narrative capabilities of your games.
– Deliver information to players through a dynamic medium.
– Elevate the emotional and atmospheric impact of your scenes.

Gaining proficiency in this class will significantly benefit developers looking to craft deeper, more engaging game experiences. Now, let’s dive into the fundamental aspects of utilizing VideoStreamPlayer in Godot 4.

CTA Small Image

Setting Up Your Godot Project for Video Playback

Before integrating videos into your Godot game, you need to set up your project to handle video files. Godot has a specific resource type for videos called VideoStream. The most common format used in Godot for video files is Ogg Theora with the .ogv extension.

First, add a VideoStreamPlayer node to your scene by clicking the ‘+’ button on the Scene dock and search for VideoStreamPlayer.

var video_stream_player =

Next, you will want to assign a video file to your VideoStreamPlayer node. You can do this via the Inspector or through code as shown here:

var video_stream = load("res://path_to_your_video.ogv") = video_stream

Make sure to place your video file in the ‘res://’ directory of your Godot project to access it through Godot’s resource path.

Loading and Playing Videos

Once your VideoStreamPlayer is set up, you will likely want to control playback programmatically. This includes play, pause, and stop functionality.

To play a video:

To pause a video:


To stop video playback:


It’s important to notice that stopping a video resets its playback position to the start. Pausing, however, keeps the current playback position.

Controlling Video Playback

Beyond the basic playback controls, you may also want to handle the video playback position and loop the video.

To seek to a specific point in the video: # Seek to 5 seconds

To enable or disable looping:

video_stream_player.set_loop(true) # Enable looping
video_stream_player.set_loop(false) # Disable looping

Enabling looping is useful for videos intended to play continuously, such as backgrounds or ambient scenes.

Connecting to VideoStreamPlayer Signals

Godot’s signal system allows you to execute code in response to certain events occurring within the VideoStreamPlayer. For instance, you might want to execute code when the video finishes playing.

To do this, you connect a signal emited by the VideoStreamPlayer to a method in your script:

video_stream_player.connect("finished", self, "_on_VideoStreamPlayer_finished")

func _on_VideoStreamPlayer_finished():
    print("Video playback finished")

Likewise, there are signals for when the video is paused or stopped which can be connected similarly:

video_stream_player.connect("paused", self, "_on_VideoStreamPlayer_paused")
video_stream_player.connect("stopped", self, "_on_VideoStreamPlayer_stopped")

func _on_VideoStreamPlayer_paused():
    print("Video playback paused")

func _on_VideoStreamPlayer_stopped():
    print("Video playback stopped")

This capability allows for sophisticated video event-handling and can be used to trigger gameplay elements or narrative sequences upon the conclusion or interruption of a video.Incorporating audio control into your video playback can also be essential, particularly if you want to adjust volume or mute audio during cutscenes.

To adjust the volume of the video, you can set the volume_db property. The value is in decibels, and you can increase or decrease the volume relative to the video’s original audio level:

video_stream_player.volume_db = 0.0 # Set to default volume
video_stream_player.volume_db = -10.0 # Decrease volume
video_stream_player.volume_db = 10.0 # Increase volume

Sometimes you may want to mute the video’s sound entirely. This can be simply done by setting the volume to a very low value:

video_stream_player.volume_db = -80.0 # Effectively mute the video

Handling the texture of the video is another powerful feature. You can display the video on any TextureRect or other objects by grabbing the current frame as a texture:

var texture_rect = $TextureRect
texture_rect.texture = video_stream_player.get_texture()

For advanced control over playback, you can query information about the video, such as whether it’s playing or its current playback position:

if video_stream_player.is_playing():
    print("The video is currently playing")

var current_position = video_stream_player.get_playback_position()
print("Current playback position: ", current_position)

If you want to perform an action after a specific time or at a certain position in the video, you can use the get_playback_position() method within the _process() function to continuously check the position:

func _process(delta):
    if video_stream_player.get_playback_position() > 10.0: # 10 seconds
        # Do something after 10 seconds of playback

Lastly, to ensure optimal user experience, particularly when dealing with resources, you may want to unload the video from memory once you’re done using it or when the player exits the scene:

video_stream_player.queue_free() # Removes the VideoStreamPlayer node and frees the associated resources

Remembering to manage your resources effectively is key to maintaining performance and preventing memory leaks in your Godot applications. Using these code examples and tips, you should now have a solid grounding in working with VideoStreamPlayer in Godot 4 to enrich your interactive projects with dynamic video content.

By providing these features in Godot 4, we are here at Zenva remain committed to empowering our students — that’s you! — with the tools and knowledge needed to build the next generation of innovative and engaging games. With each tutorial, you’re one step closer to mastering game development, expanding your skill set, and bringing your dream projects to life. Keep coding and creating!Managing the visibility and playback state of your videos can be crucial for delivering a seamless gaming experience. Godot’s VideoStreamPlayer provides straightforward ways to handle these aspects through its properties and methods.

To check if the video is visible on the screen, you might use the `visible` property:

if video_stream_player.visible:
    print("The video is visible to the player")
    print("The video is not currently visible")

You can also toggle the visibility of the VideoStreamPlayer. If you wish to hide the video at any point, you can set this property to `false`:

video_stream_player.visible = false # Hide the video

To make the VideoStreamPlayer visible again:

video_stream_player.visible = true # Show the video

Visibility is particularly handy when dealing with UI elements where you might want to display the video only at certain times.

Another aspect is audio and video synchronization. If for some reason your video and audio are out of sync, you can adjust the audio track position to match the video:


This method takes a `seconds` parameter, where you can specify the exact position in time for your audio track to synchronize it with the video.

Furthermore, handling screen resolution changes while a video is playing is an important aspect. The VideoStreamPlayer allows you to change the video’s size and scale proportionally to fit different screen resolutions:

video_stream_player.rect_scale = Vector2(1.5, 1.5) # Scale the video 1.5 times its original size

Or, to adjust the size immediately to the dimensions of its parent Control node:

video_stream_player.rect_size = video_stream_player.get_parent().rect_min_size

Lastly, if you want to implement custom behavior when the video size changes, you can register for the `size_changed` signal:

video_stream_player.connect("size_changed", self, "_on_VideoStreamPlayer_size_changed")

func _on_VideoStreamPlayer_size_changed():
    print("The video size has changed.")

And to ensure the video fits within a given layout, you could update the size of other UI elements in the `_on_VideoStreamPlayer_size_changed` method.

In modern-day game development, especially when looking to create a professional and polished end-product, these video control techniques are invaluable. As developers, we strive to make experiences that are as immersive and responsive as possible. Learning how to handle video playback with precision is a substantial step in that direction. Whether you’re creating an intricate narrative piece or a simple puzzle game, the power of video to communicate and captivate is undeniable. With Godot and VideoStreamPlayer, you’re equipping yourself to leverage this power to its fullest. Keep experimenting, implement these techniques in your own projects, and watch your games come to life!

Continuing Your Game Development Journey

Mastering video integration with VideoStreamPlayer in Godot 4 is just the beginning. As you continue your journey in game development, it’s instrumental to build on your foundation and learn how to bring more sophisticated and engaging games to life. Our Godot Game Development Mini-Degree is a comprehensive program designed to take you from the basics to creating your own 2D and 3D games in this versatile engine. You’ll delve into key topics such as GDScript, gameplay control flow, and player mechanics, enriching your developer’s toolbox.

For those eager to further explore the possibilities within Godot, our broader collection of Godot courses caters to all skill levels, ensuring that no matter where you are on your learning path, there’s something to elevate your game design ambitions. With over 250 supported courses across various programming disciplines, Zenva’s expert-crafted content is your ticket to success in the thriving world of game development. Keep learning, coding, and creating – the next level awaits!


As you’ve seen, incorporating video into your Godot 4 projects can propel your games to new heights of storytelling and player engagement. Through mastering the VideoStreamPlayer node, you unlock a treasure trove of potential, allowing your creations to stand out in the ever-growing indie game market. The ability to weave together gameplay and cinematic experiences seamlessly is a skill that will serve you well in your development career.

Whether you are a seasoned developer or just starting out, Zenva’s Godot Game Development Mini-Degree is the catalyst you need to transform your game development dreams into reality. We invite you to join us on this journey, and we can’t wait to see the incredible games you’ll create. So why wait? Start now, and let’s build amazing experiences together!

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.