NodeLink vs Lavalink

You've probably heard of Lavalink. It's the legend. The OG. The one that started it all.

And you're probably wondering: "Why NodeLink? What's different?"

Fair question. Let's talk about it.

The Extra Spice 🌶️

NodeLink isn't just a clone. We took what worked and added features that made sense to us.

What's Actually Different?

Let's break it down. No fluff. Just facts.

Lyrics Support

# Get lyrics with automatic source detection
curl "http://your-server.com/v4/loadlyrics?encodedTrack=QAAAjQI..." \
     -H "Authorization: yourPassword"

# Prefer specific language
curl "http://your-server.com/v4/loadlyrics?encodedTrack=QAAAjQI...&lang=pt" \
     -H "Authorization: yourPassword"

Supported sources:

• YouTube Captions: Synced, timestamped lyrics (when available)
• Genius: Plain text lyrics, community-sourced
• Musixmatch: Synced lyrics database (auto-obtains signature)
• LRCLib: Open-source synced lyrics repository

Chapter Markers

Perfect for podcasts, tutorials, and music albums with multiple parts.

curl "http://your-server.com/v4/loadchapters?encodedTrack=QAAAjQI..." \
     -H "Authorization: yourPassword"

Returns:

[
  {
    "title": "An intro to video chapters",
    "startTime": 0,
    "thumbnails": [
      {
        "url": "https://i.ytimg.com/vi_webp/b1Fo_M_tj6w/hqdefault.webp",
        "width": 336,
        "height": 188
      }
    ],
    "duration": 23000,
    "endTime": 23000
  },
  {
    "title": "How to set up video chapters",
    "startTime": 23000,
    "thumbnails": [
      {
        "url": "https://i.ytimg.com/vi_webp/b1Fo_M_tj6w/hqdefault.webp",
        "width": 336,
        "height": 188
      }
    ],
    "duration": 44000,
    "endTime": 67000
  },
  {
    "title": "See video chapters in action",
    "startTime": 67000,
    "thumbnails": [
      {
        "url": "https://i.ytimg.com/vi_webp/b1Fo_M_tj6w/hqdefault.webp",
        "width": 336,
        "height": 188
      }
    ],
    "duration": 12000,
    "endTime": 79000
  }
]

Connection Metrics

Know exactly how your connection is performing. Useful for debugging slow audio or buffering issues.

curl "http://your-server.com/v4/connection" \
     -H "Authorization: yourPassword"

Response:

{
  "status": "good",
  "metrics": {
    "speed": {
      "bps": 23669887.133182842,
      "kbps": 184920.99322799096,
      "mbps": 180.59
    },
    "downloadedBytes": 10485760,
    "durationSeconds": 0.44,
    "timestamp": 1764813556344
  }
}

Direct Streaming

Get direct streaming URLs and available formats for any track. Enable in config with enableTrackStreamEndpoint: true.

# Works with ANY source (YouTube, Spotify, Deezer, etc.)
# Returns JSON with streaming URL and available formats
curl "http://your-server.com/v4/trackstream?encodedTrack=QAAAjQI...&itag=251" \
     -H "Authorization: yourPassword"

{
  "url": "https://[...].googlevideo.com/videoplayback?...",
  "protocol": "http",
  "format": "webm/opus",
  "formats": [
    {
      "itag": 251,
      "mimeType": "audio/webm; codecs=\"opus\"",
      "bitrate": 146128,
      "audioQuality": "AUDIO_QUALITY_MEDIUM"
    }
  ]
}

# Only works with YouTube
curl "http://your-server.com/youtube/stream/{videoId}" \
     -H "Authorization: yourPassword" \
     --output audio.mp3

Use cases:

• Getting direct streaming URLs for custom players
• Downloading audio for offline playback
• Custom audio processing pipelines
• Building audio preview features

Text-to-Speech

# Free, no API keys required
curl "http://your-server.com/v4/loadtracks?identifier=gtts:Hello World" \
     -H "Authorization: yourPassword"

Enhanced Monitoring

Server Info

Both provide /v4/info, but NodeLink adds the isNodelink field for identification:

{
  "version": {
    "semver": "3.1.1",
    "major": 3,
    "minor": 1,
    "patch": 1
  },
  "node": "v25.2.1",
  "isNodelink": true,
  "sourceManagers": [
    "deezer",
    "bandcamp",
    "soundcloud",
    "local",
    "http",
    "applemusic",
    "youtube",
    "instagram",
    "kwai",
    "twitch",
    "spotify",
    "tidal",
    "nicovideo",
    "reddit",
    "lastfm"
  ],
  "filters": [
    "tremolo",
    "vibrato",
    "lowpass",
    "highpass",
    "rotation",
    "karaoke",
    "distortion",
    "channelMix",
    "equalizer",
    "chorus",
    "compressor",
    "echo",
    "phaser",
    "timescale"
  ]
}

