Streaming Audio Bidirezionale
In questa pagina
Aggiornato il 2 novembre 2026 — Modelli audio. Diversi modelli in questo corso sono deprecati:
tts-1,tts-1-hdegpt-4o-mini-ttssmetteranno 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-realtimee 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-transcribee/v1/audio/translationsil 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.
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.commitper 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.gatherconsente acquisizione e riproduzione simultanee sullo stesso WebSocket