Skip to content

Commit

Permalink
Merge pull request #117 from angelobreuer/feature/angelobreuer/lavali…
Browse files Browse the repository at this point in the history
…nk-v4

Lavalink v4 support
  • Loading branch information
angelobreuer authored Aug 21, 2023
2 parents 7bacfb0 + 071a0f1 commit 677f477
Show file tree
Hide file tree
Showing 701 changed files with 41,665 additions and 16,199 deletions.
15 changes: 8 additions & 7 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -26,20 +26,15 @@ jobs:
with:
dotnet-version: 7.0.x

- name: Download Lavalink Server
working-directory: ./ci
run: wget https://github.com/freyacodes/Lavalink/releases/download/3.7.3/Lavalink.jar
shell: bash

- name: Restore dependencies
run: dotnet restore src/Lavalink4NET.sln

- name: Build
run: dotnet build src/Lavalink4NET.sln --no-restore --configuration ${{ matrix.configuration }}
run: dotnet build src/Lavalink4NET.sln --no-restore --configuration ${{ matrix.configuration }} /property:Version=4.0.0-beta.1

- name: Run tests
working-directory: ci
run: java -jar ./Lavalink.jar & dotnet test ../src/Lavalink4NET.sln --no-build --configuration ${{ matrix.configuration }} --verbosity normal --collect:"XPlat Code Coverage" --results-directory ../coverage
run: dotnet test ../src/Lavalink4NET.sln --no-build --configuration ${{ matrix.configuration }} --verbosity normal --collect:"XPlat Code Coverage" --results-directory ../coverage
shell: bash

- name: Download artifact
Expand Down Expand Up @@ -79,3 +74,9 @@ jobs:
with:
recreate: true
path: coverage/DeltaSummary.md

- name: Publish NuGet artifacts
uses: actions/upload-artifact@v3
with:
name: NuGet Packages-${{ matrix.configuration }}
path: '**/*.nupkg'
39 changes: 39 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
name: Documentation

on:
push:
branches: [ "dev" ]
pull_request:
branches: [ "dev" ]

jobs:
build:
runs-on: ubuntu-latest

strategy:
matrix:
node-version: [16.x]

steps:
- uses: actions/checkout@v3

- name: Use Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'
cache-dependency-path: docs/package-lock.json

- run: npm ci
working-directory: docs
name: Restore dependencies

- run: npm run build
working-directory: docs
name: Build documentation

- name: Archive documentation
uses: actions/upload-artifact@v3
with:
name: Documentation
path: docs/build/
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
MIT License

Copyright (c) 2019-2021 Angelo Breuer
Copyright (c) 2019-2023 Angelo Breuer

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
178 changes: 87 additions & 91 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,124 +4,120 @@
</a>

<!-- Center badges -->
<p align="center">

<!-- CodeFactor.io Badge -->
<a href="https://www.codefactor.io/repository/github/angelobreuer/lavalink4net">
<img alt="CodeFactor.io" src="https://www.codefactor.io/repository/github/angelobreuer/lavalink4net/badge?style=for-the-badge" />
</a>
<p align="center"><b>High performance Lavalink wrapper for .NET</b></p>

