O Genesys AudioHook é 8 kHz µ-law, e não há onde pisar

Toda afirmação de especificação abaixo é citada da própria documentação publicada pela Genesys, com link. Onde não conseguimos confirmar algo, ele está listado como não confirmado, em vez de preenchido — há uma seção para isso perto do fim. Se qualquer parte disto estiver errada, ou mudar, nos avise e corrigiremos com uma data.

Contact centers são onde a IA de voz encontra receita de verdade, e o Genesys Cloud é um dos maiores deles. Então a pergunta que importa para qualquer um que vende processamento de áudio é estreita e respondível: como é o caminho de mídia, e existe nele um lugar onde um terceiro pode pisar?

A resposta da Genesys é incomumente legível, porque eles publicam o protocolo em vez de descrevê-lo. Aqui está a questão inteira da taxa de amostragem, como ela aparece nas definições de tipos deles:

type MediaFormat = 'PCMU';
type MediaRate = 8000;

Não é um default. Não é uma recomendação. É um tipo literal. A referência do protocolo reafirma isso em prosa — "Taxa de amostragem do formato de mídia em Hertz. O cliente do Genesys Cloud atualmente suporta apenas 8000Hz" — e a string 16000 não aparece em lugar nenhum da especificação do AudioHook.

Essa é a cunha de que este site inteiro trata, declarada pela própria plataforma. Todo terceiro que integra áudio ao Genesys Cloud pelo protocolo documentado recebe G.711 µ-law de banda estreita, e essencialmente todo modelo de aprimoramento de fala (speech enhancement) do mercado é treinado em banda larga.

O transporte, em resumo

O AudioHook inverte os papéis que você esperaria. A Genesys é o cliente WebSocket; o seu serviço é o servidor.

"O protocolo AudioHook usa WebSockets sobre TLS como transporte e é projetado para tornar fácil implementar servidores que o aceitam." — introdução

Concretamente, da página de segurança e do passo a passo de sessão:

Propriedade	Valor
Porta	443, e apenas 443
TLS	1.2 e 1.3; os certificados devem ser assinados por uma CA pública (nada de autoassinados)
Enquadramento	JSON em frames de texto, áudio bruto em frames binários
Tamanho máximo de mensagem	64,000 bytes, tanto texto quanto binário
Timeouts de open / ping / close	5,000 ms / 5,000 ms / 10,000 ms
Intervalo do ping de aplicação	a cada 5 segundos por conexão
Autenticação	header X-API-KEY, mais assinatura de requisição HMAC-SHA256 opcional com nonce obrigatório
Tentativas	até 5, backoff exponencial

Dois detalhes que vale a pena destacar, porque mordem quem implementa.

O ping não é o ping do WebSocket. São mensagens JSON ping/pong em nível de aplicação — "um recurso do protocolo distinto das mensagens ping/pong do WebSocket (que não são usadas)" — e um pong não solicitado é um erro de protocolo. Você tem cinco segundos para responder, a cada cinco segundos, ou a Genesys pode tratar a conexão como perdida e restabelecê-la.

Não há subprotocolo de WebSocket. Procuramos por um especificamente. O handshake documentado carrega os headers Audiohook-Organization-Id, Audiohook-Correlation-Id, Audiohook-Session-Id e X-API-KEY, e nenhum Sec-WebSocket-Protocol; a string não aparece em nenhuma página da especificação do AudioHook. Se você planejava rotear por subprotocolo, roteie por caminho.

A negociação de mídia, e o que os dois canais realmente são

A mensagem open carrega uma oferta e a sua resposta opened escolhe a partir dela, no estilo SDP. A regra é estrita:

"O servidor deve escolher exatamente uma das entradas oferecidas e não deve modificar um formato de mídia oferecido (incluindo os canais e a sua ordem). Isso é semelhante à troca de oferta e resposta de uma negociação de mídia SIP/SDP, só que mais simples." — passo a passo de sessão

Uma oferta típica são três entradas, todas PCMU a 8000 Hz, diferindo apenas nos canais: ["external", "internal"], ["external"], ["internal"].

Os nomes dos canais são a parte que as pessoas erram, e eles não são "quem liga" e "agente". O AudioHook segue um participante, não uma perna:

"Atualmente, dois valores são suportados: external, que representa o que a parte representada pelo participante fala, e internal, que representa o que ela ouve." — referência do protocolo

