# lavalink-rs
An API Wrapper for `lavalink`. Compatible with all `tokio 1.x` based discord crates or `asyncio` based discord python libraries.
If you have questions, you can get support in the [serenity](https://discord.gg/serenity-rs), [lavalink](https://discord.gg/2rpnXNfRRU) or [hikari](https://discord.gg/hikari)
discord servers, or by opening an issue in the [gitlab repository](https://gitlab.com/vicky5124/lavalink-rs).
Documentation for the library can be found [here for rust](https://docs.rs/lavalink-rs) or [here for python](https://vicky5124.github.io/lavalink-rs/lavalink_rs.html).
## To-Do
### 0.15
- [ ] Implement `__anext__` to QueueRef
- [ ] RoutePlanner API
### Future
- [ ] Improve documentation with examples, better formatting, and fill in missing data
- [ ] Expand event logging
- [ ] discord.py example
- [ ] hata example
- [ ] twilight-rs example
- [ ] Gitlab CI Tests
- [ ] Implement abstractions for ease of use
- [ ] Region based node selection method
### Done
- [x] `native_tls` backend
- [x] Player queues
- [x] Readbale player queues
- [x] Search engine helpers
- [x] Write basic cocumentation
- [x] Songbird utilities
- [x] Serenity utilities
- [x] Twilight utilities
- [x] Load balancer node selection method
- [x] Lavasnek (PyO3)
- [x] Lavasnek events
- [x] Remove third party dependency for custom user data.
- [x] Round-Robin node selection method
- [x] Main and fallback node selection method
- [x] CPU Load based node selection method
- [x] Memory usage based node selection method
- [x] Custom node selection method
- [x] Python stubs
- [x] Basic Twilight 0.16 support
- [x] Hide password from logs
- [x] hikari-lightbulb example
- [x] Implement python builders for all the needed model structures
- [x] Expose Http and methods to python
- [x] Switch from reqwests to `hyper`
- [x] Implement SSL support with `hyper`
- [x] Implement search utilities to python
- [x] load_tracks to return Track in python
- [x] Streamable queue reader
- [x] Support `tokio-websockets`
- [x] native and webpki roots for rustls feature separation
- [x] Update PyO3 to 0.23
## Links to download stuff you will need
To install Lavalink, you can follow their [getting started guide](https://lavalink.dev/getting-started/index.html).
## How to use
This is how you can install the library to be used.
### Rust
You can install the latest version from crates.io:
```toml
lavalink-rs = "0.14"
# or
[dependencies.lavalink-rs]
version = "0.14"
```
Or the development release:
```toml
lavalink-rs = { git = "https://gitlab.com/vicky5124/lavalink-rs/", branch = "main"}
# or
[dependencies.lavalink-rs]
git = "https://gitlab.com/vicky5124/lavalink-rs/"
branch = "main"
```
If you wish to use a development version of songbird (or serenity, or twilight-model), add the following to the Cargo.toml:
```toml
[patch.crates-io.songbird]
git = "https://github.com/serenity-rs/songbird"
branch = "next"
[dependencies.songbird]
git = "https://github.com/serenity-rs/songbird"
branch = "next"
```
### Python
You can install the latest version from [pypi](https://pypi.org/project/lavalink_rs/) by using `python3 -m pip install lavalink_rs`.
Windows | x86 | 3.8-3.13 | ✅
Windows | x64 | 3.8-3.13 | ✅
Windows | aarch64 | - | ❌
Mac OS | x86_64 | 3.8-3.13 | ✅
Mac OS | aarch64 | 3.8-3.13 | ✅
Linux | x86 | 3.8-3.13 | ✅
Linux | x86_64 | 3.8-3.13 | ✅
Linux | armv7 | 3.8-3.13 | ✅
Linux | aarch64 | 3.8-3.13 | ✅
Linux | ppc64le | - | ❌
Linux | s390x | - | ❌
## Building the library
You can build the library using `cargo build`
To build for python, you can use maturin instead.
```
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install maturin
maturin develop --target x86_64-unknown-linux-gnu
```
## Features
- `macros`: **default feature** - Adds procedural macros for ease of use.
- `python` for python3.8+ support.
**Use tokio-tungstenite as the websocket client (for Serenity):**
- `tungstenite-rustls-native-roots`: **default feature** - Use rustls with the system trusted roots.
- `tungstenite-rustls-webpki-roots`: Use rustls with the Mozilla set of trusted roots.
- `tungstenite-native-tls` Use the system native tls implementation.
**Use tokio-websockets as the websocket client (for Twilight):**
- `websockets-rustls-native-roots`: Use rustls with the system trusted roots.
- `websockets-rustls-webpki-roots`: Use rustls with the Mozilla set of trusted roots.
- `websockets-native-tls` Use the system native tls implementation.
**Discord library utilities:**
- `serenity` for [serenity](https://lib.rs/crates/serenity) support.
- `songbird` for [songbird](https://lib.rs/crates/songbird) support.
- `twilight` for [twilight-model](https://lib.rs/crates/twilight-model) v0.15 support.
## Contributing
To contribute to the project, fork the [gitlab repository](https://gitlab.com/vicky5124/lavalink-rs) and create a merge request over there. Make sure to update the changelog with whatever update you did to the library.
