Video Playback

Microsoft::Xna::Framework::Media — VideoPlayer, Video, FFmpeg-backed frame decoding

Overview

VideoPlayer and Video live in the Microsoft::Xna::Framework::Media namespace, matching the XNA 4.0 API. CNA uses FFmpeg as its optional video decoding back-end (a separate CNA::VideoFfmpeg module): the decoder reads compressed frames from the container, converts them from YUV colour space to RGBA, and uploads the result as a Texture2D. Your Draw() method retrieves that texture each frame via VideoPlayer::GetTexture() and renders it with SpriteBatch (or any other drawing path) exactly like any other Texture2D.

This is a real decoder, and it is no longer the only implemented part of Media. MediaPlayer genuinely plays songs, while MediaLibrary resolves the user's music and pictures directories, scans them recursively, parses common audio tags and playlists, discovers album art, and persists pictures. Treat individual device/library behaviors as platform-dependent rather than as a Windows Phone or Zune service emulation.

Frame timing is driven by the stream's own presentation timestamps rather than by a fixed frame counter, so playback tracks the container's real timeline instead of drifting against it.

Supported container and codec combinations:

• MP4 — H.264 / H.265
• OGV — Ogg Theora
• WEBM — VP8 / VP9
• MKV — Matroska (any FFmpeg-supported codec)
• AVI — legacy container
• MOV — QuickTime container

Video Class

A Video object represents a video asset loaded from disk. Load it through the standard ContentManager pipeline:

// LoadContent()  — Load<T> returns the Video by value
Video video = getContentProperty().Load<Video>("videos/intro");

The ContentManager resolves the file extension automatically (.mp4, .ogv, .webm, .mkv, .avi, .mov as loose files); the path should be relative to the content root and omit the extension. A compiled .xnb or .cnb video asset loads too: the built-in VideoReader is registered in every build and carries the metadata, and the media file itself is referenced, not embedded. Video has no default constructor (only CNAEXT constructors taking a file name and a graphics device, with optional metadata), so keep it in a std::optional<Video> or a std::unique_ptr when it is a class member. Once loaded, the following read-only properties are available:

VideoPlayer Class

VideoPlayer controls playback of a Video asset. Create one instance per active video stream; it is not designed for concurrent playback of multiple videos from the same instance.

Methods

Properties

Rendering Pattern

VideoPlayer decodes frames on demand rather than pre-decoding the entire video. On each call to GetTexture(), CNA checks whether the elapsed playback time requires a new frame to be decoded, converts the YUV output to RGBA, and uploads it to the GPU as a Texture2D. This means the texture pointer returned by GetTexture() is stable for the lifetime of the player, but its contents are updated in-place each frame.

The recommended pattern inside Draw():

1. Call player.GetTexture() (a VideoPlayer member) to obtain the current frame as a Texture2D*.
2. If the pointer is non-null, draw it with SpriteBatch::Draw() scaled to the desired screen rectangle.

Platform Availability

FFmpeg Setup

FFmpeg is an optional dependency, located through pkg-config at configure time and controlled by CNA_ENABLE_VIDEO. It must be installed on the host system before building CNA if you want video decoding:

On Debian and Ubuntu, the four development packages the build probes for are:

sudo apt install libavcodec-dev libavformat-dev libavutil-dev libswresample-dev

The decoder is built on libavcodec (codec implementations), libavformat (container demuxers), libavutil and libswresample (audio resampling). A game that never plays video can say so explicitly and drop the dependency:

cmake -S . -B build -DCNA_ENABLE_VIDEO=OFF

That build has no FFmpeg link edge at all; using Game or audio-only MediaPlayer does not bring FFmpeg into the final executable, and MediaLibrary reports an unknown (zero) duration for tracks because audio-duration probing also needs the backend. When the backend is present, CNA defines CNA_VIDEO_AVAILABLE (and the older CNA_FFMPEG_AVAILABLE) on its targets.

Code Examples

Loading and playing a video

// Game member variables
std::optional<Video> m_introVideo;          // Video has no default constructor
VideoPlayer          m_videoPlayer;

// LoadContent()
void MyGame::LoadContent() {
    spriteBatch_ = std::make_unique<SpriteBatch>(getGraphicsDeviceProperty());
    try {
        m_introVideo.emplace(getContentProperty().Load<Video>("videos/intro"));
        m_videoPlayer.setIsLoopedProperty(false);
        m_videoPlayer.setVolumeProperty(1.0f);
        m_videoPlayer.Play(&*m_introVideo);
    } catch (const System::NotSupportedException&) {
        // This build has no FFmpeg video backend (or the platform cannot decode): skip the intro.
        m_introVideo.reset();
    }
}

Getting the current frame and drawing with SpriteBatch

// Draw()
void MyGame::Draw(const GameTime& gameTime) {
    getGraphicsDeviceProperty().Clear(Color::Black);

    if (Texture2D* frame = m_videoPlayer.GetTexture()) {
        const Viewport vp = getGraphicsDeviceProperty().getViewportProperty();
        spriteBatch_->Begin();
        spriteBatch_->Draw(
            *frame,
            Rectangle(0, 0, vp.getWidthProperty(), vp.getHeightProperty()),
            Color::White);
        spriteBatch_->End();
    }
}

Checking playback state and looping

// Update()
void MyGame::Update(GameTime& gameTime) {
    if (!m_introVideo || m_videoPlayer.getStateProperty() == MediaState::Stopped) {
        // Intro finished (or unavailable) — transition to the main menu
        LoadMainMenu();
        return;
    }

    // Display elapsed / total time
    System::TimeSpan pos   = m_videoPlayer.getPlayPositionProperty();
    System::TimeSpan total = m_introVideo->getDurationProperty();
    UpdateProgressBar(pos, total);
}

// Enable looping before playback begins
m_videoPlayer.setIsLoopedProperty(true);
m_videoPlayer.Play(&*m_backgroundVideo);

Pausing and resuming on input

// Update()
void MyGame::Update(GameTime& gameTime) {
    auto kb = Keyboard::GetState();

    if (kb.IsKeyDown(Keys::Space) && m_prevKeyboard.IsKeyUp(Keys::Space)) {
        if (m_videoPlayer.getStateProperty() == MediaState::Playing) {
            m_videoPlayer.Pause();
        } else if (m_videoPlayer.getStateProperty() == MediaState::Paused) {
            m_videoPlayer.Resume();
        }
    }

    if (kb.IsKeyDown(Keys::Escape) && m_prevKeyboard.IsKeyUp(Keys::Escape)) {
        m_videoPlayer.Stop();
    }

    m_prevKeyboard = kb;
}

For a complete walkthrough, including a compile-time guard with CNA_VIDEO_AVAILABLE, see Tutorial 121: Video Playback.