A cross-platform Now Playing client for Linux (MPRIS2), macOS, and Windows.
- Unified Python interface for Now Playing integration across platforms.
- Platform-specific backends selected automatically at runtime.
- Typed playback/property models powered by Pydantic.
pip install aionowplayingIf you use uv:
uv add aionowplayingimport asyncio
from datetime import timedelta
from aionowplaying import NowPlaying
# Wire media callbacks to your own application logic.
def handle_play():
pass
def handle_pause():
pass
player = NowPlaying(
"My Player",
metadata={
"title": "Song Name",
"artist": ["Artist"],
"album": "Album",
"duration": timedelta(minutes=3, seconds=30),
},
on_play=handle_play,
on_pause=handle_pause,
)
# Update metadata during playback
player.title = "New Song"
player.position = timedelta(seconds=60)
player.set_playing()
# Start the backend
asyncio.run(player.start())For fine-grained control, inherit from BaseInterface:
from aionowplaying import BaseInterface
class MyPlayer(BaseInterface):
async def on_play(self):
# Custom implementation
pass
async def on_pause(self):
# Custom implementation
passThe tables below describe native backend coverage for each BaseInterface method. They focus on platform mapping, not just whether the method can be overridden in Python.
🟢 Native: implemented or triggered by the platform backend.🟡 Partial: available with limitations or semantics that differ from the base method contract.⚪ Cache only: stored locally, but not exposed by the native platform API.🔴 Unimplemented: no platform-specific implementation. Base no-op methods are treated as unimplemented.
Linux MPRIS2 backend exposes TrackList properties, methods, and signals. Applications provide queue behavior by overriding tracklist callbacks and updating TrackList properties.
| Method | Linux (MPRIS2) | macOS | Windows |
|---|---|---|---|
__init__ |
🟢 Native D-Bus setup |
🟢 Native MediaPlayer center setup |
🟢 Native SMTC setup |
start |
🟢 Native D-Bus connect/export loop |
🟢 Native no-op |
🟢 Native no-op |
stop |
🟢 Native D-Bus disconnect |
🔴 Unimplemented | 🟡 Partial local flag only |
| Method | Linux (MPRIS2) | macOS | Windows |
|---|---|---|---|
on_fullscreen |
🟢 NativeFullscreen setter |
🔴 Unimplemented | 🔴 Unimplemented |
on_raise |
🟢 NativeRaise command |
🔴 Unimplemented | 🔴 Unimplemented |
on_quit |
🟢 NativeQuit command |
🔴 Unimplemented | 🔴 Unimplemented |
| Method | Linux (MPRIS2) | macOS | Windows |
|---|---|---|---|
on_loop_status |
🟢 NativeLoopStatus setter |
🟢 Native repeat command |
🟢 Native repeat request |
on_rate |
🟢 NativeRate setter |
🟢 Native rate command |
🟢 Native rate request |
on_shuffle |
🟢 NativeShuffle setter |
🟢 Native shuffle command |
🟢 Native shuffle request |
on_volume |
🟢 NativeVolume setter |
🔴 Unimplemented | 🟡 Partial read-only sound level |
on_next |
🟢 NativeNext command |
🟢 Native next command |
🟢 Native Next button |
on_previous |
🟢 NativePrevious command |
🟢 Native previous command |
🟢 Native Previous button |
on_pause |
🟢 NativePause command |
🟢 Native pause command |
🟢 Native Pause button |
on_play_pause |
🟢 NativePlayPause command |
🟢 Native toggle command |
🔴 Unimplemented |
on_play |
🟢 NativePlay command |
🟢 Native play command |
🟢 Native Play button |
on_stop |
🟢 NativeStop command |
🟡 Partial framework-dependent |
🟢 Native Stop button |
| Method | Linux (MPRIS2) | macOS | Windows |
|---|---|---|---|
on_seek |
🟢 Native offset seek |
🟡 Partial absolute position |
🟡 Partial absolute position |
on_open_uri |
🟢 NativeOpenUri command |
🟡 Library helper open URI from current process |
🟡 Library helper open URI from current process |
on_set_position |
🟢 NativeSetPosition command |
🟢 Native position command |
🟢 Native position request |
seeked |
🟢 NativeSeeked signal |
🔴 Unimplemented | 🔴 Unimplemented |
URI activation is a split responsibility:
- On Linux,
on_open_uriis exposed natively through MPRIS. - On macOS and Windows, the library can help the current process open a URI.
- Registering a custom protocol and receiving system URI activation still belongs to the host application.
The scheme name is host-defined. aionowplaying does not require the public scheme to be aionowplaying.
Platform docs:
docs/platform-uri-activation.rstdocs/platform-uri-activation-macos.rstdocs/platform-uri-activation-windows.rst
| Method | Linux (MPRIS2) | macOS | Windows |
|---|---|---|---|
set_property |
🟢 Native player properties |
⚪ Cache only no player-level API |
⚪ Cache only no player-level API |
set_playback_property |
🟢 Native playback properties |
🟡 Partial some fields unsupported |
🟡 Partial some fields local only |
set_tracklist_property |
🟢 Native TrackList properties with D-Bus updates |
⚪ Cache only | ⚪ Cache only |
get_property |
🟢 Native player properties |
⚪ Cache only cached value |
⚪ Cache only cached value |
get_playback_property |
🟢 Native playback properties |
🟡 PartialPosition/Rate native, others cached |
⚪ Cache only cached value |
get_tracklist_property |
🟢 Native TrackList properties |
⚪ Cache only cached value |
⚪ Cache only cached value |
- Interface/API documentation: https://aionowplaying.readthedocs.io/en/latest/
- API reference page: https://aionowplaying.readthedocs.io/en/latest/api.html
Build docs locally:
sphinx-build -b html docs docs/_build/htmlInstall dependencies and run tests:
uv sync --dev
uv run pytest -vThis repository also includes the project website and GitHub Pages build.
Install the development and docs dependencies first, then build the site locally:
uv sync --dev
uv pip install -r docs/requirements.txt
uv run python scripts/build_site.pyThe generated site is written to dist/.
GitHub Pages is configured in .github/workflows/pages.yml and publishes the site automatically on pushes to master.
This project is licensed under GPL-3.0-only. See LICENSE.txt.
Contributions are welcome! Please follow the guidelines below.
If you find a bug or have a feature request:
- Search existing issues to avoid duplicates
- Use the appropriate issue template:
- Bug Report: For reporting bugs and errors
- Feature Request: For suggesting new features
- Question/Other: For other inquiries
- Provide as much detail as possible:
- For bugs: steps to reproduce, expected vs actual behavior, environment details
- For features: use case and why it would be helpful
- Fork the repository and create a feature branch from
master - Run tests locally:
uv run pytest -v - Ensure code follows project conventions
- Write clear commit messages
- Push your changes and create a pull request
- Fill out the PR template with all relevant details
# Clone your fork
git clone https://github.com/YOUR_USERNAME/aionowplaying.git
cd aionowplaying
# Install dependencies
uv sync --dev
# Run tests
uv run pytest -v
# Run linting (if available)
uv run ruff check .