### Complete Configuration Example

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/MANIFEST.md

This example demonstrates a full configuration setup for DisGoLink, including client options and node configuration. Ensure all necessary fields are provided for a robust setup.

```go
package main

import (
	"context"
	"log"
	"os"
	"os/signal"
	"syscall"

	d "github.com/disgoorg/disgolink/v2/disgolink"
	"github.com/disgoorg/disgolink/v2/lavalink"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	// Setup signal handler for graceful shutdown
	ssig := make(chan os.Signal, 1)
	ssignal.Notify(ssig, syscall.SIGINT, syscall.SIGTERM)

	// Initialize DisGoLink with custom options
	dl := disgolink.New(
		123456789, // Your bot's application ID
		d, // DisGo client instance
		disgolink.WithLogger(log.Default()), // Use default logger
		disgolink.WithHTTPClient(nil), // Use default HTTP client
		disgolink.WithListenerFunc(func(event lavalink.Event) {
			// Handle events here
			log.Printf("Received event: %T\n", event)
		}),
	)

	// Add a Lavalink node
	node, err := dl.AddNode(
		ctx,
		"MyLavalinkNode", // A unique name for the node
		"http://localhost:2333", // Lavalink REST API URL
		"your-lavalink-password", // Lavalink password
		lavalink.WithNodeSecure(false), // Use WSS for WebSocket connection
		lavalink.WithNodeResume(true, "your-resume-key"), // Enable session resumption
	)
	if err != nil {
		log.Fatalf("Failed to add node: %v\n", err)
	}

	// Wait for shutdown signal
	<-ssig

	// Disconnect from Lavalink gracefully
	log.Println("Shutting down DisGoLink...")
	_ = dl.Close()
}

```

--------------------------------

### Complete Disgolink Setup and Track Loading Example

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/load-result-handler.md

A full example demonstrating how to initialize Disgolink, add a node, and use the LoadTracksHandler to play music, queue playlists, display search results, or handle errors.

```go
package main

import (
    "context"
    "fmt"
    
    "github.com/disgoorg/snowflake/v2"
    "github.com/disgoorg/disgolink/v4/disgolink"
    "github.com/disgoorg/disgolink/v4/lavalink"
)

func main() {
    ctx := context.Background()
    client := disgolink.New(snowflake.ID(123456789))
    defer client.Close()
    
    node, _ := client.AddNode(ctx, disgolink.NodeConfig{
        Name:     "main",
        Address:  "localhost:2333",
        Password: "password",
    })
    
    guildID := snowflake.ID(987654321)
    query := "ytsearch:Rick Astley Never Gonna Give You Up"
    
    // Create handler
    handler := disgolink.NewTrackLoadingResultHandler(
        func(track lavalink.Track) {
            // Play single track
            player := client.Player(guildID)
            player.Update(ctx, disgolink.WithTrack(track))
            fmt.Printf("▶ Now playing: %s\n", track.Info.Title)
        },
        func(playlist lavalink.Playlist) {
            // Queue entire playlist
            player := client.Player(guildID)
            if len(playlist.Tracks) > 0 {
                player.Update(ctx, disgolink.WithTrack(playlist.Tracks[0]))
                fmt.Printf("▶ Playlist: %s (%d tracks)\n", 
                    playlist.Info.Name, len(playlist.Tracks))
            }
        },
        func(tracks []lavalink.Track) {
            // Show search results
            fmt.Printf("Found %d results:\n", len(tracks))
            for i, track := range tracks {
                fmt.Printf("%d. %s by %s\n", i+1, 
                    track.Info.Title, track.Info.Author)
            }
        },
        func() {
            // No results
            fmt.Println("❌ No tracks found")
        },
        func(err error) {
            // Error occurred
            fmt.Printf("❌ Failed to load: %v\n", err)
        },
    )
    
    // Load tracks with handler
    node.Rest.LoadTracksHandler(ctx, query, handler)
}

```

--------------------------------

### Install DisGoLink

Source: https://github.com/disgoorg/disgolink/blob/v4/README.md

Install the DisGoLink library using go get.

```sh
go get github.com/disgoorg/disgolink/v4
```

--------------------------------

### Complete DisGoLink Client Configuration Example

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/configuration.md

This example demonstrates creating a DisGoLink client with a custom logger, HTTP client, event listeners for various events (Ready, PlayerTrackStart, PlayerTrackEnd, Stats), and custom plugins. It also shows how to add a node with secure connection enabled.

