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...

Abspielen von Videos

Godot unterstützt die Videowiedergabe mit dem VideoStreamPlayer-Node.

Unterstützte Wiedergabeformate

The only supported format in core is Ogg Theora (not to be confused with Ogg Vorbis audio) with optional Ogg Vorbis audio tracks. It's possible for extensions to bring support for additional formats.

H.264 und H.265 können im Godot-Kern nicht unterstützt werden, da sie beide durch Softwarepatente geschützt sind. AV1 ist lizenzfrei, aber die Dekodierung auf der CPU ist nach wie vor langsam, und die Unterstützung für die Hardware-Dekodierung ist noch nicht auf allen verwendeten GPUs verfügbar.

WebM wurde in Godot 3.x im Kern unterstützt, aber die Unterstützung dafür wurde in 4.0 entfernt, da sie zu fehlerhaft und schwer zu pflegen war.

Bemerkung

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

Die Umbenennung dieser Dateierweiterungen in .ogv könnte es ermöglichen, die Videos in Godot zu importieren. Allerdings sind nicht alle Dateien mit den Erweiterungen .ogg oder .ogx Videos - einige von ihnen könnten nur Audio enthalten.

Einrichten des VideoStreamPlayers

  1. Erstellen Sie einen VideoStreamPlayer-Node mit dem Dialogfeld Neuen Knoten erstellen.

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

  3. Wenn Sie möchten, dass das Video abgespielt wird, sobald die Szene geladen ist, aktivieren Sie Autoplay im Inspektor. Wenn nicht, lassen Sie Autoplay deaktiviert und rufen Sie play() auf dem VideoStreamPlayer-Node in einem Skript auf, um die Wiedergabe bei Bedarf zu starten.

Handhabung von Größenänderungen und unterschiedlichen Seitenverhältnissen

By default, 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.

Um die Größenanpassung des VideoStreamPlayer-Nodes in Abhängigkeit von der Fenstergröße einzustellen, passen Sie die Anker über das Menü Layout oben im Viewport des 2D-Editors an. Diese Einstellung ist jedoch möglicherweise nicht leistungsfähig genug, um alle Anwendungsfälle zu bewältigen, z. B. die Wiedergabe von Videos im Vollbildmodus ohne Verzerrung des Videos (statt mit leeren Bereichen an den Rändern). Für mehr Kontrolle können Sie einen AspectRatioContainer-Node verwenden, der für diese Art von Anwendungsfall entwickelt wurde:

Fügen Sie einen AspectRatioContainer-Node hinzu. Vergewissern Sie sich, dass dieser Node kein untergeordneter Node eines anderen Containers ist. Wählen Sie den AspectRatioContainer-Node aus, und stellen Sie sein Layout oben im 2D-Editor auf Vollständiges Rechteck ein. Stellen Sie Verhältnis im AspectRatioContainer-Node so ein, dass es dem Seitenverhältnis Ihres Videos entspricht. Sie können die mathematischen Formeln im Inspektor zur Hilfe nehmen. Achten Sie darauf, dass einer der Operanden eine Float-Zahl ist. Andernfalls wird das Ergebnis der Division immer eine ganze Zahl sein.

Änderung der Verhältnis-Property des AspectRatioContainers im Inspektor des Editors

Dies ergibt einen Wert von (ungefähr) 1,777778

Nachdem Sie den AspectRatioContainer konfiguriert haben, richten Sie den VideoStreamPlayer-Node so ein, dass er ein untergeordneter Node des AspectRatioContainers ist. Stellen Sie sicher, dass Ausdehnen auf dem VideoStreamPlayer aktiviert ist. Ihr Video sollte nun automatisch so skaliert werden, dass es auf den gesamten Bildschirm passt und keine Verzerrungen aufweist.

Siehe auch

Weitere Tipps zur Unterstützung mehrerer Seitenverhältnisse in Ihrem Projekt finden Sie unter Mehrere Auflösungen.

Anzeige eines Videos auf einer 3D-Oberfläche

Mit einem VideoStreamPlayer-Node als Child eines SubViewport-Nodes ist es möglich, jeden 2D-Node auf einer 3D-Oberfläche darzustellen. Dies kann zum Beispiel verwendet werden, um animierte Werbetafeln anzuzeigen, wenn eine Frame-by-Frame-Animation zu viel Speicherplatz erfordern würde.

Dies kann mit den folgenden Schritten geschehen:

  1. Erstellen Sie einen SubViewport-Node. Stellen Sie seine Größe so ein, dass sie der Größe Ihres Videos in Pixeln entspricht.

  2. Erstellen Sie einen VideoStreamPlayer-Node als untergeordnetes Element des SubViewport-Nodes und geben Sie darin einen Videopfad an. Stellen Sie sicher, dass Ausdehnen deaktiviert ist, und aktivieren Sie Autoplay, falls erforderlich.

  3. Erstellen Sie einen MeshInstance3D-Node mit einer PlaneMesh- oder QuadMesh-Ressource in seiner Mesh-Property. Passen Sie die Größe des Meshes an das Seitenverhältnis des Videos an (andernfalls wird es verzerrt angezeigt).

  4. Erstellen Sie eine neue Ressource StandardMaterial3D in der Property Material-Override im Abschnitt GeometryInstance3D.

  5. Aktivieren Sie Lokal zu Szene im Abschnitt Ressource des StandardMaterial3D (ganz unten). Dies ist erforderlich, bevor Sie eine ViewportTexture in ihrer Albedo-Textur-Property verwenden können.

  6. Setzen Sie im StandardMaterial3D die Property Albedo > Textur auf Neue ViewportTexture. Bearbeiten Sie die neue Ressource, indem Sie darauf klicken, und geben Sie den Pfad zum SubViewport-Node in der Viewport Path-Property an.

  7. Aktivieren Sie Albedo-Textur sRGB erzwingen im StandardMaterial3D, um zu verhindern, dass die Farben ausgewaschen werden.

  8. Wenn das Billboard sein eigenes Licht emittieren soll, setzen Sie Shading-Modus auf kein Shading, um die Performance zu verbessern.

