Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Utilitários de conversão de áudio em Python

Aula 16 de 16 Atualizada a 30 de julho de 2026 Programador
Nesta página
  1. Uma biblioteca de utilitários de áudio
  2. PCM16 para base64 e vice-versa
  3. Reamostragem (Resampling)
  4. Conversão entre G.711 e PCM
  5. Deteção de silêncio no lado do cliente
  6. Guardar e carregar ficheiros WAV
  7. Pontos-chave
  8. Teste os seus conhecimentos

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_base64 e base64_to_audio sã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 audioop gere as conversões G.711 mu-law e A-law; foi removido da biblioteca padrão no Python 3.13, por isso instale audioop-lts do 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.