A mobile-first web client for the Soulseek network.
Built predominantly with AI assistance under human review — see AI-DECLARATION.md.
Try before you install → https://nicotine-hub-web-phi.vercel.app/
No bridge required. Enter any username/password to explore search (including link-paste for two sample Discogs releases), chat, profiles, browse & Files (rename is mocked in-memory) with mocked data.
Downloads/uploads are disabled in the demo.
All captures from a local demo build (NEXT_PUBLIC_DEMO=true, mocked data) — desktop 1280×800, mobile 390×844.
Each shot names its theme — see docs/themes.md for all 22 built-in themes.
| Desktop: search → filters → downloads → spectrum | Mobile: search → browse → downloads |
|---|---|
![]() |
![]() |
| Login | Search | Filters | Release-link paste |
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
| Downloads | Spectrum Full | Spectrum Zoom | Browse shares |
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
| Chat rooms | Private chat |
|---|---|
![]() |
![]() |
| Search | More sheet | Downloads | Private chat |
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
This is an almost 1:1 port of nicotine-plus (GitHub) to a modern Next.js web app. Built on doc/SLSKPROTOCOL.md.
[ Browser (Next.js PWA :3000) ] --WS /ws + HTTP /api/*--> [ web entrypoint ] --pipe--> [ Bun bridge :8787 ] --TCP--> server.slsknet.org:2242
|--/api/bridge/*--> [ Bun bridge :8787 ]
\--/api/worker/*--> [ Python worker :8789 ] --HTTP--> Discogs/Bandcamp/Apple/…
--P2P--> peers (bridge)
Only web:3000 (+ Soulseek peer LISTEN_PORT) is published — browsers reach the bridge/worker through the web entrypoint (same-origin /ws + /api/* proxy), so :8787/:8789 stay on the compose network. NEXT_PUBLIC_BRIDGE_URL / NEXT_PUBLIC_WORKER_URL re-enable direct mode (remote bridge/worker).
The browser can't open raw TCP sockets, so the bridge translates JSON over WebSocket to Soulseek binary framing. Heavy work (link scraping, spectrum rendering, tagging) lives in the worker so the SLSK event loop stays clean. See docs/architecture.md for protocol and env details.
Security: Soulseek sends passwords in plaintext — use credentials you trust. The bridge keeps one shared login (encrypted in
CONFIG_DIR/session.vault,0600) so every device on your home network attaches without re-entering the password. Sign out clears it.
- Search — global, user, room, wishlist & buddies; tabs + live filters (size/bitrate/length/type/slot/country); paste a Discogs/Bandcamp/Apple/Qobuz/Tidal/MusicBrainz/Deezer link to auto-identify the release (worker
POST /scrape) - Transfers — queue, resume (
INCOMPLETE<md5>),GET /files/:token, throttled streaming; Analyze Spectrum (see below) for finished audio via workersoxFull 2000×513 + Zoom 500×1025 (oxipng, shared/tmpcache) - Worker (scrape/spectrum/tag) — separate Python FastAPI service for CPU/IO-heavy ops (same-origin
/api/worker;:8789internal only); bridge stays SLSK-only - Browse — shares & folders via peers
- Chat — rooms + private, tickers, owned/member lists
- Social — buddies
- Profiles — description, picture, stats, privileges
- Mobile shell —
TopBar/BottomNav, safe-area, PWA, diagnostics live tail - Keyboard shortcuts —
g dnav,/search focus,p/rpause/resume all,j/klist stepping,?help (seedocs/hotkeys.md)
After a download finishes, right-click the card on /downloads → Analyze Spectrum (only for finished audio: flac, wav, aiff, mp3, ogg, …). The worker renders two PNGs (own code; output semantics match the old bridge port of smoked-salmon uploader/spectrals.py, Apache-2.0):
- Full
2000×513-z 120Kaiser (remix 1) — whole file - Zoom
500×1025-z 120Kaiser-S <mid> -d 0:02— 2-second slice from the middle (like salmon’scalculateZoomStartpoint)
Images are oxipng -o 2 --strip all compressed and stored only in /tmp/spectrals (ephemeral /tmp/spectrals, no volume — regenerated on demand, wiped on reboot/restart). The web shows a badge SPECTRUM ✓ on the card, hover preview (desktop, Full) with instant cache via blob URL / ETag, and a modal with tabs for Full + Zoom, downloads, and a tip about lossy cutoffs (~16 kHz). While generating you see Generating spectrum…; on error the card shows the reason. See docs/spectrum.md and docs/architecture.md#transfers--spectrum.
apps/bridge — Bun bridge (WebSocket `/ws` + `/health` + `/files/:token` + volume `DATA_DIR`, SLSK-only)
apps/worker — Python FastAPI (scrape/spectrum/tag via same-origin `/api/worker`; `:8789` internal only, volume `data:/data`)
apps/web — Next.js 15 PWA
compose.yaml — web:3000 (only published UI port) + bridge LISTEN_PORT + internal bridge:8787/worker:8789 → config:/config + data:/data
bun install
bun run dev # bridge + web
bun test && bun run build
docker compose up --build # http://localhost:3000 (build from source)Bridge URL: NEXT_PUBLIC_BRIDGE_URL (build) or localStorage.nicotineHub.bridgeUrl (runtime). All env vars are documented in docs/architecture.md#env-full — including BRIDGE_TOKEN, DATA_DIR, LISTEN_PORT (60754, editable in Settings → Network), SHARED_DIRS, UPLOAD_LIMIT, etc.
For prebuilt images and release workflow, see docs/deployment.md.
Modify accordingly if running with unRAID or setting up with Portainer.
- Logging is optional
- Host port mapping might need to be changed to not collide with other apps
- Change
BASE_DOCKER_CONFIG_PATH(./config) andBASE_DOCKER_DATA_PATH(./data) to match your setup - Set a custom network if needed
- Only
web:3000+LISTEN_PORTare published: browsers reach bridge/worker through the web UI (same-origin/ws+/api/*proxy) — no8787/8789mapping needed - Forward
LISTEN_PORT60754TCP+UDP on your router for Soulseek searches (or usenetwork_mode: hostfor UPnP). Changing the port in Settings → Network recreates the bridge container automatically when the opt-in Docker-socket mode is on (/var/run/docker.sock+ALLOW_CONTAINER_RESTART=1, seecompose.yaml); otherwise follow withLISTEN_PORT=NEW docker compose up -d.
Create docker-compose.yml and add the following. If you have an existing setup change to fit that.
services:
bridge:
container_name: nicotinehub-bridge
image: ghcr.io/mlnl221/nicotinehub-bridge:latest
restart: unless-stopped
ports:
- 60754:60754
- 60754:60754/udp
volumes:
- ${BASE_DOCKER_CONFIG_PATH:-./config}:/config
- ${BASE_DOCKER_DATA_PATH:-./data}:/data
# - /home/you/Music:/data/Music:ro # add shares via Settings → Shares
environment:
- LISTEN_PORT=60754
# - BRIDGE_TOKEN=changeme # optional, protects /ws + /files/:token
worker:
container_name: nicotinehub-worker
image: ghcr.io/mlnl221/nicotinehub-worker:latest
restart: unless-stopped
# no ports: reached via web same-origin /api/worker proxy
volumes:
- ${BASE_DOCKER_CONFIG_PATH:-./config}:/config:ro
- ${BASE_DOCKER_DATA_PATH:-./data}:/data
web:
container_name: nicotinehub-web
image: ghcr.io/mlnl221/nicotinehub-web:latest
restart: unless-stopped
ports:
- 3000:3000
# - BRIDGE_TOKEN=changeme # must match bridge when set (proxy fallback)
# - WORKER_TOKEN=changeme # must match worker when set (proxy fallback)Then start with:
docker compose up -dOpen http://localhost:3000 → Settings → Network check LISTEN_PORT, login with Soulseek creds (stored encrypted on your server only, cleared on sign-out). Health: http://localhost:3000/api/bridge/health + http://localhost:3000/api/worker/health (proxied — bridge/worker publish no ports). See docs/deployment.md for TAG pinning (TAG=v0.25.0 docker compose pull && up -d), BRIDGE_TOKEN, and network_mode: host.
bun test # unit tests (bridge + web)
bun run --cwd apps/bridge test:soulfind # live end-to-end vs local soulfindEnd-to-end runs against soulfind (local Soulseek test server — local testing only, never production),
NOT the real server.slsknet.org. The suite (apps/bridge/src/soulfind-live.test.ts, header comment has the level map)
spawns a host-native soulfind on :2244
and verifies login, rooms, chat, PM, search relay, errors/reconnects, and real peer
search/browse/download across all 26 tests. Without SOULFIND_E2E=1 the file self-skips.
# one-time: fetch the soulfind binary (no build needed)
mkdir -p ~/.cache/nicotine-hub/soulfind
curl -sfSL -o /tmp/sf.zip https://github.com/soulfind-dev/soulfind/releases/latest/download/soulfind-linux-x86_64.zip
unzip -o -q /tmp/sf.zip -d ~/.cache/nicotine-hub/soulfind && chmod +x ~/.cache/nicotine-hub/soulfind/soulfindManual UI testing: docker run -d --name soulfind-e2e -v soulfind-e2e:/data -p 127.0.0.1:2243:2243 ghcr.io/soulfind-dev/soulfind soulfind -p 2243,
attach it to the compose network (docker network connect nicotine_mobile_default soulfind-e2e),
then login at http://localhost:3000 with host soulfind-e2e port 2243 (any credentials — auto-register).
Agent workflow: read the header comment in apps/bridge/src/soulfind-live.test.ts first, keep everything local-only (no CI/prod/compose changes),
extend the suite for new protocol surface before fixing bridge code.
docs/architecture.md— bridge, worker, search & protocol, transfers + spectrum, WS JSON,LISTEN_PORT/PortMapper, env, testsdocs/spectrum.md— Analyze Spectrum pipeline (workersox+oxipng, HTTP, caching, UI)docs/deployment.md— Docker & GHCR images,TAGpinning, promotion workflow (stage→main)docs/hotkeys.md— keyboard shortcuts (nav, search, transfers, lists)docs/DESIGN.md— UI tokensdocs/themes.md— all 22 built-in themes (light/dark pair, where each screenshot was taken)docs/proposals/— future backlog (r/Soulseek improvements not yet built)AGENTS.md— agent & worktree conventions
PRs welcome! Please read CONTRIBUTING.md first — target the stage branch, use Conventional Commits, and verify with bun test && bun run build. All PRs are reviewed by @mlnl221. Bug reports and feature requests via issues; security issues via SECURITY.md (never public). Releases are cut from main — see docs/deployment.md.
License: GPL-3.0-or-later. © 2001–2026 Nicotine+, PySoulSeek; © 2025–2026 Nicotine Hub. See ATTRIBUTION.md (upstream 8d81e66) and LICENSE.
Soulseek network / server.slsknet.org is volunteer-operated and not affiliated with this project. By connecting you agree to the Soulseek rules and Terms. Soulseek is unencrypted; see Security above.
















