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 支援影片播放，可使用 VideoStreamPlayer 節點。

支援的播放格式

核心僅支援 Ogg Theora (不要與 Ogg Vorbis 音訊混淆) ，可選配 Ogg Vorbis 音軌。其他格式則可由擴充功能提供支援。

Godot 核心無法支援 H.264 和 H.265，因為它們都被軟體專利所限。AV1 不需要授權，但 CPU 解碼仍然很慢，也不是所有 GPU 都已支援硬體解碼。

Godot 3.x 核心中支援 WebM，但是會在 4.0 中移除支援，因為 bug 很多難以維護。因此**不推薦使用 WebM**。

備註

你可能會看到副檔名為 .ogg 或 .ogx 的影片，這是 Ogg 容器中資料的通用副檔名。

將這些檔副檔名修改為 .ogv``*可能*可以讓影片在 Godot 中匯入。不過，並不是所有 ``.ogg 或 .ogx 副檔名的檔都是影片——有些可能只包含音訊。

設定 VideoStreamPlayer

  1. 請使用「建立新節點」對話框新增一個 VideoStreamPlayer 節點。

  2. 在場景樹中選取 VideoStreamPlayer 節點，前往屬性檢視器，於 Stream 屬性載入 .ogv 檔案。

  3. 如果你希望在場景載入時立即播放影片，請在屬性檢視器中勾選 Autoplay。否則，請保持 Autoplay 關閉，並在需要時在腳本中呼叫 VideoPlayer 節點的 play() 開始播放。

處理大小變化及不同的縱橫比

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.

要調整 VideoPlayer 節點的大小隨視窗大小改變的方式，請通過 2D 編輯器視口頂部的**佈局**按鈕調整錨點。不過，這種設定可能不足以處理所有可能的情況，例如全屏播放影片但不造成形變（需要在邊界處留白）。要進行精確的控制，你可以使用專為處理這種情況設計的 AspectRatioContainer 節點：

新增一個 AspectRatioContainer 節點。請確保它不是任何其他容器節點的子節點。選中該 AspectRatioContainer 節點，然後在 2D 編輯器的頂部將 佈局 設定為 整個矩形 。將 AspectRatioContainer 節點的 Ratio（比例） 設定為與你的影片的長寬比配對的比例。你可以在屬性檢視器裡直接輸入數學公式。請記住要將其中的一個運算元寫成浮點形式，否則會得到整數的商。

在編輯器屬性檢視器中修改 AspectRatioContainer 的 Ratio 屬性

求值會得到（大約）1.777778

配置好 AspectRatioContainer 之後，請將你的 VideoPlayer 節點調整為該 AspectRatioContainer 節點的子節點。請確保禁用了該 VideoPlayer 的 Expand。你的影片現在應該就會自動適應到全屏的大小，不產生變形。

也參考

更多在專案中支援不同的長寬比的技巧，請參閱 多重解析度。

在 3D 表面上顯示影片

使用 VideoPlayer 節點作為 SubViewport 節點的子節點，就可以在 3D 表面上顯示任何 2D 節點。例如，可以用於顯示動態的廣告板，影格動畫可能花費太多的記憶體。

填寫下列設定：

  1. 建立一個 SubViewport 節點。 將其設定為與你的影片大小相配對的像素大小。

  2. 建立一個 VideoPlayer 節點*作為該 Viewport 節點的子節點*，並為其指定一個影片的路徑。請確保禁用了 Expand，需要時啟用 Autoplay。

  3. 建立一個 MeshInstance 節點，將其 Mesh 屬性設為 PlaneMesh 或 QuadMesh。將該網格的大小調整到與影片的長寬比一致（否則看上去就會變形）。

  4. 在 GeometryInstance 部分的 Material Override 屬性中新建一個 SpatialMaterial 資源。

  5. 在該 SpatialMaterial（底部）的 Resource 部分啟用 Local To Scene。這是在 Albedo Texture 屬性中使用 ViewportTexture 所*必須的*。

  6. 在該 SpatialMaterial 中，將 Albedo > Texture 屬性設定為**新建 ViewportTexture**。點擊編輯這個新的資源，在 Viewport Path 屬性中指定指向 Viewport 節點的路徑。

  7. 在該 SpatialMaterial 中啟用 Albedo Tex Force sRGB，防止顏色變化。

  8. 如果廣告板應該自發光，請啟用 Flags > Unshaded 提升算繪性能。

請參閱 使用視口 以及 3D 中的 GUI 範例，以了解更多關於此設定的資訊。

循環播放影片

如需讓影片循環播放，可啟用 Loop（循環） 屬性。啟用後，影片播放到結尾時會自動無縫重新開始播放。

請注意，若將專案設定中的 Video Delay Compensation（影片延遲補償） 設為非 0 值，可能會導致循環播放時出現不連續（卡頓），因為每次循環時音訊與影像會重新同步，偶爾會漏掉影格。建議將專案設定的 Video Delay Compensation 設為 0，以避免掉幀問題。

限制

Godot 目前的影片播放實作有以下限制：

  • 不支援從 URL 播放影片流。

  • 僅支援單聲道與立體聲輸出。具有 4、5.1、7.1 聲道的影片可播放，但會被向下混音為立體聲。

去背（Chroma Key）影片

Chroma Key（去背），也就是常見的「綠幕」或「藍幕」效果，可以將畫面中指定顏色去除，並用其他背景取代。這種特效常用於影片製作中，讓不同元素能夠無縫合成。

../../_images/chroma_key_video.webp

我們將透過自訂 GDScript 著色器（Shader）並搭配 VideoStreamPlayer 節點來實現去背效果，將影片內容顯示出來。

場景設定

請確認場景中包含一個 VideoStreamPlayer 節點（用於播放影片），以及一個 Control 節點（用來放置控制去背效果的 UI 元件）。

../../_images/chroma_key_scene.webp

自訂著色器編寫

欲實作去背（Chroma Key）效果，請依下列步驟操作：

  1. 在場景中選取 VideoStreamPlayer 節點，於其屬性的 CanvasItem > Material 下，建立一個新的著色器（Shader），命名為 "ChromaKeyShader.gdshader"

  2. 在 "ChromaKeyShader.gdshader" 檔案中，請輸入如下自訂著色器程式碼：

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

這個著色器會計算畫素與去背顏色的距離，將與指定色值足夠接近的畫素去除，達到去除目標顏色的效果。而距離稍遠的畫素則會根據 fade_factor 產生漸層透明，使邊緣過渡更自然。如此即可達到預期的去背（Chroma Key）效果，讓背景看起來像是被其他圖片或影片取代。

上述程式碼為 Chroma Key 著色器的簡單範例，你可以依照實際需求進一步調整與自訂。

UI 控制元件

為了讓使用者能即時調整去背效果，我們在 Control 節點中建立了滑桿（Slider）控制元件。Control 節點的程式腳本包含如下功能：

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

請確保滑桿的數值範圍設置合理。我們建議的設定如下：

../../_images/slider_range.webp

訊號處理

請將 UI 元件的對應訊號（Signal）連接到 Control 節點的腳本，以便控制去背效果。這些訊號處理函式會根據使用者操作，即時更新著色器的 uniform 變數。

儲存並執行場景後，即可看到去背效果！透過 UI 控制元件，現在你可以即時調整去背顏色、容差範圍與漸層強度，讓影片內容達到理想的去背功能。