plyr.fm - status#

long-term vision#

the problem#

today's music streaming is fundamentally broken:

spotify and apple music trap your data in proprietary silos
artists pay distribution fees and streaming cuts to multiple gatekeepers
listeners can't own their music collections - they rent them
switching platforms means losing everything: playlists, play history, social connections

the atproto solution#

plyr.fm is built on the AT Protocol (the protocol powering Bluesky) and enables:

portable identity: your music collection, playlists, and listening history belong to you, stored in your personal data server (PDS)
decentralized distribution: artists publish directly to the network without platform gatekeepers
interoperable data: any client can read your music records - you're not locked into plyr.fm
authentic social: artist profiles are real ATProto identities with verifiable handles (@artist.bsky.social)

the dream state#

plyr.fm should become:

for artists: the easiest way to publish music to the decentralized web
- upload once, available everywhere in the ATProto network
- direct connection to listeners without platform intermediaries
- real ownership of audience relationships
for listeners: a streaming platform where you actually own your data
- your collection lives in your PDS, playable by any ATProto music client
- switch between plyr.fm and other clients freely - your data travels with you
- share tracks as native ATProto posts to Bluesky
for developers: a reference implementation showing how to build on ATProto
- open source end-to-end example of ATProto integration
- demonstrates OAuth, record creation, federation patterns
- proves decentralized music streaming is viable

started: October 28, 2025 (first commit: 454e9bc - relay MVP with ATProto authentication)

recent work#

December 2025#

