waterlink

📖 Table of Contents

• 📖 Table of Contents
• 📚 Introduction
• 📦 Installation
• 🍀 Getting started
• ✨ Client related
  • Creating a client
  • Loading tracks
  • Decoding a single track
  • Decoding multiple tracks
• ⛵ Connection related
  • Opening a connection
  • 🦷 Configuring session resuming
  • ❌ Disabling session resuming
  • 📜 Getting a guild
• 🏠 Guild related
  • Destroying its player
  • Updating its voice server
  • Playing a track
  • Stopping the playback
  • Pausing/Resuming the playback
  • Seeking the playback
  • Updating the volume
• 📂 Examples
  • octave

---

📚 Introduction

Waterlink is a Lavalink API wrapper written in Go.

---

📦 Installation

go get -u github.com/lukasl-dev/waterlink/v2

---

🍀 Getting started

For the further guides, a Lavalink instance is used, which uses the following application.yml configuration:

server:
  port: 2333
  address: 0.0.0.0
lavalink:
  server:
    password: "youshallnotpass"

---

✨ Client related

Creating a client

creds := waterlink.Credentials{
  Authorization: "youshallnotpass",
}

client, err := waterlink.NewClient("http://localhost:2333", creds)

Loading tracks

res, err := client.LoadTracks(query.Of("https://www.youtube.com/watch?v=dQw4w9WgXcQ"))

res, err := client.LoadTracks(query.YouTube("Never Gonna Give You Up"))

res, err := client.LoadTracks(query.SoundCloud("Never Gonna Give You Up"))

Decoding a single track

info, err := client.DecodeTrack(
  "QAAAoQIAPFJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAgKE9mZmljaWFsIE11c2ljIFZpZGVvKQALUmljayBBc3RsZXkAAAAAAANACAALZFF3NHc5V2dYY1EAAQAraHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g/dj1kUXc0dzlXZ1hjUQAHeW91dHViZQAAAAAAAAAA",
)

Decoding multiple tracks

tracks, err := client.DecodeTracks([]string{
  "QAAAoQIAPFJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAgKE9mZmljaWFsIE11c2ljIFZpZGVvKQALUmljayBBc3RsZXkAAAAAAANACAALZFF3NHc5V2dYY1EAAQAraHR0cHM6Ly93d3cueW91dHViZS5jb20vd2F0Y2g/dj1kUXc0dzlXZ1hjUQAHeW91dHViZQAAAAAAAAAA",
})

---

⛵ Connection related

Opening a connection

The opts parameter is optional. In this example, it is used to register an EventHandler. If this is not needed, omit it.

creds := waterlink.Credentials{
  Authorization: "youshallnotpass", // password of the Lavalink instance
  UserID:        0,                 // id of the bot user
}

opts := waterlink.ConnectionOptions{
  EventHandler: waterlink.EventHandlerFunc(func(evt interface{}) {
    fmt.Printf("%s received\n", reflect.TypeOf(evt))
  }),
}

conn, err := waterlink.Open("ws://localhost:2333", creds, opts)

To restore a past session, its resume key can be defined in the credentials.

See Configuring session resuming

creds := waterlink.Credentials{
  Authorization: "youshallnotpass", // password of the Lavalink instance
  UserID:        0,                 // id of the bot user
  ResumeKey:     "myResumeKey",     // the resume key of the previous session
}

🦷 Configuring session resuming

Configures a resume key with a timeout of 5 minutes.

err := conn.ConfigureResuming("myResumeKey", 5*time.Minute)

❌ Disabling session resuming

err := conn.DisableResuming()

📜 Getting a guild

A guild is necessary to access its audio player. The function does not check whether the bot user is on this guild.

g := conn.Guild(0) // id of the guild to access

---

🏠 Guild related

A guild can be obtained via its own ID with the use of a connection.

See Getting a guild

Destroying its player

err := g.Destroy()

Updating its voice server

This function is primarily performed inside a 3rd party libraries' event listener.

See Examples

err := g.UpdateVoice("session", "token", "endpoint")

Playing a track

The params parameter is optional. It can be used to specify more information. If this is not needed, omit it.

params := waterlink.PlayParams{
  StartTime: 0,
  EndTime:   0,
  Volume:    0,
  NoReplace: false,
  Pause:     false,
}
err := g.PlayTrack(t, params) // `t` is the preloaded track to play

Stopping the playback

err := g.Stop()

Pausing/Resuming the playback

err := g.SetPaused(true)

Seeking the playback

err := g.Seek(25 * time.Second) // seek to 25 seconds

Updating the volume

err := g.UpdateVolume(25) // 25%

---

📂 Examples

octave

Octave is a simple music bot written by myself. It uses discordgo as its Discord library.