The batteries-included Soulseek web client
Releases • Issues • Features • Quick Start • Discord
slskdN(OT) (as in, NOT slskd), is a richly feature-added fork of slskd, the modern web-based Soulseek client. While slskd focuses on being a lean, API-first daemon that lets users implement advanced features via external scripts, slskdN takes the opposite approach:
Everything built-in. No scripts required.
If you've ever seen a feature request closed with "this can be done via the API with a script" and thought "but I just want it to work"—slskdN is for you. We have also extended the client functionality and network in ways that we think improve security, longevity, and quality.
Downloads get stuck. Users go offline. Transfers time out. Instead of manually searching for alternatives, slskdN does it automatically.
- Toggle switch in Downloads header ("Auto-Replace")
- Detects stuck downloads (timed out, errored, rejected, cancelled)
- Searches network for alternatives, filters by extension and size (default 5%)
- Ranks by size match, free slots, queue depth, speed
- Auto-cancels stuck download and enqueues best alternative
--auto-replace-enabled --auto-replace-max-size-diff-percent 5.0 --auto-replace-interval 60Save searches that run automatically in the background. Never miss rare content again.
- New Wishlist item in navigation sidebar
- Add searches with custom filters and max results
- Toggle auto-download, configurable interval, track matches and run history
- Manual "Run Now" button for each search
--wishlist-enabled --wishlist-interval 60 --wishlist-auto-download --wishlist-max-results 100Configure multiple download folders and choose where files go.
destinations:
folders:
- name: "Music"
path: "/downloads/music"
default: true
- name: "Audiobooks"
path: "/downloads/audiobooks"One-click cleanup for your search history.
- Red "Clear All" button in top-right of search list
- Removes all completed searches, real-time UI update via SignalR
Intelligent sorting that considers multiple factors to show best sources first.
- New default sort: "⭐ Smart Ranking (Best Overall)"
- Combines: Upload speed (40pts), Queue length (30pts), Free slot (15pts), History (+/-15pts)
- Purple badge shows smart score next to each username
- Also adds "File Count" sort option
See at a glance which users you've successfully downloaded from before.
- 🟢 Green = 5+ successful downloads | 🔵 Blue = 1-4 successful | 🟠 Orange = More failures
- Hover for exact counts
Hide specific users from your search results.
- Click user icon (👤✕) to block, "Hide Blocked Users (N)" toggle
- Block list stored in localStorage, persists across sessions
Clean up unwanted downloads directly from the UI.
- "Remove and Delete File(s) from Disk" button in Downloads
- Deletes file AND removes from list, cleans empty parent directories
Set your preferred search filters once and forget them.
- Enter filters (e.g.
isLossless minbr:320), click Save icon - Filters auto-load for all future searches
Power user filtering with a visual interface.
- Visual Filter Editor: Bitrate, Duration, File Size (Min/Max), CBR/VBR/Lossless toggles
- Page Size: 25, 50, 100, 200, 500 results per page
- Settings persist across sessions
Keep track of users with persistent notes and color-coded ratings.
- Add notes from Search Results or Browse views
- Assign color ratings (Red, Green, etc.), mark as "High Priority"
Enhanced interaction in chat rooms.
- Right-click users: Browse Files, Private Chat, Add Notes
Download multiple folders at once with checkbox selection.
- In Browse view, check folders and click "Download Selected"
- Recursively collects all files in folders/subfolders
Get notified on your phone when important things happen.
- Native support for Ntfy and Pushover
- Notifications for Private Messages and Room Mentions
Browse multiple users at once.
- Open multiple users in separate tabs, state preserved per tab
- Browse data cached per-user
All automatic downloads use intelligent source selection based on your history.
- Tracks success/failure rates per user, used by auto-replace and wishlist
- API endpoint at
/api/v0/ranking
Install slskdN as an app on your phone.
- Add to Home Screen on iOS/Android, standalone mode
The following advanced features are fully implemented and production-ready:
Download files from multiple peers simultaneously for faster, more reliable transfers.
- Parallel chunk downloads from multiple sources
- Automatic source discovery finds all peers with matching files
- Intelligent stitching assembles chunks seamlessly
- Failure resilience continues from other sources if one fails
- SHA-256 verification ensures content integrity
- Network-friendly — distributes load instead of hammering single users
- Advanced discovery — content-aware matching with fuzzy/variant classification
- Adaptive scheduling — learns from chunk outcomes to optimize assignment
- Domain-aware swarming — Movies, TV, Books, and GenericFile support
📖 Design docs: Network impact analysis • Architecture • Roadmap • Rescue mode • Scheduling
Understand swarm performance and make data-driven optimizations.
- Analytics service — success rates, speed, duration, and chunk efficiency
- Peer rankings — reputation, RTT, throughput, and success metrics
- System UI dashboard — trends, recommendations, and summaries
Discover other slskdN users via BitTorrent DHT and form encrypted mesh overlay.
- DHT bootstrap — 60+ bootstrap nodes for peer discovery
- Mesh overlay network — TLS-encrypted P2P connections
- Hash database sync — Epidemic protocol for content verification database
- Peer greeting service — Auto-discovery and handshake
- NAT detection — UPnP/NAT-PMP port mapping
- Live status bar — Real-time DHT nodes, mesh peers, hash counts in UI footer
📖 Design docs: MeshCore research • Mesh architecture
Zero-trust security framework with defense-in-depth:
- NetworkGuard — Rate limiting, connection caps per IP
- ViolationTracker — Auto-escalating bans for bad actors
- PathGuard — Directory traversal prevention (always enabled)
- ContentSafety — Magic byte verification, quarantine suspicious files
- PeerReputation — Behavioral scoring system
- CryptographicCommitment — Pre-transfer hash commitment
- ProofOfStorage — Random chunk challenges
- ByzantineConsensus — 2/3+1 voting for multi-source verification
- Security dashboard — Real-time monitoring in Web UI (System → Security tab)
📖 Design docs: Security implementation • Guidelines • Database poisoning • Adversarial resilience
Automated metadata enrichment and quality assurance.
- MusicBrainz Client — Query recordings, releases, artists
- Album Targets — MBID-based album tracking and completion monitoring
- Chromaprint Integration — Audio fingerprinting for identification
- AcoustID API — Fingerprint-to-MBID lookups
- Auto-Tagging Pipeline — Automatic metadata tagging from MusicBrainz
- Library Health Scanner — Detects transcodes, quality issues, missing tracks
- Remediation Service — Auto-fix via automatic re-download of better quality
📖 Design docs: Canonical scoring • Library health • Advanced fingerprinting
Topic-based micro-communities over the mesh overlay.
- Pod creation/management — Private, Unlisted, or Listed visibility
- DHT-based pod discovery — Find pods by name, focus, or tags
- Decentralized chat — Pod messaging over mesh overlay
- Soulseek chat bridge — Bridge legacy Soulseek rooms to pods
- Gold Star Club — Auto-join pod for first 1000 users
- Pod APIs — Full REST API for pod operations
📖 Design docs: PodCore research • Chat bridge • Gold Star Club • API design
Optional integration with Solid for decentralized identity and Pod-backed metadata storage.
- WebID resolution — Resolve WebID profiles and extract OIDC issuer information
- Solid-OIDC Client ID Document — Serves compliant JSON-LD document at
/solid/clientid.jsonld(dereferenceable per Solid-OIDC spec) - SSRF hardening — Comprehensive security controls:
- Host allow-list (
AllowedHosts) — Empty list denies all remote fetches by default (SSRF protection) - HTTPS-only enforcement — Configurable
AllowInsecureHttpfor dev/test only - Private IP blocking — Automatically blocks localhost,
.localdomains, and RFC1918/link-local IPs - Response limits — Configurable max response size (1MB default) and timeout (10s default)
- Host allow-list (
- RDF parsing — Uses dotNetRDF library for parsing WebID profiles (Turtle and JSON-LD formats)
- API endpoints —
GET /api/v0/solid/statusandPOST /api/v0/solid/resolve-webid - Frontend UI — New "Solid" navigation item and settings page for WebID resolution testing
- Security by default — Feature enabled by default but non-functional until
AllowedHostsis configured (SSRF safety)
Configuration:
feature:
Solid: true # Enable Solid integration (default: true)
solid:
allowedHosts: [] # Empty = deny all remote fetches (SSRF safety)
# Add hostnames like ["your-solid-idp.example", "your-pod-provider.example"]
timeoutSeconds: 10
maxFetchBytes: 1000000
allowInsecureHttp: false # ONLY for dev/test. Keep false in production
redirectPath: "/solid/callback"Future extensions (planned):
- Full OIDC Authorization Code + PKCE flow
- Token storage (encrypted via Data Protection)
- DPoP proof generation
- Pod metadata read/write (playlists, sharelists)
- Type Index / SAI registry discovery
- Access control (WAC/ACP) writers
📖 Design docs: Solid implementation map • User guide
Decentralized content discovery without relying solely on the Soulseek network.
- Shadow Index — Decentralized MBID→peers mapping
- Traffic Observer — Observes search results and extracts MBIDs
- Privacy Controls — Username pseudonymization, configurable retention
- Disaster Mode — Mesh-only operation when Soulseek unavailable
- Scene System — Topic-based micro-networks for niche content
📖 Design docs: VirtualSoulfind v2 • Implementation design • User guide • Content domains
Visibility into performance and network behavior.
- OpenTelemetry tracing —
telemetry.tracingconfig with console, Jaeger, or OTLP exporters - Component activity sources — transfers, mesh, HashDb, and search tracing
Generic service layer for mesh-based applications.
- Service descriptors — Signed Ed25519 descriptors for service discovery
- Service directory — DHT-based service registry
- Service router — Routes requests to service providers
- HTTP gateway — API key + CSRF authentication for services
- Service wrappers — Pods, VirtualSoulfind, introspection wrapped as services
📖 Design docs: Service Fabric tasks • Security audit • How it works
Getting started is simple.
Drop-in replacement for slskd — preserves your existing config at /var/lib/slskd/.
yay -S slskdn # build from source (recommended)
yay -S slskdn-bin # Binary package
sudo systemctl enable --now slskdAccess at http://localhost:5030
For latest experimental features:
Version: 0.24.1-dev-91769043447 | Branch: master
# Arch Linux (AUR)
yay -S slskdn-dev
# Fedora/RHEL (COPR)
sudo dnf copr enable slskdn/slskdn-dev
sudo dnf install slskdn-dev
# Ubuntu/Debian (PPA)
sudo add-apt-repository ppa:keefshape/slskdn
sudo apt update
sudo apt install slskdn-dev
# Docker
docker pull ghcr.io/snapetech/slskdn:devInstall the pre-built binary:
brew tap snapetech/slskdn
brew install slskdnnix profile install github:snapetech/slskdnsudo snap install slskdnwinget install snapetech.slskdnchoco install slskdndocker run -d \
-p 5030:5030 -p 50300:50300 \
-e SLSKD_SLSK_USERNAME=your_username \
-e SLSKD_SLSK_PASSWORD=your_password \
-v /path/to/downloads:/downloads \
-v /path/to/app:/app \
--name slskdN \
ghcr.io/snapetech/slskdn:latestversion: "3"
services:
slskdN:
image: ghcr.io/snapetech/slskdn:latest
container_name: slskdN
ports:
- "5030:5030"
- "50300:50300"
environment:
- SLSKD_SLSK_USERNAME=your_username
- SLSKD_SLSK_PASSWORD=your_password
volumes:
- ./app:/app
- ./downloads:/downloads
- ./music:/music:ro
restart: unless-stoppedgit clone https://github.com/snapetech/slskdn.git && cd slskdn
curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --channel 8.0
export PATH="$HOME/.dotnet:$PATH"
dotnet run --project src/slskd/slskd.csproj| Feature | slskd | slskdN |
|---|---|---|
| Core Soulseek functionality | ✅ | ✅ |
| Web UI & REST API | ✅ | ✅ |
| Auto-replace stuck downloads | ❌ | ✅ |
| Wishlist/background search | ❌ | ✅ |
| Multiple download destinations | ❌ | ✅ |
| Clear all searches | ❌ | ✅ |
| Smart result ranking | ❌ | ✅ |
| User download history badges | ❌ | ✅ |
| Block users from search | ❌ | ✅ |
| Delete files on disk | ❌ | ✅ |
| Save default filters | ❌ | ✅ |
| Multi-select folder downloads | ❌ | ✅ |
| Ntfy/Pushover notifications | ❌ | ✅ |
| Tabbed browsing | ❌ | ✅ |
| Smart source ranking | ❌ | ✅ |
| User notes & ratings | ❌ | ✅ |
| PWA support | ❌ | ✅ |
| Multi-source downloads | ❌ | ✅ |
| DHT mesh networking | ❌ | ✅ |
| Security hardening | ❌ | ✅ |
| MusicBrainz integration | ❌ | ✅ |
| Library health scanner | ❌ | ✅ |
| Pod communities | ❌ | ✅ 🧪 |
| VirtualSoulfind v2 | ❌ | ✅ 🧪 |
| Service fabric | ❌ | ✅ 🧪 |
| Open to community feedback | ✅ | ✅ |
🧪 = Experimental feature (available in dev builds)
slskdN uses the same config format as slskd, with additional options:
soulseek:
username: your_username
password: your_password
listen_port: 50300
directories:
downloads: /downloads
incomplete: /downloads/incomplete
shares:
directories:
- /music
web:
port: 5030
authentication:
username: admin
password: change_me
# slskdN-specific features
global:
download:
auto_replace_stuck: true
auto_replace_threshold: 5.0
auto_replace_interval: 60
wishlist:
enabled: true
interval: 60
auto_download: false
destinations:
folders:
- name: "Music"
path: "/downloads/music"
default: true
- name: "Audiobooks"
path: "/downloads/audiobooks"
# Experimental features (dev builds only)
security:
enabled: true
profile: Standard # Minimal, Standard, Maximum, or Custom
mesh:
enabled: true
dht:
bootstrap_nodes: 60
overlay:
udp_port: 50301
quic_port: 50302Detailed documentation for configuration options can be found in docs/config.md, and an example of the YAML configuration file can be reviewed in config/slskd.example.yml.
| Document | Description |
|---|---|
| Features Overview | Complete feature list and configuration |
| Advanced Features | Deep dives for major slskdN features |
| How It Works | Technical architecture and design |
| Multi-Source Downloads | Network impact analysis |
| DHT Rendezvous Design | Peer discovery architecture |
| Security Specs | Security feature details |
| Implementation Roadmap | Development status |
| Configuration | All configuration options |
| Building | Build instructions |
| Docker | Container deployment |
| Test Coverage Summary | Current test counts and coverage |
| Test Coverage Assessment | Coverage rationale and gaps |
Features in the master branch:
| Feature Category | Status | Notes |
|---|---|---|
| Auto-Replace | ✅ Stable | Production-ready |
| Wishlist | ✅ Stable | Production-ready |
| Smart Ranking | ✅ Stable | Production-ready |
| User Notes | ✅ Stable | Production-ready |
| UI Enhancements | ✅ Stable | Status bars, network monitoring |
| Multi-Source Downloads | ✅ Stable | Concurrency limits, network-friendly |
| DHT Peer Discovery | ✅ Stable | Fully functional mesh overlay |
| Security Hardening | ✅ Stable | Comprehensive framework, tested |
| MusicBrainz Integration | ✅ Stable | Fingerprinting, auto-tagging |
| Library Health Scanner | ✅ Stable | Quality detection and remediation |
| PodCore | 🟡 Experimental | Functional, API may evolve |
| VirtualSoulfind v2 | 🟡 Experimental | Shadow index, disaster mode |
| Service Fabric | 🟡 Experimental | Generic service layer |
For the stable upstream client, see slskd/slskd.
slskdN may require extra configuration when running it behind a reverse proxy. Refer to docs/reverse_proxy.md for a short guide.
We welcome contributions from everyone—first-timers and veterans alike. No prior commit history required.
- Pick an issue from our Issue Tracker
- Fork the repo and create a feature branch
- Submit a PR with your changes
cd src/slskd && dotnet watch run # Backend
cd src/web && npm install && npm start # FrontendFor experimental features, see:
- SECURITY-GUIDELINES.md - Security requirements
- CURSOR-WARNINGS.md - LLM implementation risk assessment
- SERVICE_FABRIC_TASKS.md - Task breakdowns
Features that prove stable may be submitted as PRs to upstream slskd. Our auto-replace feature was first: slskd PR #1553. We aim to be a proving ground, not a permanent fork. We believe good software comes from open dialogue—not just with established contributors, but with everyone who has something to offer. Our door is always open.
slskdN follows slskd's version numbers with a suffix: 0.24.1-slskdN.1 = First slskdN release based on slskd 0.24.1
Development builds use epoch-based versioning: 0.24.1-dev-91769014133 for proper sorting.
GNU Affero General Public License v3.0, same as slskd.
Key requirements:
- Source code must be made available when running the software over a network
- Derivative works must also be AGPL-3.0 licensed
- Copyright notices and license information must be preserved
slskdn is built on the excellent work of others:
This project is a fork of slskd by jpdillingham and contributors.
- slskd is a modern, headless Soulseek client with a web interface and REST API
- Licensed under AGPL-3.0
- We maintain the same license and contribute our changes back to the community
- Philosophy: slskd focuses on a lean core with API-driven extensibility; slskdn focuses on batteries-included features
Why we forked: To build experimental features (mesh networking, multi-source downloads, advanced automation) that go beyond slskd's core mission. We deeply respect the upstream project and its maintainer's design philosophy.
- Soulseek Protocol - The P2P file-sharing protocol created by Nir Arbel
- Soulseek.NET - The excellent .NET Soulseek library
- The Soulseek community
- MusicBrainz - Open music encyclopedia for metadata enrichment
- Cover Art Archive - Album art for verified releases
- AcoustID - Audio fingerprinting service
This project was built in partnership with tools, not replacements for people. Throughout its development, we made deliberate use of AI-powered assistants—most notably Cursor and several leading large language models—as part of the day-to-day engineering workflow.
These systems helped in three main ways:
| Area | How AI Assisted |
|---|---|
| Research & Exploration | Quickly surfacing prior art, sketching out alternative designs, and pressure-testing edge cases that would have taken much longer to explore alone. |
| Automation & Busywork | Generating initial scaffolding, refactoring repetitive patterns, and handling mechanical changes that are important but rarely insightful. |
| Thinking Partner | Serving as a second pair of eyes on tricky problems, helping articulate trade-offs, and translating rough ideas into shapes that could be implemented and tested. |
What these tools did not do is replace responsibility. Every behavior that matters—protocol decisions, data flows, failure modes, and user-visible effects—was reviewed, edited, or rewritten by a human before it landed in this repository. The models accelerated the work and helped make the project possible at this scope, but accountability for the result sits squarely with the maintainer.
If you're reading this code, you should assume that:
- ✅ AI tools were used as collaborators in research, drafting, and mechanical edits
- ✅ The final form of the project reflects human judgment, testing, and ongoing maintenance
In other words: this is an AI-assisted project, not an AI-generated one.
Based on slskd 0.24.1 with extensive enhancements:
- Commits ahead: 4,473+ commits
- New systems: 7 major subsystems (Mesh, Swarm, Security, Pods, MediaCore, VirtualSoulfind, Service Fabric)
- New features: 127+ individual features
- Test coverage: ~2,678 total tests (~2,671 passing, 2-3 skipped)
- Documentation: 100+ markdown files
- Files changed: 450+ files
slskdN — For users who'd rather download music than learn Python.
"built on the backs of giants" 🍦🤖✨