Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Streaming Audio Bidirezionale

Lezione 3 di 18 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Streaming Audio Bidirezionale
  2. Formato Audio PCM16
  3. Invio Audio: Acquisizione dal Microfono
  4. Ricezione dell’Audio di Risposta
  5. Applicazione Completa: Conversazione Vocale
  6. Punti chiave

Aggiornato il 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati: tts-1, tts-1-hd e gpt-4o-mini-tts smetteranno di funzionare il 6 gennaio 2027 (il sostituto indicato è gpt-realtime-2.1-mini, che la guida TTS di OpenAI specifica non essere supportato da /v1/audio/speech: la migrazione della sintesi vocale passa alle Realtime API); gpt-realtime, gpt-4o-realtime e i modelli audio legacy il 20 gennaio 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe e /v1/audio/translations il 26 febbraio 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Per la voce full-duplex, GPT-Live 1 è disponibile nelle API dal 10 settembre 2026.

Streaming Audio Bidirezionale

Lo streaming audio bidirezionale è il cuore delle Realtime API. Invii continuamente frammenti audio dal microfono e il modello restituisce continuamente frammenti audio di risposta. Questi due flussi sono indipendenti e possono operare simultaneamente: è proprio questo che rende la conversazione naturale.

Formato Audio PCM16

Le Realtime API utilizzano il formato PCM a 16 bit mono a 24 kHz. Si tratta di un formato grezzo e non compresso: ogni campione è un intero con segno a 16 bit. Questa scelta privilegia la bassa latenza rispetto all’efficienza della banda.

24 kHz
Frequenza di campionamento
16 bit
Profondità del campione
Mono
Canale singolo
48 KB/s
Bitrate audio grezzo

I frammenti audio vengono inviati codificati in Base64 all’interno di eventi JSON. Ogni frammento rappresenta tipicamente da 20 a 100 ms di audio.

Invio Audio: Acquisizione dal Microfono

Ecco come acquisire l’audio dal microfono e trasmetterlo in streaming:

import asyncio
import sounddevice as sd
import numpy as np
import base64
import json

SAMPLE_RATE = 24000
CHUNK_DURATION_MS = 100
CHUNK_SIZE = int(SAMPLE_RATE * CHUNK_DURATION_MS / 1000)

async def stream_microphone(ws):
    """Acquisisci il microfono e invia i frammenti alle Realtime API."""
    loop = asyncio.get_event_loop()
    audio_queue = asyncio.Queue()

    def audio_callback(indata, frames, time_info, status):
        if status:
            print(f"Audio warning: {status}")
        # Converti in int16 e metti in coda
        pcm_data = (indata[:, 0] * 32767).astype(np.int16)
        loop.call_soon_threadsafe(audio_queue.put_nowait, pcm_data)

    # Avvia l'acquisizione
    stream = sd.InputStream(
        samplerate=SAMPLE_RATE,
        channels=1,
        dtype="float32",
        blocksize=CHUNK_SIZE,
        callback=audio_callback
    )

    with stream:
        print("Microfono attivo — parla ora...")
        while True:
            pcm_data = await audio_queue.get()
            audio_b64 = base64.b64encode(pcm_data.tobytes()).decode("utf-8")

            await ws.send(json.dumps({
                "type": "input_audio_buffer.append",
                "audio": audio_b64
            }))

Il Buffer Audio Lato Server

I frammenti inviati tramite input_audio_buffer.append si accumulano in un buffer sul server. Questo buffer viene elaborato in due modi:

  • Modalità VAD automatica (server_vad): il server rileva quando smetti di parlare e conferma automaticamente il buffer.
  • Modalità manuale: invii esplicitamente input_audio_buffer.commit per attivare l’elaborazione.
# Conferma manuale del buffer audio
await ws.send(json.dumps({
    "type": "input_audio_buffer.commit"
}))

# Oppure svuota il buffer senza elaborarlo
await ws.send(json.dumps({
    "type": "input_audio_buffer.clear"
}))

Ricezione dell’Audio di Risposta

Le risposte audio arrivano a frammenti tramite eventi response.output_audio.delta. Devi decodificarli e riprodurli continuamente:

import pyaudio

async def play_response_audio(ws):
    """Ricevi e riproduci l'audio di risposta."""
    pa = pyaudio.PyAudio()
    player = pa.open(
        format=pyaudio.paInt16,
        channels=1,
        rate=SAMPLE_RATE,
        output=True,
        frames_per_buffer=CHUNK_SIZE
    )

    try:
        async for raw_message in ws:
            event = json.loads(raw_message)

            if event["type"] == "response.output_audio.delta":
                # Decodifica il frammento audio Base64
                audio_bytes = base64.b64decode(event["delta"])
                player.write(audio_bytes)

            elif event["type"] == "response.output_audio.done":
                print("Risposta audio terminata")

            elif event["type"] == "response.output_audio_transcript.delta":
                # Trascrizione testuale della risposta
                print(event["delta"], end="", flush=True)

    finally:
        player.stop_stream()
        player.close()
        pa.terminate()

Applicazione Completa: Conversazione Vocale

Ecco come assemblare acquisizione e riproduzione per una conversazione completa:

async def conversation_vocale():
    headers = {
        "Authorization": f"Bearer {OPENAI_API_KEY}"
    }

    async with websockets.connect(URL, additional_headers=headers) as ws:
        # Attendi session.created
        await ws.recv()

        # Configura la sessione
        await ws.send(json.dumps({
            "type": "session.update",
            "session": {
                "type": "realtime",
                "output_modalities": ["audio"],
                "instructions": "You are a voice assistant. Respond in English.",
                "audio": {
                    "input": {
                        "format": {"type": "audio/pcm", "rate": 24000},
                        "turn_detection": {
                            "type": "server_vad",
                            "threshold": 0.5,
                            "silence_duration_ms": 700
                        }
                    },
                    "output": {
                        "format": {"type": "audio/pcm", "rate": 24000},
                        "voice": "marin"
                    }
                }
            }
        }))
        await ws.recv()  # session.updated

        # Avvia acquisizione e riproduzione in parallelo
        await asyncio.gather(
            stream_microphone(ws),
            play_response_audio(ws)
        )

asyncio.run(conversation_vocale())

Gestione di Flussi Concorrenti

La sfida dello streaming bidirezionale consiste nell’inviare e ricevere simultaneamente sullo stesso WebSocket. asyncio.gather avvia entrambe le coroutine in parallelo, ma condividono lo stesso oggetto WebSocket. La libreria websockets gestisce correttamente questa concorrenza.

Punti chiave

  • L’audio viene trasmesso come PCM mono a 16 bit e 24 kHz, codificato in Base64 negli eventi JSON
  • I frammenti sono tipicamente di 20-100 ms per un buon compromesso tra latenza e overhead
  • Il buffer audio lato server accumula i frammenti fino alla conferma (automatica in modalità VAD)
  • La riproduzione della risposta avviene frammento per frammento tramite response.output_audio.delta
  • asyncio.gather consente acquisizione e riproduzione simultanee sullo stesso WebSocket