Unity Video Playback

Retrieval Sources

That's 74 verified rows, well above the 20-30+ target; the local docs set covers all 125 Video-namespace pages, and the rows above were selected as the ones that carry unique, actionable information (the remaining ~50 pages are either per-enum-member stub pages with no content beyond their parent enum's page, or unrelated Video* matches like PlayerLoop.PreUpdate.UpdateVideo, Profiling.ProfilerArea.Video, and Windows VideoCapture/WebCamTexture APIs that belong to other subsystems, not the UnityEngine.Video playback namespace).

Key Guidelines

VideoPlayer Setup & Render Modes

A VideoPlayer component is a source (VideoClip or URL) routed to a target via renderMode (Manual/VideoPlayer-intro.html, ScriptReference/Video.VideoRenderMode.html). Unity picks a sensible default when you create the component: dropping a clip onto an existing Renderer-bearing GameObject sets MaterialOverride targeting that Renderer's main texture; dragging a clip into empty scene space targets the main camera's far plane; adding the component via script defaults to RenderTexture unless it's on a Camera, in which case it defaults to that camera's background plane. The five render modes serve different purposes: CameraNearPlane draws in front of everything (cutscene overlays, letterboxed intros, UI-level video), CameraFarPlane draws behind everything (animated skyboxes, backgrounds), RenderTexture decouples the video from any camera so multiple GameObjects or post-processing can share one texture, MaterialOverride writes directly into a specific Renderer's material property (video on a screen prop, a monitor, a in-world billboard) without an intermediate Render Texture, and APIOnly produces no automatic draw target at all — you pull frames yourself via VideoPlayer.texture for a fully custom pipeline (e.g. feeding a UI RawImage, a compute shader, or a native plugin). Camera-plane modes expose a global targetCameraAlpha for letting the scene show through; RenderTexture/MaterialOverride don't have that field because transparency there comes from the texture's own alpha channel and how the receiving material blends it. Preparation and playback are decoupled from render-mode choice — set the mode before or after assigning a source, but set it before the first frame is expected to show up somewhere meaningful.

using UnityEngine;
using UnityEngine.Video;

public class CutsceneVideoPlayer : MonoBehaviour
{
    [SerializeField] private VideoClip clip;
    [SerializeField] private Camera targetCamera;
    [SerializeField] private RenderTexture cutsceneTexture; // pre-configured per VideoPlayer-rendertexture.html
    [SerializeField] private AudioSource narrationAudio;

    private VideoPlayer player;

    void Awake()
    {
        player = gameObject.AddComponent<VideoPlayer>();
        player.playOnAwake = false;               // we drive Play() ourselves after Prepare()
        player.source = VideoSource.VideoClip;
        player.clip = clip;

        // Render to an offscreen texture so it can also feed a UI RawImage or a monitor prop.
        player.renderMode = VideoRenderMode.RenderTexture;
        player.targetTexture = cutsceneTexture;

        // Route audio through a dedicated AudioSource instead of Direct output
        // so it can be positioned, ducked, or routed through a mixer group.
        player.audioOutputMode = VideoAudioOutputMode.AudioSource;
        player.EnableAudioTrack(0, true);
        player.SetTargetAudioSource(0, narrationAudio);

        player.waitForFirstFrame = true;           // avoid showing a blank/garbage first frame
        player.isLooping = false;

        player.prepareCompleted += OnPrepareCompleted;
        player.loopPointReached += OnVideoFinished;
        player.errorReceived += OnVideoError;

        player.Prepare(); // start preparing immediately; Play() is called once ready
    }

    void OnPrepareCompleted(VideoPlayer vp)
    {
        Debug.Log($"Cutscene ready: {vp.clip.name}, {vp.frameCount} frames @ {vp.frameRate} fps");
        vp.Play();
    }

    void OnVideoFinished(VideoPlayer vp)
    {
        Debug.Log("Cutscene finished playing.");
        // Hand control back to gameplay here.
    }

    void OnVideoError(VideoPlayer vp, string message)
    {
        Debug.LogError($"VideoPlayer error: {message}");
    }
}

Video Clip Import Settings & Formats

