Unity VideoPlayer组件使用教程：核心参数详解与视频播放进度控制

本文详细介绍如何在 Unity 游戏引擎中使用 VideoPlayer 组件播放视频，涵盖其支持的格式、核心参数配置及多种渲染模式。同时，文章将分享两个实用技巧：如何将视频渲染到 UI 层以实现视频上方显示 UI 元素，以及通过脚本精确控制视频播放进度。

一、VideoPlayer 组件核心功能与参数

VideoPlayer 组件是 Unity 用于播放视频文件的核心工具，常用于播放过场动画、在 3D 对象（如场景中的电视机屏幕）表面播放视频等场景。

支持格式： MP4， .mov， .webm， .wmv。

以下示例展示了在球形 3D 对象的材质贴图上播放视频的效果：

如图所示，Material Property 的值被自动设置为 GameObject 上 Renderer 组件的材质主贴图（Main Texture）。视频内容被渲染到该贴图上，从而实现了视频在球体表面播放的视觉效果。

VideoPlayer 支持将视频渲染到多种目标：

• Camera Plane (近平面或远平面)
• Render Texture (渲染纹理)
• Material Override (材质的指定纹理)
• 其他指定的 Texture

主要参数详解

• Source (视频源)： 指定视频来源。
  • Video Clip： 直接指定项目中的视频文件（Video Clip）对象。
  • URL： 指定本地或远程视频文件的路径。
• Play On Awake： 场景启动时是否自动播放。若取消勾选，则需在代码中调用 Play() 方法。
• Wait For First Frame： 勾选后，Unity 会等待视频数据准备就绪后才开始播放，确保视频播放与 GameObject 生命周期同步。
• Loop： 是否循环播放。
• Playback Speed： 播放速度倍率 (0-10)，1为正常速度。
• Render Mode (渲染模式)： 决定视频画面的输出目标。
  • Camera Far Plane： 渲染到指定摄像机的远平面，会被场景中的 3D 物体遮挡。
  • Camera Near Plane： 渲染到指定摄像机的近平面，可设置 Alpha 透明度以实现半透明叠加效果。
  • Render Texture： 将视频渲染到指定的 Render Texture 上，可用于后期处理或作为其他材质的输入。这在构建复杂的 云原生/IaaS 应用架构中的媒体处理流水线时可能用到。
  • Material Override： 将视频渲染到指定 Renderer 组件的材质贴图上。Material Property 用于指定目标纹理属性。
  • API Only： 仅渲染到 VideoPlayer.texture 属性，必须在脚本中手动将此纹理赋给目标对象。
• Aspect Ratio (宽高比模式)： 当渲染目标为摄像机平面或 Render Texture 时，用于控制视频画面的适配方式（如居中、拉伸、裁剪等）。
• Audio Output Mode (音频输出模式)： 定义音频流的输出目标。
  • None： 不输出音频。
  • Audio Source： 输出到指定的 Audio Source 组件。
  • Direct： 直接输出到声卡。
  • API Only： 输出到 AudioSampleProvider，供脚本处理。

二、通过脚本控制 VideoPlayer

以下是一个使用 C# 脚本动态创建并控制 VideoPlayer 的示例：

using UnityEngine;
using UnityEngine.Video; // 注意引入命名空间

public class VideoController : MonoBehaviour
{
    void Start()
    {
        // 找到主摄像机并添加VideoPlayer组件
        GameObject camObject = GameObject.Find("Main Camera");
        VideoPlayer videoPlayer = camObject.AddComponent<VideoPlayer>();

        // 配置参数
        videoPlayer.playOnAwake = false;
        videoPlayer.renderMode = VideoRenderMode.CameraNearPlane;
        videoPlayer.targetCameraAlpha = 0.5f; // 设置透明度，可看到背后场景
        videoPlayer.url = "/Users/username/movie.mov"; // 设置视频文件路径

        // 跳过前100帧
        videoPlayer.frame = 100;

        // 注册视频播放完毕回调事件
        videoPlayer.loopPointReached += OnVideoEndReached;

        // 开始播放
        videoPlayer.Play();
    }

    void OnVideoEndReached(VideoPlayer vp)
    {
        // 播放完毕后，将播放速度设置为0.5倍慢放
        vp.playbackSpeed = 0.5f;
        Debug.Log("视频播放结束，进入慢放模式。");
    }
}

三、实用经验技巧

1. 在视频上方显示 UI

将视频的 Render Mode 设置为 Camera Far Plane，并指定渲染到你的 UICamera。由于 UI 通常由 UICamera 渲染在更近的平面上，这样视频就作为背景，UI 元素可以自然地显示在其上方。这是 前端 & 移动 开发中实现丰富视觉效果的常用思路。

2. 精确控制视频播放进度

你可以通过 videoPlayer.time 属性直接跳转到视频的特定时间点。这在实现视频预览、快进快退等功能时非常有用。合理设计进度跳转逻辑，有时也需要一些简单的 算法/数据结构 思维来优化用户体验。

// 假设 videoPlayer 是已初始化的 VideoPlayer 实例
float minTime = 0;
float maxTime = (float)videoPlayer.clip.length; // 获取视频总长度

// 跳转到第4秒（确保时间在有效范围内）
if (4 >= minTime && 4 <= maxTime)
{
    videoPlayer.time = 4;
}