```go
package main

import (
    "context"
    "log"
    "log/slog"
    "net/http"
    "os"
    "time"
    
    "github.com/disgoorg/snowflake/v2"
    "github.com/disgoorg/disgolink/v4/disgolink"
)

func main() {
    ctx := context.Background()
    
    // Create custom logger
    logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        Level: slog.LevelDebug,
    }))
    
    // Create custom HTTP client
    httpClient := &http.Client{
        Timeout: 30 * time.Second,
        Transport: &http.Transport{
            MaxIdleConns:        100,
            MaxIdleConnsPerHost: 10,
            IdleConnTimeout:     30 * time.Second,
        },
    }
    
    // Create client with full configuration
    client := disgolink.New(snowflake.ID(123456789),
        disgolink.WithLogger(logger),
        disgolink.WithHTTPClient(httpClient),
        disgolink.WithListenerFunc[*disgolink.ReadyEvent](onReady),
        disgolink.WithListenerFunc[*disgolink.PlayerTrackStartEvent](onTrackStart),
        disgolink.WithListenerFunc[*disgolink.PlayerTrackEndEvent](onTrackEnd),
        disgolink.WithListenerFunc[*disgolink.StatsEvent](onStats),
        disgolink.WithPlugins(
            &CustomPlugin{logger: logger},
        ),
    )
    defer client.Close()
    
    // Add nodes
    nodeConfig := disgolink.NodeConfig{
        Name:     "primary",
        Address:  "lavalink.example.com:2333",
        Password: "youshallnotpass",
        Secure:   true,
    }
    
    node, err := client.AddNode(ctx, nodeConfig)
    if err != nil {
        log.Fatalf("Failed to add node: %v", err)
    }
    
    log.Printf("Connected to node %s (status: %s)", node.Config.Name, node.Status())
}

func onReady(e *disgolink.ReadyEvent) {
    log.Println("Lavalink ready")
}

func onTrackStart(e *disgolink.PlayerTrackStartEvent) {
    log.Printf("Playing: %s by %s", e.Track.Info.Title, e.Track.Info.Author)
}

func onTrackEnd(e *disgolink.PlayerTrackEndEvent) {
    log.Printf("Track ended: %s", e.Reason)
}

func onStats(e *disgolink.StatsEvent) {
    log.Printf("Stats - Players: %d, Playing: %d, Uptime: %s",
        e.Players, e.PlayingPlayers, e.Uptime.String())
}

type CustomPlugin struct {
    logger *slog.Logger
}

func (p *CustomPlugin) Name() string    { return "custom" }
func (p *CustomPlugin) Version() string { return "1.0.0" }
```

--------------------------------

### Complete Disgolink Client Setup with Listeners

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/events.md

Demonstrates a complete Disgolink client setup, including initialization with embedded listeners for ReadyEvent, PlayerTrackStartEvent, and PlayerTrackEndEvent, and adding more listeners at runtime for StatsEvent.

```go
package main

import (
    "context"
    "log"
    
    "github.com/disgoorg/snowflake/v2"
    "github.com/disgoorg/disgolink/v4/disgolink"
)

func main() {
    ctx := context.Background()
    
    // Create client with listeners
    client := disgolink.New(snowflake.ID(123456789),
        disgolink.WithListenerFunc[*disgolink.ReadyEvent](func(e *disgolink.ReadyEvent) {
            log.Println("Lavalink ready")
        }),
        disgolink.WithListenerFunc[*disgolink.PlayerTrackStartEvent](func(e *disgolink.PlayerTrackStartEvent) {
            log.Printf("Now playing: %s", e.Track.Info.Title)
        }),
        disgolink.WithListenerFunc[*disgolink.PlayerTrackEndEvent](func(e *disgolink.PlayerTrackEndEvent) {
            log.Printf("Track ended: %s", e.Reason)
        }),
    )
    
    // Add more listeners at runtime
    client.AddListeners(
        disgolink.NewListenerFunc[*disgolink.StatsEvent](func(e *disgolink.StatsEvent) {
            log.Printf("Players: %d", e.Players)
        }),
    )
    
    defer client.Close()
}
```

--------------------------------

### NodeConfig Example

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/node.md

An example demonstrating how to create a NodeConfig instance with essential parameters for connecting to a Lavalink server. The SessionID is optional for resuming previous sessions.

```go
config := disgolink.NodeConfig{
    Name:      "main",
    Address:   "lavalink.example.com:2333",
    Password:  "mysecretpassword",
    Secure:    true,
    SessionID: "abc123def456", // optional
}
```

--------------------------------

### Listen for Player Track Start Events

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/00-START-HERE.md

Adds a listener to the client to react to PlayerTrackStartEvent. This example prints the title of the track that just started playing.

```go
client.AddListeners(
    disgolink.NewListenerFunc[*disgolink.PlayerTrackStartEvent](
        func(e *disgolink.PlayerTrackStartEvent) {
            fmt.Println("Now playing:", e.Track.Info.Title)
        },
    ),
)
```

--------------------------------

### Register Plugin with AddPlugins

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/plugins.md

Example of creating a plugin instance and registering it with the client using the AddPlugins method.

```go
plugin := &MyPlugin{}
client.AddPlugins(plugin)
```

--------------------------------

### Complete SponsorBlock Plugin Example

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/plugins.md

A comprehensive example of a Disgolink plugin that integrates with SponsorBlock. It implements the Plugin interface and the EventPlugin interface to handle custom events.

```go
package main

import (
    "encoding/json"
    "log"
    
    "github.com/disgoorg/disgolink/v4/disgolink"
    "github.com/disgoorg/disgolink/v4/lavalink"
    "github.com/disgoorg/json/v2"
)

// SponsorBlockPlugin handles SponsorBlock plugin integration
type SponsorBlockPlugin struct {
    logger *log.Logger
}

func (p *SponsorBlockPlugin) Name() string {
    return "sponsorblock"
}

func (p *SponsorBlockPlugin) Version() string {
    return "1.0"
}

// Implement EventPlugin for SponsorBlock segment events
func (p *SponsorBlockPlugin) EventPlugins() []disgolink.EventPlugin {
    return []disgolink.EventPlugin{
        &SegmentEventHandler{logger: p.logger},
    }
}

type SegmentEventHandler struct {
    logger *log.Logger
}

func (h *SegmentEventHandler) Event() lavalink.EventType {
    return "SegmentEvent"
}

func (h *SegmentEventHandler) OnEventInvocation(player *disgolink.Player, data json.RawMessage) {
    var segment struct {
        Category string `json:"category"`
        StartTime int64 `json:"startTime"`
        EndTime int64 `json:"endTime"`
    }
    if err := json.Unmarshal(data, &segment); err != nil {
        h.logger.Printf("Error parsing segment: %v\n", err)
        return
    }
    h.logger.Printf("Sponsor segment: %s (%d-%d)\n", 
        segment.Category, segment.StartTime, segment.EndTime)
}

func (h *SegmentEventHandler) OnNodeOpen(node *disgolink.Node) {}
func (h *SegmentEventHandler) OnNodeClose(node *disgolink.Node) {}
func (h *SegmentEventHandler) OnNewPlayer(player *disgolink.Player) {}
func (h *SegmentEventHandler) OnDestroyPlayer(player *disgolink.Player) {}

// Usage
func ExampleUsage() {
    client := disgolink.New(123456789,
        disgolink.WithPlugins(
            &SponsorBlockPlugin{logger: log.Default()},
        ),
    )
    defer client.Close()
}
```