Importing a video file creates a VideoClip asset whose Inspector exposes an sRGB (Color Texture) toggle (leave enabled for normal color footage, disable for non-color/data video) and a Transcode toggle (Manual/class-VideoClip.html). With Transcode off, Unity ships the source file's container/codec as-is into the build — fastest import, smallest build-time cost, but you are responsible for verifying every target platform can decode it (Manual/video-sources-compatibility-target-platforms.html). With Transcode on, the Video Clip Importer re-encodes into one of three codecs — H.264, H.265, or VP8 — automatically pairing the matching audio codec (AAC for H.264/H.265, Vorbis for VP8), and exposes Dimensions (resize/aspect controls), Bitrate Mode (Low/Medium/High), Spatial Quality, Keep Alpha, Deinterlace, Flip Horizontal/Vertical, and Import Audio (Manual/video-transcode-intro.html, Manual/video-encoding-compatibility.html). Transcoding is scriptable per-platform via VideoClipImporter.SetTargetSettings(BuildTargetGroup, VideoImporterTargetSettings) for batch pipelines that need e.g. VP8/WebM for Linux/Android and H.264/MP4 everywhere else. Codec choice follows real tradeoffs: H.264 has the widest native hardware-decode support and is the safe default; H.265 compresses better but needs newer hardware (6th-gen+ Intel, iOS 11+ with A9+ for hardware decode, Android 5.0+, Windows 10 + HEVC extension) so treat it as an optional high-end target, not a baseline; VP8 is cross-platform and open but costs more CPU than hardware H.264 decode, though Android does have native VP8 hardware acceleration on many devices. .ogv imports fine in the Editor but is not broadly supported on other platforms and should always be transcoded to .mp4/.webm before shipping.

using UnityEditor;
using UnityEngine;

public static class BatchVideoImportSettings
{
    [MenuItem("Tools/Video/Apply Mobile Transcode Preset")]
    public static void ApplyMobilePreset()
    {
        foreach (var guid in AssetDatabase.FindAssets("t:VideoClip", new[] { "Assets/Video/Cutscenes" }))
        {
            var path = AssetDatabase.GUIDToAssetPath(guid);
            var importer = AssetImporter.GetAtPath(path) as VideoClipImporter;
            if (importer == null) continue;

            var androidSettings = new VideoImporterTargetSettings
            {
                enableTranscoding = true,
                codec = VideoCodec.H264,
                bitrateMode = VideoBitrateMode.Medium,
                resizeMode = VideoResizeMode.ThreeQuarterRes,
                spatialQuality = VideoSpatialQuality.MediumSpatialQuality,
            };
            importer.SetTargetSettings("Android", androidSettings);
            importer.importAudio = true;
            importer.deinterlaceMode = VideoDeinterlaceMode.Off; // source is already progressive
            importer.SaveAndReimport();
        }
    }
}

Audio Output Configuration

