waterlink

package module
v1.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 19, 2022 License: MIT Imports: 26 Imported by: 2

README

📚 Introduction

Waterlink is a Lavalink client written in Go. The library is based on the Lavalink 3.x.x protocol.

🔎 Compatibility

The following Lavalink versions have been tested for compatibility with waterlink:

🗳 Installation

It is assumed that you have already worked with the Go environment. If this is not the case, see this page first.

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

🎨 Structural design

🏠 Architecture

I have tried to implement my interpretation of Clean Architecture by Robert C. Martin (Uncle Bob). If you have any corrections or suggestions, please create an issue.

🦟 Mocking

To simplify testing for the handling of the library, waterlink offers the possibility of mock implementations. The mocking library used for this is stretchr/testify.

🎍 Getting started

Firstly, we need to differentiate between connectionless and connection-oriented use cases. ** Connection-oriented** use cases require an active web socket connection to the Lavalink server and ** connectionless** use cases are only based on simple HTTP requests.

⛵ Opening a connection

The Connection is the interface between waterlink and Lavalink's web socket API. It is required to access the ** connection-oriented use cases** and can be opened by the waterlink.Connect function.

Usage 

package main

import (
  "context"
  "net/url"

  "github.com/lukasl-dev/waterlink"
)

var (
  host = url.URL{ // TODO: adjust
  	Scheme: "ws",
  	Host:   "localhost:2333",
  }
  passphrase = "youshallnotpass" // TODO: adjust
)

func main() {
  opts := waterlink.NewConnectOptions().WithPassphrase(passphrase) // more options available
  conn, err := waterlink.Connect(context.TODO(), host, opts)
  if err != nil {
  	// TODO: handle error
  	return
  }
  // TODO: use conn
}

☎ Creating a requester

The Requester is the interface between waterlink and Lavalink's HTTP API. It is required to access the ** connectionless use cases** and can be created by the waterlink.NewRequester function.

Usage 

package main

import (
  "net/url"

  "github.com/lukasl-dev/waterlink"
)

var (
  host = url.URL{ // TODO: adjust
  	Scheme: "http",
  	Host:   "localhost:2333",
  }
  passphrase = "youshallnotpass" // TODO: adjust
)

func main() {
  opts := waterlink.NewRequesterOptions().WithPassphrase(passphrase) // more options available
  req := waterlink.NewRequester(host, opts)
  // TODO: use req
}

🎹 Interacting with tracks
Loading multiple tracks
Usage 

package main

import (
  "github.com/lukasl-dev/waterlink"
)

var (
  req        waterlink.Requester                             // TODO: create req
  identifier = "https://www.youtube.com/watch?v=dQw4w9WgXcQ" // TODO: adjust
)

func main() {
  resp, err := req.LoadTracks(identifier)
  if err != nil {
  	// TODO: handle error
  	return
  }
  // TODO: use resp
}

Decoding multiple tracks
Usage 

package main

import (
  "github.com/lukasl-dev/waterlink"
)

var (
  req      waterlink.Requester // TODO: create req
  trackIDs []string            // TODO: define trackIDs
)

func main() {
  tracks, err := req.DecodeTracks(trackIDs...)
  if err != nil {
  	// handle error
  	return
  }
  // TODO: use tracks
}

🎶 Interacting with an audio player

The interaction with an audio player requires an active web socket connection.

Additionally, a voice update event must be intercepted to play a track.

Destroying an audio player
Usage 

package main

import "github.com/lukasl-dev/waterlink"

var (
  conn    waterlink.Connection // TODO: open conn
  guildID string               // TODO: define guildID
)

func main() {
  if err := conn.Destroy(guildID); err != nil {
  	// TODO: handle error
  }
}

Pausing/Resuming the current playing track
Usage 

package main

import "github.com/lukasl-dev/waterlink"

var (
  conn    waterlink.Connection // TODO: open conn
  guildID string               // TODO: define guildID
  paused  bool                 // TODO: define paused
)

func main() {
  if err := conn.SetPaused(guildID, paused); err != nil {
  	// TODO: handle error
  }
}

Playing a track
Usage 

package main

import (
  "github.com/lukasl-dev/waterlink"
  "github.com/lukasl-dev/waterlink/usecase/play"
)

var (
  conn    waterlink.Connection // TODO: open conn
  guildID string               // TODO: define guildID
  trackID string               // TODO: load trackID
  volume  uint                 // TODO: define volume
)

func main() {
  opts := play.NewOptions().WithVolume(volume) // more options available
  if err := conn.Play(guildID, trackID, opts); err != nil {
  	// TODO: handle error
  }
}

Seeking the current playing track
Usage 

package main

import (
  "github.com/lukasl-dev/waterlink"
)

