O que é Lavalink e como hospedar um bot de música

Tocar música num bot do Discord dá mais trabalho do que parece. É preciso buscar a faixa, decodificar o áudio, codificar em Opus e mandar os pacotes por uma conexão de voz sem engasgar. Fazer isso dentro do próprio bot consome CPU e memória, e qualquer travada afeta também os comandos comuns.

O Lavalink resolve isso tirando o áudio do bot. Ele é um programa à parte que faz o trabalho pesado, enquanto o bot cuida só de comandos e eventos.

O que é o Lavalink?#

Lavalink é um nó de envio de áudio independente (standalone), baseado na biblioteca Lavaplayer e no projeto Koe. É software livre, mantido em github.com/lavalink-devs/Lavalink. Ele roda como servidor próprio, expõe uma API REST e um WebSocket, e envia o áudio direto ao Discord sem que ele passe pelos shards do seu bot.

Não é um bot e não tem comandos de usuário. É uma peça de infraestrutura que o seu bot controla.

Como o Lavalink funciona por dentro?#

Três peças conversam entre si:

1. O bot recebe /play de um usuário.
2. Uma biblioteca cliente dentro do bot repassa o pedido ao servidor Lavalink e informa os dados da conexão de voz do Discord.
3. O servidor Lavalink carrega a faixa, aplica filtros, codifica o áudio e o envia ao canal de voz.

Bot e servidor trocam mensagens por HTTP (REST) e por WebSocket. O bot manda "toque esta faixa", "pause", "mude o volume" e recebe eventos como "a faixa terminou". O áudio nunca volta para o bot.

Para autenticar, o cliente envia a senha configurada no cabeçalho Authorization. Para conferir se o servidor está de pé, GET /version devolve a versão em texto puro.

Para que serve e quando vale a pena?#

O Lavalink faz sentido quando:

• o bot toca música ou áudio de fontes externas;
• o bot está em muitos servidores e o áudio pesa no processo principal;
• você quer reiniciar ou atualizar o bot sem mexer no serviço de áudio;
• vários bots ou instâncias podem compartilhar poucos nós de áudio.

Ele traz filtros prontos (equalizador, karaokê, timescale, tremolo, vibrato, rotação, entre outros) e fontes como SoundCloud, Bandcamp, Twitch, Vimeo e links HTTP.

Não vale a pena para um bot que só toca um arquivo curto de vez em quando, ou que não usa voz. Também não resolve direitos autorais: ele toca o que a fonte entrega, e respeitar os termos de cada plataforma continua sendo responsabilidade de quem opera o bot.

O que preciso para rodar um servidor Lavalink?#

• Uma versão LTS do Java. Confira o mínimo na documentação, que recomenda a LTS mais recente.
• Um arquivo application.yml no diretório de execução.
• Uma senha e uma porta (o exemplo oficial usa 2333).
• Uma biblioteca cliente compatível com Lavalink v4 no seu bot.

Um application.yml mínimo:

server:
  port: 2333
  address: 0.0.0.0
lavalink:
  server:
    password: "troque-esta-senha"
    sources:
      youtube: false
      soundcloud: true
  plugins:
    - dependency: "dev.lavalink.youtube:youtube-plugin:VERSION"
      snapshot: false

Troque VERSION pela versão atual mostrada na aba Releases do youtube-source. O exemplo oficial traz a senha youshallnotpass: nunca a mantenha em produção.

Para rodar, a documentação indica o binário (java -jar Lavalink.jar), o systemd no Linux ou Docker. Em Docker, a imagem oficial é ghcr.io/lavalink-devs/lavalink:4, com o arquivo montado em /opt/Lavalink/application.yml.

Como o bot se conecta ao Lavalink?#

Cada linguagem tem clientes mantidos pela comunidade, listados em lavalink.dev/clients: Shoukaku, Riffy e Moonlink.js para JavaScript; Wavelink e Mafic para Python; Lavalink-Client para JVM. O Wavelink 3, por exemplo, trabalha com o Lavalink v4; confira no PyPI a versão mínima do Python. Um esqueleto com discord.py e Wavelink 3 (pip install -U wavelink):