VideoAudioOutputMode (ScriptReference/Video.VideoAudioOutputMode.html) has four values: None mutes embedded audio entirely (useful for background/ambient loops you don't want competing with game audio, or when audio is handled separately); Direct sends embedded audio straight to the platform's audio hardware, bypassing Unity's AudioSource/AudioMixer graph entirely — lowest latency and overhead, but no mixing, no spatialization, no mixer-group routing; AudioSource routes each enabled audio track into an AudioSource you assign via VideoPlayer.SetTargetAudioSource(trackIndex, source), which lets video audio participate in the normal mixer graph (ducking, snapshots, spatial blend, output group) exactly like any other clip; APIOnly produces no automatic output, letting you pull audio via the audio sample-provider API for a fully custom pipeline. A clip's audio tracks must be individually enabled with VideoPlayer.EnableAudioTrack(trackIndex, true) before playback — disabling unused tracks skips decoding them entirely (cheaper than track-muting, which still decodes). On WebGL only None and Direct are reliably supported; requesting AudioSource mode there still plays audio but Unity ignores every AudioSource field except mute, since 3D spatialization of video audio isn't available on the web (Manual/webgl-video.html).

using UnityEngine;
using UnityEngine.Video;
using UnityEngine.Audio;

public class VideoAudioRouting : MonoBehaviour
{
    [SerializeField] private VideoPlayer player;
    [SerializeField] private AudioSource dialogueSource; // routed to a "Dialogue" AudioMixerGroup
    [SerializeField] private AudioMixerGroup dialogueGroup;

    void Awake()
    {
        dialogueSource.outputAudioMixerGroup = dialogueGroup;

        player.audioOutputMode = VideoAudioOutputMode.AudioSource;

        // Must enable each track you intend to use before playback starts.
        player.EnableAudioTrack(0, true);
        player.SetTargetAudioSource(0, dialogueSource);

        // If the clip has a second (e.g. commentary) track and we don't need it,
        // leave it disabled so Unity skips decoding it entirely.
        if (player.clip != null && player.clip.audioTrackCount > 1)
            player.EnableAudioTrack(1, false);
    }
}

Streaming from URL

Setting VideoPlayer.source = VideoSource.Url and VideoPlayer.url = "..." plays video that isn't imported as a project asset (Manual/video-sources-reference.html, ScriptReference/Video.VideoPlayer-url.html). Three URL forms are supported on native platforms: a bare/file:// local filesystem path (useful for user-generated content or downloaded video, with no asset-pipeline management — you must guarantee the path is valid and accessible yourself); an http:///https:// web URL, for which Unity performs its own pre-buffering and error handling; and a StreamingAssets-relative path built from Application.streamingAssetsPath, for files that ship with the build but bypass normal asset import/compression. A player can hold both a clip and a url at once — whichever was assigned most recently wins, and VideoPlayer.source lets you switch between them explicitly without clearing the other. On the Web (WebGL) platform, only VideoSource.Url is supported at all (clip is not supported), and the URL must be a real web URL — local filesystem and Application.persistentDataPath playback are not supported there. Because URL-sourced content is never scanned by the asset importer, none of its metadata (length, width/height, audioTrackCount, etc.) is known until Prepare()/Play() completes — always gate any UI or logic that reads those properties on isPrepared being true.

using System.Collections;
using UnityEngine;
using UnityEngine.Video;
using UnityEngine.Networking;

public class StreamedVideoLoader : MonoBehaviour
{
    [SerializeField] private VideoPlayer player;
    [SerializeField] private string remoteUrl = "https://example.com/videos/intro.mp4";

    IEnumerator Start()
    {
        player.playOnAwake = false;
        player.source = VideoSource.Url;
        player.url = remoteUrl;

        player.Prepare();
        while (!player.isPrepared)
        {
            // Optionally surface buffering UI here; errorReceived also fires
            // if the URL is unreachable, so don't spin forever without a timeout.
            yield return null;
        }

        Debug.Log($"Streamed clip ready: {player.width}x{player.height}, {player.length:F1}s");
        player.Play();
    }

    // Example of a StreamingAssets-relative URL instead of a remote one.
    public void PlayFromStreamingAssets(string relativePath)
    {
        player.Stop();
        player.url = System.IO.Path.Combine(Application.streamingAssetsPath, relativePath);
        player.Prepare();
    }
}

Preparing, Seeking, and Looping

Prepare() reserves playback resources and preloads initial content asynchronously; it fires prepareCompleted and flips isPrepared to true on success (ScriptReference/Video.VideoPlayer.Prepare.html). Calling Play() without a prior Prepare() still works — Unity prepares implicitly first — but playback then isn't instantaneous, which matters for tightly-timed cutscenes or rhythm-critical sequences. Stop() resets time to 0 and tears down internal resources (buffers, textures), which is why isPrepared goes back to false afterward and a subsequent Play() re-pays the preparation cost; use Pause() instead when you want to halt playback but resume instantly later, since it preserves both current time and prepared state (ScriptReference/Video.VideoPlayer.Pause.html, ScriptReference/Video.VideoPlayer.Stop.html). Setting VideoPlayer.time (or frame) performs an async seek: playback moves toward the target, seekCompleted fires on arrival, then frameReady fires once that frame is actually decoded and displayed — seek latency depends on codec and how the source was encoded (frequent keyframes seek faster). isLooping = true makes loopPointReached restart the clip instead of stopping it; the event fires either way, so it's a reliable single hook for both "loop again" and "cutscene over, hand back control" logic. skipOnDrop (gated by canSetSkipOnDrop) controls whether the player catches up by skipping frames when it falls behind its time source, versus playing every frame regardless of drift; frameDropped fires whenever the decoder misses a scheduled frame, which is a good signal for detecting playback performance problems on-device. StepForward() pauses (if playing) and advances exactly one frame — useful for frame-accurate scrubbing/debugging tools, though it isn't frame-accurate on WebGL.

using UnityEngine;
using UnityEngine.Video;

public class VideoScrubber : MonoBehaviour
{
    [SerializeField] private VideoPlayer player;

    public void SeekToNormalized(float t01)
    {
        if (!player.isPrepared) return; // length/frameCount aren't valid before this
        player.time = player.length * Mathf.Clamp01(t01);
    }

    void OnEnable()
    {
        player.seekCompleted += vp => Debug.Log($"Seek landed at {vp.time:F2}s");
        player.frameDropped += vp => Debug.LogWarning($"Frame dropped near {vp.time:F2}s — check decode perf");
    }

    public void StepOneFrame() => player.StepForward();
}

Platform-Specific Codec Support

Codec support is a function of the target platform's native decoding libraries, not the Editor's — a file that previews fine in the Editor can still fail to decode in a build on a different OS (Manual/video-sources-compatibility-target-platforms.html). H.264 is the broadly-safe baseline codec across desktop, mobile, and console. H.265/HEVC needs explicit hardware/software capability checks per platform: on macOS, hardware encode/decode needs a 6th-generation-or-newer Intel processor while software encode/decode works on all Macs (SDK 10.13+); on Windows, both encode and decode need the HEVC Video Extensions package on Windows 10+, with hardware-only encode but hardware+software decode; on iOS/tvOS (SDK 11.0+), hardware decode needs an A9 chip or later while software decode works on all devices; on Android 5.0+ and UWP, device-family-level "H.265 supported" claims don't guarantee every device in that family actually supports it (Manual/video-encoding-compatibility.html). VP8 is Unity's software-decode fallback path (paired with Vorbis audio) and is used internally when a platform's hardware decoder imposes unwanted restrictions on resolution, multi-track audio, or alpha transparency; Linux's optimal encoding target is specifically WebM/VP8+Vorbis, since Linux has no broad H.264/H.265 hardware decode story in the Editor. WebM import is normally restricted to VP8 video + Vorbis audio, but Android, Nintendo Switch, and Web additionally support VP9 video and (on Switch/Web) Opus audio when the WebM file is loaded via StreamingAssets + VideoPlayer.url rather than the normal asset pipeline — a raw-file bypass that skips Editor codec validation entirely, at the cost of losing in-Editor preview and drag-and-drop assignment (Manual/VideoSources-FileCompatibility.html).

Common Mistakes

Quick Reference

Advanced Notes

Platform codec/format support is the dominant source of video bugs. The Editor previews video using the host OS's native decode libraries, while a build uses the target platform's — these are frequently different, so "it plays in the Editor" is not evidence it will play on-device (Manual/video-sources-compatibility-target-platforms.html). Treat H.264 as the safe cross-platform baseline; treat H.265 as an opt-in enhancement gated behind explicit per-platform hardware-generation checks (documented precisely in Manual/video-encoding-compatibility.html — e.g. 6th-gen+ Intel on macOS/Windows, A9+ chip on iOS/tvOS); treat VP8/WebM as the Linux-optimal and transparency-safe choice, at a higher CPU cost than hardware H.264 decode. Alpha-channel video narrows the codec choice further to just two options (Apple ProRes 4444 or WebM/VP8), and even VP8's alpha support isn't free on Android — the platform's hardware VP8 decode path drops alpha, forcing a transcode to Unity's software-decoded internal alpha representation to recover it. When in doubt for a multi-platform release, enable Transcode per-platform via VideoClipImporter/VideoImporterTargetSettings and let Unity produce a codec/container combination it has already validated against each target, accepting the tradeoffs of longer build times, potentially many hours for large sources, and some quality loss versus a source encoded by a purpose-built external tool.

Streaming vs. local-file playback is a genuinely different engineering problem, not just a different URL scheme. A bundled VideoClip asset is validated at import time, has all its metadata (length, dimensions, track counts) available synchronously once prepared, and its preparation cost is bounded by local I/O and decode setup. A url-sourced stream — whether http(s)://, a local file:// path outside the asset pipeline, or StreamingAssets — is never scanned by the importer, so nothing is known about it until Prepare()/Play() actually contacts it; metadata reads before that point are meaningless, and preparation failure surfaces only through the async errorReceived event (HTTP errors, missing files, permission problems, unsupported formats) rather than an exception you can catch synchronously. For genuine network streams, Unity performs its own pre-buffering, but you're still responsible for UX around buffering stalls, connectivity loss mid-playback, and (per Manual/video-clock.html) the fact that non-GameTime update modes run the player asynchronously and may skip/repeat frames to stay in sync rather than blocking the rest of the game — appropriate for background/ambient video, less so for anything that must frame-lock with gameplay or audio. StreamingAssets splits the difference: files ship with the build (so no network dependency and bounded I/O latency like a local asset) but bypass the importer's compatibility checks and per-platform transcoding entirely, which is exactly the trapdoor Manual/video-files-unsupported.html recommends for using target-platform-only formats the Editor itself can't preview — you trade in-Editor preview and drag-and-drop convenience for the ability to ship a file the Editor doesn't understand but the runtime does.