pl8list-rewind/README.md

pl8list ∞

An endless, TikTok-style scroll through pl8list, with its own recommendation algorithm that learns from what you like, finish and skip. Sign in with your pl8list account; each user gets their own feed and taste profile.

Not affiliated with pl8list.

Likes	Filters

Run

docker compose up -d --build       # http://127.0.0.1:8790

or without Docker (Rust 1.85+, Node 22+):

cd web && npm ci && npm run build   # front end into web/dist
cd ../backend && cargo run --release # embeds web/dist at build time
cargo test                          # unit tests + API tests against a fake pl8list

For front-end work run the server, then npm run dev in web/: Vite serves the page with hot reload on http://127.0.0.1:5173/static/ and passes API calls to the server (BACKEND= to point it elsewhere). Debug builds of the server read web/dist from disk, so npm run build is enough to see changes on :8790 too.

The server is the Rust crate in backend/, the front end is TypeScript in web/ (Vite, no framework). The old Python server (server.py and friends) still works on the same database but not with this front end; to roll back, check out 54a436a.

Before going public in Germany, set the Impressum variables below. /impressum and /datenschutz are filled in from them at startup; the texts are in backend/templates/. Have them checked: they are a careful draft, not legal advice.

compose.override.yaml puts it behind Traefik at pl8.narl.io on the external narl network, the same way as the other narl.io services. Docker Compose picks it up automatically. Delete it, or change the host name, to run somewhere else.

Data (catalogue, users, listening history) lives in the data volume as one SQLite file.

variable	default	meaning
HOST	127.0.0.1	bind address (0.0.0.0 in the image)
PORT	8790	port
PL8_DB	./pl8list.db	SQLite path (/data/pl8list.db in the image)
TRUSTED_PROXY_HOPS	0	reverse proxies in front that append to X-Forwarded-For (TRUST_PROXY=1 also means 1)
PUBLIC_ORIGIN	unset	https://host of the site; POSTs with any other Origin are refused
CACHE_DIR	cache next to DB	disk cache for audio segments and artist images
CACHE_MAX_MB	2048	cache size limit, least recently used files go first
LINK_KEY	unset	server half of the key for stored pl8list sessions (base64, 32 bytes)
LINK_KEY_FILE	link.key next to DB	used when LINK_KEY is unset; created on first start
INSECURE_COOKIES	0	1 only for plain-http development from another machine
IMPRESSUM_NAME, IMPRESSUM_ADDRESS, IMPRESSUM_EMAIL, IMPRESSUM_PHONE	empty	operator details for /impressum and /datenschutz; separate address lines with |
HOSTING_PROVIDER	empty	hosting company and address, named in the privacy policy

Accounts

There are no passwords here. Users sign in with the email of their pl8list account:

1. The user enters their email. The server starts pl8list's own login, and pl8list mails them a 6-digit code.
2. The user types the code. The server passes it to pl8list. If pl8list accepts it, the server reads the user's pl8list id and handle, creates a local account, and sets its own session cookie (__Host-pl8inf, Secure, HttpOnly, SameSite=Lax). It ends after 30 days without use and gets a new token every 7 days.

By default the pl8list session from step 2 is used once, in memory, to sync with the user's pl8list account: their personal feed, their saved tracks (they become likes here) and their saved artists (they become follows). It is never written to disk, and when the sync is done (or fails) the server logs that session out at pl8list. Only a SHA-256 hash of the local session token is stored.

Stay connected is an opt-in checkbox at sign-in, per device. Then the pl8list session is stored in that device's sessions row, encrypted with XChaCha20-Poly1305 under a key derived (HKDF-SHA256) from the device's local session token and a server key (LINK_KEY). The token only exists in the browser cookie, so a copy of the database, even with the server key, opens nothing; the server can only decrypt during that device's own requests. With it, the app resyncs on use every 6 hours and on the "resync with pl8list" button, and saves new likes and follows to the user's pl8list library (add-to-library?addOnly=true, so it never removes anything). If pl8list sends a new cookie it is stored again; if pl8list redirects to its login, the stored session is deleted. Weekly token rotation re-encrypts it for the new token. "stop staying connected", sign out and account deletion log it out at pl8list and delete it. pl8list's _session is a signed cookie, so their logout may not invalidate a copy; treat a stored session as long-lived.

Without stay connected, "resync with pl8list" in the account menu runs the email-code sign-in again and syncs once.

Every login start and resend makes pl8list send a mail, so they are rate-limited: 5 per IP and 3 per email per 15 minutes, 30 per 10 minutes for the whole server, at most 2 resends and 5 code attempts per login, and at most 500 logins pending at once. Behind a proxy (TRUSTED_PROXY_HOPS=1) the client IP is the last X-Forwarded-For entry, the one the proxy added; IPv6 addresses are limited per /64.

