Skip to content

About

🚀 A cross-platform Now Playing client for Linux (MPRIS2), macOS, and Windows, providing a unified Python interface for integrating current playback information. | 跨平台的 Now Playing 客户端,支持 Linux (MPRIS2)、macOS 和 Windows,提供统一的 Python 接口来集成当前播放信息。

Topics

Resources

Stars

8 stars

Watchers

1 watching

Forks

Repository files navigation

aionowplaying

English | 中文

CI codecov PyPI version Python versions PyPI downloads Platforms Read the Docs Made with uv License: GPL-3.0

A cross-platform Now Playing client for Linux (MPRIS2), macOS, and Windows.

Features

  • Unified Python interface for Now Playing integration across platforms.
  • Platform-specific backends selected automatically at runtime.
  • Typed playback/property models powered by Pydantic.

Installation

pip install aionowplaying

If you use uv:

uv add aionowplaying

Quick Start

import 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())

Advanced Usage

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
        pass

BaseInterface Platform Coverage

The 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.

Construction And Lifecycle

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

App-Level Callbacks

Method Linux (MPRIS2) macOS Windows
on_fullscreen 🟢 Native
Fullscreen setter
🔴 Unimplemented 🔴 Unimplemented
on_raise 🟢 Native
Raise command
🔴 Unimplemented 🔴 Unimplemented
on_quit 🟢 Native
Quit command
🔴 Unimplemented 🔴 Unimplemented

Playback Callbacks

Method Linux (MPRIS2) macOS Windows
on_loop_status 🟢 Native
LoopStatus setter
🟢 Native
repeat command
🟢 Native
repeat request
on_rate 🟢 Native
Rate setter
🟢 Native
rate command
🟢 Native
rate request
on_shuffle 🟢 Native
Shuffle setter
🟢 Native
shuffle command
🟢 Native
shuffle request
on_volume 🟢 Native
Volume setter
🔴 Unimplemented 🟡 Partial
read-only sound level
on_next 🟢 Native
Next command
🟢 Native
next command
🟢 Native
Next button
on_previous 🟢 Native
Previous command
🟢 Native
previous command
🟢 Native
Previous button
on_pause 🟢 Native
Pause command
🟢 Native
pause command
🟢 Native
Pause button
on_play_pause 🟢 Native
PlayPause command
🟢 Native
toggle command
🔴 Unimplemented
on_play 🟢 Native
Play command
🟢 Native
play command
🟢 Native
Play button
on_stop 🟢 Native
Stop command
🟡 Partial
framework-dependent
🟢 Native
Stop button

Position And URI Callbacks

Method Linux (MPRIS2) macOS Windows
on_seek 🟢 Native
offset seek
🟡 Partial
absolute position
🟡 Partial
absolute position
on_open_uri 🟢 Native
OpenUri command
🟡 Library helper
open URI from current process
🟡 Library helper
open URI from current process
on_set_position 🟢 Native
SetPosition command
🟢 Native
position command
🟢 Native
position request
seeked 🟢 Native
Seeked signal
🔴 Unimplemented 🔴 Unimplemented

URI Activation

URI activation is a split responsibility:

  • On Linux, on_open_uri is 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:

Property APIs

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
🟡 Partial
Position/Rate native, others cached
⚪ Cache only
cached value
get_tracklist_property 🟢 Native
TrackList properties
⚪ Cache only
cached value
⚪ Cache only
cached value

Documentation

Build docs locally:

sphinx-build -b html docs docs/_build/html

Development

Install dependencies and run tests:

uv sync --dev
uv run pytest -v

Website

This 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.py

The generated site is written to dist/.

GitHub Pages is configured in .github/workflows/pages.yml and publishes the site automatically on pushes to master.

License

This project is licensed under GPL-3.0-only. See LICENSE.txt.

Contributing

Contributions are welcome! Please follow the guidelines below.

Reporting Issues

If you find a bug or have a feature request:

  1. Search existing issues to avoid duplicates
  2. Use the appropriate issue template:
    • Bug Report: For reporting bugs and errors
    • Feature Request: For suggesting new features
    • Question/Other: For other inquiries
  3. 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

Pull Requests

  1. Fork the repository and create a feature branch from master
  2. Run tests locally: uv run pytest -v
  3. Ensure code follows project conventions
  4. Write clear commit messages
  5. Push your changes and create a pull request
  6. Fill out the PR template with all relevant details

Development Setup

# 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 .

About

🚀 A cross-platform Now Playing client for Linux (MPRIS2), macOS, and Windows, providing a unified Python interface for integrating current playback information. | 跨平台的 Now Playing 客户端,支持 Linux (MPRIS2)、macOS 和 Windows,提供统一的 Python 接口来集成当前播放信息。

Topics

Resources

Stars

8 stars

Watchers

1 watching

Forks

Releases

Used by

Contributors

Languages