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

ADR-008: Reference plugin language — Python

ADR-008: Reference plugin language — Python

Status

Accepted

Context

FR-REF-1 requires a reference local-files plugin that ships with Rymflux. Its job is twofold:

  1. Make the platform usable out of the box (scan a directory, index audio files, serve search and stream).
  2. Serve as a reference implementation for third-party plugin authors.

The language choice sends a signal about the ecosystem. Options:

  • Python: Widely known, readable, minimal boilerplate. The JSON-RPC stdin/stdout protocol (ADR-001) is ~40 lines. A developer reads it and understands the protocol without explanation.
  • Rust: Matches the core language. Better performance for file indexing. Static binary, no runtime dependency. But the signal says “this is a Rust ecosystem” — contradictory to the language-agnostic promise.
  • Go: Strong cross-compilation, clean concurrency, static binary. Better than Python for distribution but less readable for the widest audience.

Decision

The reference plugin is written in Python 3.10+. The plugin ships as a directory containing plugin.toml and main.py. The pyproject.toml declares dependencies (none beyond stdlib). Documentation explicitly pins Python 3.10+ as a requirement.

The reference plugin:

  • Scans configured directories for .mp3, .flac, .ogg files
  • Reads ID3/FLAC/Vorbis tags using a stdlib XML parser and binary header parsing (no external dependencies)
  • Indexes files into an in-process dictionary (no SQLite — it’s a reference, not a production service)
  • Returns Track/Album/Artist results from the index on search
  • Returns file:// URIs on stream (ADR-006 — URL-only)
  • Ships with the platform distribution in ~/.rymflux/plugins/local-files/ (Rymflux installer places it there)

The platform will also distribute a compiled Go example plugin as a separate downloadable artifact (not bundled) to demonstrate static-binary distribution for authors who prefer that path. This is a documentation concern, not a build concern.

Alternatives considered

  • Rust: Would produce a single static binary with no runtime dependency. But the reference plugin’s primary audience is potential plugin authors, not end users. A Rust reference plugin with Cargo.toml, build.rs, and 200 lines of error handling sends the wrong signal. Plugin authors evaluating “can I write a plugin?” see “I need to learn Rust to write a plugin” even though that’s false.
  • Go: A strong middle ground. Static binary, no runtime, clean JSON-RPC. The stdlib net/http makes URL-mode streaming trivial. However, Python has wider reach among the hobbyist/enthusiast audience most likely to write plugins for a media platform. Go is the right choice for the second reference plugin.
  • Bash/shell script: Too limited for a meaningful reference. Would not demonstrate error handling, structured data, or streaming patterns.

Consequences

Positive:

  • Lowest barrier to entry for new plugin authors. Python’s syntax is accessible, and the JSON-RPC over stdin/stdout pattern is a well-known teaching example.
  • The plugin is readable documentation first, production code second. Any tradeoff that makes the code clearer is the right choice.
  • Python’s json and sys modules are stdlib — zero dependencies.
  • If Python is not installed, the platform still works (plugins are optional; the reference plugin is a convenience).

Negative:

  • Python is a runtime dependency. The user must have Python 3.10+ installed. Not guaranteed on Windows or macOS. Mitigation: the installer checks and prompts; documentation covers setup.
  • Python startup time is ~100-200ms vs ~5ms for Rust or Go. This affects the 5-second launch window in FR-PLUGIN-3. Mitigation: acceptable for v1; the local-files plugin is typically launched once and kept alive by the idle timeout.
  • File indexing is slower in Python than Rust or Go. A large collection (100k+ files) would take seconds on first scan. Mitigation: the index is ephemeral (in-process dictionary); if this becomes a problem, the second reference plugin (Go) or a future v2 optimization can address it.

References

  • FR-REF-1 (functional.md)
  • ADR-001 (JSON-RPC over stdin/stdout)
  • ADR-006 (URL-only streaming)

Was this page helpful?