Sons de entrada

Um som de entrada é um clipe de áudio curto que uma conta reproduz enquanto está conectada a um canal de voz. Uma conta faz o upload de um clipe uma vez para sua própria biblioteca e, em seguida, o atribui a um escopo: globalmente, em canais de voz de guilda, em chamadas privadas ou em uma guilda nomeada. Voz define o estado da voz e o posicionamento.

Todas as rotas nesta página são apenas para usuários (user-only), não exigem permissão e atuam na própria biblioteca do chamador.

Limites de clipes

Cada limite abaixo é uma constante fixa da instância e nenhum é resolvido a partir de uma regra de limite da conta.

Limite	Valor
Clipes por conta	8
Tamanho do clipe decodificado1	1048576 bytes
Carga de upload codificada1	1398134 caracteres
Duração do clipe2	100 a 5200 milissegundos
Nome de exibição	1 a 32 caracteres após normalização

¹ O limite de caracteres é o teto decodificado de 1 MiB expresso em base64 com 32 caracteres de folga, portanto, é o limite que uma carga superdimensionada atinge primeiro ² Apenas Fazer upload de som de entrada aplica o limite inferior

O documento de descoberta de instâncias publica uma chave de limite feature_voice_entrance_sounds. O cliente do Decoding Chat lê essa chave para decidir se abre a caixa de diálogo de upload de clipe e se chama Reproduzir som de entrada após se conectar a um canal de voz. Nenhuma rota nesta página a verifica, de modo que uma biblioteca pode ser lida, gravada e reproduzida independentemente do seu valor resolvido.

Contêineres suportados

O Decoding Chat detecta o contêiner a partir dos bytes decodificados, portanto, um nome de arquivo, um tipo de mídia data: ou qualquer outro tipo declarado não tem efeito sobre o resultado. O contêiner detectado resolve para uma extensão armazenada e qualquer outra entrada falha com ENTRANCE_SOUND_INVALID_FORMAT.

Contêiner detectado	Extensão armazenada	Tipo de conteúdo armazenado
MP3, MPEG1	mp3	audio/mpeg
Ogg2	ogg	audio/ogg
MP4, QuickTime, AAC3	m4a	audio/mp4
WAV	wav	audio/wav

¹ Um stream de programa MPEG resolve aqui, assim como o áudio MPEG puro ² Um Ogg de áudio e um Ogg de vídeo resolvem ambos aqui ³ O contêiner sozinho decide essa linha, portanto, um arquivo MP4 ou QuickTime com um stream de vídeo é aceito desde que seja possível medir a duração a partir dele. Um stream AAC puro fora de um contêiner MP4 não é detectado e é rejeitado

FLAC, WebM, Matroska, AIFF, 3GPP, AVI, FLV, WMV, MPEG-TS e todos os tipos de imagem não resolvem para nenhuma extensão e são rejeitados.

Os bytes enviados são armazenados exatamente como recebidos (verbatim)

Os bytes decodificados são gravados exatamente como chegaram, sob a extensão e o tipo de conteúdo que a tabela atribui. Um upload QuickTime continua sendo um arquivo QuickTime, e o Decoding Chat o serve como audio/mp4 sob uma extensão m4a.

Objeto de som de entrada

Um clipe de áudio armazenado de propriedade de uma conta. Todos os campos, exceto name, são fixos no momento do upload, e id é o único identificador (handle) que as outras rotas aceitam.

Estrutura

Campo	Tipo	Descrição
id	snowflake	O ID do som
name	string	O rótulo de exibição mostrado para o clipe (1-32 caracteres)
hash1	string	O digest de conteúdo do áudio armazenado, 16 caracteres hexadecimais
extension	string	A extensão armazenada, uma de mp3, ogg, m4a e wav, escolhida pelo contêiner detectado
content_type	string	O tipo MIME com o qual o clipe é armazenado e servido, derivado de extension
duration_ms2	integer	A duração medida em milissegundos (0-5200)
size_bytes	integer	O tamanho decodificado em bytes (0-1048576)
url3	string	A URL absoluta do CDN de onde o clipe é buscado
created_at	ISO8601 timestamp	A hora em que o clipe foi enviado

