Skip to content

Local Playback

Jump to bottom
alsi-lawr edited this page Jul 29, 2026 · 1 revision

Local playback

On supported x86-64 Linux and Windows hosts, phrasic serve <config> starts a private native gRPC service and a paired Local browser page on 127.0.0.1.

Configuration

schema_version = 1
port = 8080
source_pin = "optional exact source identifier"
browser_handoff = "open"

The file accepts only:

  • schema_version, exactly 1;
  • port, an integer from 1024 through 65535;
  • optional source_pin, an exact native source identifier;
  • optional browser_handoff, either open or print.

open is the default and launches the one-use fragment URL. print writes the URL only to a controlling terminal, which is useful when the page must be opened in a particular browser profile or browser-source surface.

Run from source

Build the matching Bun Local host before running the Rust service:

bun run build:local-host linux
PHRASIC_LOCAL_HOST="$(pwd)/dist/native/linux/phrasic-local-host" \
  cargo run --locked -p phrasic -- serve ./phrasic.toml

Use windows for a Windows build.

Pairing and lifecycle

Pairing creates one private browser session for the lifetime of the native process. The capability is carried in the URL fragment, redeemed once, and removed from browser-visible navigation state. Restart phrasic serve to pair a different browser.

The Local page retries transient playback reads automatically. Invalid native or pairing state fails closed rather than falling back to stale or fabricated data.

When playback is active, Phrasic presents the selected source's current metadata. Paused or stopped playback returns to the neutral spinning-vinyl state instead of retaining the previous item.

Source selection

Without source_pin, Phrasic selects through its deterministic native policy and reports ambiguity instead of depending on source enumeration order. An exact pin wins while that source is available and does not silently fall back when it disappears.

Linux artwork

The selected MPRIS source may provide PNG, JPEG, or WebP artwork through a local file:// URL or a public HTTPS URL. Phrasic:

  • reads artwork only from the selected source;
  • follows no redirects;
  • rejects private and reserved HTTPS destinations;
  • accepts only supported image signatures;
  • embeds the bytes for the browser instead of exposing the source URL;
  • applies the existing source deadline but no application-specific artwork-size ceiling.

Missing, invalid, inaccessible, or slow artwork leaves playback metadata available and uses the vinyl fallback.

Phrasic

Clone this wiki locally