# 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.
```rust,no_run
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");
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:
```rust,ignore
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.
| 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:
```rust,no_run
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.
[zbus]: https://crates.io/crates/zbus
[souvlaki]: https://github.com/Sinono3/souvlaki