Media playback

Media playback lets people listen to audio or watch video within an app. Playback controls let them decide when to start, pause, or move through the content.

day-piece-media plays audio and video through platform players. Use a media piece for playback attached to a screen, or an audio session when playback needs to outlive that screen.

Add to your app

Add day-piece-media to your app:

cargo add 'day-piece-media@0.*'

Crate · API reference · Source. The Day CLI enables the matching toolkit feature and packages the native integration. No dependency entry is needed in Day.toml.

Play media in a view

This API excerpt accepts a URL supplied by the caller and leaves playback under the person’s control. The selected engine supplies the transport controls.

use day::prelude::*;
use day_piece_media::{media, PlaybackState};

pub fn player(url: Signal<String>, state: Signal<PlaybackState>) -> impl Piece {
    media(url).no_autoplay().state(state)
}

media() autoplays by default. Use no_autoplay() to require a deliberate start. Browser autoplay policies can block playback even when requested. For bundled media, use the generated asset constant; see resources.

Media accepts play, pause, stop, and load triggers, optional looping, mute, and reactive volume. Volume ranges from 0 to 1. Removing the piece releases its player; a newly constructed piece starts a new playback lifetime.

Observe playback and errors

Bind state(), timeline(), and error() to signals when building custom controls. Loading, buffering, playing, paused, ended, and failed states are distinct. A requested action is not proof that playback started.

MediaTimeline reports duration and seekable ranges. Live streams can have no known duration or only a moving seek window. Enable seeking according to the reported ranges rather than assuming every source can seek. Playback rate support depends on the engine; Linux GTK does not support changing it.

StreamMetadata contains stream-provided information. Treat station names and titles as external content. App-owned labels and empty states still use generated localized accessors.

Keep audio playing across screens

Retain an AudioSession in app-owned state. Its snapshots include playback, timeline, errors, and metadata. Clones share the player; dropping the last handle releases it.

use day_piece_media::{AudioSession, MediaError};

pub fn start_audio(source: String) -> Result<AudioSession, MediaError> {
    let session = AudioSession::new();
    session.load(source, true)?;
    Ok(session)
}

This is an API excerpt; the caller must retain the returned handle. A successful load() returns a load generation, not a playback-completion result. Observe the snapshot for later engine failures. Create and use the session on the UI thread.

For background playback, configure BackgroundAudio with localized presentation text on the UI thread. Android needs the media foreground service; iOS needs the audio background mode. The crate contributes these native requirements through Day’s build metadata. OS policy and permissions still govern playback. NowPlayingInfo and RemoteCommand connect metadata and system transport actions to your session.

Platform behavior

Platform / toolkitPlayer and constraints
AppKit / UIKitAVFoundation. Background audio and lock-screen behavior require the appropriate app configuration.
AndroidMedia3/ExoPlayer. Background audio uses a foreground service and media session.
WinUIMediaPlayer. Available formats depend on Windows codecs.
Linux GTKGStreamer. Install the codecs needed for your sources; playback-rate changes are unsupported.
QtQt Multimedia and its platform plugins. Include the runtime plugins in the app package.
HarmonyOSNative media players. Video supports mute but not adjustable volume.
WebHTML audio/video. Autoplay, codecs, CORS, and background behavior follow browser policy.

Test the actual formats, streams, and packaged runtime on each target. Use sound effects for short clips that do not need a media timeline. See Apple’s audio guidance and Android audio focus.