--------------------------------

### Create Client with Plugins

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/plugins.md

Example of creating a Disgolink client and initializing it with multiple plugins using the WithPlugins configuration option.

```go
client := disgolink.New(userID,
    disgolink.WithPlugins(
        &SponsorBlockPlugin{},
        &LavaQueuePlugin{},
    ),
)
```

--------------------------------

### Duration Formatting Example

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/types.md

Demonstrates how to create a Duration and format it into a human-readable string using the String() method.

```go
d := 5*time.Second + 500*time.Millisecond
dur := lavalink.Duration(d.Milliseconds())
fmt.Println(dur.String())  // Output: "5s500ms"
```

--------------------------------

### Example Function Signature

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/00-START-HERE.md

Illustrates the signature of an exported function, including its name, parameters, and return types. This is a typical example of how API signatures are presented.

```Go
func New(userID snowflake.ID, opts ...ConfigOpt) *Client
```

--------------------------------

### Iterate Over Registered Plugins

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/plugins.md

Example demonstrating how to iterate over all registered plugins using the Plugins() method and print their name and version.

```go
for plugin := range client.Plugins() {
    fmt.Printf("Plugin: %s v%s\n", plugin.Name(), plugin.Version())
}
```

--------------------------------

### Add Event Listener

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/client.md

Add custom event listeners to the client. This example shows how to add a listener for the 'ReadyEvent'.

```go
client.AddListeners(disgolink.NewListenerFunc[*disgolink.ReadyEvent](func(e *disgolink.ReadyEvent) {
    fmt.Println("Client ready")
}))
```

--------------------------------

### Register Listener for PlayerTrackStartEvent

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/events.md

Example of creating and registering a type-safe listener for PlayerTrackStartEvent using NewListenerFunc. The listener prints the title of the track that starts playing.

```go
listener := disgolink.NewListenerFunc[*disgolink.PlayerTrackStartEvent](func(e *disgolink.PlayerTrackStartEvent) {
    fmt.Printf("Track: %s\n", e.Track.Info.Title)
})
client.AddListeners(listener)
```

--------------------------------

### Apply Karaoke Filter

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/filters.md

Example of applying the Karaoke filter to a player. Ensure the Karaoke struct is properly configured.

```go
err := player.Update(ctx,
    disgolink.WithFilters(lavalink.Filters{
        Karaoke: &lavalink.Karaoke{
            Level:       1.0,
            MonoLevel:   1.0,
            FilterBand:  220.0,
            FilterWidth: 100.0,
        },
    }),
)
```

--------------------------------

### Initialize DisGo Bot and DisGoLink Client

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/common-patterns.md

Sets up the DisGo client and a DisGoLink client, adding event listeners for ready and track start events. It also adds a Lavalink node.

```go
package main

import (
    "context"
    "log"
    
    "github.com/disgoorg/disgo"
    "github.com/disgoorg/disgo/bot"
    "github.com/disgoorg/disgo/events"
    "github.com/disgoorg/snowflake/v2"
    "github.com/disgoorg/disgolink/v4/disgolink"
    "github.com/disgoorg/disgolink/v4/lavalink"
)

type Bot struct {
    disgo  disgo.Client
    lavalink *disgolink.Client
}

func NewBot(token string, userID snowflake.ID) (*Bot, error) {
    ctx := context.Background()
    
    // Create bot
    client, err := disgo.New(token,
        bot.WithEventListeners(&Bot{}),
    )
    if err != nil {
        return nil, err
    }
    
    // Create Lavalink client
    lavalinkClient := disgolink.New(userID,
        disgolink.WithListenerFunc[*disgolink.ReadyEvent](func(e *disgolink.ReadyEvent) {
            log.Println("Lavalink ready")
        }),
        disgolink.WithListenerFunc[*disgolink.PlayerTrackStartEvent](func(e *disgolink.PlayerTrackStartEvent) {
            log.Printf("Playing: %s\n", e.Track.Info.Title)
        }),
    )
    
    // Add node
    if _, err := lavalinkClient.AddNode(ctx, disgolink.NodeConfig{
        Name:     "main",
        Address:  "localhost:2333",
        Password: "youshallnotpass",
    }); err != nil {
        return nil, err
    }
    
    return &Bot{disgo: client, lavalink: lavalinkClient}, nil
}

func (b *Bot) OnVoiceStateUpdate(event *events.GuildVoiceStateUpdate) {
    // Only process bot's voice updates
    if event.VoiceState.UserID != b.disgo.ApplicationID() {
        return
    }
    b.lavalink.OnVoiceStateUpdate(context.TODO(), 
        event.VoiceState.GuildID, 
        event.VoiceState.ChannelID, 
        event.VoiceState.SessionID)
}

func (b *Bot) OnVoiceServerUpdate(event *events.VoiceServerUpdate) {
    b.lavalink.OnVoiceServerUpdate(context.TODO(),
        event.GuildID,
        event.Token,
        *event.Endpoint)
}

```