Então internal é tudo o que aquele participante ouve — o que pode ser prompts de IVR, música de espera do ACD ou, em uma conferência, uma mixagem. A Genesys diz isso explicitamente: "o áudio do canal 'internal' no nosso AudioHook representa uma mixagem do áudio dos dois agentes." Se você está construindo qualquer coisa que presume uma voz por canal, essa premissa falha em uma transferência assistida. Em uma resposta estéreo, a esquerda é o índice 0 e a direita é o índice 1.

Tamanhos de frame: não existem

Esta é a fonte mais provável de bug em uma primeira implementação, e a especificação é direta sobre isso.

"O número de amostras por frame é variável e fica a critério do cliente... O servidor não deve fazer nenhuma suposição sobre tamanhos de frame de áudio e deve manter uma linha do tempo do stream de áudio contando as amostras." — passo a passo de sessão

O único número concreto dado é ilustrativo: um frame de 100 ms de PCMU em dois canais a 8000 Hz são 1600 bytes, sem cabeçalho e intercalados. O seu orçamento de enquadramento é o teto de 64,000 bytes por mensagem e os limites de taxa — 10 mensagens binárias por segundo em média, com rajada de 25, o mesmo para texto.

E o stream não é cadenciado como uma chamada telefônica. A Genesys mantém buffer:

"O cliente mantém um buffer de histórico de pelo menos 20 segundos de áudio... ele enviará o áudio em buffer para o servidor mais rápido que o tempo real e então continuará com o stream em tempo real. A taxa na qual o cliente 'alcança' o tempo real é indefinida."

Então uma sessão abre com uma rajada de histórico a uma taxa não especificada e depois se assenta no tempo real. Qualquer coisa que você construa com tamanho de bloco fixo — o que é todo modelo de aprimoramento em streaming, o nosso incluído — precisa do seu próprio buffer de reenquadramento na frente, e qualquer coisa que meça o fator de tempo real a partir da chegada em relógio de parede vai ler um disparate nos primeiros segundos.

Quando o cliente não consegue acompanhar, ele te avisa, com uma mensagem discarded carregando as durações start e discarded e o invariante position = start + discarded. Isso é um anúncio de lacuna, não um comando de controle: "sempre que há uma descontinuidade no stream de áudio devido a perda inesperada de áudio." Pausa e retomada explícitas não produzem um. Se você está contando amostras para manter uma linha do tempo — e a especificação manda — discarded é como você fica sabendo que a sua linha do tempo acabou de se mover.

A pergunta que decide tudo: você pode enviar áudio de volta?

Depende inteiramente de qual dos quatro recursos do AudioHook você está implementando, e as respostas não se parecem entre si.

Recurso	Áudio para o seu servidor	Áudio de volta para a chamada	O que você pode retornar
AudioHook Monitor	Sim, external e/ou internal	Não	Nada em banda
Audio Connector	Sim, apenas external	Sim — reproduzido para quem liga	Áudio, como prompts de bot
Transcription Connector	Sim	Não	Eventos transcript
Bot Transcription Connector	Sim (PCMU ou L16)	Não	transcript e eventos de fala

O AudioHook Monitor é um tap e diz isso. A página de recursos não deixa espaço para interpretação:

"aqui o cliente transmitirá o áudio da conversa para o servidor, mas nenhum dado em banda pode ser enviado de volta ao cliente. Dados retornados pelo servidor serão silenciosamente ignorados e descartados."

Note o silenciosamente. Não é um erro, não é um aviso — o seu áudio processado desaparece e a sessão parece saudável. A introdução enquadra o protocolo inteiro da mesma forma: "Pense nisto como 'taps' nos streams de áudio de e para as partes dos participantes."

O Audio Connector é genuinamente bidirecional, e esse é o que parece, à primeira vista, a abertura:

"Este recurso suporta streaming de áudio bidirecional... Qualquer dado de áudio enviado ao cliente será reproduzido para quem liga. Apenas o canal de áudio external é enviado do cliente para o servidor." — recursos

Ele tem a maquinaria que você esperaria para isso: mensagens de cliente playback-started e playback-completed, um evento de servidor barge_in, uma mensagem dtmf. O áudio do servidor para o cliente é limitado a "não mais que 64,000 bytes por mensagem" e cadenciado — "o servidor não deve enviar áudio com frequência maior do que a cada 200ms".

