plyr.fm documentation#

organized knowledge base for plyr.fm development.

operations#

runbooks/ - production incident procedures
- connection-pool-exhaustion - 500s, stuck connections

backend#

background-tasks.md - docket-based task system (copyright scan, export, scrobble, genre classification)
configuration.md - environment setup and settings
database/ - connection pooling, neon-specific patterns
feature-flags.md - per-user feature rollout system
streaming-uploads.md - SSE progress tracking
transcoder.md - rust audio conversion service (lossless support)
mood-search.md - semantic search with CLAP embeddings (Modal + turbopuffer)
genre-classification.md - ML genre tagging via effnet-discogs (Replicate)
playlist-recommendations.md - inline track suggestions via CLAP embeddings
liked-tracks.md - like system and liked tracks endpoint
atproto-identity.md - ATProto identity resolution and handle management

frontend#

state-management.md - svelte 5 runes patterns
keyboard-shortcuts.md - global shortcuts
navigation.md - SvelteKit routing patterns
search.md - unified search with Cmd+K

deployment#

environments.md - staging vs production
database-migrations.md - alembic workflow

tools#

logfire.md - SQL query patterns for observability
neon.md - postgres database management
pdsx.md - ATProto PDS explorer
plyrfm.md - Python SDK and MCP server
tap.md - ATProto sync utility for backfilling custom lexicons
status-maintenance.md - automated status podcasts

atproto#

lexicons/ - record schemas (track, like, comment, list, profile)
authentication.md - OAuth 2.1 flow

moderation#

moderation/ - copyright detection, sensitive content, labeler

testing#

testing/ - pytest patterns, parallel execution

local development#

local-development/setup.md - getting started

architecture overview#

plyr.fm uses a hybrid storage model:

audio files: cloudflare R2 (CDN-backed, zero egress)
metadata: ATProto records on user's PDS (decentralized, user-owned)
indexes: neon postgres for fast queries

lossless audio: AIFF/FLAC uploads are transcoded to MP3 for universal browser playback while originals are preserved for export. browsers that support lossless (Safari, native apps) are served the original quality.

key namespaces:

fm.plyr.track - track metadata
fm.plyr.like - user likes
fm.plyr.comment - timed comments
fm.plyr.list - playlists and albums
fm.plyr.actor.profile - artist profiles

quick start#

# backend
just backend run

# frontend
just frontend run

# run tests
just backend test

see local-development/setup.md for complete setup.

contributing#

check docs before researching externally
document decisions as you make them
keep it simple - MVP over perfection
use lowercase aesthetic