Skip to content

About

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Nicotine Hub

Nicotine Hub logo

AI-DECLARATION: pair CI Latest release License: GPL-3.0-or-later

A mobile-first web client for the Soulseek network.
Built predominantly with AI assistance under human review — see AI-DECLARATION.md.

Demo

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.

Screenshots

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
Desktop walkthrough: multi-tab search with filters, downloads with live throughput, Analyze Spectrum Full/Zoom modal Mobile walkthrough: search results, More sheet, browse shares, downloads

Desktop

Login Search Filters Release-link paste
Login — any credentials in demo (Flexoki Light) Search — tabs, scope, grouped results (Tokyo Night) Search filters — size/bitrate/type/slot/country (Catppuccin) Paste a Discogs/Bandcamp/Apple link to auto-identify the release via the worker (Nord)
Downloads Spectrum Full Spectrum Zoom Browse shares
Downloads — live progress, stats, SPECTRUM badge on finished audio (Gruvbox) Analyze Spectrum — Full 2000×513 sox render (Everforest) Analyze Spectrum — 2-second Zoom slice (Retro 82) Browse — shares tree, folder search, per-file actions (Lumon)
Chat rooms Private chat
Chat rooms — room list, tickers, members (Kanagawa) Private chat — 1:1 threads (Ristretto)

Mobile

Search More sheet Downloads Private chat
Mobile search with bottom nav (Osaka Jade) Mobile More sheet — browse, buddies, uploads, rooms, profiles, settings (Hackerman) Mobile downloads (Matte Black) Mobile private chat (Rose Pine)

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.


Features

  • 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 worker sox Full 2000×513 + Zoom 500×1025 (oxipng, shared /tmp cache)
  • Worker (scrape/spectrum/tag) — separate Python FastAPI service for CPU/IO-heavy ops (same-origin /api/worker; :8789 internal 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 d nav, / search focus, p/r pause/resume all, j/k list stepping, ? help (see docs/hotkeys.md)

Analyze Spectrum (FLAC / audio)

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 120 Kaiser (remix 1) — whole file
  • Zoom 500×1025 -z 120 Kaiser -S <mid> -d 0:02 — 2-second slice from the middle (like salmon’s calculateZoomStartpoint)

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.


Repo layout

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

Quick start

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.

Docker Compose

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) and BASE_DOCKER_DATA_PATH (./data) to match your setup
  • Set a custom network if needed
  • Only web:3000 + LISTEN_PORT are published: browsers reach bridge/worker through the web UI (same-origin /ws + /api/* proxy) — no 8787/8789 mapping needed
  • Forward LISTEN_PORT 60754 TCP+UDP on your router for Soulseek searches (or use network_mode: host for 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, see compose.yaml); otherwise follow with LISTEN_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 -d

Open 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.

Testing

bun test                 # unit tests (bridge + web)
bun run --cwd apps/bridge test:soulfind   # live end-to-end vs local soulfind

End-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/soulfind

Manual 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

  • docs/architecture.md — bridge, worker, search & protocol, transfers + spectrum, WS JSON, LISTEN_PORT/PortMapper, env, tests
  • docs/spectrum.md — Analyze Spectrum pipeline (worker sox + oxipng, HTTP, caching, UI)
  • docs/deployment.md — Docker & GHCR images, TAG pinning, promotion workflow (stage → main)
  • docs/hotkeys.md — keyboard shortcuts (nav, search, transfers, lists)
  • docs/DESIGN.md — UI tokens
  • docs/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

Contributing

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.


Legal

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.


Star History

Star History Chart

About

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages