A modern Lavalink alternative built entirely in Node.js
Lightweight, modular, and optimized for real-time performance.
📚 Documentation • API Reference • NodeLink vs Lavalink • Troubleshooting
- Node.js v22 or higher (v24 recommended)
- Git
NodeLink is an alternative audio server built in Node.js, designed for those who value control and efficiency. 🌿 It doesn’t try to reinvent the wheel — it just makes it spin with less weight. Easy to configure, naturally scalable, and with smooth playback, it provides a solid foundation for music bots and real-time audio systems.
Created by Brazilian developers, NodeLink was born from the desire for a simpler, open, and truly accessible audio server for everyone.
Full documentation available at nodelink.js.org 💚
- 100% Node.js implementation – No external runtime required
- Lavalink-compatible API – Works with most existing clients
- Optimized decoding ⚡ – Powered by WebAssembly and native modules
- Worker-based architecture – Each player can run in its own process for true isolation
- Real-time audio filters – Equalizer, timescale, tremolo, compressor, echo, chorus, phaser, and more
- Low memory footprint – Efficient even with multiple active players
- Prometheus metrics – Production-ready monitoring with detailed statistics
- Multiple source support – 15+ sources including YouTube, Spotify, Apple Music, Deezer, and more
# Clone the repository
git clone https://github.com/PerformanC/NodeLink.git
cd NodeLink
# Install dependencies
npm install
# Copy the default configuration file
cp config.default.js config.js
# Start the server
npm run startOnce started, NodeLink runs a Lavalink-compatible WebSocket server, ready for immediate use.
NodeLink also supports Docker for easy deployment:
# Using Docker Compose
docker-compose up -d
# Or using Docker directly
docker build -t nodelink .
docker run -p 2333:2333 nodelinkSee the Docker guide: nodelink.js.org/docs/advenced/docker
NodeLink is compatible with most Lavalink clients, as it implements nearly the entire original API. However, some clients may not work properly, since NodeLink changes certain behaviors and endpoints.
| Client | Platform | v3 supported? | NodeLink Features? | NodeLink major version |
|---|---|---|---|---|
| Lavalink-Client | JVM | unknown | No | v1 and v2 |
| Lavalink.kt | Kotlin | unknown | No | v1 |
| DisGoLink | Go | unknown | No | v1 and v2 |
| Lavalink.py | Python | unknown | No | v1 and v2 |
| Mafic | Python | unknown | No | v1 and v2 |
| Wavelink | Python | unknown | No | v1 and v2 |
| Pomice | Python | unknown | No | v1 and v2 |
| Hikari-ongaku | Python | unknown | No | v1 and v2 |
| Moonlink.js | TypeScript | unknown | No | v1 and v2 |
| Magmastream | TypeScript | unknown | No | v1 |
| Lavacord | TypeScript | unknown | No | v1 and v2 |
| Shoukaku | TypeScript | unknown | No | v1 and v2 |
| Lavalink-Client | TypeScript | unknown | No | v1 |
| Rainlink | TypeScript | unknown | No | v1 and v2 |
| Poru | TypeScript | unknown | No | v1 and v2 |
| Blue.ts | TypeScript | unknown | No | v1 and v2 |
| FastLink | Node.js | unknown | No | v1 and v2 |
| Riffy | Node.js | unknown | No | v1 and v2 |
| TsumiLink | Node.js | unknown | No | v1 and v2 |
| AquaLink | JavaScript | unknown | No | v1 and v2 |
| DisCatSharp | .NET | unknown | No | v1 and v2 |
| Lavalink4NET | .NET | unknown | No | v1 and v2 |
| Nomia | .NET | unknown | No | v1 and v2 |
| CogLink | C | unknown | No | v1 and v2 |
| Lavalink-rs | Rust, Python | unknown | No | v1 and v2 |
| nyxx_lavalink | Dart | unknown | No | v1 |
Important
Lack of explicit NodeLink support usually means that the client implements the Lavalink API inconsistently, not following its defined formats and fields. Using such clients may lead to unexpected behavior.
Note
Data was sourced from the official Lavalink documentation and manually updated. Compatibility information for NodeLink v3 is still being verified.
NodeLink is designed to be memory-efficient ⚡
At startup, it typically uses around 50 MB, stabilizing near 24 MB when idle. Each active player adds between 4 and 15 MB, depending on stream format and applied filters.
Cluster workers run independently, maintaining their own caches and pipelines — enabling parallel, scalable playback without session interference.
NodeLink exposes Prometheus metrics at /v4/metrics for production monitoring:
- Audio frame statistics (sent, nulled, deficit)
- Memory breakdown (RSS, heap, external buffers)
- Event loop lag and GC pauses
- CPU load and active handles
- API request tracking per endpoint
- Source usage tracking
See the monitoring guide: nodelink.js.org/docs/advenced/prometheus
NodeLink follows a worker-based model, where each process manages its own players and buffers. Each worker acts as an autonomous mini-instance, communicating with the main process only when necessary. This reduces bottlenecks and keeps stability even under heavy load.
Its modular structure also allows swapping components, adding new sources or filters, and adjusting internal behavior without touching the core server.
Internally, NodeLink combines native and WebAssembly modules for precise audio processing, buffering, and packet handling.
@performanc/pwsl-server⚡@performanc/voice⚡@alexanderolsen/libsamplerate-js@ecliptia/faad2-wasm💙@ecliptia/seekable-stream💙@toddynnn/symphonia-decodermp4boxmyzodtoddy-mediaplex
Optional Dependencies:
prom-client– Required only if Prometheus metrics are enabled in config. Install withnpm install prom-client.
Note
Dependencies marked with ⚡ are maintained by PerformanC.
Dependencies marked with 💙 are maintained by Ecliptia.
These modules form the essential foundation that keeps NodeLink’s playback stable and reliable.
Pull requests are welcome!
Feel free to open issues, share suggestions, or join discussions on Discord. Every contribution helps make NodeLink more stable, accessible, and well-documented.
Found a bug? Report it and we'll fix it.
Need a feature? Let us know and we'll consider it.
Want to contribute? The codebase is waiting for you.
Together, we make NodeLink better. 💚
A huge thank you to @RainyXeon for generously allowing us to incorporate the NicoVideo streaming logic from LunaStream. Your contribution made this possible and is greatly appreciated!
Questions, feedback, or contributions are always welcome:
NodeLink is open-source software released under the BSD 2-Clause License. See LICENSE for full details.
NodeLink was born from a simple desire: to understand and master every detail of an audio server — without relying on closed, heavy, or complicated solutions. The goal is to make audio accessible, transparent, and fun to build.
NodeLink — where lightness meets sound. 🌿
Made with ⚡ and curiosity by PerformanC and Ecliptia 💙
(BRAZIL 🇧🇷)
