最后同步日期：2026-04-15 | Godot 官方原文 — VideoStreamPlayer

VideoStreamPlayer

节点继承关系

继承链：Node → CanvasItem → Control → VideoStreamPlayer

Control

类型	名称	说明
属性	Size	控件尺寸
属性	Position	控件位置
属性	AnchorsPreset	锚点预设
属性	GrowDirection	超出容器时的扩展方向
属性	MouseFilter	鼠标事件过滤（停止 / 通过 / 忽略）
属性	FocusMode	焦点模式（无 / 单击 / 全部）
信号	gui_input	接收到 GUI 输入事件
信号	mouse_entered	鼠标进入控件区域
信号	mouse_exited	鼠标离开控件区域
信号	focus_entered	获得焦点
信号	focus_exited	失去焦点
信号	resized	尺寸变化
方法	GrabFocus()	获取焦点
方法	ReleaseFocus()	释放焦点
方法	SetAnchorsPreset()	设置锚点预设
方法	GetMinimumSize()	获取最小尺寸

CanvasItem

类型	名称	说明
属性	Visible	是否可见
属性	Modulate	整体颜色叠加（乘法）
属性	SelfModulate	自身颜色叠加（不影响子节点）
属性	ZIndex	绘制层级（Z 轴排序）
信号	visibility_changed	可见性变化时触发
方法	GetGlobalMousePosition()	获取鼠标全局坐标

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

在 UI 中播放视频——比如过场动画、游戏开场 CG。就像一个内嵌的播放器，你给它一个视频文件，它就帮你播出来。

使用频率：★★ 偶尔使用（有过场动画时使用）

节点用途

• 播放过场动画（CG）
• 播放游戏开场视频
• 播放教程演示视频

使用场景

• 游戏开场的 Logo/CG 动画
• 过关后的动画演出
• 教程中的操作演示

常用节点搭配

• 搭配 AspectRatioContainer 保持视频比例
• 搭配 ColorRect 做视频未加载时的背景

生效必备素材/资源

• 必需：视频文件（.ogv 格式，Godot 推荐使用 Theora 编码）
• 对应的 VideoStream 资源

节点属性与信号

自有属性

属性	类型	默认值	继承自	说明
stream	VideoStream	null	—	要播放的视频资源
autoplay	bool	false	—	是否自动播放
volume_db	float	0.0	—	音量（分贝），0 为原始音量
paused	bool	false	—	是否暂停
loop	bool	false	—	是否循环播放
mix_audio	bool	true	—	是否混入音频
buffering_msec	int	500	—	缓冲时间（毫秒）

信号

信号	触发时机	参数
finished	视频播放完毕时	无

常用方法

方法	说明
Play()	开始播放
Stop()	停止播放
Pause()	暂停播放
GetStreamName()	获取视频名称
GetStreamPosition()	获取当前播放位置（秒）

代码示例

C

using Godot;

public partial class VideoPlayer : Control
{
    private VideoStreamPlayer _videoPlayer;

    public override void _Ready()
    {
        _videoPlayer = new VideoStreamPlayer();
        _videoPlayer.Stream = GD.Load<VideoStream>("res://assets/video/intro.ogv");
        _videoPlayer.Autoplay = false;
        _videoPlayer.VolumeDb = -5;  // 稍微降低音量
        _videoPlayer.Size = new Vector2(800, 600);
        _videoPlayer.SetAnchorsPreset(LayoutPreset.Center);

        _videoPlayer.Finished += () =>
        {
            GD.Print("视频播放完毕");
            // 播放完毕后跳转到主菜单
            GetTree().ChangeSceneToFile("res://scenes/MainMenu.tscn");
        };

        AddChild(_videoPlayer);
    }

    // 按空格键播放
    public override void _Input(InputEvent @event)
    {
        if (@event is InputEventKey { Pressed: true } keyEvent && keyEvent.Keycode == Key.Space)
        {
            _videoPlayer.Play();
        }
    }
}

GDScript

extends Control

var video_player: VideoStreamPlayer

func _ready():
    video_player = VideoStreamPlayer.new()
    video_player.stream = load("res://assets/video/intro.ogv")
    video_player.autoplay = false
    video_player.volume_db = -5  # 稍微降低音量
    video_player.size = Vector2(800, 600)
    video_player.set_anchors_preset(Control.LayoutPreset.CENTER)

    video_player.finished.connect(func():
        print("视频播放完毕")
        # 播放完毕后跳转到主菜单
        get_tree().change_scene_to_file("res://scenes/MainMenu.tscn")
    )

    add_child(video_player)

# 按空格键播放
func _input(event: InputEvent):
    if event is InputEventKey and event.pressed and event.keycode == KEY_SPACE:
        video_player.play()