Hardware-accelerated MP4 video playback (H.264/HEVC) using the OS's own decoders. Zero-copy to the GPU, drop-in compatible with Godot's VideoStreamPlayer. Instead of bundling a software decoder, this GDExtension uses each OS's media framework purely as a hardware decoder and presents decoded frames to the GPU with no CPU copies.

Drop a recognized clip (.mp4, .mov, .m4v) onto a stock VideoStreamPlayer to play it. No scene setup, no custom nodes required.

HIGHLIGHTS

• Decoder mode, engine-owned clock — audio-master sync with a monotonic fallback for silent clips; drop-late/hold-early present policy recovers from decode hiccups without permanent drift.
• Zero-copy present pipeline — no per-frame CPU copies, no BGRA→RGBA swizzle, no GPU round-trip (see platform notes below for the one Windows exception).
• Hardware decode via the OS — low CPU and battery, no bundled FFmpeg.
• Adaptive scrubbing — keyframe-only while dragging fast, exact frame on settle.
• Shared decode-worker pool — many videos in one scene without a thread per video.

REQUIREMENTS

• Godot 4.4+
• Forward+ or Mobile renderer (RenderingDevice). The Compatibility/OpenGL renderer is not supported — there is no CPU present path.

PLATFORM SUPPORT

• macOS (AVFoundation) — supported, always zero-copy.
• Windows (Media Foundation) — supported. Present path is chosen automatically at runtime based on your Godot version and rendering driver: Godot 4.5+ with the d3d12 driver gets zero-copy D3D12 import (recommended); stock Vulkan gets a verified CPU-copy fallback (one GPU→CPU readback per frame).
• Linux — not yet supported (GStreamer vs. VA-API backend decision pending).

V1 DECODE SCOPE

• Codecs: H.264, HEVC (Main and Main10).
• Containers: MP4, MOV (registers .mp4, .mov, .m4v).
• Pixel formats: NV12 (8-bit) and x420/P010 (10-bit), matched to the source's bit depth.
• Colorimetry: BT.709, BT.601, BT.2020 matrices and primaries; BT.709, PQ (HDR10), and HLG transfer functions.
• HDR: PQ/HLG clips tone-map to watchable SDR by default, or output scene-linear HDR (RGBA16F) on request.
• Audio: AAC → interleaved float32 PCM, with mono/stereo/5.1 channel mixing. Multi-track audio is supported — enumerate tracks with get_audio_tracks() and select one via VideoStreamPlayer.audio_track.

HEVC playback additionally depends on the OS having an HEVC decoder installed (built-in on macOS; on Windows, typically the "HEVC Video Extensions" package from the Microsoft Store — not present on all machines).

KNOWN LIMITATIONS

• Headless mode: decode and audio keep running, but no texture output (no RenderingDevice).
• VP9/AV1 are out of scope for v1.
• Mixed-sample-rate audio tracks: the first track's sample rate wins; a mid-stream switch to a differing rate is refused.

Full documentation, architecture notes, and build-from-source instructions: https://github.com/claytercek/gdextension-platform-media-streams