aionowplaying

English | 中文

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

# Create player with metadata and callbacks
player = NowPlaying(
    "My Player",
    metadata={
        "title": "Song Name",
        "artist": ["Artist"],
        "album": "Album",
        "duration": timedelta(minutes=3, seconds=30),
    },
    on_play=lambda: my_player.play(),
    on_pause=lambda: my_player.pause(),
    on_next=lambda: my_player.next(),
)

# 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

Documentation

• 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/html

Development

Install dependencies and run tests:

uv sync --dev
uv run pytest -v

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