Há uma contradição documentada que vale conhecer antes de gastar um dia nisso. A tabela de erros na mesma referência do protocolo ainda diz o oposto:

"415 Unsupported Media Type — O servidor enviou uma mensagem binária ao cliente... enviar áudio do servidor para o cliente não é suportado."

A nossa leitura é que o 415 é anterior ao Audio Connector e se aplica a sessões do Monitor e do Transcription Connector, onde binário vindo do servidor é de fato ilegal; o changelog mostra áudio bidirecional, DTMF, playback e barge-in chegando em uma atualização posterior. Mas a especificação contém as duas afirmações hoje, e, se você está construindo contra ela, deve esperar descobrir empiricamente qual delas se aplica ao seu tipo de sessão.

Por que o Audio Connector ainda não é um ponto de inserção

Aqui é onde a arquitetura, e não o protocolo, fecha a porta. O Audio Connector é um turno de bot, não um filtro inline, e três propriedades dele são, cada uma por si, desqualificantes para qualquer um que tente limpar áudio antes do bot de outra pessoa:

"A ação Call Audio Connector no Architect bifurca o stream de voz, envia-o para a URL configurada e então pausa a execução do fluxo nesse ponto, até que o stream bidirecional termine... A sessão de streaming bidirecional está ativa apenas no canal de IVR. Ela não é transferida para um agente." — visão geral do Audio Connector

1. O áudio que você envia vai para quem liga, não para o bot. Estão te pedindo para ser a voz do outro lado. Não existe a direção "retorne o áudio limpo de quem liga e deixe o reconhecedor de fala da plataforma ouvi-lo no lugar do original", porque a direção que existe aponta para o humano.
2. É um fork com fluxo bloqueante. A execução para na ação e retoma quando a sua sessão termina. Isso é um turno de diálogo, não um estágio de pipeline.
3. Ele nunca chega a um agente. Apenas IVR.

Mais as restrições menores, todas documentadas na mesma página: um único stream bidirecional, apenas o canal external, 300 chamadas simultâneas de Audio Connector e um teto de 900 segundos por chamada, e nenhum suporte sob BYOC Premises.

Então a conclusão honesta, checada superfície por superfície: o Genesys Cloud documenta a saída de áudio, o diálogo de áudio na perna de IVR e o retorno de metadados. Ele não documenta nenhuma forma de um terceiro receber áudio, processá-lo e fazer com que o áudio processado seja o que os próprios consumidores rio abaixo da plataforma ouvem. Checamos o Monitor, o Audio Connector, o Transcription Connector, o Bot Transcription Connector, o Genesys Agent Assist (um recurso de exibição de conhecimento sem caminho de áudio nenhum), o Genesys Bot Connector (texto e intenções, apenas fluxos de mensagem) e o Bring Your Own Interactions (ingestão a posteriori, não mídia ao vivo).

Onde você pode pisar, e é exatamente um lugar

Existe um ponto de inserção real, e não é o que as pessoas procuram.

Se você é o reconhecedor de fala, você pode limpar o áudio antes do seu próprio reconhecedor. O Bot Transcription Connector existe precisamente para deixar um terceiro ser a engine de STT — "permite que o áudio seja transmitido para o servidor baseado em AudioHook que servirá como engine de STT" — e a própria central de ajuda da Genesys o descreve como a forma de "integrar engines de ASR de terceiros usando o protocolo Genesys AudioHook". Esse caminho recebe PCMU, é o único que também oferece L16, e retorna transcript e eventos de início de fala, em vez de áudio.

O que realoca a pergunta em vez de respondê-la. Dentro dessa fronteira, a cadeia inteira é sua: 8 kHz µ-law entrando, o seu processamento, o seu reconhecedor, transcrição saindo. Nada na plataforma te impede de colocar um filtro ali. O que te impede é que, nas nossas próprias medições, a maior parte do que você poderia colocar ali é, hoje, uma má ideia: nas nossas sete condições de telefonia, nenhuma engine que testamos produziu melhora significativa sobre o áudio não processado, e várias o degradaram em cinco a dez pontos de taxa de erro de palavras (WER). O lugar para pisar existe. O que tem faltado é algo com que valha a pena pisar ali, e essa é a razão inteira de esta empresa existir.

