DOCSEARCHbyAlgolia
Submit Docs

OmniPlayr Documentation

website·Indexed 32 days ago

https://omniplayr.wokki20.nl/docs/

A self-hosted music player that aggregates sources like Spotify, YouTube, and SoundCloud into a single interface. It features a plugin-based architecture with a stable API, allowing users to build and install backend and frontend plugins. The system runs entirely on local hardware via Docker and supports installation on Linux, Windows, and macOS.

Tokens
25K
Snippets
138
Records
204
Agent score
49%

What's inside OmniPlayr

  1. Overview of OmniPlayr architecture

    OmniPlayr is a self-hosted, open-source music player that uses a plugin-based architecture. The core platform is source-agnostic, while individual plugins handle the logic for fetching and streaming audio from specific sources such as local files, Spotify, and YouTube Music. It runs entirely on user-owned hardware without cloud dependencies or tracking.

  2. Navigate the server setup wizard

    Once on the Overview page, click the Let's Get Started! button to proceed to the next step (Setting a Password). You can expand the steps overview on any setup page by clicking on the current step indicator to see your progress and remaining tasks.

  3. Understand OmniPlayr's local-first architecture

    OmniPlayr is a self-hosted media server that operates entirely on the user's own hardware. It requires no external services, third-party APIs, cloud dependencies, or internet connectivity for core functionality. All data—including the music library, playback history, and configuration—remains on the local network and is not synced to external servers.

  5. Unified audio playback with OmniPlayr

    OmniPlayr acts as a single interface for multiple audio sources, eliminating the need to switch between different streaming apps. It allows users to browse libraries from various services in one place and maintain a single playback queue containing tracks from different sources (e.g., a local file followed by a Spotify song) without manual routing.

  6. Understand OmniPlayr's local-first architecture

    OmniPlayr is a self-hosted media server that works entirely on the user's own hardware. It requires no external services, third-party APIs, cloud dependencies, or internet connectivity for its core functionality. All data, including the music library, play history, and configuration, remains on the local network. While the core platform is offline-capable, individual plugins may require internet access if they connect to external services.

  7. Unify multiple audio sources with OmniPlayr

    OmniPlayr acts as a single interface for multiple audio sources, eliminating the need to switch between different streaming apps. It allows users to browse libraries from various services and manage a single, unified playback queue regardless of the track's origin (e.g., a local file followed by a streaming track).

  8. Understand OmniPlayr failure page and error reporting

    OmniPlayr displays a failure page (similar to a BSOD) when the app cannot safely continue, typically during startup or due to backend-fatal failures. The failure page is triggered in three scenarios:

    1. The setup wizard reports setup or service startup failures.
    2. The backend writes a fatal crash report before exiting during startup.
    3. The frontend detects that the backend is unreachable via health checks.

    If the backend fails without writing a crash report, the frontend defaults to error code OP-BACKEND-RUNTIME-UNREACHABLE-001.

  9. Install OmniPlayr on a repurposed device

    To set up OmniPlayr on a compatible device (such as an old laptop or Raspberry Pi), follow these steps: 1. Clone the repository. 2. Run the setup script using Python 3. 3. Complete the setup wizard. 4. Access the server via a web browser using the device's IP address on port 8223.
    # 1. Clone the repository (via git)
# 2. Run the setup script
python3 setup.py
# 3. Follow the setup wizard
# 4. Access via: http://<your-device-ip>:8223

  10. Install OmniPlayr on Linux

    To install OmniPlayr, ensure you have Docker, Docker Compose, and Python 3.12+ installed. Clone the server repository and execute the setup script, which installs dependencies and launches a setup wizard. If the browser does not open automatically, access the wizard at http://<your-device-ip>:8080.
    # Verify Python version
python3 --version

# Clone and install
git clone https://github.com/OmniPlayr/OmniPlayr-server.git
cd OmniPlayr-server
python3 setup.py

  11. Handle request bodies and query parameters in API routes

    API routes use FastAPI-style parameter resolution:

    • Request Bodies: Use Pydantic models to define the expected JSON structure.
    • Query Parameters: Defined as function arguments; FastAPI resolves them automatically from the URL query string.
    from pydantic import BaseModel
from omniplayr.plugins import api, verify_auth
from fastapi import Depends

class CreateItemRequest(BaseModel):
    name: str
    url: str

# Example with Request Body
@api.post("/my-plugin/items")
def create_item(body: CreateItemRequest, auth=Depends(verify_auth)):
    return {"status": "created", "name": body.name}

# Example with Query Parameters
@api.get("/my-plugin/search")
def search(q: str, limit: int = 20, auth=Depends(verify_auth)):
    return {"query": q, "limit": limit}

  12. Register plugin routes for navigation

    Before navigating to a plugin-owned route, you must register that route using registerRoute. Route paths are not automatically namespaced, so you should include your plugin key or a unique prefix to avoid collisions with other plugins or the core app.
    import { navigate, registerRoute } from '@omniplayr/plugins';
import MyDetailPage from './MyDetailPage';

registerRoute({
    path: '/my-plugin/:id',
    component: MyDetailPage,
});

navigate('/my-plugin/123');