¹ Um hash de conteúdo. Clipes com áudio idêntico têm o mesmo hash ² Medido a partir do áudio decodificado e arredondado para o milissegundo mais próximo ³ Construído como /entrance-sounds/{user_id}/{hash}.{extension} no endpoint de mídia da instância. A rota que o serve não aceita nenhuma credencial, portanto, qualquer pessoa com a URL pode buscar o áudio

Exemplo

{
  "id": "1501314428688998182",
  "name": "airhorn",
  "hash": "9f2c41ab77de0135",
  "extension": "mp3",
  "content_type": "audio/mpeg",
  "duration_ms": 1240,
  "size_bytes": 20416,
  "url": "https://cdn.example.com/entrance-sounds/1490000000000000000/9f2c41ab77de0135.mp3",
  "created_at": "2026-08-31T09:12:04.118Z"
}

Objeto de seleção de som de entrada

Um escopo e o clipe atribuído a ele.

Estrutura

Campo	Tipo	Descrição
scope_id	string	O Escopo de som de entrada a que a seleção se aplica
sound_id	snowflake	O clipe atribuído a esse escopo

Um escopo sem som atribuído não tem um objeto de seleção. Limpar um escopo exclui sua entrada.

Exemplo

{
  "scope_id": "guild:1490000000000000123",
  "sound_id": "1501314428688998182"
}

Escopos de som de entrada

Valor	Descrição
global	Aplica-se onde nenhum escopo mais restrito está selecionado
guilds	Aplica-se em canais de voz de guilda
dms	Aplica-se em mensagens diretas e chamadas em grupo
guild:{guild_id}	Aplica-se a uma guilda nomeada, onde o ID é de 1 a 20 dígitos

scope_id deve corresponder exatamente a uma dessas formas. Qualquer outro valor falha com o código de validação INVALID_FORMAT no caminho scope_id.

Os clientes selecionam o som a tocar

Use as seleções de escopo para escolher um clipe e, em seguida, passe seu ID para Reproduzir som de entrada.

Listar sons de entrada

GET/v1/users/@me/entrance-sounds

Retorna a biblioteca completa de sons de entrada da conta atual, juntamente com suas seleções por escopo.

Corpo da resposta

Campo	Tipo	Descrição
sounds	array[objeto de som de entrada]	Cada clipe de propriedade da conta, no máximo 8
selections	array[objeto de seleção de som de entrada]	Cada escopo com um som atribuído

Ambos os membros estão sempre presentes e ambos os arrays estão vazios para uma conta que não fez upload de nada. Uma seleção sempre nomeia um som presente em sounds.

Resposta

Status	Corpo	Condição
200	corpo da resposta	A biblioteca foi retornada

Limite de taxa

30 solicitações por minuto para cada usuário autenticado, no bucket user:entrance_sound:list.

Fazer upload de som de entrada

POST/v1/users/@me/entrance-sounds

Decodifica, valida e armazena um clipe de áudio na biblioteca da conta atual e retorna o objeto de som de entrada criado.

Corpo JSON

Campo	Tipo	Descrição
name1	string	O rótulo de exibição mostrado para o clipe (1-32 caracteres)
audio2	base64 string	Os bytes de áudio do clipe, codificados em base64 (1-1398134 caracteres)

¹ Aparado (trimmed) antes que seu comprimento seja medido ² Um prefixo de URI data: é aceito e descartado, e apenas a parte após a primeira vírgula é medida e decodificada

Caracteres invisíveis em name não são removidos e contam para o limite de 32 caracteres.

Validação

Cada falha abaixo retorna 400 INVALID_FORM_BODY. Uma resposta pode conter mais de um erro de campo.