--------------------------------

### LifecyclePlugin Implementation

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/plugins.md

An example implementation of the PluginEventHandler interface. This plugin logs node connection events and player creation/destruction events.

```go
type LifecyclePlugin struct {
    logger *log.Logger
}

func (p *LifecyclePlugin) Name() string { return "lifecycle" }
func (p *LifecyclePlugin) Version() string { return "1.0" }

func (p *LifecyclePlugin) OnNodeOpen(node *disgolink.Node) {
    p.logger.Printf("Node %s opened\n", node.Config.Name)
}

func (p *LifecyclePlugin) OnNodeClose(node *disgolink.Node) {
    p.logger.Printf("Node %s closed\n", node.Config.Name)
}

func (p *LifecyclePlugin) OnNewPlayer(player *disgolink.Player) {
    p.logger.Printf("Player created for guild %d\n", player.GuildID)
}

func (p *LifecyclePlugin) OnDestroyPlayer(player *disgolink.Player) {
    p.logger.Printf("Player destroyed for guild %d\n", player.GuildID)
}
```

--------------------------------

### Common Pattern: Implementing Custom Plugins

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/MANIFEST.md

This example outlines the structure for implementing a custom plugin for DisGoLink. Plugins can extend the library's functionality, such as adding custom commands or features.

```go
type MyCustomPlugin struct {
	// Plugin fields
}

func (p *MyCustomPlugin) Name() string {
	return "MyCustomPlugin"
}

func (p *MyCustomPlugin) Register(client *disgolink.Disgolink) {
	// Register plugin specific logic, e.g., add custom commands or handlers
	log.Println("MyCustomPlugin registered.")
}

func (p *MyCustomPlugin) Unregister() {
	// Cleanup logic when the plugin is unregistered
	log.Println("MyCustomPlugin unregistered.")
}

// Example of how to add the plugin:
// plugin := &MyCustomPlugin{}
// dl := disgolink.New(botID, disgoClient, disgolin.WithPlugins(plugin))

```

--------------------------------

### Setup Player Event Listeners

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/common-patterns.md

Register listeners for various player events like Ready, Stats, TrackStart, TrackEnd, TrackException, TrackStuck, and WebSocket closure. Ensure the client is properly initialized before adding listeners.

```go
func setupPlayerListeners(client *disgolink.Client) {
    client.AddListeners(
        disgolink.NewListenerFunc[*disgolink.ReadyEvent](func(e *disgolink.ReadyEvent) {
            log.Printf("Lavalink ready (resumed: %v, session: %s)\n",
                e.Resumed, e.SessionID)
        }),
        
        disgolink.NewListenerFunc[*disgolink.StatsEvent](func(e *disgolink.StatsEvent) {
            log.Printf("Stats: %d players, %.1f%% load\n",
                e.PlayingPlayers,
                (e.CPU.SystemLoad / float64(e.CPU.Cores)) * 100)
        }),
        
        disgolink.NewListenerFunc[*disgolink.PlayerTrackStartEvent](func(e *disgolink.PlayerTrackStartEvent) {
            log.Printf("[%d] Playing: %s by %s\n",
                e.Player.GuildID,
                e.Track.Info.Title,
                e.Track.Info.Author)
        }),
        
        disgolink.NewListenerFunc[*disgolink.PlayerTrackEndEvent](func(e *disgolink.PlayerTrackEndEvent) {
            log.Printf("[%d] Track ended: %s\n",
                e.Player.GuildID,
                e.Reason)
        }),
        
        disgolink.NewListenerFunc[*disgolink.PlayerTrackExceptionEvent](func(e *disgolink.PlayerTrackExceptionEvent) {
            log.Printf("[%d] Track exception: %s (%s)\n",
                e.Player.GuildID,
                e.Exception.Message,
                e.Exception.Severity)
        }),
        
        disgolink.NewListenerFunc[*disgolink.PlayerTrackStuckEvent](func(e *disgolink.PlayerTrackStuckEvent) {
            log.Printf("[%d] Track stuck (threshold: %s)\n",
                e.Player.GuildID,
                e.Threshold.String())
        }),
        
        disgolink.NewListenerFunc[*disgolink.PlayerWebSocketClosedEvent](func(e *disgolink.PlayerWebSocketClosedEvent) {
            log.Printf("[%d] Voice disconnected: %d %s\n",
                e.Player.GuildID,
                e.Code,
                e.Reason)
        }),
    )
}
```

--------------------------------

### Apply ChannelMix Filter

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/filters.md

Example of applying the ChannelMix filter to a player. This preset mixes both channels equally for mono output.

```go
err := player.Update(ctx,
    disgolink.WithFilters(lavalink.Filters{
        ChannelMix: &lavalink.ChannelMix{
            LeftToLeft:   0.5,
            LeftToRight:  0.5,
            RightToLeft:  0.5,
            RightToRight: 0.5,
        },
    }),
)
```

--------------------------------

### Add Multiple Event Listeners to Client

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/events.md