self-hosted redis (PR #674-675, Dec 30)#

replaced Upstash with self-hosted Redis on Fly.io - ~$75/month → ~$4/month:

Upstash pay-as-you-go was charging per command (37M commands = $75)
self-hosted Redis on 256MB Fly VMs costs fixed ~$2/month per environment
deployed plyr-redis (prod) and plyr-redis-stg (staging)
added CI workflow for redis deployments on merge

no state migration needed - docket stores ephemeral task queue data, job progress lives in postgres.

supporter-gated content (PR #637, Dec 22-23)#

atprotofans paywall integration - artists can now mark tracks as "supporters only":

tracks with support_gate require atprotofans validation before playback
non-supporters see lock icon and "become a supporter" CTA linking to atprotofans
artists can always play their own gated tracks

backend architecture:

audio endpoint validates supporter status via atprotofans API before serving gated content
HEAD requests return 200/401/402 for pre-flight auth checks (avoids CORS issues)
R2Storage.move_audio() moves files between public/private buckets when toggling gate
background task handles bucket migration asynchronously
ATProto record syncs when toggling gate (updates supportGate field and audioUrl)

frontend:

playback.svelte.ts guards queue operations with gated checks BEFORE modifying state
clicking locked track shows toast with CTA - does NOT interrupt current playback
portal shows support gate toggle in track edit UI

supporter badges (PR #627, Dec 21-22)#

phase 1 of atprotofans integration:

supporter badge displays on artist pages when logged-in viewer supports the artist
calls atprotofans validateSupporter API directly from frontend (public endpoint)
badge only shows when viewer is authenticated and not viewing their own profile

rate limit moderation endpoint (PR #629, Dec 21)#

incident response: detected suspicious activity - 72 requests in 17 seconds from a single IP targeting /moderation/sensitive-images. added 10/minute rate limit using existing slowapi infrastructure.

end-of-year sprint planning (PR #626, Dec 20)#

focus: two foundational systems need solid experimental implementations by 2026.

track	focus	status
moderation	consolidate architecture, add rules engine	in progress
atprotofans	supporter validation, content gating	shipped (phase 1-3)

research docs:

beartype + moderation cleanup (PRs #617-619, Dec 19)#

runtime type checking (PR #619):

enabled beartype runtime type validation across the backend
catches type errors at runtime instead of silently passing bad data
test infrastructure improvements: session-scoped TestClient fixture (5x faster tests)

moderation cleanup (PRs #617-618):

consolidated moderation code, addressing issues #541-543
sync_copyright_resolutions now runs automatically via docket Perpetual task
removed dead init_db() from lifespan (handled by alembic migrations)

UX polish (PRs #604-607, #613, #615, Dec 16-18)#

login improvements (PRs #604, #613):

login page now uses "internet handle" terminology for clarity
input normalization: strips @ and at:// prefixes automatically

artist page fixes (PR #615):

track pagination on artist pages now works correctly
fixed mobile album card overflow

mobile + metadata (PRs #605-607):

Open Graph tags added to tag detail pages for link previews
mobile modals now use full screen positioning
fixed /tag/ routes in hasPageMetadata check

offline mode foundation (PRs #610-611, Dec 17)#

experimental offline playback:

storage layer using Cache API for audio bytes + IndexedDB for metadata
GET /audio/{file_id}/url backend endpoint returns direct R2 URLs for client-side caching
"auto-download liked" toggle in experimental settings section
Player checks for cached audio before streaming from R2

Earlier December 2025#

See .status_history/2025-12.md for detailed history including:

visual customization with custom backgrounds (PRs #595-596, Dec 16)
performance & moderation polish (PRs #586-593, Dec 14-15)
mobile UI polish & background task expansion (PRs #558-572, Dec 10-12)
confidential OAuth client for 180-day sessions (PRs #578-582, Dec 12-13)
pagination & album management (PRs #550-554, Dec 9-10)
public cost dashboard (PRs #548-549, Dec 9)
docket background tasks & concurrent exports (PRs #534-546, Dec 9)
artist support links & inline playlist editing (PRs #520-532, Dec 8)
playlist fast-follow fixes (PRs #507-519, Dec 7-8)
playlists, ATProto sync, and library hub (PR #499, Dec 6-7)
sensitive image moderation (PRs #471-488, Dec 5-6)
teal.fm scrobbling (PR #467, Dec 4)
unified search with Cmd+K (PR #447, Dec 3)
light/dark theme system (PR #441, Dec 2-3)
tag filtering and bufo easter egg (PRs #431-438, Dec 2)

November 2025#

See .status_history/2025-11.md for detailed history including:

developer tokens (PR #367)
copyright moderation system (PRs #382-395)
export & upload reliability (PRs #337-344)
transcoder API deployment (PR #156)

immediate priorities#

quality of life mode (Dec 29-31)#

end-of-year sprint #625 complete. remaining days before 2026 are for minor polish and bug fixes as they arise.

what shipped in the sprint:

moderation consolidation: sensitive images moved to moderation service (#644)
atprotofans: supporter badges (#627) and content gating (#637)

aspirational (deferred until scale justifies):

configurable rules engine for moderation
time-release gating (#642)

known issues#

playback auto-start on refresh (#225)
iOS PWA audio may hang on first play after backgrounding

backlog#

audio transcoding pipeline integration (#153) - transcoder service deployed, integration deferred
share to bluesky (#334)
lyrics and annotations (#373)

technical state#

architecture#

backend

language: Python 3.11+
framework: FastAPI with uvicorn
database: Neon PostgreSQL (serverless)
storage: Cloudflare R2 (S3-compatible)
background tasks: docket (Redis-backed)
hosting: Fly.io (2x shared-cpu VMs)
observability: Pydantic Logfire
auth: ATProto OAuth 2.1

frontend

framework: SvelteKit (v2.43.2)
runtime: Bun
hosting: Cloudflare Pages
styling: vanilla CSS with lowercase aesthetic
state management: Svelte 5 runes

deployment

ci/cd: GitHub Actions
backend: automatic on main branch merge (fly.io)
frontend: automatic on every push to main (cloudflare pages)
migrations: automated via fly.io release_command

what's working

core functionality

✅ ATProto OAuth 2.1 authentication
✅ secure session management via HttpOnly cookies
✅ developer tokens with independent OAuth grants
✅ platform stats and Media Session API
✅ timed comments with clickable timestamps
✅ artist profiles synced with Bluesky
✅ track upload with streaming
✅ audio streaming via 307 redirects to R2 CDN
✅ play count tracking, likes, queue management
✅ unified search with Cmd/Ctrl+K
✅ teal.fm scrobbling
✅ copyright moderation with ATProto labeler
✅ docket background tasks (copyright scan, export, atproto sync, scrobble)
✅ media export with concurrent downloads
✅ supporter-gated content via atprotofans

albums

✅ album CRUD with cover art
✅ ATProto list records (auto-synced on login)

playlists

✅ full CRUD with drag-and-drop reordering
✅ ATProto list records (synced on create/modify)
✅ "add to playlist" menu, global search results

deployment URLs

production frontend: https://plyr.fm
production backend: https://api.plyr.fm
staging: https://stg.plyr.fm / https://api-stg.plyr.fm

technical decisions#

why Python/FastAPI instead of Rust?

rapid prototyping velocity during MVP phase
trade-off: accepting higher latency for faster development

why Cloudflare R2 instead of S3?

zero egress fees (critical for audio streaming)
S3-compatible API, integrated CDN

why async everywhere?

I/O-bound workload: most time spent waiting on network/disk
PRs #149-151 eliminated all blocking operations

cost structure#

current monthly costs: ~$20/month (plyr.fm specific)

see live dashboard: plyr.fm/costs

fly.io (backend + redis + moderation): ~$14/month
neon postgres: $5/month
cloudflare (R2 + pages + domain): ~$1/month
audd audio fingerprinting: $5-10/month (usage-based)
logfire: $0 (free tier)

admin tooling#

content moderation#

script: scripts/delete_track.py

usage:

uv run scripts/delete_track.py <track_id> --dry-run
uv run scripts/delete_track.py <track_id>
uv run scripts/delete_track.py --url https://plyr.fm/track/34

for new contributors#

getting started#

clone: gh repo clone zzstoatzz/plyr.fm
install dependencies: uv sync && cd frontend && bun install
run backend: uv run uvicorn backend.main:app --reload
run frontend: cd frontend && bun run dev
visit http://localhost:5173

development workflow#

create issue on github
create PR from feature branch
ensure pre-commit hooks pass
merge to main → deploys to staging
create github release → deploys to production

key principles#

type hints everywhere
lowercase aesthetic
ATProto first
async everywhere (no blocking I/O)
mobile matters
cost conscious

project structure#

plyr.fm/
├── backend/              # FastAPI app & Python tooling
│   ├── src/backend/      # application code
│   ├── tests/            # pytest suite
│   └── alembic/          # database migrations
├── frontend/             # SvelteKit app
│   ├── src/lib/          # components & state
│   └── src/routes/       # pages
├── moderation/           # Rust moderation service (ATProto labeler)
├── transcoder/           # Rust audio transcoding service
├── redis/                # self-hosted Redis config
├── docs/                 # documentation
└── justfile              # task runner

documentation#

docs/README.md - documentation index
runbooks - production incident procedures
background tasks - docket task system
logfire querying - observability queries
moderation & labeler - copyright, sensitive content
lexicons overview - ATProto record schemas

this is a living document. last updated 2025-12-30.