Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Utility di conversione audio in Python

Lezione 16 di 16 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Una libreria di utility audio
  2. Da PCM16 a base64 e viceversa
  3. Ricampionamento (Resampling)
  4. Conversione tra G.711 e PCM
  5. Rilevamento del silenzio lato client
  6. Salvataggio e caricamento di file WAV
  7. Punti chiave
  8. Verifica la tua comprensione

Una libreria di utility audio

Per costruire un’app Voice Agent robusta, hai bisogno di funzioni utility che convertano l’audio tra diversi formati. Questa lezione raccoglie gli strumenti Python essenziali per l’elaborazione audio in tempo reale.

Da PCM16 a base64 e viceversa

Queste sono le due funzioni che userai più spesso: codificare l’audio catturato in base64 per inviarlo e decodificare l’audio base64 ricevuto per riprodurlo.

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

Utilizzo nel flusso del Voice Agent

import pyaudio
import json

# Cattura microfono → invio
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
    }))

# Ricezione → riproduzione
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())

Ricampionamento (Resampling)

Se il tuo microfono cattura a una frequenza di campionamento diversa da quella attesa dalle API, devi ricampionare l’audio:

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)

# Esempio: microfono 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)

Conversione tra G.711 e PCM

Per le integrazioni telefoniche, dovrai convertire tra G.711 e PCM lineare. Fai attenzione alla versione di Python: audioop è stato rimosso dalla libreria standard nella versione 3.13. Su una versione recente di Python, installa il pacchetto audioop-lts, che fornisce la stessa interfaccia:

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)

Un relay telefonico completo

Ecco un esempio di relay tra uno stream SIP G.711 e le API del 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:
        # Converti 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)

Rilevamento del silenzio lato client

Se gestisci manualmente il push-to-talk o desideri un rilevamento locale del silenzio prima dell’invio, questa funzione misura l’energia del segnale:

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

# Utilizzo
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
    }))

Salvataggio e caricamento di file WAV

Per il debug e i test, puoi salvare e caricare file 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

Punti chiave

  • audio_to_base64 e base64_to_audio sono le due funzioni essenziali per il flusso del Voice Agent
  • Il ricampionamento è necessario quando la frequenza di campionamento del microfono non corrisponde a quella delle API
  • Il modulo audioop gestisce le conversioni G.711 mu-law e A-law; è stato rimosso dalla libreria standard in Python 3.13, quindi installa audioop-lts da PyPI sulle versioni recenti
  • Il rilevamento del silenzio lato client risparmia banda inviando solo audio utile
  • Le utility WAV semplificano il debug permettendoti di salvare e riprodurre stream audio

Verifica la tua comprensione

WebSocket, VAD, audio: il voice agent da capo a fondo.

1. Come si configura una sessione Voice Agent?

Risposta: Con una connessione WebSocket in tempo reale, autenticata con token effimeri (mai la chiave principale sul client), quindi configurata tramite session.update e confermata da session.created e session.updated.

2. Cosa gestisce il VAD?

Risposta: Il rilevamento automatico della voce: stabilisce quando l’utente inizia e smette di parlare, così l’agente sa quando ascoltare e quando rispondere, senza bisogno di pulsanti.

3. Come fluisce l'audio?

Risposta: L’input esce tramite input_audio_buffer.append (con commit e clear del buffer), e la risposta arriva come eventi audio da riprodurre, in PCM o G.711 a seconda del canale.

4. Cosa rendono possibili gli strumenti e MCP in una conversazione vocale?

Risposta: La chiamata di funzioni e gli strumenti integrati (web, X, collezioni) durante lo scambio parlato: l’agente effettua ricerche e agisce mentre parla, inclusi gli eventi MCP.

5. E per la telefonia?

Risposta: SIP e LiveKit con G.711: il voice agent si collega alla rete telefonica e le utility di conversione audio in Python fanno da ponte tra i formati.

Una sessione sicura, VAD, buffer gestiti correttamente, strumenti vocali: l’assistente telefonico completo è a portata di mano e questo corso ti ha fornito tutti gli elementi necessari.