Adds multiple event listeners to the Disgolink client. This example shows how to register listeners for ReadyEvent, StatsEvent, and PlayerTrackStartEvent.

```go
client.AddListeners(
    disgolink.NewListenerFunc[*disgolink.ReadyEvent](onReady),
    disgolink.NewListenerFunc[*disgolink.StatsEvent](onStats),
    disgolink.NewListenerFunc[*disgolink.PlayerTrackStartEvent](onTrackStart),
)
```

--------------------------------

### Info

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/rest-client.md

Gets detailed server information including version, plugins, source managers, and filters. This method requires a context for cancellation.

```APIDOC
## Info

### Description
Gets detailed server information (version, plugins, source managers, filters).

### Method
GET

### Endpoint
/info

### Parameters
#### Query Parameters
- **ctx** (`context.Context`) - Required - Context for cancellation

### Response
#### Success Response (200)
- **info** (`lavalink.Info`) - An object containing server information.
  - **version** (`string`)
  - **plugins** (`[]lavalink.Plugin`)
  - **sourceManagers** (`[]string`)
  - **filters** (`string`)

#### Response Example
```json
{
  "version": "4.0.10",
  "plugins": [],
  "sourceManagers": ["youtube", "http", "local"],
  "filters": "availableFilters"
}
```
```

--------------------------------

### Get Lavalink Server Version

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/rest-client.md

Retrieves the version string of the Lavalink server. Requires a context for cancellation.

```go
version, err := node.Rest.Version(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Lavalink version: %s\n", version)
```

--------------------------------

### Play Track with DisGoLink Player

Source: https://github.com/disgoorg/disgolink/blob/v4/README.md

Creates or retrieves a player for a guild and updates it with a track to start playback. The 'toPlay' variable should be obtained from a result handler.

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