Falha	Código de validação	Caminho
O campo está ausente ou é uma string vazia literal1	INVALID_FORMAT	name ou audio
O nome normalizado está vazio ou tem mais de 32 caracteres	STRING_LENGTH_INVALID	name
A carga codificada está vazia ou tem mais de 1398134 caracteres2	BASE64_LENGTH_INVALID	audio
A carga útil não é um base64 válido	INVALID_BASE64_FORMAT	audio
A biblioteca já contém 8 clipes	ENTRANCE_SOUND_QUOTA_REACHED	audio
Os bytes decodificados excedem 1048576 bytes	ENTRANCE_SOUND_SIZE_EXCEEDS_LIMIT	audio
Os bytes não resolvem para nenhum contêiner suportado, ou a sua duração não pode ser medida	ENTRANCE_SOUND_INVALID_FORMAT	audio
A duração medida é superior a 5200 ms ou inferior a 100 ms	ENTRANCE_SOUND_DURATION_EXCEEDS_LIMIT	audio
O clipe validado não pôde ser gravado no armazenamento	FAILED_TO_UPLOAD_IMAGE	audio

¹ Uma string vazia é lida como null sob a normalização de entrada, e nenhum dos campos aceita null ² Medido após qualquer prefixo data: ser descartado, de modo que um valor que consiste apenas em espaços em branco, ou que termina em sua primeira vírgula, tem zero caracteres de carga útil e falha aqui

O Decoding Chat verifica as primeiras quatro linhas antes da cota, de modo que uma conta que já possui 8 clipes recebe BASE64_LENGTH_INVALID ou INVALID_BASE64_FORMAT para uma carga útil malformada ou excessivamente longa.

A entrada de validação não tem membro indicando qual limite de duração o clipe ultrapassou.

Resposta

Status	Corpo	Condição
201	objeto de som de entrada	O clipe foi armazenado
400	resposta de erro	Name ou audio falha na validação

Efeitos colaterais

A operação não atribui nenhum escopo e não emite Dispatch de Gateway.

Áudios duplicados podem compartilhar um URL

Fazer o upload dos mesmos bytes duas vezes cria entradas de biblioteca distintas com os mesmos hash e url. A exclusão de um deixa o outro utilizável.

Limite de taxa

5 solicitações por 5 minutos para cada usuário autenticado, no bucket user:entrance_sound:upload.

Renomear som de entrada

PATCH/v1/users/@me/entrance-sounds/{sound_id}

Altera o rótulo de exibição de um clipe e retorna o objeto de som de entrada atualizado.

Parâmetros de rota

Campo	Tipo	Descrição
sound_id	snowflake	O ID do som

Corpo JSON

Campo	Tipo	Descrição
name1	string	Rótulo de exibição substituto (1-32 caracteres)

¹ Obrigatório, e normalizado e limitado exatamente como o name em Fazer upload de som de entrada

Resposta

Status	Corpo	Condição
200	objeto de som de entrada	O clipe foi renomeado
400	resposta de erro	O nome é normalizado para a string vazia ou excede 32 caracteres e a solicitação retorna STRING_LENGTH_INVALID no caminho name, ou a conta não possui tal clipe e a solicitação retorna ENTRANCE_SOUND_NOT_FOUND no caminho sound_id

Um clipe desconhecido retorna 400, não 404

O Decoding Chat relata um clipe de propriedade de outra conta exatamente como um que nunca existiu, de modo que um chamador não pode distinguir a propriedade da existência. Definir seleção de som de entrada e Reproduzir som de entrada relatam um clipe desconhecido da mesma maneira.

Efeitos colaterais

Apenas o rótulo muda. O áudio armazenado permanece intacto, e toda seleção apontando para o clipe continua apontando para ele. O Decoding Chat não emite Gateway Dispatch.

Limite de taxa

20 solicitações por minuto para cada usuário autenticado, no bucket user:entrance_sound:mutate, que é compartilhado com Excluir som de entrada e Definir seleção de som de entrada.

Excluir som de entrada

DELETE/v1/users/@me/entrance-sounds/{sound_id}

Exclui um clipe da biblioteca da conta atual, limpa todas as seleções de escopo que apontavam para ele e retorna 204 com um corpo vazio. Um clipe desconhecido ou um clipe de propriedade de outra conta é uma operação no-op bem-sucedida.

Parâmetros de rota

Campo	Tipo	Descrição
sound_id	snowflake	O ID do som

Resposta

Status	Corpo	Condição
204	vazio	O clipe foi excluído ou nenhum clipe de propriedade existia