A consequência de segunda ordem vale ser declarada para qualquer um que esteja escolhendo plataforma. No AudioHook, a decisão de qualidade de áudio do seu canal de maior volume é tomada rio acima de você e não pode ser mudada por você. Você recebe 8 kHz µ-law e o que quer que a perna da operadora tenha feito com ele, e a única alavanca que você tem é o que fazer depois que ele chega.

O que não conseguimos confirmar

Nomeado explicitamente, porque um post voltado a desenvolvedores que preenche lacunas em silêncio não vale nada.

• A taxa de amostragem da transcrição da própria Genesys. Não conseguimos encontrar nenhuma declaração da Genesys sobre em que taxa o speech-to-text deles roda, e nenhuma comparação de 8 kHz contra 16 kHz em lugar nenhum. As engines deles são apoiadas em fornecedores (Google, Microsoft Azure, AWS Transcribe, uma engine nativa da Genesys, Deepgram) e nenhuma taxa é publicada para nenhuma delas. Os codecs de tronco podem incluir G.722 e Opus, então a perna da operadora não é necessariamente banda estreita — mas o que chega ao transcritor não é documentado. O número de 8000 Hz neste post é apenas o caminho de terceiros do AudioHook. Não o estenda ao pipeline da própria Genesys com base na nossa palavra.
• Qualquer forma suportada de inserir um SBC ou servidor de mídia em um caminho SIP BYOC para modificar o áudio. O BYOC Cloud permite definir troncos SIP para operadoras terceiras, e os codecs de tronco são configuráveis. Não encontramos nenhum documento da Genesys que endosse, descreva ou proíba colocar um elemento de processamento nesse caminho. Ausência de documentação não é permissão e não é proibição.
• Um número máximo de conexões simultâneas do AudioHook Monitor. Apenas contagens de integrações e de monitores são publicadas — cinco integrações de AudioHook Monitor, até 20 instalações de integração, até 500 monitores configurados, dez integrações de Transcription Connector. As 300 chamadas simultâneas do Audio Connector são o único número de concorrência que encontramos.
• O formato de fio do áudio do servidor para o cliente no Audio Connector. A especificação dá a cadência (com frequência não maior do que a cada 200 ms) e o teto de tamanho (64,000 bytes), mas nunca reafirma o formato. Presumivelmente é o negociado. Ela não diz isso.
• "AudioHook Media Service" não parece ser um nome de produto da Genesys. Pesquisamos o sitemap do centro de desenvolvedores e o índice completo de artigos da central de ajuda e não encontramos nada. Se você viu o termo, ele não veio da documentação da Genesys.

Também notamos que a Genesys publica uma implementação de servidor de referência em TypeScript, com uma ferramenta de cliente e uma suíte de testes, e um servidor de referência do Audio Connector separado, cujo código-fonte fixa MediaFormat em 'PCMU' | 'L16', MediaRate em 8000 e a mensagem binária máxima em 64000 — o que é uma segunda confirmação independente dos números acima, em código em vez de prosa.

Se você está implementando isto

1. Conte amostras, não conte frames. A especificação exige, e a rajada de alcance pune qualquer coisa que não o faça.
2. Acumule em buffer até o tamanho de bloco do seu modelo, e nunca tome o timing de chegada como proxy do timing do áudio durante os primeiros vinte segundos.
3. Trate discarded como um evento de linha do tempo, não como um erro para logar e seguir em frente. O seu contador de amostras fica errado depois dele, se você não tratar.
4. Responda ao ping em até cinco segundos, sempre, a partir de um caminho que não possa ser bloqueado pela inferência. Se o seu modelo e o seu plano de controle compartilham um event loop, um bloco lento come a sua conexão.
5. Decida qual recurso você é antes de projetar qualquer coisa. Monitor e Audio Connector parecem o mesmo protocolo e são arquiteturas opostas, e a tabela de erros não vai te impedir de construir o errado.
6. Note a fronteira de PCI. O AudioHook adere à conformidade PCI DSS quando a pausa segura roda durante fluxos seguros, e você não pode usá-lo para transmitir áudio durante um fluxo seguro. O que quer que você construa tem um buraco por design, e esse buraco é deliberado.

O post companheiro cobrindo Amazon Connect, Twilio, NICE CXone e Avaya lê a mesma pergunta contra as outras quatro plataformas — e uma delas acaba documentando algo que a Genesys não documenta.