var (
  conn     waterlink.Connection // TODO: open conn
  guildID  uint                 // TODO: define guildID
  position uint                 // TODO: define position
)

func main() {
  if err := conn.Seek(guildID, position); err != nil {
  	// TODO: handle error
  }
}

Stopping the current playing track
Usage 

package main

import (
  "github.com/lukasl-dev/waterlink"
)

var (
  conn    waterlink.Connection // TODO: open conn
  guildID string               // TODO: define guildID
)

func main() {
  if err := conn.Stop(guildID); err != nil {
  	// TODO: handle error
  }
}

Intercepting a voice update event
Usage 

package main

import (
  "github.com/lukasl-dev/waterlink"
)

var (
  conn      waterlink.Connection // TODO: open conn
  guildID   uint                 // TODO: define guildID
  sessionID string               // TODO: define sessionID
  token     string               // TODO: define token
  endpoint  string               // TODO: define endpoint
)

func main() {
  if err := conn.UpdateVoice(guildID, sessionID, token, endpoint); err != nil {
  	// TODO: handle error
  }
}

Updating the volume of an audio player
Usage 

package main

import (
  "github.com/lukasl-dev/waterlink"
)

var (
  conn    waterlink.Connection // TODO: open conn
  guildID string               // TODO: define guildID
  volume  uint                 // TODO: define volume
)

func main() {
  if err := conn.UpdateVolume(guildID, volume); err != nil {
  	// TODO: handle error
  }
}

📫 Monitoring events
Usage 

package main

import (
  "github.com/lukasl-dev/waterlink"
  "github.com/lukasl-dev/waterlink/entity/event"
  "github.com/lukasl-dev/waterlink/entity/player"
  "github.com/lukasl-dev/waterlink/entity/server"
)

var (
  conn waterlink.Connection // TODO: open conn
)

func main() {
  for evt := range conn.Events() {
    switch evt.Type() {
    case event.Stats: // more events available
      evt := evt.(server.Stats)
      println("Server uses", evt.Memory.Used, "memory")
    case event.TrackStart: // more events available
      evt := evt.(player.TrackStart)
      println("Track", evt.TrackID, "started on guild", evt.GuildID)
    }
  }
}

📓 Examples

Integrating bwmarrin/discordgo

<External Repository>

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ConnectOptions added in v1.0.0 

type ConnectOptions struct {
	// contains filtered or unexported fields
}

ConnectOptions is used to configure further specifications of the Connect method.

func NewConnectOptions added in v1.0.0 

func NewConnectOptions() *ConnectOptions

NewConnectOptions returns a new ConnectOptions.

func (*ConnectOptions) WithDialer added in v1.0.0 

func (opts *ConnectOptions) WithDialer(dialer *websocket.Dialer) *ConnectOptions

WithDialer sets the dialer to the parameter value.

func (*ConnectOptions) WithNumShards added in v1.0.0 

func (opts *ConnectOptions) WithNumShards(numShards uint) *ConnectOptions

WithNumShards sets the number of shards to the parameter value.

func (*ConnectOptions) WithPassphrase added in v1.0.0 

func (opts *ConnectOptions) WithPassphrase(passphrase string) *ConnectOptions

WithPassphrase sets the passphrase to the parameter value.

func (*ConnectOptions) WithResumeKey added in v1.0.0 

func (opts *ConnectOptions) WithResumeKey(resumeKey string) *ConnectOptions

WithResumeKey sets the resume key to the parameter value.

func (*ConnectOptions) WithUserID added in v1.0.0 

func (opts *ConnectOptions) WithUserID(userID string) *ConnectOptions

WithUserID sets the user id to the parameter value.

type Connection added in v1.0.0 

type Connection interface {
	receiveevent.EventReceiver
	configureresuming.ResumingConfigurer
	destroy.Destroyer
	equalize.Equalizer
	pause.Pauser
	play.Player
	seek.Seeker
	stop.Stopper
	updatevoice.VoiceUpdater
	updatevolume.VolumeUpdater

	// Resumed returns true whenever the Connection has
	// been resumed.
	Resumed() bool
}

Connection wraps all connection-oriented use cases.

func Connect added in v1.0.0 

func Connect(ctx context.Context, host url.URL, opts ...*ConnectOptions) (Connection, error)

Connect opens a Connection to the passed host.

type MockedConnection added in v1.0.0 

type MockedConnection struct {
	mock.Mock
}

MockedConnection is the mocking implementation of Connection.

func (*MockedConnection) ConfigureResuming added in v1.0.0 

func (conn *MockedConnection) ConfigureResuming(resumeKey string, timeout uint) error

ConfigureResuming configures the resume key used to resume a connection.

func (*MockedConnection) Destroy added in v1.0.0 

func (conn *MockedConnection) Destroy(guildID string) error

Destroy is used to destroy a guild's audio player.