Efeitos colaterais

O clipe e cada seleção nomeando-o são removidos da biblioteca. Nenhum Dispatch de Gateway é emitido.

Limite de taxa

20 solicitações por minuto para cada usuário autenticado, no bucket compartilhado user:entrance_sound:mutate.

Definir seleção de som de entrada

PUT/v1/users/@me/entrance-sound-selections

Atribui um dos clipes da conta a um escopo, ou limpa esse escopo, e retorna 204 com um corpo vazio. Cada chamada aborda exatamente um escopo e um escopo que já possui um som é substituído.

Corpo JSON

Campo	Tipo	Descrição
scope_id	string	Escopo de som de entrada para gravar (1-32 caracteres)
sound_id1	?snowflake	O clipe para atribuir, ou null para limpar o escopo

¹ Obrigatório. Um null explícito limpa o escopo, tem êxito mesmo quando o escopo não tinha seleção e não procura nenhum clipe

Um escopo guild:{guild_id} não requer associação atual à guilda. Um sound_id não nulo deve nomear um clipe de propriedade da conta.

Resposta

Status	Corpo	Condição
204	vazio	A seleção foi gravada ou limpa
400	resposta de erro	O escopo não é reconhecido e a solicitação retorna INVALID_FORMAT no caminho scope_id, ou a conta não possui tal clipe e a solicitação retorna ENTRANCE_SOUND_NOT_FOUND no caminho sound_id

Efeitos colaterais

O Decoding Chat grava ou remove a seleção do escopo. Um clipe pode ser selecionado em qualquer número de escopos ao mesmo tempo. A operação não emite Dispatch de Gateway, então as outras sessões do chamador só ficam sabendo da mudança ao listar a biblioteca novamente.

Limite de taxa

20 solicitações por minuto para cada usuário autenticado, no bucket compartilhado user:entrance_sound:mutate.

Reproduzir som de entrada

POST/v1/voice/channels/{channel_id}/entrance-sound

Diz a todas as outras contas conectadas a um canal de voz para tocar o clipe escolhido pelo chamador e retorna 204 com um corpo vazio. O chamador já deve ter um estado de voz naquele canal e deve ser o dono do clipe. Emite um evento de Gateway ENTRANCE_SOUND_PLAY.

Os destinatários buscam e reproduzem o clipe localmente a partir do URL no evento.

Parâmetros de rota

Campo	Tipo	Descrição
channel_id	snowflake	O ID do canal de voz no qual o clipe é reproduzido

Corpo JSON

Campo	Tipo	Descrição
sound_id	snowflake	O clipe para tocar, extraído da própria biblioteca do chamador

Resposta

Status	Corpo	Condição
204	vazio	O Decoding Chat tentou um Dispatch para todas as outras contas conectadas
400	resposta de erro	O chamador não mantém estado de voz no canal, inclusive quando o canal não existe, e a solicitação retorna ENTRANCE_SOUND_INVALID_SCOPE no caminho channel_id, ou a conta não possui tal clipe e a solicitação retorna ENTRANCE_SOUND_NOT_FOUND no caminho sound_id

A conexão é a única autorização

O Decoding Chat não avalia a permissão do canal e não verifica a participação na guilda.

Um ID que não nomeia nenhum canal é recusado exatamente como um canal ao qual o chamador não está conectado. A verificação da conexão é executada antes que o clipe seja procurado, de modo que um chamador que não está conectado nunca saberá se o clipe nomeado existe.

Efeitos colaterais

O Decoding Chat envia um Dispatch ENTRANCE_SOUND_PLAY para todas as outras contas que mantêm um estado de voz no canal, no máximo uma vez para cada conta, e nunca para o chamador. Um destinatário cujo Dispatch falha é ignorado e a solicitação ainda retorna 204.

O Decoding Chat endereça o Dispatch para a conta, de modo que todas as sessões que essa conta detém o recebem, incluindo sessões que não estão no canal. Um cliente filtra no channel_id.

Limite de taxa

3 solicitações por 30 segundos para cada usuário autenticado e ID de canal, no bucket voice:entrance_sound:play::user_id::channel_id.