<!-- Releases Badge -->
<a href="https://github.com/angelobreuer/Lavalink4NET/releases">
<img alt="GitHub tag (latest SemVer)" src="https://img.shields.io/github/tag/angelobreuer/Lavalink4NET.svg?label=RELEASE&style=for-the-badge">
</a>
[Lavalink4NET](https://github.com/angelobreuer/Lavalink4NET) is a [Lavalink](https://github.com/freyacodes/Lavalink) wrapper with node clustering, caching and custom players for .NET with support for [Discord.Net](https://github.com/RogueException/Discord.Net) and [DSharpPlus](https://github.com/DSharpPlus/DSharpPlus/).

<!-- GitHub issues Badge -->
<a href="https://github.com/angelobreuer/Lavalink4NET/issues">
<img alt="GitHub issues" src="https://img.shields.io/github/issues/angelobreuer/Lavalink4NET.svg?style=for-the-badge">
</a>
### Features
- ⚖️ **Node Clustering / Load Balancing**<br>Distribute load across nodes for efficient and reliable audio playback (for large scale bots).

<a href="https://dev.azure.com/angelo-breuer/Lavalink4NET/_build?definitionId=7">
<img alt="Azure DevOps builds (branch)" src="https://img.shields.io/azure-devops/build/angelo-breuer/59efcb96-30b1-4853-8b73-4906861ebe5f/7/master?label=Build&style=for-the-badge">
</a>
- ✳️ **Extensible**<br>Customize and enhance features using plugins to match your bot's needs.

</p>
- 🎤 **Lyrics**<br>Display song lyrics alongside audio playback to enrich the user experience.

[Lavalink4NET](https://github.com/angelobreuer/Lavalink4NET) is a [Lavalink](https://github.com/freyacodes/Lavalink) wrapper with node clustering, caching and custom players for .NET with support for [Discord.Net](https://github.com/RogueException/Discord.Net) and [DSharpPlus](https://github.com/DSharpPlus/DSharpPlus/).
- 🗳️ **Queueing / Voting-System**<br>Let users queue tracks and vote on the next songs, enhancing collaborative playlists.

### Features
- 🔌 **Asynchronous Interface**
- ⚖️ **Node Clustering / Load Balancing**
- ✳️ **Extensible**
- 🎤 **Lyrics**
- 🗳️ **Queueing / Voting-System**
- 🎵 **Track Decoding and Encoding**
- 🔄 **Auto-Reconnect and Resuming**
- 📝 **Logging** *(optional)*
-**Request Caching** *(optional)*
- ⏱️ **Inactivity Tracking** *(optional)*
- 🖋️ **Supports Lavalink plugins**
- 🎶 **Custom players**
- 🖼️ **Artwork resolution**
- 🎚️ **Audio filter support**
- 📊 **Statistics tracking support**
-**Compatible with [DSharpPlus](https://github.com/DSharpPlus/DSharpPlus) and [Discord.Net](https://github.com/discord-net/Discord.Net).**

<span>&nbsp;&nbsp;&nbsp;</span>*and a lot more...*
- 🎵 **Track Decoding and Encoding**<br>Lavalink4NET supports high efficient track decoding and encoding of lavaplayer track identifiers.

- 🔄 **Auto-Reconnect and Resuming**<br>Maintain uninterrupted audio playback during connection disruptions.

- 🔌 **Fully Asynchronous Interface**<br>Effortlessly communicate with the Lavalink audio server without causing delays in your bot. All actions that can be offloaded are asynchronous and can be canceled at any time if needed.

- 📝 **Logging** *(optional)*<br>Enable insights for troubleshooting and debugging.

-**Request Caching** *(optional)*<br>Improve performance by reducing redundant requests.

- ⏱️ **Inactivity Tracking** *(optional)*<br>Monitor inactive players and disconnect them to save resources.

- 🖋️ **Supports Lavalink plugins**<br>Expand capabilities by integrating with Lavalink plugins.

- 🎶 **Custom players**<br>Manage audio playback instances tailored to your bot's requirements.

- 🖼️ **Artwork resolution**<br>Lavalink4NET allows the user to resolve artwork images for the tracks to display an appealing image to the user.

- 🎚️ **Audio filter support**<br>Lavalink4NET supports all audio filters provided by lavaplayer and even more when installing the ExtraFilters plugin.

- 📊 **Statistics tracking support**<br>Lavalink4NET supports tracking and evaluation of node statistics. In clustering, node statistics can be used to evaluate the best node for efficient resource usage.

-**Compatible with [DSharpPlus](https://github.com/DSharpPlus/DSharpPlus) and [Discord.Net](https://github.com/discord-net/Discord.Net).**<br>Lavalink4NET has an adaptive client API, meaning it can support any discord client. Currently, DSharpPlus and Discord.Net are supported out-of-the-box.

[![Lavalink4NET Support Server Banner](https://discordapp.com/api/guilds/894533462428635146/embed.png?style=banner3)](https://discord.gg/cD4qTmnqRg)

### NuGet
- Download [Lavalink4NET Core ![NuGet - Lavalink4NET Core](https://img.shields.io/nuget/vpre/Lavalink4NET.svg?style=flat-square)](https://www.nuget.org/packages/Lavalink4NET/)
- Download [Lavalink4NET for Discord.Net ![NuGet - Lavalink4NET Discord.Net](https://img.shields.io/nuget/vpre/Lavalink4NET.Discord.Net.svg?style=flat-square)](https://www.nuget.org/packages/Lavalink4NET.Discord.NET/)
- Download [Lavalink4NET for DSharpPlus ![NuGet - Lavalink4NET DSharpPlus](https://img.shields.io/nuget/vpre/Lavalink4NET.DSharpPlus.svg?style=flat-square)](https://www.nuget.org/packages/Lavalink4NET.DSharpPlus/)
- Download [Lavalink4NET MemoryCache ![NuGet - Lavalink4NET MemoryCache](https://img.shields.io/nuget/vpre/Lavalink4NET.MemoryCache.svg?style=flat-square)](https://www.nuget.org/packages/Lavalink4NET.MemoryCache/)
- Download [Lavalink4NET Microsoft.Extensions.Logging Provider ![NuGet - Lavalink4NET Microsoft.Extensions.Logging Provider](https://img.shields.io/nuget/vpre/Lavalink4NET.Logging.Microsoft.svg?style=flat-square)](https://www.nuget.org/packages/Lavalink4NET.Logging.Microsoft/)
- Download [Lavalink4NET NLog Provider ![NuGet - Lavalink4NET NLog Provider](https://img.shields.io/nuget/vpre/Lavalink4NET.Logging.NLog.svg?style=flat-square)](https://www.nuget.org/packages/Lavalink4NET.Logging.NLog/)
- Download [Lavalink4NET SponsorBlock Integration ![NuGet - Lavalink4NET SponsorBlock Integration](https://img.shields.io/nuget/vpre/Lavalink4NET.Integrations.SponsorBlock.svg?style=flat-square)](https://www.nuget.org/packages/Lavalink4NET.Integrations.SponsorBlock/)
### Documentation

### Prerequisites
- One or more Lavalink Nodes
- .NET Core >= 2.0
You can find the documentation for Lavalink4NET v4 [here](https://lavalink4net.angelobreuer.de/docs/introduction/intro).

### Getting Started
### Components

You can use Lavalink4NET in 3 different modes: **Cluster**, **Node** and **Rest**.
- [**Cluster**](https://github.com/angelobreuer/Lavalink4NET/wiki/Cluster) is useful for combining a bunch of nodes to one to load balance.
- [**Node**](https://github.com/angelobreuer/Lavalink4NET/wiki/Node) is useful when you have a small discord bot with one Lavalink Node.
- [**Rest**](https://github.com/angelobreuer/Lavalink4NET/wiki/Tracks) is useful when you only want to resolve tracks.
Lavalink4NET offers high flexibility and extensibility by providing an isolated interface. You can extend Lavalink4NET by adding additional packages which add integrations with other services, support for additional lavalink/lavaplayer plugins, or additional client support.

#### _Client Support_

##### Using the constructor
- [**Lavalink4NET.Discord.Net**](https://www.nuget.org/packages/Lavalink4NET.Discord.Net/)&nbsp;&nbsp;&nbsp;![NuGet](https://img.shields.io/nuget/vpre/Lavalink4NET.Discord.Net.svg?style=flat-square)<br>Enhance your Discord bots with advanced audio playback using this integration for Lavalink4NET. Designed for end users building Discord.Net-based applications.

Here is an example, how you can create the AudioService for a single node:
```csharp
var audioService = new LavalinkNode(new LavalinkNodeOptions
{
RestUri = "http://localhost:8080/",
WebSocketUri = "ws://localhost:8080/",
Password = "youshallnotpass"
}, new DiscordClientWrapper(client));
```
- [**Lavalink4NET.DSharpPlus**](https://www.nuget.org/packages/Lavalink4NET.DSharpPlus/)&nbsp;&nbsp;&nbsp;![NuGet](https://img.shields.io/nuget/vpre/Lavalink4NET.DSharpPlus.svg?style=flat-square)<br>Add powerful audio playback to your DSharpPlus-based applications with this integration for Lavalink4NET. Suitable for end users developing with DSharpPlus.

##### Usage with Dependency Injection / IoC *(recommended)*
#### _Clustering_

```csharp
var serviceProvider = new ServiceCollection()
.AddSingleton<IAudioService, LavalinkNode>()
.AddSingleton<IDiscordClientWrapper, DiscordClientWrapper>();
.AddSingleton(new LavalinkNodeOptions {[...]})
[...]
.BuildServiceProvider();

var audioService = serviceProvider.GetRequiredService<IAudioService>();
- [**Lavalink4NET.Cluster**](https://www.nuget.org/packages/Lavalink4NET.Cluster/)&nbsp;&nbsp;&nbsp;![NuGet](https://img.shields.io/nuget/vpre/Lavalink4NET.Cluster.svg?style=flat-square)<br>Scale and improve performance by using multiple Lavalink nodes with this cluster support module. Ideal for handling high-demand music streaming applications.

// Do not forget disposing the service provider!
```
Lookup the LavalinkNodeOptions in the **`application.yml`** of your Lavalink Node(s).
#### _Integrations_

- [**Lavalink4NET.Integrations.ExtraFilters**](https://www.nuget.org/packages/Lavalink4NET.Integrations.ExtraFilters/)&nbsp;&nbsp;&nbsp;![NuGet](https://img.shields.io/nuget/vpre/Lavalink4NET.Integrations.ExtraFilters.svg?style=flat-square)<br>Enhance your audio playback experience with extra filters in Lavalink4NET. Apply additional audio effects and modifications to customize the sound output. Requires the installation of the corresponding plugin on the Lavalink node.

- [**Lavalink4NET.Integrations.SponsorBlock**](https://www.nuget.org/packages/Lavalink4NET.Integrations.SponsorBlock/)&nbsp;&nbsp;&nbsp;![NuGet](https://img.shields.io/nuget/vpre/Lavalink4NET.Integrations.SponsorBlock.svg?style=flat-square)<br>Integrate SponsorBlock functionality into Lavalink4NET. Automatically skip sponsored segments in videos for a seamless and uninterrupted playback experience. Requires the installation of the corresponding plugin on the Lavalink node.

- [**Lavalink4NET.Integrations.TextToSpeech**](https://www.nuget.org/packages/Lavalink4NET.Integrations.TextToSpeech/)&nbsp;&nbsp;&nbsp;![NuGet](https://img.shields.io/nuget/vpre/Lavalink4NET.Integrations.TextToSpeech.svg?style=flat-square)<br>Enable text-to-speech functionality in Lavalink4NET. Convert written text into spoken words, allowing your application to generate and play audio from text inputs. Requires the installation of the corresponding plugin on the Lavalink node.

#### _Services_

- [**Lavalink4NET.Lyrics**](https://www.nuget.org/packages/Lavalink4NET.Lyrics/)&nbsp;&nbsp;&nbsp;![NuGet](https://img.shields.io/nuget/vpre/Lavalink4NET.Lyrics.svg?style=flat-square)<br>Fetch and display song lyrics from lyrics.ovh with this lyrics service integrated with Lavalink4NET. Enhance the music experience for your users.

- [**Lavalink4NET.Artwork**](https://www.nuget.org/packages/Lavalink4NET.Artwork/)&nbsp;&nbsp;&nbsp;![NuGet](https://img.shields.io/nuget/vpre/Lavalink4NET.Artwork.svg?style=flat-square)<br>Artwork resolution service for the Lavalink4NET client library.

- [**Lavalink4NET.InactivityTracking**](https://www.nuget.org/packages/Lavalink4NET.InactivityTracking/)&nbsp;&nbsp;&nbsp;![NuGet](https://img.shields.io/nuget/vpre/Lavalink4NET.InactivityTracking.svg?style=flat-square)<br>Optimize resource usage by tracking and disconnecting inactive players. Ensure efficient audio playback in your application.

#### _Core Components_

##### Initializing the node
- [**Lavalink4NET**](https://www.nuget.org/packages/Lavalink4NET/)&nbsp;&nbsp;&nbsp;![NuGet](https://img.shields.io/nuget/vpre/Lavalink4NET.svg?style=flat-square)<br>This core library is used to implement client wrappers. It is not intended for end users. Please use Lavalink4NET.Discord.Net or Lavalink4NET.DSharpPlus instead.

**Before** using the service you have to initialize it, this can be done
using the Ready event of your discord client implementation:
- [**Lavalink4NET.Abstractions**](https://www.nuget.org/packages/Lavalink4NET.Abstractions/)&nbsp;&nbsp;&nbsp;![NuGet](https://img.shields.io/nuget/vpre/Lavalink4NET.Abstractions.svg?style=flat-square)<br>General abstractions and common primitives for the Lavalink4NET client library.

- [**Lavalink4NET.Protocol**](https://www.nuget.org/packages/Lavalink4NET.Protocol/)&nbsp;&nbsp;&nbsp;![NuGet](https://img.shields.io/nuget/vpre/Lavalink4NET.Protocol.svg?style=flat-square)<br>Protocol implementation for the Lavalink4NET client library used to interact with the Lavalink REST API.

- [**Lavalink4NET.Rest**](https://www.nuget.org/packages/Lavalink4NET.Rest/)&nbsp;&nbsp;&nbsp;![NuGet](https://img.shields.io/nuget/vpre/Lavalink4NET.Rest.svg?style=flat-square)<br>Easily interact with the Lavalink REST API using this REST API client primitives library. Build custom functionalities or integrate Lavalink4NET with other services.

### Prerequisites
- At least one lavalink node
- At least .NET 6

### Getting Started

Lavalink4NET works by using dependency injection to make management of services very easy. You just have to add `services.AddLavalink();` to your startup code:

```csharp
client.Ready += () => audioService.InitializeAsync();
using var serviceProvider = new ServiceCollection()
.AddLavalink() // Contained in the client support packages
[...]
.BuildServiceProvider();

var audioService = serviceProvider.GetRequiredService<IAudioService>();

// [...]
```

##### Joining a voice channel and playing a track
> (ℹ️) Since Lavalink4NET v4, boilerplate code has been drastically reduced. It is also no longer required to initialize the node.
```csharp
// get player
var player = _audioService.GetPlayer<LavalinkPlayer>(guildId)
?? await _audioService.JoinAsync<LavalinkPlayer>(guildId, voiceChannelId);

// resolve a track from youtube
var myTrack = await _audioService.GetTrackAsync("<search query>", SearchMode.YouTube);
// Play a track
var playerOptions = new LavalinkPlayerOptions
{
InitialTrack = new TrackReference("https://www.youtube.com/watch?v=dQw4w9WgXcQ"),
};

// play track
await player.PlayAsync(myTrack);
await audioService.Players
.JoinAsync(<guild id>, <voice channel id>, playerOptions, stoppingToken)
.ConfigureAwait(false);
```

For **more documentation, see: [Lavalink4NET Wiki](https://github.com/angelobreuer/Lavalink4NET/wiki)** or you could also **take a look at [Upcoming Features](https://github.com/angelobreuer/Lavalink4NET/projects?query=is%3Aopen)**.
You can take a look at the [example bots](https://github.com/angelobreuer/Lavalink4NET/tree/dev/samples).
20 changes: 20 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
# Dependencies
/node_modules

# Production
/build

# Generated files
.docusaurus
.cache-loader

# Misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*
3 changes: 3 additions & 0 deletions docs/babel.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
module.exports = {
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};
17 changes: 17 additions & 0 deletions docs/docs/caching.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
# Caching

Lavalink4NET supports caching of track queries, track searches and lyrics resolution. Caching improves performance and reduces the amount of requests to the Lavalink server/lyrics API.

Lavalink4NET utilizes the [Microsoft.Extensions.Caching](https://www.nuget.org/packages/Microsoft.Extensions.Caching.Abstractions/) package to provide a caching abstraction. This allows you to use any caching provider you want. You can use the default in-memory cache of `Microsoft.Extensions.Caching` or build your own caching provider.

## Usage

To enable caching, you just need to register the caching service in the dependency injection container. You can do this by calling the `AddMemoryCache` extension method on the `IServiceCollection` instance.

```csharp
builder.Services.AddMemoryCache();
```

:::note
You need to add the `Microsoft.Extensions.Caching.Memory` package to your project to use the in-memory cache.
:::
7 changes: 7 additions & 0 deletions docs/docs/cluster/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"label": "Cluster",
"position": 8,
"link": {
"type": "generated-index"
}
}
5 changes: 5 additions & 0 deletions docs/docs/cluster/best-practices.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
sidebar_position: 2
---

# Best practices
5 changes: 5 additions & 0 deletions docs/docs/cluster/failover.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
sidebar_position: 5
---

# Automatic failover
5 changes: 5 additions & 0 deletions docs/docs/cluster/introduction.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
sidebar_position: 1
---

# Introduction
5 changes: 5 additions & 0 deletions docs/docs/cluster/load-balancing.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
sidebar_position: 4
---

# Load balancing
5 changes: 5 additions & 0 deletions docs/docs/cluster/track-affinity.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
sidebar_position: 3
---

# Track affinity
7 changes: 7 additions & 0 deletions docs/docs/controlling-player/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"label": "Player controls",
"position": 2,
"link": {
"type": "generated-index"
}
}
Loading

0 comments on commit 677f477

Please sign in to comment.