Siehe Verwenden von Viewports und die GUI in 3D-Demo für weitere Informationen zur Einrichtung dieser Funktion.

Looping eines Videos

Um ein Video in einer Loop laufen zu lassen, kann die Property Loop aktiviert werden. Dadurch wird das Video nahtlos neu gestartet, wenn es sein Ende erreicht.

Beachten Sie, dass die Projekteinstellung Videoverzögerungskompensation auf einen Wert ungleich Null gesetzt werden kann, was dazu führen kann, dass Ihre Loop nicht nahtlos ist, da die Synchronisierung von Audio und Video am Anfang jeder Loop stattfindet, wodurch gelegentlich Frames ausgelassen werden. Setzen Sie die Videoverzögerungskompensation in Ihren Projekteinstellungen auf 0, um Frame-Drop-Probleme zu vermeiden.

Einschränkungen bei der Wiedergabe

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

  • Das Streamen eines Videos von einer URL wird nicht unterstützt.

  • Only mono and stereo audio output is supported. Videos with 4, 5.1 and 7.1 audio channels are supported but down-mixed to stereo.

Chroma Key-Videos

Mit dem Chroma Key-Effekt, der auch als "Greenscreen"- oder "Bluescreen"-Effekt bekannt ist, können Sie eine bestimmte Farbe aus einem Bild oder Video entfernen und durch einen anderen Hintergrund ersetzen. Dieser Effekt wird in der Videoproduktion häufig verwendet, um verschiedene Elemente nahtlos zusammenzufügen.

../../_images/chroma_key_video.webp

Wir erreichen den Chroma Key-Effekt, indem wir einen benutzerdefinierten Shader in GDScript schreiben und einen VideoStreamPlayer-Node verwenden, um den Videoinhalt anzuzeigen.

Einrichten der Szene

Stellen Sie sicher, dass die Szene einen VideoStreamPlayer-Node zur Wiedergabe des Videos und einen Control-Node zur Aufnahme der UI-Elemente zur Steuerung des Chroma Key-Effekts enthält.

../../_images/chroma_key_scene.webp

Schreiben des benutzerdefinierten Shaders

Gehen Sie folgendermaßen vor, um den Chroma Key-Effekt zu implementieren:

  1. Wählen Sie den VideoStreamPlayer-Node in der Szene und gehen Sie zu seinen Propertys. Erstellen Sie unter CanvasItem > Material einen neuen Shader namens "ChromaKeyShader.gdshader".

  2. Schreiben Sie in die Datei "ChromaKeyShader.gdshader" den benutzerdefinierten Shader-Code wie unten gezeigt:

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);
}

Der Shader verwendet die Abstandsberechnung, um Pixel in der Nähe der Chroma Key-Farbe zu identifizieren und verwirft sie, wodurch die ausgewählte Farbe effektiv entfernt wird. Pixel, die etwas weiter von der Chroma Key-Farbe entfernt sind, werden auf der Grundlage des fade_factor ausgeblendet, so dass sie sanft mit den umgebenden Farben überblendet werden. Dieser Prozess erzeugt den gewünschten Chroma Key-Effekt, der den Eindruck erweckt, dass der Hintergrund durch ein anderes Bild oder Video ersetzt wurde.

Der obige Code stellt eine einfache Demonstration des Chroma Key-Shaders dar und kann von den Benutzern entsprechend ihren spezifischen Anforderungen angepasst werden.

UI-Steuerelemente

Damit die Benutzer den Chroma Key-Effekt in Echtzeit beeinflussen können, haben wir Schieberegler im Control-Node erstellt. Das Skript des Control-Nodes enthält die folgenden Funktionen:

 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()

Vergewissern Sie sich auch, dass der Bereich der Schieberegler angemessen ist. Unsere Einstellungen sind:

../../_images/slider_range.webp

Behandlung von Signalen

Verbinden Sie das entsprechende Signal von den UI-Elementen mit dem Skript des Control-Nodes, das Sie im Skript des Control Nodes erstellt haben, um den Chroma Key-Effekt zu steuern. Diese Signal-Handler aktualisieren die Uniform-Variablen des Shaders als Reaktion auf Benutzereingaben.

Speichern Sie die Szene und führen Sie sie aus, um den Chroma Key-Effekt in Aktion zu sehen! Mit den bereitgestellten Steuerelementen der Benutzeroberfläche können Sie jetzt die Chroma Key-Farbe, den Aufnahmebereich und den Fading-Grad in Echtzeit anpassen und so die gewünschte Chroma Key-Funktionalität für Ihre Videoinhalte erzielen.