A Golang Lavalink Client

Go Reference Go Report Go Version License Disgolink Version Support Discord

discord gopher


DisGolink is a Lavalink Client written in Golang which supports the latest Lavalink 3.4 release and the new plugin system(lavalink dev only).

While DisGoLink can be used with any Discord Library DisGo is the best fit for it as usage with other Libraries can be a bit annoying due to different Snowflake implementations.

This Library uses the Disgo Snowflake package like DisGo

Getting Started


For DisGo and DiscordGo there is a sub module which simplifies the usage of DisGolink a bit. You can skip those if you want and directly get the Lavalink Client via

go get github.com/disgoorg/disgolink/lavalink

or you can get the library specific packages via


go get github.com/disgoorg/disgolink/disgolink


go get github.com/disgoorg/disgolink/dgolink



First create a new lavalink instance. You can do this either with

import "github.com/disgoorg/disgolink/lavalink"

link := lavalink.New(lavalink.WithUserID("user_id_here"))

or with the library specific packages


import "github.com/disgoorg/disgolink/disgolink"

link := disgolink.New(disgo)


import "github.com/disgoorg/disgolink/dgolink"

link := dgolink.New(session)

then you add your lavalink nodes. This directly connects to the nodes and is a blocking call

node, err := link.AddNode(context.TODO(), lavalink.NodeConfig{
		Name:        "test", // a unique node name
		Host:        "localhost",
		Port:        "2333",
		Password:    "youshallnotpass",
		Secure:      false, // ws or wss
		ResumingKey: "", // only needed if you want to resume a lavalink session

after this you can play songs from lavalinks supported sources.

Loading a track

To play a track you first need to resolve the song. For this you need to call the Lavalink rest loadtracks endpoint which returns a result with various track instances. Those tracks can then be played.

query := "ytsearch:Rick Astley - Never Gonna Give You Up"

err := link.BestRestClient().LoadItemHandler(context.TODO(), query, lavalink.NewResultHandler(
		func(track lavalink.AudioTrack) {
				// Loaded a single track
		func(playlist lavalink.AudioPlaylist) {
				// Loaded a playlist
		func(tracks []lavalink.AudioTrack) {
				// Loaded a search result
		func() {
				// nothing matching the query found
		func(ex lavalink.FriendlyException) {
				// something went wrong while loading the track

Playing a track

To play a track we first need to to connect to the voice channel. Connecting to a voice channel differs with every lib but here are some quick usages with some

// DisGo
err := client.Connect(context.TODO(), guildID, channelID)

// DiscordGo
err := session.ChannelVoiceJoinManual(guildID, channelID, false, false)

after this you can get/create your player and play the track

player := link.Player("guild_id") // This will either return an existing or new player

var track lavalink.channelID // track from result handler before
err := player.Play(track)

now audio should start playing

Listening for events

You can listen for following lavalink events

  • PlayerUpdate
  • PlayerPause
  • PlayerResume
  • TrackStart
  • TrackEnd
  • TrackException
  • TrackStuck
  • WebsocketClosed

for this implement the PlayerEventListener interface. To listen to only a few events you can optionally embed the PlayerEventAdapter struct which has empty dummy methods.

After implementing the interface you can add the listener to the player and your methods should start getting called

type EventListener struct {
func (l *EventListener) OnTrackStart(player Player, track AudioTrack)                                  {}
func (l *EventListener) OnTrackEnd(player Player, track AudioTrack, endReason AudioTrackEndReason)     {}
func (l *EventListener) OnTrackException(player Player, track AudioTrack, exception FriendlyException) {}



Lavalink added plugins on the dev branch. DisGolink exposes a similar API for you to use. With that you can create plugins which require server & client work. To see what you can do with plugins see here

You register plugins when creating the link instance like this

link := lavalink.New(lavalink.WithUserID("user_id_here"), lavalink.WithPlugins(yourPlugin))

// DisGo
link := disgolink.New(client, lavalink.WithPlugins(yourPlugin)) 

// DiscordGo
link := dgolink.New(session, lavalink.WithPlugins(yourPlugin))

Here is a list of plugins(you can pr your own to here):


You can find examples under


For help feel free to open an issue or reach out on Discord


Contributions are welcomed but for bigger changes please first reach out via Discord or create an issue to discuss your intentions and ideas.


Distributed under the License. See LICENSE for more information.

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.