Up to date
This page is up to date for Godot 4.2
.
If you still find outdated information, please open an issue.
Lire des vidéos¶
Godot supports video playback with the VideoStreamPlayer node.
Formats de lecture pris en charge¶
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 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.
Note
Vous pouvez trouver des vidéos avec une extension .ogg
ou .ogx
, qui sont des extensions génériques pour les données d'un conteneur Ogg.
Renommer ces extensions de fichiers en .ogv
peut permettre ces vidéos d'être importées dans Godot. Cependant, tous les fichiers avec des extensions .ogg
ou ``.ogx``ne sont pas des vidéos - certaines d'entre elles peuvent ne contenir que de l'audio.
Setting up VideoStreamPlayer¶
Create a VideoStreamPlayer node using the Create New Node dialog.
Select the VideoStreamPlayer node in the scene tree dock, go to the inspector and load an
.ogv
file in the Stream property.Si vous n'avez pas encore votre vidéo en format Ogg Theora, consultez Paramètres recommandés pour l'encodage Theora.
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.
Handling resizing and different aspect ratios¶
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:
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.
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.
Voir aussi
See Résolutions multiples for more tips on supporting multiple aspect ratios in your project.
Afficher une vidéo sur une surface 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.
This can be done with the following steps:
Create a SubViewport node. Set its size to match your video's size in pixels.
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.
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).
Create a new StandardMaterial3D resource in the Material Override property in the GeometryInstance3D section.
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.
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.
Enable Albedo Texture Force sRGB in the StandardMaterial3D to prevent colors from being washed out.
If the billboard is supposed to emit its own light, set Shading Mode to Unshaded to improve rendering performance.
See Utilisation de Viewports and the GUI in 3D demo for more information on setting this up.
Looping a video¶
For looping a video, the Loop property can be enabled. This will seamlessly restart the video when it reaches its end.
Note that setting the project setting Video Delay Compensation to a non-zero value might cause your loop to not be seamless, because the synchronization of audio and video takes place at the start of each loop causing occasional missed frames. Set Video Delay Compensation in your project settings to 0 to avoid frame drop issues.
Video decoding conditions and recommended resolutions¶
Video decoding is performed on the CPU, as GPUs don't have hardware acceleration for decoding Theora videos. Modern desktop CPUs can decode Ogg Theora videos at 1440p @ 60 FPS or more, but low-end mobile CPUs will likely struggle with high-resolution videos.
Pour s'assurer que vos vidéos se décodent sans problème sur tout type de matériel :
Lorsque vous développez des jeux pour des plateformes de bureau, il est recommandé d'encoder en 1080p au maximum (de préférence à 30 IPS). La plupart des gens utilisent encore des écrans à résolution 1080p ou inférieure, et l'encodage de vidéos à plus haute résolution ne vaut pas forcément la peine d'augmenter la taille du fichier et les exigences du processeur.
Lorsque vous développez des jeux pour des plateformes mobiles ou web, il est recommandé d'encoder en 720p au maximum (de préférence à 30 IPS ou même moins). La différence visuelle entre les vidéos 720p et 1080p sur un appareil mobile n'est généralement pas très marquée.
Playback limitations¶
L'implémentation actuelle de la lecture vidéo dans Godot présente plusieurs limitations :
Lancer la vidéo à un moment précis n'est pas pris en charge.
Changing playback speed is not supported. VideoStreamPlayer also won't follow Engine.time_scale.
Le streaming d'une vidéo à partir d'une URL n'est pas prise en charge.
Paramètres recommandés pour l'encodage Theora¶
Un conseil : évitez de vous fier aux exportateurs Ogg Theora intégrés (la plupart du temps). Il y a deux raisons pour lesquelles vous pouvez préférer l'utilisation d'un programme externe pour encoder votre vidéo :
Certains programmes tels que Blender peuvent effectuer un rendu en Ogg Theora. Cependant, les préréglages de qualité par défaut sont généralement très bas par rapport aux normes actuelles. Vous pouvez peut-être augmenter les options de qualité dans le logiciel que vous utilisez, mais la qualité de sortie risque de ne pas être idéale (compte tenu de la taille accrue du fichier). Cela signifie généralement que le logiciel ne prend en charge que l'encodage à débit binaire constant (CBR), au lieu du débit binaire variable (VBR). L'encodage VBR est préférable dans la plupart des cas, car il offre un meilleur rapport qualité/taille de fichier.
Certains autres programmes ne peuvent pas du tout effectuer le rendu en Ogg Theora.
Dans ce cas, vous pouvez rendre la vidéo dans un format intermédiaire de haute qualité (comme une vidéo H.264 à haut débit) puis la réencoder en Ogg Theora. Idéalement, vous devriez utiliser un format sans perte ou non compressé comme format intermédiaire pour maximiser la qualité de la vidéo Ogg Theora de sortie, mais cela peut nécessiter beaucoup d'espace disque.
HandBrake (GUI) et FFmpeg (CLI) sont des outils open source populaires à cet effet. FFmpeg a une courbe d'apprentissage plus raide, mais il est plus puissant.
Voici des exemples de commandes FFmpeg pour convertir une vidéo MP4 en Ogg Theora. Comme FFmpeg supporte de nombreux formats d'entrée, vous devriez pouvoir utiliser les commandes ci-dessous avec presque tous les formats vidéo d'entrée (AVI, MOV, WebM, ...).
Note
Assurez-vous que votre copie de FFmpeg est compilée avec le support de libtheora et libvorbis. Vous pouvez vérifier cela en exécutant ffmpeg
sans aucun argument, puis en regardant la ligne configuration:
dans la sortie de la commande.
Équilibrer la qualité et la taille des fichiers¶
** Le niveau de qualité de la vidéo **(-q:v
) doit être compris entre 1
et 10
. La qualité 6
est un bon compromis entre la qualité et la taille du fichier. Si vous encodez à une haute résolution (comme 1440p ou 4K), vous voudrez probablement diminuer -q:v
à 5
pour garder une taille de fichier raisonnable. La densité de pixels étant plus élevée sur une vidéo 1440p ou 4K, les préréglages de qualité inférieure à des résolutions plus élevées auront un aspect aussi bon, voire meilleur, que les vidéos à basse résolution.
The audio quality level (-q:a
) must be between -1
and 10
. Quality
6
provides a good compromise between quality and file size. In contrast to
video quality, increasing audio quality doesn't increase the output file size
nearly as much. Therefore, if you want the cleanest audio possible, you can
increase this to 9
to get perceptually lossless audio. This is especially
valuable if your input file already uses lossy audio compression. Higher quality
audio does increase the CPU usage of the decoder, so it might lead to audio
dropouts in case of high system load. See
this page
for a table listing Ogg Vorbis audio quality presets and their respective
variable bitrates.
FFmpeg : Convertissez en préservant la résolution vidéo d'origine¶
La commande suivante convertit la vidéo tout en conservant sa résolution d'origine. Le débit binaire de la vidéo et de l'audio sera variable pour maximiser la qualité tout en économisant de l'espace dans les parties de la vidéo/audio qui ne nécessitent pas un débit binaire élevé (comme les scènes statiques).
ffmpeg -i input.mp4 -q:v 6 -q:a 6 output.ogv
FFmpeg : Redimensionner la vidéo puis la convertir¶
La commande suivante permet de redimensionner une vidéo pour qu'elle ait une taille de 720 pixels (720p), tout en préservant son rapport hauteur/largeur existant. Cela permet de réduire considérablement la taille du fichier si la source est enregistrée à une résolution supérieure à 720p :
ffmpeg -i input.mp4 -vf "scale=-1:720" -q:v 6 -q:a 6 output.ogv
Chroma Key Videos¶
Chroma key, commonly known as the "green screen" or "blue screen" effect, allows you to remove a specific color from an image or video and replace it with another background. This effect is widely used in video production to composite different elements together seamlessly.
We will achieve the chroma key effect by writing a custom shader in GDScript and using a VideoStreamPlayer node to display the video content.
Scene Setup¶
Ensure that the scene contains a VideoStreamPlayer node to play the video and a Control node to hold the UI elements for controlling the chroma key effect.
Writing the Custom Shader¶
To implement the chroma key effect, follow these steps:
Select the VideoStreamPlayer node in the scene and go to its properties. Under CanvasItem > Material, create a new shader named "ChromaKeyShader.gdshader."
In the "ChromaKeyShader.gdshader" file, write the custom shader code as shown below:
shader_type canvas_item;
# Uniform variables for chroma key effect
uniform vec3 chroma_key_color : source_color = vec3(0.0, 1.0, 0.0);
uniform float pickup_range : hint_range(0.0, 1.0) = 0.1;
uniform float fade_amount : hint_range(0.0, 1.0) = 0.1;
void fragment() {
# Get the color from the texture at the given UV coordinates
vec4 color = texture(TEXTURE, UV);
# Calculate the distance between the current color and the chroma key color
float distance = length(color.rgb - chroma_key_color);
# If the distance is within the pickup range, discard the pixel
# the lesser the distance more likely the colors are
if (distance <= pickup_range) {
discard;
}
# Calculate the fade factor based on the pickup range and fade amount
float fade_factor = smoothstep(pickup_range, pickup_range + fade_amount, distance);
# Set the output color with the original RGB values and the calculated fade factor
COLOR = vec4(color.rgb, fade_factor);
}
The shader uses the distance calculation to identify pixels close to the chroma key color and discards them, effectively removing the selected color. Pixels that are slightly further away from the chroma key color are faded based on the fade_factor, blending them smoothly with the surrounding colors. This process creates the desired chroma key effect, making it appear as if the background has been replaced with another image or video.
The code above represents a simple demonstration of the Chroma Key shader, and users can customize it according to their specific requirements.
UI Controls¶
To allow users to manipulate the chroma key effect in real-time, we created sliders in the Control node. The Control node's script contains the following functions:
extends Control
func _on_color_picker_button_color_changed(color):
# Update the "chroma_key_color" shader parameter of the VideoStreamPlayer's material
$VideoStreamPlayer.material.set("shader_parameter/chroma_key_color", color)
func _on_h_slider_value_changed(value):
# Update the "pickup_range" shader parameter of the VideoStreamPlayer's material
$VideoStreamPlayer.material.set("shader_parameter/pickup_range", value)
func _on_h_slider_2_value_changed(value):
# Update the "fade_amount" shader parameter of the VideoStreamPlayer's material
$VideoStreamPlayer.material.set("shader_parameter/fade_amount", value)
func _on_video_stream_player_finished():
# Restart the video playback when it's finished
$VideoStreamPlayer.play()
also make sure that the range of the sliders are appropriate, our settings are :
Signal Handling¶
Connect the appropriate signal from the UI elements to the Control node's script. you created in the Control node's script to control the chroma key effect. These signal handlers will update the shader's uniform variables in response to user input.
Save and run the scene to see the chroma key effect in action! With the provided UI controls, you can now adjust the chroma key color, pickup range, and fade amount in real-time, achieving the desired chroma key functionality for your video content.