Skip to content
Rymflux Documentation
Esc
↑↓navigate↵open⌘Jpreview
On this page

Scope

Scope

Status

Draft v1 — 2026-07-30

In scope (v1)

1. Plugin system

  • Manifest format (plugin.toml) with id, name, version, entry point, supported capabilities, and permissions.
  • Plugin discovery via scanning a well-known plugins directory.
  • JSON-based communication protocol between core and plugin executables.
  • Plugin lifecycle: launch, request-response, timeout, shutdown, crash recovery.
  • Support for plugins written in any language (Python, Go, Rust, JavaScript, Bash, etc.).
  • Plugin capabilities: search, get_track, get_album, get_artist, stream. (get_lyrics is reserved for v2.)
  • Reference plugin: A local-files plugin ships with Rymflux, providing basic search and playback from the local file system. This ensures the platform is usable out of the box and serves as a reference for third-party plugin authors.
  • Plugin debugging: plugin stdout/stderr is captured and surfaced through core diagnostics. A plugin health command verifies the plugin is responsive.

2. Room framework

  • A room registration mechanism: rooms declare themselves to the shell and receive control over navigation, search, and player expansion.
  • Standard room lifecycle: activate, deactivate, suspend.
  • Shared services available to all rooms: search manager, library, queue, playback engine handle.
  • Room-provided search filters and result rendering.
  • Room-provided player expansion view (metadata, controls).

3. Core platform services

  • Playback engine: Stream audio from a URL or file path. Play, pause, seek, stop. Volume control. Queue management (add, remove, reorder, next, previous). Source-agnostic — no awareness of plugins or rooms.
  • Library: Unified collection of saved content (favorites, history, playlists). Content tracked by stable ID, not by source plugin.
  • Queue: Ordered list of content items, playable by the engine. Persistent across room switches.
  • Search manager: Dispatches search queries to all active plugins in parallel, merges results, deduplicates by content ID, returns unified result set to the requesting room.

4. Initial rooms

  • Music Room: Browse by album/artist/genre. Search with music-specific filters (artist, album, track). Player expansion shows artwork, lyrics, queue. Standard audio player controls.
  • Home (Lobby): Continue listening, recently played, pinned rooms, recommendations, recent searches. Not a room — a shell-level view.

5. Identity system

  • Stable, unique IDs for Content, Creator, Collection, Plugin, Room, Library entries.
  • IDs are UUIDs. Content IDs are content-addressed or plugin-assigned but source-independent at the library layer.

6. Plugin protocol specification

  • Complete specification of: request format, response format, error format (standard error codes), timeout behavior.
  • Streaming semantics: The protocol defines two modes — (a) plugin returns a stream URL and the core is responsible for fetching audio bytes, (b) plugin pipes audio bytes to the core over the IPC channel. The streaming mode is declared in the plugin manifest. The exact choice between these is an ADR decision (see ADR-001).
  • Specification of data models: Track, Album, Artist, Playlist, SearchResult, StreamInfo, Lyrics.

7. Documentation

  • Plugin developer guide (how to write and register a plugin).
  • Room author guide (how to create a new room).
  • API reference for the plugin protocol.
  • Getting-started guide for end users.
  • Architecture decision records for major design choices.

Out of scope (tracked for v2)

Item Rationale
Additional rooms (Podcast, Audiobook, Radio, Meditation, Educational) Requires room framework to be stable first
Event system / event bus Rooms and plugins can communicate directly through the plugin protocol initially; event bus is an optimization for scaling
Extension points beyond plugins (search ranking plugins, recommendation engine plugins, widget plugins) Requires the base plugin system and room framework to be proven
Plugin permissions system beyond capability declarations Start with trust model (user-installed plugins); add sandboxing later
Plugin SDK / helper libraries The protocol spec is sufficient for v1; SDKs reduce friction but are not required for the first plugins
User accounts and syncing v1 is local-first; cloud features are future
Advanced playback features (gapless, crossfade, audio normalization) Standard playback is sufficient for v1
Offline downloads managed by the core Plugins may handle their own caching; core downloads are v2
Mobile/web UIs v1 is a desktop application

Explicit non-goals

  • Rymflux is not a Spotify client. You can write a Spotify plugin, but the platform does not ship with one.
  • Rymflux is not a podcast player. A Podcast Room can be built on the room framework.
  • Rymflux does not host or provide content. It is a middleware platform between sources and listeners.
  • Rymflux does not define what a room looks like in detail. The room framework defines the contract; room authors define the experience.
  • v1 is local-first and single-user. No authentication, no sync, no sharing.

Was this page helpful?