The "account" menu shows the pl8list sync state and lets users resync, stop staying connected, download everything stored about them (JSON), sign out on all devices, or delete their account (likes, follows, history and sessions, right away). Expired sessions are purged hourly and "served" events after 180 days. The browser only ever talks to this server: hls.js is bundled into the front end and audio and images are proxied, so no visitor address reaches pl8list or a CDN.

Controls

phone	desktop	action
tap	click · space	play / pause
double-tap	double-click · l	like
swipe up / down	↓ j · ↑ k	next / previous
drag waveform	drag waveform · ← →	seek
follow button	f	follow the artist
✕ button	x	not for me (skip, show less)
share button	s	share / copy link
	m	mute
	? · Esc	help · close panels

Lock-screen, notification and headphone buttons control playback too (Media Session API). "likes" lists your likes newest first; ▶ plays one right away. Filters (free only, BPM range) are remembered per browser. The site can be installed to the home screen as an app.

Front end

web/src/:

• pager.ts: the feed. One card fills the screen; drag, flick, wheel and keys turn the page, with a spring that follows the finger's speed and a rubber band at the ends. Only the current card and its neighbours are in the DOM. One wheel or trackpad gesture moves one page.
• player.ts: two audio decks. The next track is buffered a few seconds after the current one starts, so it plays at once; tracks crossfade (0.9 s, equal power) and the next one starts just before the current one ends. Both decks run through a Web Audio graph with an analyser. Not on iOS: its element volume is read-only and Web Audio stops with the screen locked, so there tracks switch with a cut and lock-screen playback keeps working.
• visual.ts: per frame, the waveform progress and a bass level (--energy) that pulses the artwork and its glow. Without the analyser the level comes from the track's waveform.
• color.ts: each card's accent colour (--card-accent) from the artist image.
• cards.ts, api.ts, main.ts: cards, server calls, and everything else.

Design tokens are CSS custom properties at the top of style.css. prefers-reduced-motion turns off the spring, the pulse and the animations.

How it works

pl8list has no public API, but it is a Remix app: every page loader returns JSON when you add ?_data=<route id>, and /api/* routes return JSON directly. Paginated loaders also need pagination=true. All of this works without an account for public data:

endpoint	gives
/?_data=routes/_index	best sellers, recommended, ticker
/api/feed?page=N&pagination=true	a user's feed (needs their session)
/api/activity-ticker	artists with recent downloads/sales
/best-selling-artists?_data=routes/best-selling-artists	top artists
/search/users?q=…&page=N&pagination=true&_data=routes/search.users	artist search (≥ 3 chars)
/<handle>?page=N&pagination=true&_data=routes/$handle	an artist's tracks, 10 per page
/<handle>/<slug>/related?_data=routes/$handle_.$slug.related	3 related tracks
/api/<handle>/<slug>/hls/playlist.m3u8?v=<uploadId>[&preview=true]	HLS audio
/login, /verify?email=…&mode=login	email + 6-digit code login
/library/tracks?page=N&pagination=true&_data=routes/library.tracks	saved tracks (needs session)
/library/artists?…&_data=routes/library.artists	saved artists (needs session)
POST /api/<handle>[/<slug>]/add-to-library?addOnly=true	save artist or track (needs session)

Crawler (backend/src/crawler.rs). There is no "all tracks" listing, so one shared catalogue grows by snowballing: home sections, the ticker, best-selling artists and artist search give artists; artist pages give tracks; related pages pull in neighbours. Artists are re-checked daily for new uploads. Requests are throttled to about 1.4 per second while someone has used the app in the last 30 minutes, or while the catalogue has fewer than 500 tracks. Otherwise it slows to one request every 20 seconds. When a user likes or finishes a track, its related tracks and its artist's catalogue are crawled first.

Ranking (backend/src/ranker.rs). Each track the user has not seen yet gets a score from popularity, freshness, artist affinity (from their likes, completions, skips, "not for me" and follows), closeness to the BPM and key of tracks they liked, whether it is related to something they liked, and some random exploration. Artists are then spread out so you don't get five tracks from one person in a row. Weights live in a Ranker; ?mode= on /local/feed picks one, so discovery modes can be added next to Classic.

Audio. The browser only talks to this server. HLS playlists and segments are proxied from pl8list as a guest, so users hear previews of paid tracks and full free tracks, the same as a logged-out visitor on pl8list. Segments and images are cached on disk, so a repeat play costs pl8list nothing. Segment URLs carry a signed token; only tokens seen in a playlist we fetched ourselves are used as cache keys, so a forged token can't pull another track out of the cache.