{
  "version": {
    "semver": "4.0.0",
    "major": 4,
    "minor": 0,
    "patch": 0
  },
  "jvm": "18.0.2.1",
  "lavaplayer": "1.3.98.4",
  "sourceManagers": [
    "youtube",
    "soundcloud"
  ],
  "filters": [
    "equalizer",
    "karaoke",
    "timescale",
    "channelMix"
  ]
}

Detailed Statistics

NodeLink's /v4/stats includes detailedStats with granular tracking:

{
  "players": 5,
  "playingPlayers": 3,
  "uptime": 17930,
  "detailedStats": {
    "api": {
      "requests": {
        "/v4/loadtracks": 150,
        "/v4/info": 5,
        "/v4/loadlyrics": 42
      },
      "errors": {}
    },
    "sources": {
      "youtube": 120,
      "spotify": 30
    },
    "playback": {
      "events": {
        "TrackStartEvent": 100,
        "TrackEndEvent": 95
      }
    }
  }
}

Audio Sources Comparison

Here's where things get interesting. Let's see what's built-in vs what needs plugins.

# Search Spotify then play via YouTube
curl "http://your-server.com/v4/loadtracks?identifier=spsearch:never gonna give you up" \
     -H "Authorization: yourPassword"

# Search Deezer directly
curl "http://your-server.com/v4/loadtracks?identifier=dzsearch:daft punk" \
     -H "Authorization: yourPassword"

# Text-to-speech
curl "http://your-server.com/v4/loadtracks?identifier=gtts:Hello World" \
     -H "Authorization: yourPassword"

The Plugin Situation

Let's address the elephant in the room: Lavalink has plugins. NodeLink doesn't.

But here's the thing...

Lavalink's Approach

Lavalink has a thriving plugin ecosystem built by the community:

• LavaSrc: Spotify, Apple Music, Deezer, Yandex Music support
• LavaLyrics: Lyrics API for other plugins to consume
• SponsorBlock: YouTube chapters and sponsor segment skipping
• YouTube Plugin: Enhanced YouTube with OAuth, age-restriction bypass
• Google TTS Plugin: Text-to-speech via Google Cloud API
• LavaSearch: Advanced search across platforms
• LavaDSPX: Additional audio filters (echo, compressor, phaser)
• And many more...

How plugin installation works:

Lavalink can auto-download plugins from Maven repositories. You declare them in application.yml with their dependency coordinates, and Lavalink downloads the .jar files on startup.

Advantages:

• Flexibility: Install only what you need
• Community-driven: Third-party developers can extend functionality
• Modularity: Each plugin is independent
• Auto-download: No manual .jar management needed
• Extensibility: You can create custom plugins in Java/Kotlin

Trade-offs:

• Version compatibility: Plugins must match your Lavalink version (v3 vs v4)
• Configuration complexity: Each plugin has its own config section
• Dependency management: Need to track plugin versions and updates
• Restart required: Adding/updating plugins requires restarting Lavalink

NodeLink's Approach

NodeLink has most common features built-in:

• 15+ sources out of the box
• Lyrics from 4 providers
• Chapters extraction
• TTS without API keys
• Connection metrics
• Direct streaming

Advantages:

• Simplicity: One package, everything works
• No version conflicts: Everything is tested together
• Unified config: One config file for all features

Trade-offs:

• Less flexibility: Can't add custom plugins
• Larger base package: Includes features you might not use
• Fixed feature set: Dependent on core team for new features

Configuration Tokens

Some sources need tokens. Here's the reality:

applemusic: {
  enabled: true,
  mediaApiToken: "token_here" // NodeLink generates it automatically!
}

WebSocket Events

NodeLink emits additional events for fine-grained control:

So... Which One?

Still unsure? Let's make it personal.

The Real Answer

NodeLink is API-compatible with Lavalink v4. Your client works with both seamlessly.

Want to try NodeLink? Install it. Test your use case. If you love it, stick with it. If you need something Lavalink-specific, you can switch — your client code doesn't change.

The beauty is that you're not locked in. These are tools, not commitments.

Detecting NodeLink

Want to detect if you're connected to NodeLink vs Lavalink? Check the /v4/info endpoint:

const info = await fetch('http://your-server.com/v4/info', {
  headers: { 'Authorization': 'yourPassword' }
}).then(r => r.json());

if (info.isNodelink) {
  console.log(`🌿 NodeLink v${info.version.semver}`);
  // Use NodeLink-specific features
  // - /v4/loadlyrics
  // - /v4/loadchapters
  // - /v4/connection
  // - Extra sources (Instagram, Reddit, etc.)
} else {
  console.log(`🎵 Lavalink v${info.version.semver}`);
  // Standard Lavalink features only
}

What's Next?

Now that you know the differences, it's time to try it out.

Questions?

Found something unclear? Want to suggest a feature? Have a cool use case?

Join our community or open an issue. We're always listening. 💙