import os
import discord
import wavelink
from discord.ext import commands

class Bot(commands.Bot):
    async def setup_hook(self):
        node = wavelink.Node(
            uri=os.environ["LAVALINK_URI"],  # ex.: http://localhost:2333
            password=os.environ["LAVALINK_PASSWORD"],
        )
        await wavelink.Pool.connect(nodes=[node], client=self)

intents = discord.Intents.default()
intents.message_content = True
bot = Bot(command_prefix="!", intents=intents)

@bot.command()
async def play(ctx, *, busca: str):
    if not ctx.author.voice:
        return await ctx.send("Entre em um canal de voz primeiro.")
    player = ctx.voice_client or await ctx.author.voice.channel.connect(cls=wavelink.Player)
    faixas = await wavelink.Playable.search(busca)
    if faixas:
        await player.play(faixas[0])

bot.run(os.environ["DISCORD_TOKEN"])

Guarde URI, senha e token em variáveis de ambiente, nunca no código. Se você ainda não tem um bot, comece por como criar um bot do Discord.

Por que o YouTube não toca no Lavalink?#

O suporte a YouTube que vinha embutido no servidor foi marcado como obsoleto e fica desativado no application.yml de exemplo. O caminho indicado é o plugin youtube-source, que exige desligar a fonte embutida (youtube: false) e declarar o plugin, como no exemplo acima.

Por ser um plugin, ele evolui separado do servidor e pode precisar de atualização quando o YouTube muda algo. Se a música parou do nada, confira primeiro os logs e a versão do plugin, e veja por que o bot de música parou de tocar YouTube.

Que cuidados a hospedagem exige?#

O Lavalink é um processo Java que precisa ficar ligado o tempo todo: se ele cair, todas as músicas param. Planeje quatro pontos:

• Disponibilidade contínua. O mesmo raciocínio de manter um bot do Discord online 24/7 vale para o nó de áudio.
• Memória. A JVM aceita um teto de heap por JAVA_TOOL_OPTIONS=-Xmx.... Meça o consumo real com algumas músicas tocando ao mesmo tempo antes de fixar o valor, e veja quanta RAM um bot do Discord precisa.
• Latência. Quanto mais perto o Lavalink estiver do bot, melhor.
• Segurança. Use senha forte e não exponha a porta sem necessidade: quem tem a senha controla o seu nó.

Como fazer isso na Square Cloud#

Na Square Cloud, bot e nó de áudio viram duas aplicações na mesma conta: o Lavalink roda como aplicação web (a partir de 512 MB), e você reinicia cada uma sem derrubar a outra. No application.yml, use port: ${PORT} para escutar na porta que a plataforma define; o bot conecta no subdomínio da aplicação pela porta 443, com conexão segura (secure: true, ou uma URI https:// no Wavelink). O runtime Java da plataforma roda o servidor; confira se a versão do Java atende ao mínimo que o Lavalink exige.

Você faz o deploy por ZIP no painel, pela CLI, pelo GitHub ou pela extensão do VS Code. O arquivo de configuração squarecloud.app é opcional: o painel gera runtime, memória e arquivo principal no deploy, e escrever o arquivo na raiz do projeto é a alternativa. A RAM do plano é um pool compartilhado entre as suas aplicações, com mínimo de 256 MB por aplicação de fundo, como o bot. Os containers ficam sempre ligados, o reinício automático vem ligado no deploy pelo painel e traz o processo de volta quando ele encerra com erro, e os logs aparecem em tempo real no painel.

O bot do Discord pode usar discord.js, discord.py, JDA e outras bibliotecas, com sharding e voz, e a latência média até o Gateway do Discord é de cerca de 30 ms. Veja os detalhes em hospedagem de bots do Discord.