func (*MockedConnection) Events added in v1.1.3 

func (conn *MockedConnection) Events() <-chan event.Event

Events returns a channel in which all events are streamed.

func (*MockedConnection) Play added in v1.0.0 

func (conn *MockedConnection) Play(guildID string, trackID string, opts ...*play.Options) error

Play plays the track with the given id on the guild's audio player. More options can be configured via Options.

func (*MockedConnection) Resumed added in v1.0.0 

func (conn *MockedConnection) Resumed() bool

Resumed returns true whenever the Connection has been resumed.

func (*MockedConnection) Seek added in v1.0.0 

func (conn *MockedConnection) Seek(guildID string, position uint) error

Seek skips the current track of a guild's audio player to the passed position.

func (*MockedConnection) SetPaused added in v1.0.0 

func (conn *MockedConnection) SetPaused(guildID string, paused bool) error

SetPaused sets the paused state of a guild's audio player to the passed parameter value.

func (*MockedConnection) Stop added in v1.0.0 

func (conn *MockedConnection) Stop(guildID string) error

Stop stops the current track of a guild's audio player.

func (*MockedConnection) UpdateVoice added in v1.0.0 

func (conn *MockedConnection) UpdateVoice(guildID string, sessionID, token, endpoint string) error

UpdateVoice is sent when the voice server of a guild has been updated. This method must be performed to play a track. See: https://discord.com/developers/docs/topics/gateway#voice-server-update

func (*MockedConnection) UpdateVolume added in v1.0.0 

func (conn *MockedConnection) UpdateVolume(guildID string, volume uint) error

UpdateVolume changes the volume of a guild's audio player.

func (*MockedConnection) UseEqualizer added in v1.0.0 

func (conn *MockedConnection) UseEqualizer(guildID string, bands ...equalize.Band) error

UseEqualizer applies the passed bands on a guild's audio player.

type MockedRequester added in v1.0.0 

type MockedRequester struct {
	mock.Mock
}

MockedRequester is the mocking implementation of Requester.

func NewMockedRequester added in v1.0.0 

func NewMockedRequester() *MockedRequester

NewMockedRequester returns a new MockedRequester.

func (*MockedRequester) DecodeTracks added in v1.0.0 

func (r *MockedRequester) DecodeTracks(trackIDs ...string) ([]*track.Info, error)

DecodeTracks is used to decode the passed trackIDs to track infos.

func (*MockedRequester) LoadTracks added in v1.0.0 

func (r *MockedRequester) LoadTracks(identifier string) (*loadtrack.Response, error)

LoadTracks loads multiple tracks by the passed identifier.

func (*MockedRequester) Status added in v1.0.0 

func (r *MockedRequester) Status() (*routeplanner.Status, error)

Status returns the routeplanner's status.

func (*MockedRequester) UnmarkAddress added in v1.0.0 

func (r *MockedRequester) UnmarkAddress(address string) error

UnmarkAddress unmarks the passed (failed) address.

func (*MockedRequester) UnmarkAddresses added in v1.0.0 

func (r *MockedRequester) UnmarkAddresses() error

UnmarkAddresses unmarks all failed addresses.

type Requester added in v1.0.0 

type Requester interface {
	decodetrack.TrackDecoder
	loadtrack.TrackLoader
	getstatus.StatusGetter
	unmarkaddress.AddressUnmarker
	unmarkaddresses.AddressesUnmarker
}

Requester wraps all connectionless use cases.

func NewRequester added in v1.0.0 

func NewRequester(host url.URL, opts ...*RequesterOptions) Requester

NewRequester returns a new Requester which uses the passed host as destination.

type RequesterOptions added in v1.0.0 

type RequesterOptions struct {
	// contains filtered or unexported fields
}

RequesterOptions is used to configure further specifications of the Requester.

func NewRequesterOptions added in v1.0.0 

func NewRequesterOptions() *RequesterOptions

NewRequesterOptions returns a new RequesterOptions.

func (*RequesterOptions) WithClient added in v1.0.0 

func (opts *RequesterOptions) WithClient(client *http.Client) *RequesterOptions

WithClient sets the client to the parameter value.

func (*RequesterOptions) WithPassphrase added in v1.0.0 

func (opts *RequesterOptions) WithPassphrase(passphrase string) *RequesterOptions

WithPassphrase sets the passphrase to the parameter value.

Source Files

View all Source files

Directories

Path Synopsis
adapter
receiveevent
driver
httpdriver
websocketdriver
entity
event
player
routeplanner
server
track
usecase
configureresuming
decodetrack
destroy
equalize
loadtrack
pause
play
routeplanner/getstatus
routeplanner/unmarkaddress
routeplanner/unmarkaddresses
seek
stop
updatevoice
updatevolume

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.