Utilitários de conversão de áudio em Python
Nesta página
Uma biblioteca de utilitários de áudio
Para criar uma aplicação Voice Agent robusta, precisa de funções utilitárias que convertam áudio entre formatos. Esta lição reúne as ferramentas Python essenciais para o processamento de áudio em tempo real.
PCM16 para base64 e vice-versa
Estas são as duas funções que mais vai utilizar: codificar áudio capturado em base64 para o enviar e descodificar áudio base64 recebido para o reproduzir.
import base64
import numpy as np
def audio_to_base64(audio_data: np.ndarray) -> str:
"""Converts a float32 numpy array in [-1, 1] to base64 PCM16."""
audio_int16 = (audio_data * 32767).astype(np.int16)
return base64.b64encode(audio_int16.tobytes()).decode("utf-8")
def base64_to_audio(base64_audio: str) -> np.ndarray:
"""Converts a base64 PCM16 string to a float32 numpy array."""
audio_bytes = base64.b64decode(base64_audio)
audio_int16 = np.frombuffer(audio_bytes, dtype=np.int16)
return audio_int16.astype(np.float32) / 32768.0
Utilização no fluxo do Voice Agent
import pyaudio
import json
# Captura do microfone → envio
def capture_and_send(ws, stream, chunk_size=4096):
raw_data = stream.read(chunk_size, exception_on_overflow=False)
audio_array = np.frombuffer(raw_data, dtype=np.int16)
audio_float = audio_array.astype(np.float32) / 32768.0
b64 = audio_to_base64(audio_float)
ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": b64
}))
# Receção → reprodução
def play_received(player_stream, base64_audio):
audio_float = base64_to_audio(base64_audio)
audio_int16 = (audio_float * 32767).astype(np.int16)
player_stream.write(audio_int16.tobytes())
Reamostragem (Resampling)
Se o seu microfone capturar a uma taxa de amostragem diferente da esperada pela API, precisa de fazer reamostragem:
from scipy.signal import resample
def resample_audio(
audio: np.ndarray,
original_rate: int,
target_rate: int
) -> np.ndarray:
"""Resamples audio from one sample rate to another."""
if original_rate == target_rate:
return audio
num_samples = int(len(audio) * target_rate / original_rate)
return resample(audio, num_samples)
# Exemplo: microfone a 44100 Hz → API a 24000 Hz
audio_44100 = capture_microphone()
audio_24000 = resample_audio(audio_44100, 44100, 24000)
b64 = audio_to_base64(audio_24000)
Conversão entre G.711 e PCM
Para integrações telefónicas, precisará de converter entre G.711 e PCM linear. Preste atenção à sua versão do Python: o módulo audioop foi removido da biblioteca padrão na versão 3.13. Num Python recente, instale o pacote audioop-lts, que fornece a mesma interface:
import audioop
def pcm_to_mulaw(pcm_data: bytes) -> bytes:
"""Converts PCM16 to G.711 mu-law."""
return audioop.lin2ulaw(pcm_data, 2)
def mulaw_to_pcm(mulaw_data: bytes) -> bytes:
"""Converts G.711 mu-law to PCM16."""
return audioop.ulaw2lin(mulaw_data, 2)
def pcm_to_alaw(pcm_data: bytes) -> bytes:
"""Converts PCM16 to G.711 A-law."""
return audioop.lin2alaw(pcm_data, 2)
def alaw_to_pcm(alaw_data: bytes) -> bytes:
"""Converts G.711 A-law to PCM16."""
return audioop.alaw2lin(alaw_data, 2)
Um retransmissor telefónico completo
Eis um exemplo de um retransmissor entre um fluxo SIP G.711 e a API Voice Agent:
async def relay_sip_to_voice_agent(sip_stream, ws):
"""Relays audio from a SIP call to the Voice Agent API."""
async for mulaw_chunk in sip_stream:
# Converter mu-law → PCM → base64
pcm_data = mulaw_to_pcm(mulaw_chunk)
b64 = base64.b64encode(pcm_data).decode("utf-8")
await ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": b64
}))
async def relay_voice_agent_to_sip(ws, sip_stream):
"""Relays the API's audio response to the SIP stream."""
async for message in ws:
event = json.loads(message)
if event["type"] == "response.output_audio.delta":
pcm_data = base64.b64decode(event["delta"])
mulaw_data = pcm_to_mulaw(pcm_data)
await sip_stream.send(mulaw_data)
Deteção de silêncio no lado do cliente
Se gerir o push-to-talk manualmente ou quiser detetar silêncio localmente antes de enviar, esta função mede a energia do sinal:
def is_silence(
audio: np.ndarray,
threshold: float = 0.01
) -> bool:
"""Detects whether an audio chunk is silence."""
rms = np.sqrt(np.mean(audio ** 2))
return rms < threshold
# Utilização
audio_chunk = capture_microphone()
if not is_silence(audio_chunk, threshold=0.02):
b64 = audio_to_base64(audio_chunk)
ws.send(json.dumps({
"type": "input_audio_buffer.append",
"audio": b64
}))
Guardar e carregar ficheiros WAV
Para depuração e testes, pode guardar e carregar ficheiros WAV:
import wave
def save_wav(
filename: str,
audio: np.ndarray,
sample_rate: int = 24000
):
"""Saves a numpy array as a WAV file."""
audio_int16 = (audio * 32767).astype(np.int16)
with wave.open(filename, "wb") as wf:
wf.setnchannels(1)
wf.setsampwidth(2)
wf.setframerate(sample_rate)
wf.writeframes(audio_int16.tobytes())
def load_wav(filename: str) -> tuple[np.ndarray, int]:
"""Loads a WAV file as a float32 numpy array."""
with wave.open(filename, "rb") as wf:
sample_rate = wf.getframerate()
frames = wf.readframes(wf.getnframes())
audio_int16 = np.frombuffer(frames, dtype=np.int16)
return audio_int16.astype(np.float32) / 32768.0, sample_rate
Pontos-chave
audio_to_base64ebase64_to_audiosão as duas funções essenciais para o fluxo do Voice Agent- A reamostragem é necessária quando a taxa de amostragem do seu microfone não corresponde à da API
- O módulo
audioopgere as conversões G.711 mu-law e A-law; foi removido da biblioteca padrão no Python 3.13, por isso instaleaudioop-ltsdo PyPI em versões recentes - A deteção de silêncio no lado do cliente poupa largura de banda ao enviar apenas áudio útil
- Os utilitários WAV facilitam a depuração, permitindo guardar e reproduzir fluxos de áudio
Teste os seus conhecimentos
WebSocket, VAD, áudio: o agente de voz de ponta a ponta.
1. Como configura uma sessão de Voice Agent?
Resposta: Com uma ligação WebSocket em tempo real, autenticada com tokens efémeros (nunca a chave principal no cliente), e depois configurada através de session.update, confirmada por session.created e session.updated.
2. O que trata o VAD?
Resposta: Deteção automática de fala: determina quando o utilizador começa e para de falar, para que o agente saiba quando ouvir e quando responder, sem necessidade de botão.
3. Como flui o áudio?
Resposta: A entrada sai através de input_audio_buffer.append (com commit e limpeza do buffer), e a resposta chega como eventos de áudio para reproduzir, em PCM ou G.711, dependendo do canal.
4. O que permitem as ferramentas e o MCP numa conversa de voz?
Resposta: Chamada de funções e ferramentas integradas (web, X, coleções) durante a troca falada: o agente pesquisa informações e age enquanto fala, incluindo eventos MCP.
5. E para a telefonia?
Resposta: SIP e LiveKit com G.711: o agente de voz liga-se à rede telefónica e os utilitários de conversão de áudio em Python fazem a ponte entre os formatos.
Uma sessão segura, VAD, buffers bem geridos, ferramentas em voz: o assistente telefónico completo está ao seu alcance, e este curso deu-lhe todas as peças.