Quick-start

Connecting to an Andesite node

Let’s imagine the most basic use case first: You have one Andesite server which you would like to connect to. For this case there’s the Client which does this for you. In reality the andesite client is a combination of both the web socket client and the http client, but it aims to hide this complexity.

Unless you’re using the discord.py library, you have to manually pass voice server updates to Andesite using Client.voice_server_update. If you are using discord.py, please refer to Using the discord.py integration

import andesite

# We use the create function because it creates
# the underlying clients for us.
client = andesite.create_client(
    "http://localhost:5000",                # url for the http endpoints
    "ws://localhost:5000/websocket",        # url for the web socket endpoints
    None,                                   # andesite password. None means there's no password
    549905730099216384,                     # your bot's user id
)

# connect the client
await client.connect(max_attempts=3)

Using pools

To create a pool you can just use the HTTPPool and WebSocketPool classes which both take an iterable of their respective clients. However, if you want to create a combined Andesite client with the default implementation you can use the create_pool function.

The great thing is that you can use the pools just like any other client. The http client pool uses a round-robin to delegate each request to a separate client and the WebSocket pool assigns the best client for each guild and migrates the state to another client if a node goes down.

import andesite

http_nodes = [
    ("http://localhost:5000", None),
    ("http://example.com:5000", "password"),
]

web_socket_nodes = [
    ("ws://localhost:5000/websocket", None),
    ("ws://example.com:5000/websocket", "password"),
    ("ws://example2.com:5000/websocket", None),
]

client = andesite.create_pool(http_nodes, web_socket_nodes,
    user_id=549905730099216384,
)

Using the discord.py integration

If you’re using discord.py there are a number of utilities in place which you ought to use. Instead of having to manually intercept voice server updates you can use add_voice_server_update_handler which adds a listener to automatically pass these events on. There’s also the analogue function remove_voice_server_update_handler to remove it again.

There’s also connect_voice_channel and disconnect_voice_channel which help you connect to a voice channel and also disconnect.

import discord
from discord.ext.commands import Bot, Context

from andesite.discord import add_voice_server_update_handler, connect_voice_channel, disconnect_voice_channel

bot = Bot()

client = ... # create our Andesite client somehow

# that's all we need. Now all voice server updates are automatically
# forwarded to Andesite. This also works with normal client discord
# clients, not just commands.Bot
add_voice_server_update_handler(bot, client)

@bot.command()
async def connect(ctx: Context, channel: discord.VoiceChannel = None) -> None:
    if channel:
        await connect_voice_channel(ctx.bot, channel)
    else:
        await disconnect_voice_channel(ctx.bot, ctx.guild)

bot.run("token")