// toPlay is from result handler in the example above
err := player.Update(context.TODO(), lavalink.WithTrack(*toPlay))
```

--------------------------------

### Apply LowPass Filter

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/filters.md

Example of applying the LowPass filter to a player. The Smoothing parameter controls the filter's resonance.

```go
err := player.Update(ctx,
    disgolink.WithFilters(lavalink.Filters{
        LowPass: &lavalink.LowPass{
            Smoothing: 3.0,
        },
    }),
)
```

--------------------------------

### Handle PlayerWebSocketClosedEvent

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/events.md

Example of how to add a listener to handle PlayerWebSocketClosedEvent. This listener will print the close code and reason when a voice connection is disconnected.

```go
client.AddListeners(disgolink.NewListenerFunc[*disgolink.PlayerWebSocketClosedEvent](func(e *disgolink.PlayerWebSocketClosedEvent) {
    fmt.Printf("Voice disconnected: %d %s\n", e.Code, e.Reason)
}))
```

--------------------------------

### Get Server Information

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/endpoints.md

Retrieves comprehensive server information, including version, build details, and supported features. Use this to understand the Lavalink server's capabilities.

```json
{
  "version": {
    "semver": "4.0.0",
    "major": 4,
    "minor": 0,
    "patch": 0,
    "preRelease": ""
  },
  "buildTime": 1234567890,
  "git": {
    "branch": "main",
    "commit": "abc123",
    "commitTime": 1234567890
  },
  "jvm": "11.0.12",
  "lavaplayer": "1.4.0",
  "sourceManagers": ["youtube", "soundcloud", "http"],
  "filters": ["volume", "equalizer", "timescale", "tremolo", "vibrato", "rotation", "karaoke", "distortion", "channelMix", "lowPass"],
  "plugins": [
    {"name": "sponsorblock", "version": "1.0.0"}
  ]
}
```

```go
info, err := node.Rest.Info(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Println(info.Version.Semver)
```

--------------------------------

### Get a Player for a Guild

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/00-START-HERE.md

Retrieves a player instance for a specific guild ID. This player will manage audio playback within that guild.

```go
player := client.Player(guildID)
```

--------------------------------

### Client.AddPlugins

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/plugins.md

Adds one or more plugins to the Disgolink client. This method can be invoked either during the initial setup of the client or at any point while the client is running.

```APIDOC
## Client.AddPlugins

### Description
Adds plugins to the client. Can be called during initialization or at runtime.

### Method
func (c *Client) AddPlugins(plugins ...Plugin)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
plugin := &MyPlugin{}
client.AddPlugins(plugin)
```

### Response
None
```

--------------------------------

### Comprehensive DisGoLink Error Handling

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/errors.md

This example provides a comprehensive error handling function (`handleError`) that uses type assertions and `errors.As`/`errors.Is` to differentiate between various DisGoLink and standard Go errors. It covers specific errors like `disgolink.ErrNodeAlreadyExists`, `disgolink.ErrPlayerNoNode`, `lavalink.Error`, `lavalink.Exception`, `context.DeadlineExceeded`, and `context.Canceled`, with a fallback for unknown errors.

```go
package main

import (
    "context"
    "errors"
    "fmt"
    "log"
    "time"
    
    "github.com/disgoorg/disgolink/v4/disgolink"
    "github.com/disgoorg/disgolink/v4/lavalink"
)

func handleError(err error) {
    // Type assertions for specific errors
    var lavalinkErr lavalink.Error
    var exception lavalink.Exception
    
    if err == disgolink.ErrNodeAlreadyExists {
        fmt.Println("Node already exists - skipping")
        return
    }
    
    if err == disgolink.ErrPlayerNoNode {
        fmt.Println("Player has no node - reassign first")
        return
    }
    
    if errors.As(err, &lavalinkErr) {
        fmt.Printf("Lavalink error %d: %s at %s\n", 
            lavalinkErr.Status, lavalinkErr.Message, lavalinkErr.Path)
        return
    }
    
    if errors.As(err, &exception) {
        fmt.Printf("Track load failed (%s): %s\n", 
            exception.Severity, exception.Message)
        return
    }
    
    if errors.Is(err, context.DeadlineExceeded) {
        fmt.Println("Operation timed out")
        return
    }
    
    if errors.Is(err, context.Canceled) {
        fmt.Println("Operation was cancelled")
        return
    }
    
    // Generic error
    fmt.Printf("Unknown error: %v\n", err)
}

func main() {
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
    defer cancel()
    
    client := disgolink.New(123456789)
    defer client.Close()
    
    // Add node with error handling
    node, err := client.AddNode(ctx, disgolink.NodeConfig{
        Name:     "main",
        Address:  "localhost:2333",
        Password: "password",
    })
    
    if err != nil {
        handleError(err)
        return
    }
    
    // Load tracks with error handling
    result, err := node.Rest.LoadTracks(ctx, "ytsearch:song name")
    if err != nil {
        handleError(err)
        return
    }
    
    // Handle load result
    if result.LoadType == lavalink.LoadTypeError {
        handleError(result.Data.(lavalink.Exception))
        return
    }
}
```

--------------------------------

### Get Lavalink Server Info

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/rest-client.md

Fetches detailed information about the Lavalink server, including its version, loaded plugins, and source managers. Requires a context for cancellation.

```go
info, err := node.Rest.Info(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Source managers: %v\n", info.SourceManagers)
fmt.Printf("Plugins: %v\n", info.Plugins)
```

--------------------------------

### Add Initial Plugins

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/configuration.md

Use WithPlugins to add initial plugins during client creation. This allows extending DisGoLink's functionality.

```go
client := disgolink.New(userID,
    disgolink.WithPlugins(
        &SponsorBlockPlugin{},
        &LavaQueuePlugin{},
        &LavaSearchPlugin{},
    ),
)
```

--------------------------------

### Initialize DisGoLink Client

Source: https://github.com/disgoorg/disgolink/blob/v4/README.md

Create a new DisGoLink client instance with your user ID.

```go
import (
	"github.com/disgoorg/snowflake/v2"
	"github.com/disgoorg/disgolink/v4/disgolink"
)

var userID = snowflake.ID(1234567890)
lavalinkClient := disgolink.New(userID)
```

--------------------------------

### Server Information - GET /version

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/endpoints.md

Retrieves the version string of the Lavalink server.

```APIDOC
## GET /version

### Description
Gets the Lavalink server version string.

### Method
GET

### Endpoint
/v4/version

### Response
#### Success Response (200)
- Plain text version string (e.g., "4.0.0")

### Response Example
```
4.0.0
```
```

--------------------------------

### Players

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/rest-client.md

Gets all players on this node for the current session. Useful for monitoring active players.

```APIDOC
## Players

### Description
Gets all players on this node for the current session.

### Method
GET

### Endpoint
/v4/sessions/{sessionId}/players

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The session ID for the connection.

#### Query Parameters
This method does not have query parameters.

#### Request Body
This method does not have a request body.

### Response
#### Success Response (200)
- **players** ([]lavalink.Player) - Array of player objects

#### Response Example
```json
[
  {
    "guildId": "...",
    "sessionId": "...",
    "channelId": null,
    "volume": 100,
    "paused": false,
    "playing": true,
    "position": 0,
    "length": 0,
    "loop": false,
    " 24/7": false,
    "filters": {},
    "state": "playing"
  }
]
```
```

--------------------------------

### Version

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/rest-client.md

Gets the Lavalink server version string. This method requires a context for cancellation.

```APIDOC
## Version

### Description
Gets the Lavalink server version string.

### Method
GET

### Endpoint
/version

### Parameters
#### Query Parameters
- **ctx** (`context.Context`) - Required - Context for cancellation

### Response
#### Success Response (200)
- **version** (`string`) - The Lavalink server version string.

#### Response Example
```json
"4.0.10"
```
```

--------------------------------

### Initialize DisGoLink Client with Plugins

Source: https://github.com/disgoorg/disgolink/blob/v4/README.md

Registers custom plugins with the DisGoLink client during initialization. Replace 'yourPlugin' with your actual plugin instance.

```go
lavalinkClient := disgolink.New(userID, disgolink.WithPlugins(yourPlugin))
```

--------------------------------

### Player

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/rest-client.md

Gets a specific player by guild ID. Use this to retrieve the state of a player in a particular guild.

```APIDOC
## Player

### Description
Gets a specific player by guild ID.

### Method
GET

### Endpoint
/v4/sessions/{sessionId}/players/{guildId}

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The session ID for the connection.
- **guildId** (string) - Required - Guild ID of the player to retrieve

#### Query Parameters
This method does not have query parameters.

#### Request Body
This method does not have a request body.

### Response
#### Success Response (200)
- **player** (*lavalink.Player) - The requested player object

#### Response Example
```json
{
  "guildId": "...",
  "sessionId": "...",
  "channelId": null,
  "volume": 100,
  "paused": false,
  "playing": true,
  "position": 0,
  "length": 0,
  "loop": false,
  " 24/7": false,
  "filters": {},
  "state": "playing"
}
```
```

--------------------------------

### Add Initial Event Listeners

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/configuration.md

Use WithListeners to add initial event listeners during client creation. Listeners can be of various event types.

```go
listener1 := disgolink.NewListenerFunc[*disgolink.ReadyEvent](func(e *disgolink.ReadyEvent) {
    fmt.Println("Ready")
})
listener2 := disgolink.NewListenerFunc[*disgolink.PlayerTrackStartEvent](func(e *disgolink.PlayerTrackStartEvent) {
    fmt.Printf("Playing: %s\n", e.Track.Info.Title)
})

client := disgolink.New(userID,
    disgolink.WithListeners(listener1, listener2),
)
```

--------------------------------

### Events

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/INDEX.md

Defines the event system for receiving messages from the Lavalink server, including track start, end, and exceptions.

```APIDOC
## Events

### Description
Manages the event system for DisGoLink, allowing the client to receive and process various events emitted by the Lavalink server. This includes events related to player state, track progress, and connection status.

### Event Types
- **ReadyEvent**: Fired when the Lavalink server is ready.
- **StatsEvent**: Fired periodically with server statistics.
- **PlayerUpdateEvent**: Fired when a player's state is updated.
- **PlayerTrackStartEvent**: Fired when a new track begins playing.
- **PlayerTrackEndEvent**: Fired when a track finishes playing.
- **PlayerTrackExceptionEvent**: Fired when an error occurs during track playback.
- **PlayerTrackStuckEvent**: Fired when a track becomes stuck.
- **PlayerWebSocketClosedEvent**: Fired when the player's WebSocket connection is closed.
- **UnknownPlayerEvent**: Fired for unknown player-related events.
- **UnknownEvent**: Fired for any other unknown events.

### Interfaces
- **Event**: The base interface for all events.
- **EventListener**: An interface for objects that can listen to events.

### Constructor
- **NewListenerFunc(fn func(event Event))**: Creates an EventListener from a function.
```

--------------------------------

### Common Pattern: Basic Playback

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/MANIFEST.md

This snippet demonstrates the fundamental steps for loading and playing a track using DisGoLink. It covers searching for a track and initiating playback on a player.

```go
func playTrack(ctx context.Context, dl *disgolink.Disgolink, guildID string, query string) {
	// Find the best node available
	node := dl.BestNode()
	if node == nil {
		log.Println("No Lavalink nodes available.")
		return
	}

	// Load the track
	result, err := node.LoadTracks(ctx, query)
	if err != nil {
		log.Printf("Failed to load tracks: %v\n", err)
		return
	}

	if result.LoadType == lavalink.LoadTypeNoMatches {
		log.Println("No tracks found for the query.")
		return
	}

	var track lavalink.Track
	if result.LoadType == lavalink.LoadTypePlaylist {
		if len(result.Tracks) > 0 {
			track = result.Tracks[0]
		}
	} else {
		track = result.Track
	}

	if track.ID == "" {
		log.Println("No track data available.")
		return
	}

	// Play the track on the specified guild
	player, err := dl.Player(guildID)
	if err != nil {
		log.Printf("Failed to get player for guild %s: %v\n", guildID, err)
		return
	}

	if err = player.Play(track); err != nil {
		log.Printf("Failed to play track: %v\n", err)
	}
}

```

--------------------------------

### Create DisGoLink Client

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/INDEX.md

Create a DisGoLink client instance. Requires your Discord user ID and can accept optional configuration options.

```go
client := disgolink.New(userID, opts...)
```

--------------------------------

### Get All Players

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/rest-client.md

Retrieves all players currently managed by the Lavalink node for the current session. No parameters are needed other than the context.

```go
func (c *RestClient) Players(ctx context.Context) (players []lavalink.Player, err error)
```

--------------------------------

### Iterate Over Active Players

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/client.md

Use this to get an iterator for all currently active players. This can be useful for monitoring or batch operations.

```go
for player := range client.Players() {
    if player.Track != nil {
        fmt.Printf("Guild %d playing %s\n", player.GuildID, player.Track.Info.Title)
    }
}
```

--------------------------------

### Add PlayerTrackStuckEvent Listener

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/events.md

Listen for PlayerTrackStuckEvent when a track gets stuck and stops playing, logging the threshold duration.

```go
client.AddListeners(disgolink.NewListenerFunc[*disgolink.PlayerTrackStuckEvent](func(e *disgolink.PlayerTrackStuckEvent) {
    fmt.Printf("Track stuck for %s\n", e.Threshold.String())
}))
```

--------------------------------

### Load and Play a Track

Source: https://github.com/disgoorg/disgolink/blob/v4/README.md

Load a track using a search query and handle the result with a callback.

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

var toPlay *lavalink.Track
lavalinkClient.BestNode().LoadTracksHandler(context.TODO(), query, disgolink.NewResultHandler(
	func(track lavalink.Track) {
		// Loaded a single track
		toPlay = &track
	},
	func(playlist lavalink.Playlist) {
		// Loaded a playlist
	},
	func(tracks []lavalink.Track) {
		// Loaded a search result
	},
	func() {
		// nothing matching the query found
	},
	func(err error) {
		// something went wrong while loading the track
	},
))

```

--------------------------------

### Direct Usage with LoadTracks

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/load-result-handler.md

Demonstrates how to use `LoadTracks()` directly and manually handle the results using a switch statement.

```APIDOC
## Direct Usage with LoadTracks

### Description
This section shows how to use the `LoadTracks()` method directly to fetch results and then manually process them using a `switch` statement on the result type.

### Method
`node.Rest.LoadTracks(ctx context.Context, query string) (lavalink.LoadResult, error)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
result, err := node.Rest.LoadTracks(ctx, "ytsearch:song")
if err != nil {
    fmt.Printf("Network error: %v\n", err)
    return
}

handler := disgolink.NewTrackLoadingResultHandler(
    onTrack,
    onPlaylist,
    onSearch,
    onEmpty,
    onError,
)

switch data := result.Data.(type) {
case lavalink.Track:
    handler.OnTrack(data)
case lavalink.Playlist:
    handler.OnPlaylist(data)
case lavalink.Search:
    handler.OnSearch(data)
case lavalink.Empty:
    handler.OnEmpty()
case lavalink.Exception:
    handler.OnError(data)
}
```

### Response
The `LoadTracks` method returns a `lavalink.LoadResult` which contains the data and potentially an error.
```

--------------------------------

### Add PlayerUpdateEvent Listener

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/events.md

Listen for PlayerUpdateEvent to get periodic updates on the player's current position and state.

```go
client.AddListeners(disgolink.NewListenerFunc[*disgolink.PlayerUpdateEvent](func(e *disgolink.PlayerUpdateEvent) {
    fmt.Printf("Position: %dms\n", e.State.Position.Milliseconds())
}))
```

--------------------------------

### Listen for Player Events

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/INDEX.md

Register event listeners to receive notifications for all Lavalink state changes, such as track start or end.

```go
client.AddListeners(disgolink.NewListenerFunc[*disgolink.PlayerTrackStartEvent](handler))
```

--------------------------------

### Create New DisGoLink Client

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/client.md

Instantiates a new DisGoLink client. Requires the bot's user ID and accepts optional configuration options.

```go
import (
    "github.com/disgoorg/snowflake/v2"
    "github.com/disgoorg/disgolink/v4/disgolink"
)

userID := snowflake.ID(1234567890)
client := disgolink.New(userID)
```

--------------------------------

### Initialize DisGoLink Client with Event Listeners

Source: https://github.com/disgoorg/disgolink/blob/v4/README.md

Initializes the DisGoLink client with various event listeners for Lavalink events. Each listener function handles a specific event type.

```go
lavalinkClient := disgolink.New(userID,
    disgolink.WithListenerFunc(onReady),
    disgolink.WithListenerFunc(onStats),
    disgolink.WithListenerFunc(onPlayerUpdate),
	disgolink.WithListenerFunc(onTrackStart),
	disgolink.WithListenerFunc(onTrackEnd),
	disgolink.WithListenerFunc(onTrackException),
	disgolink.WithListenerFunc(onTrackStuck),
	disgolink.WithListenerFunc(onWebSocketClosed),
)

func onReady(event *disgolink.ReadyEvent) {
    // do something with the event
}

func onStats(event *disgolink.StatsEvent) {
    // do something with the event
}

func onPlayerUpdate(event *disgolink.PlayerUpdateEvent) {
    // do something with the event
}

func onTrackStart(event *disgolink.PlayerTrackStartEvent) {
    // do something with the event
}

func onTrackEnd(event *disgolink.PlayerTrackEndEvent) {
    // do something with the event
}

func onTrackException(event *disgolink.PlayerTrackExceptionEvent) {
    // do something with the event
}

func onTrackStuck(event *disgolink.PlayerTrackStuckEvent) {
    // do something with the event
}

func onWebSocketClosed(event *disgolink.PlayerWebSocketClosedEvent) {
    // do something with the event
}
```

--------------------------------

### Load Tracks with Handler Callback

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/INDEX.md

Search and load audio tracks from a query. Uses handler callbacks to process the loading results.

```go
node.Rest.LoadTracksHandler(ctx, query, handler)
```

--------------------------------

### Get All Players for a Session

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/endpoints.md

Retrieves a list of all players associated with a given session ID. Useful for monitoring active players.

```go
players, err := node.Rest.Players(ctx)
if err != nil {
    log.Fatal(err)
}

for _, player := range players {
    fmt.Printf("Guild %d: %v\n", player.GuildID, player.Track)
}
```

--------------------------------

### AddPlugins Method

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/plugins.md

Adds one or more plugins to the Disgolink client. This can be done during client initialization or at runtime.

```go
func (c *Client) AddPlugins(plugins ...Plugin)
```

--------------------------------

### Get Lavalink Server Version

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/endpoints.md

Fetches the specific version string of the Lavalink server. Useful for compatibility checks or logging.

```go
version, err := node.Rest.Version(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Println(version)
```

--------------------------------

### Get Specific Player

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/rest-client.md

Retrieves a specific player by its associated guild ID. Requires the guild ID to identify the player.

```go
func (c *RestClient) Player(ctx context.Context, guildID snowflake.ID) (player *lavalink.Player, err error)
```

--------------------------------

### WithPlugins Configuration Option

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/api-reference/plugins.md

A configuration option used to add plugins when creating a new Disgolink client instance.

```go
func WithPlugins(plugins ...Plugin) ConfigOpt
```

--------------------------------

### Import DisGoLink and Lavalink Packages

Source: https://github.com/disgoorg/disgolink/blob/v4/_autodocs/INDEX.md

Import the necessary DisGoLink and Lavalink packages for using the library's client and data types.

```go
import (
    "github.com/disgoorg/disgolink/v4/disgolink"
    "github.com/disgoorg/disgolink/v4/lavalink"
)
```