playwire 2.1.0

Cross-platform OS media controls and now-playing metadata: MPRIS, SMTC and Now Playing behind one API.
Documentation

playwire

Cross-platform OS media controls and now-playing metadata, behind one API.

  • Linux — MPRIS v2 over D-Bus (pure Rust via zbus; no libdbus to link)
  • Windows — System Media Transport Controls
  • macOS — MPNowPlayingInfoCenter / MPRemoteCommandCenter

You publish a [PlaybackState] whenever something changes, and receive an [Event] whenever the user presses a media key or touches the OS media widget.

use std::time::Duration;
use playwire::{Capabilities, MediaControls, PlaybackState, PlayerConfig, Repeat, Track};

# fn main() -> playwire::Result<()> {
let config = PlayerConfig::new("Fauxplayer")
    .desktop_entry("com.example.fauxplayer")
    .track_id_prefix("/com/example/fauxplayer/track");

let mut controls = MediaControls::new(config, |event| {
    // Called from an OS thread: hand off, don't block.
    println!("{event:?}");
})?;

controls.set_state(&PlaybackState {
    track: Some(Track {
        id: "1234".to_string(),
        title: "When The Sun Hits".to_string(),
        artists: vec!["Slowdive".to_string()],
        album: "Souvlaki".to_string(),
        artwork_url: "https://example.com/art.jpg".to_string(),
        url: "https://example.com/track/1234".to_string(),
    }),
    playing: true,
    position: Duration::from_secs(42),
    duration: Some(Duration::from_secs(290)),
    volume: 1.0,
    repeat: Repeat::Off,
    shuffle: false,
    capabilities: Capabilities { can_go_next: true, can_go_previous: false, can_seek: true },
})?;
# Ok(())
# }

Controls detach on drop.

Platform notes

PlayerConfig::hwnd is required on Windows — SMTC attaches to a window. Get it from your windowing library's raw window handle (HWND as an integer). To show your app's name and icon in the Windows media flyout, register an AppUserModelID on your installed Start Menu shortcut (or app package) and use the same ID for the process and PlayerConfig::app_media_id. The Windows backend publishes that ID to SMTC. If app_media_id is omitted, it uses an AppUserModelID already set explicitly on the process. identity is a display name and does not register a Windows app; without a resolvable ID, the flyout may say "Unknown app". For example:

let config = PlayerConfig::new("Fauxplayer")
    .hwnd(hwnd)
    .app_media_id("com.example.fauxplayer");

On Linux, desktop_entry is what lets GNOME and KDE resolve your player to its .desktop file and show your icon in the media widget. Without it you get a generic placeholder.

On macOS the process needs a running NSApplication for Now Playing to appear.

Feature support

Not every platform exposes every control. Publishing state that a backend cannot represent is silently ignored rather than an error.

Linux Windows macOS
Play / Pause / PlayPause / Next / Previous ✓ ✓ ✓
Stop ✓ ✓ ✓
Seek to position ✓ ✓ ✓
Seek by amount ✓ ✓ (fixed 10s) —
Volume ✓ — —
Shuffle / repeat ✓ ✓ ✓
Capability flags ✓ ✓ ✓
Artwork ✓ URL ✓ URL ✓ fetched
Raise / Quit / OpenUri ✓ — —
Track list / GoTo ✓ — —

Track lists

On Linux, publish an ordered list of nearby queue entries for MPRIS clients:

use playwire::{MediaControls, Track, TrackListEntry};
use std::time::Duration;

# fn publish(controls: &mut MediaControls) -> playwire::Result<()> {
let queue = vec![TrackListEntry {
    track: Track { id: "queue_entry_1".into(), title: "Alison".into(), ..Track::default() },
    duration: Some(Duration::from_secs(231)),
}];
controls.set_tracklist(Some(&queue))?;
# Ok(())
# }

Use a stable, nonempty ID for each queue occurrence, even when the same song appears more than once. IDs must remain unique after characters outside ASCII letters and digits are replaced with underscores. Publish the current track with the same ID in PlaybackState. Handle Event::GoTo(id) to play a requested entry, then publish the resulting state. Republish the list when it changes; Some(&[]) publishes an empty list and None disables it. MPRIS clients cannot edit the list. Windows and macOS ignore track lists.

Position updates

Publish position on every tick. Backends diff against the last snapshot, so unchanged fields cost nothing: MPRIS Position is deliberately not a change-signalling property (clients extrapolate from Rate and the Seeked signal, which is emitted only on genuine discontinuities), and Windows and macOS only rebuild their timeline when the track or duration actually changes.

Prior art

souvlaki solves the same problem and was the reference for this crate's shape. playwire exists because souvlaki has been unmaintained for over a year and its backends are missing pieces that a real player needs: no shuffle or repeat on any platform, capability flags hardcoded to true, mpris:trackid emitted as the literal /, a single artist rather than the credited list, no xesam:url, no DesktopEntry (and HasTrackList misspelled), no stopCommand on macOS, and no MPNowPlayingInfoPropertyPlaybackRate — without which Control Center's scrubber never advances. Its macOS backend also reads the seek position out of the private _positionTime ivar rather than the public accessor.

No souvlaki code is vendored here; every backend is written against current crates.

License

MIT OR Apache-2.0, at your option.