Como usar a gravação de voz do bot Discord com o módulo de gravação Pycord

Bots do Discord podem gravar áudio de canais de voz usando o módulo de gravação integrado da biblioteca Pycord. Esse recurso permite que seu bot capture o áudio de usuários específicos, útil para registros de reuniões, arquivamento de podcasts ou transcrição. O módulo de gravação do Pycord gerencia automaticamente o WebSocket e os fluxos de dados de áudio, então você não precisa lidar com codificação Opus bruta ou pacotes RTP. Este artigo explica como configurar um bot Pycord, entrar em um canal de voz, iniciar e parar a gravação e salvar arquivos de áudio no disco.

Visão geral do módulo de gravação do Pycord

Pycord é um wrapper Python moderno para a API do Discord. A versão 2.0 e superiores inclui um módulo de gravação de voz que permite que bots recebam áudio de canais de voz. O módulo usa a classe VoiceRecvClient, que estende o cliente de voz padrão com capacidades de escuta. Quando o bot entra em um canal de voz, ele pode ouvir todos os usuários que estão falando. O áudio gravado é entregue como pacotes Opus. O Pycord fornece vários sinks integrados que convertem esses pacotes Opus em formatos de áudio comuns, como WAV e MP3. Você também pode escrever um sink personalizado se precisar de um formato de saída diferente.

Antes de começar, você precisa de um token de bot do Discord, Python 3.8 ou superior e Pycord instalado. Instale o Pycord com o extra de voz: pip install py-cord[voice]. O bot deve ter as intenções voice_states e guilds ativadas. Você pode ativá-las no Portal do Desenvolvedor do Discord, na seção Bot. O recurso de gravação funciona em canais de voz de servidores. Não funciona em DMs em grupo ou canais de palco.

Passos para gravar voz com um bot Pycord

Siga estes passos para criar um bot que entre em um canal de voz, grave áudio e salve em um arquivo. O exemplo usa o sink padrão, que gera dados PCM brutos. Para saída WAV ou MP3, substitua o sink pela classe apropriada.

1. Crie o bot e ative as intenções
   Crie um novo arquivo Python. Importe o discord e crie uma instância de Bot com as intenções voice_states e guilds. Defina o prefixo do comando. Exemplo: bot = discord.Bot(intents=discord.Intents.all()). Usar todas as intenções é a abordagem mais simples para desenvolvimento.
2. Escreva um comando para entrar em um canal de voz
   Crie um comando de barra ou comando com prefixo que receba um canal de voz como argumento. Dentro do comando, chame await channel.connect(cls=discord.VoiceRecvClient). Isso conecta o bot e retorna uma instância de VoiceRecvClient. Armazene o cliente em uma variável para uso posterior.
3. Inicie a gravação de áudio
   Chame voice_client.listen(discord.sinks.WaveSink()) para iniciar a gravação. O WaveSink salva o áudio como arquivos WAV. Você pode passar discord.sinks.MP3Sink() para saída MP3. Para gravar apenas um usuário, passe o ID do usuário como segundo argumento: voice_client.listen(sink, user_id). O bot gravará apenas o áudio desse usuário.
4. Pare a gravação e salve os arquivos
   Chame voice_client.stop_listening() para parar a gravação. Após parar, o objeto sink contém os dados gravados. Acesse os dados usando sink.audio_data, que é um dicionário mapeando IDs de usuário para seus dados de áudio. Escreva o áudio de cada usuário em um arquivo. Exemplo: with open(f"{user_id}.wav", "wb") as f: f.write(sink.audio_data[user_id].file.read()).
5. Saia do canal de voz
   Após salvar os arquivos, chame await voice_client.disconnect() para sair do canal e liberar recursos.

Erros comuns e limitações a evitar

O bot não recebe áudio após entrar

Isso geralmente acontece quando o bot não possui as intenções necessárias. Certifique-se de ter ativado voice_states no Portal do Desenvolvedor do Discord e passado as intenções corretas ao criar a instância do Bot. Verifique também se o bot tem as permissões connect e speak no servidor.

O áudio gravado está silencioso ou com volume baixo

O sink padrão grava o áudio no volume original do Discord. Se o arquivo estiver silencioso, o usuário pode não estar falando. Use um sink que escreva o áudio imediatamente no disco para verificar se os dados estão sendo capturados. Verifique também se a codificação do sink corresponde ao seu player. Por exemplo, o WaveSink gera PCM de 16 bits a 48 kHz. Se o seu player esperar um formato diferente, talvez seja necessário converter o arquivo usando uma biblioteca como pydub.

O uso de memória cresce muito durante gravações longas

Os sinks padrão armazenam todo o áudio na memória até que você chame stop_listening. Para gravações longas, isso pode consumir muita RAM. Use um sink personalizado que escreva o áudio no disco em tempo real. Para criar um sink personalizado, subclassifique discord.sinks.Sink e implemente o método write para escrever os dados de áudio em um arquivo à medida que chegam.

Comparação dos sinks de áudio do Pycord

Item	WaveSink	MP3Sink	DefaultSink
Formato de saída	WAV (PCM 16 bits)	MP3	PCM bruto
Extensão do arquivo	.wav	.mp3	Nenhum (bytes brutos)
Requer FFmpeg	Não	Sim	Não
Uso de memória	Armazena todo o áudio na memória	Armazena todo o áudio na memória	Armazena todo o áudio na memória
Melhor para	Testes rápidos, arquivamento	Tamanho de arquivo menor, compartilhamento	Processamento personalizado

O módulo de gravação do Pycord é uma maneira confiável de capturar áudio de canais de voz do Discord. Agora você sabe como configurar um bot, entrar em um canal de voz, iniciar e parar a gravação com os métodos listen e stop_listening, e salvar arquivos de áudio usando sinks. Para uso em produção, considere escrever um sink personalizado que grave continuamente no disco para evitar problemas de memória. O módulo discord.sinks também suporta gravação estéreo e arquivos por usuário, que podem ser configurados através dos parâmetros do sink.