Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Äänen kaksisuuntainen suoratoisto

Oppitunti 3 / 18 Päivitetty 2. marraskuuta 2026 Kehittäjä
Tällä sivulla
  1. Äänen kaksisuuntainen suoratoisto
  2. PCM16-äänimuoto
  3. Äänen lähettäminen: Mikrofonin kaappaus
  4. Vastausäänen vastaanottaminen
  5. Täydellinen sovellus: Äänikeskustelu
  6. Keskeiset asiat

Päivitetty 2. marraskuuta 2026 — Äänimallit. Useat tämän kurssin malleista on poistettu käytöstä: tts-1, tts-1-hd ja gpt-4o-mini-tts lakkaavat toimimasta 6. tammikuuta 2027 (suositeltu korvaaja on gpt-realtime-2.1-mini, jonka OpenAI:n TTS-opas ilmoittaa ei tukevan polkua /v1/audio/speech: puheentuotto siirtyy Realtime APIiin); gpt-realtime, gpt-4o-realtime ja vanhat äänimallit 20. tammikuuta 2027 (gpt-realtime-2.1, gpt-realtime-2.1-mini, gpt-audio-1.5); whisper-1, gpt-4o-transcribe ja /v1/audio/translations 26. helmikuuta 2027 (gpt-transcribe, gpt-live-transcribe, v1/realtime/translations). Täysdupleksista ääntä varten GPT-Live 1 on ollut saatavilla rajapinnassa 10. syyskuuta 2026 lähtien.

Äänen kaksisuuntainen suoratoisto

Äänen kaksisuuntainen suoratoisto on Realtime API:n ydin. Lähetät jatkuvasti äänipaloja mikrofonilta, ja malli palauttaa jatkuvasti vastausäänipaloja. Nämä kaksi virtaa ovat toisistaan riippumattomia ja voivat toimia samanaikaisesti – mikä tekee keskustelusta luontevan tuntuisen.

PCM16-äänimuoto

Realtime API käyttää 24 kHz:n mono 16-bittistä PCM-muotoa. Tämä on raaka, pakkaamaton muoto: jokainen näyte on 16-bittinen etumerkillinen kokonaisluku. Tämä valinta priorisoi pientä viivettä kaistanleveyden tehokkuuden sijaan.

24 kHz
Näytetaajuus
16 bit
Näytesyvyys
Mono
Yksi kanava
48 KB/s
Raaka-äänibittivirta

Äänipalat lähetetään Base64-koodattuina JSON-tapahtumien sisällä. Jokainen pala edustaa tyypillisesti 20–100 millisekuntia ääntä.

Äänen lähettäminen: Mikrofonin kaappaus

Näin kaappaat mikrofonin ja suoratoistat äänen:

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):
    """Kaappaa mikrofoni ja lähetä palat Realtime APIiin."""
    loop = asyncio.get_event_loop()
    audio_queue = asyncio.Queue()

    def audio_callback(indata, frames, time_info, status):
        if status:
            print(f"Audio warning: {status}")
        # Muunna int16-muotoon ja lisää jonoon
        pcm_data = (indata[:, 0] * 32767).astype(np.int16)
        loop.call_soon_threadsafe(audio_queue.put_nowait, pcm_data)

    # Aloita kaappaus
    stream = sd.InputStream(
        samplerate=SAMPLE_RATE,
        channels=1,
        dtype="float32",
        blocksize=CHUNK_SIZE,
        callback=audio_callback
    )

    with stream:
        print("Mikrofoni aktiivinen — puhu nyt...")
        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
            }))

Palvelinpuolen äänipuskuri

input_audio_buffer.append-komennolla lähetetyt palat kertyvät palvelimella olevaan puskuriin. Tämä puskuri käsitellään kahdella tavalla:

  • Automaattinen VAD-tila (server_vad): Palvelin havaitsee, kun lopetat puhumisen, ja sitoo puskurin automaattisesti.
  • Manuaalinen tila: Lähetät nimenomaisesti komennon input_audio_buffer.commit käsittelyn käynnistämiseksi.
# Sitou äänipuskuri manuaalisesti
await ws.send(json.dumps({
    "type": "input_audio_buffer.commit"
}))

# Tai tyhjennä puskuri käsittelemättä sitä
await ws.send(json.dumps({
    "type": "input_audio_buffer.clear"
}))

Vastausäänen vastaanottaminen

Äänivastaukset saapuvat paloina response.output_audio.delta-tapahtumien kautta. Sinun on purettava ne ja toistettava jatkuvasti:

import pyaudio

async def play_response_audio(ws):
    """Vastaanota ja toista vastausääni."""
    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":
                # Puretta Base64-koodattu äänipala
                audio_bytes = base64.b64decode(event["delta"])
                player.write(audio_bytes)

            elif event["type"] == "response.output_audio.done":
                print("Äänivastaus päättynyt")

            elif event["type"] == "response.output_audio_transcript.delta":
                # Vastauksen tekstitys
                print(event["delta"], end="", flush=True)

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

Täydellinen sovellus: Äänikeskustelu

Näin yhdistät kaappauksen ja toiston täyttä keskustelua varten:

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

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

        # Määritä istunto
        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

        # Käynnistä kaappaus ja toisto rinnakkain
        await asyncio.gather(
            stream_microphone(ws),
            play_response_audio(ws)
        )

asyncio.run(conversation_vocale())

Samanaikaisten virtauksen hallinta

Kaksisuuntaisen suoratoiston haasteena on, että lähetät ja vastaanotat samanaikaisesti samaa WebSocket-yhteyttä pitkin. asyncio.gather käynnistää molemmat korutiinit rinnakkain, mutta ne jakavat saman WebSocket-olion. websockets-kirjasto käsittelee tämän samanaikaisuuden oikein.

Keskeiset asiat

  • Ääni lähetetään 24 kHz:n mono 16-bittisenä PCM-muotona, Base64-koodattuna JSON-tapahtumiin
  • Palat ovat tyypillisesti 20–100 ms:n pituisia hyvän viiveen ja yleiskustannusten tasapainottamiseksi
  • Palvelinpuolen äänipuskuri kerää paloja sitomiseen asti (automaattinen VAD-tilassa)
  • Vastauksen toisto tapahtuu pala kerrallaan response.output_audio.delta-tapahtumien kautta
  • asyncio.gather mahdollistaa samanaikaisen kaappauksen ja toiston samalla WebSocket-yhteydellä