Strumieniowanie w czasie rzeczywistym
Na tej stronie
Kurs zaktualizowano 3 listopada 2026 r. dla Voxtral TTS 3, na podstawie przewodnika Migrate from Voxtral 2 oraz dokumentacji Mistral Text to Speech: model
voxtral-mini-tts-2603, wycofany 31 października 2026 r. i całkowicie usunięty 30 kwietnia 2027 r., został zastąpiony w przykładach modelemvoxtral-mini-tts-3-0. Predefiniowane głosy z Voxtral 2 (gb_jane_neutral…) są nadal obsługiwane; Voxtral 3 wprowadza tagi[emotion=…]i[pace=…]w tekście, ustawienieexpressiveness, niestandardową wymowę (phoneme_hints) oraz obsługę 35 języków. Mistral zaleca ponowne zmierzenie opóźnień po migracji. Źródła: Migrate from Voxtral 2 · Speech generation.
Dlaczego strumieniowanie zmienia wszystko
Do tej pory pracowałeś w trybie synchronicznym: wysyłałeś tekst, czekałeś na całkowite zakończenie syntezy, a dopiero potem otrzymywałeś pełny plik audio. W przypadku powitania wygenerowanego dzień wcześniej to oczekiwanie nie ma znaczenia. Dla asystenta głosowego odpowiadającego klientowi przez telefon jest to jednak problem krytyczny – dwie sekundy ciszy po zadaniu pytania sprawiają, że użytkownik myśli, iż połączenie zostało zerwane.
Strumieniowanie eliminuje to oczekiwanie. Audio jest wysyłane w miarę generowania, fragment po fragmencie, dzięki czemu użytkownik słyszy pierwsze słowa, gdy model wciąż produkuje koniec zdania. Całkowity czas generowania się nie zmienia; to, co ulega skróceniu, to opóźnienie przed pojawieniem się pierwszego dźwięku.
Protokół zdarzeń
Strumień opiera się na zdarzeniach Server-Sent Events (SSE). Każda otrzymana wiadomość jest zdarzeniem określonego typu, a dwa z nich są dla Ciebie kluczowe:
speech.audio.delta: zawiera fragment audio zakodowany w base64. To główne zdarzenie, którym będziesz się zajmować.speech.audio.done: sygnał końca – generowanie zostało zakończone.
Po stronie kodu przejście na tryb strumieniowy oznacza dodanie parametru stream=True i przetwarzanie odpowiedzi w bloku with. Poniższy przykład gromadzi fragmenty w pamięci, aby zapisać plik na końcu: nie jest to jeszcze rozwiązanie czasu rzeczywistego, ale stanowi strukturę pętli, na której będziemy budować w dalszej części lekcji.
import base64
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
audio_chunks = []
with client.audio.speech.complete(
model="voxtral-mini-tts-3-0",
input="Streaming makes voice agents responsive and natural.",
voice_id="your-voice-id",
response_format="opus",
stream=True,
) as stream:
for event in stream:
if event.event == "speech.audio.delta":
chunk = base64.b64decode(event.data.audio_data)
audio_chunks.append(chunk)
print(f"Chunk received: {len(chunk)} bytes")
# Assemble all chunks
audio_complet = b"".join(audio_chunks)
Path("streaming-output.opus").write_bytes(audio_complet)
print(f"Final audio: {len(audio_complet)} bytes")
Odtwarzanie dźwięku w miarę jego napływania
Aby osiągnąć obiecaną responsywność, przestań gromadzić dane i zapisuj każdy fragment bezpośrednio do karty dźwiękowej. Przy użyciu biblioteki pyaudio zmiana sprowadza się do jednej linii: zamiast dodawać zdekodowany fragment do listy, wysyłasz go do strumienia wyjściowego otwartego wcześniej, skonfigurowanego dla mono Float32 przy częstotliwości 24 000 Hz.
import base64
import pyaudio
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# PCM audio configuration (fastest format)
p = pyaudio.PyAudio()
stream_audio = p.open(
format=pyaudio.paFloat32,
channels=1,
rate=24000,
output=True,
)
with client.audio.speech.complete(
model="voxtral-mini-tts-3-0",
input="You're hearing this sentence while I generate it.",
voice_id="your-voice-id",
response_format="pcm",
stream=True,
) as stream:
for event in stream:
if event.event == "speech.audio.delta":
audio_data = base64.b64decode(event.data.audio_data)
stream_audio.write(audio_data)
stream_audio.stop_stream()
stream_audio.close()
p.terminate()
Żądany format zmienił się z opus na pcm i ma to istotne znaczenie. PCM nie wymaga dekodowania: otrzymane bajty są gotowe do natychmiastowego odtworzenia, co czyni ten format rekomendowanym do zastosowań w czasie rzeczywistym.
Przekazywanie strumienia do przeglądarki
W aplikacji internetowej serwer nie odtwarza dźwięku – przekazuje go dalej. Klasyczny wzorzec wykorzystuje WebSocket, który odbiera tekst z przeglądarki, otwiera strumień Voxtral i pushuje każdy zdekodowany fragment z powrotem do klienta. Po stronie przeglądarki interfejs Web Audio API przejmuje kontrolę, aby odtwarzać otrzymane fragmenty PCM.
# Server side (FastAPI example)
from fastapi import FastAPI, WebSocket
import base64
from mistralai.client import Mistral
app = FastAPI()
client = Mistral(api_key="your-api-key")
@app.websocket("/ws/tts")
async def tts_websocket(websocket: WebSocket):
await websocket.accept()
texte = await websocket.receive_text()
with client.audio.speech.complete(
model="voxtral-mini-tts-3-0",
input=texte,
voice_id="your-voice-id",
response_format="pcm",
stream=True,
) as stream:
for event in stream:
if event.event == "speech.audio.delta":
await websocket.send_bytes(
base64.b64decode(event.data.audio_data)
)
await websocket.close()
Ustawienie, które robi różnicę: bufor
Rozmiary fragmentów są zmienne i zazwyczaj reprezentują kilka milisekund audio każdy. Jeśli zaczniesz odtwarzać pierwszy fragment w momencie jego nadejścia, każda nieregularność sieciowa spowoduje słyszalne mikro-przerwanie – „czkawkę“ w głosie, która natychmiast zdradzi maszynę. Rozwiązaniem jest buforowanie dwóch lub trzech fragmentów przed rozpoczęciem odtwarzania. Kosztuje to kilkadziesiąt milisekund, ale wygładza resztę strumienia.
Istotny jest również wybór formatu, który stanowi kompromis między opóźnieniem a przepustowością. PCM dostarcza pierwszy dźwięk najszybciej – około 0,7 sekundy według pomiarów wykonanych dla Voxtral 2 (należy je powtórzyć dla Voxtral TTS 3) – kosztem wysokiego zużycia przepustowości. Opus nieco przegrywa pod względem opóźnienia, ale mocno kompresuje dane, co czyni go właściwym kompromisem, gdy Twoi użytkownicy korzystają z urządzeń mobilnych.
Kluczowe wnioski
- Strumieniowanie wysyła audio fragment po fragmencie w trakcie generowania.
- Włączasz je, dodając
stream=Truew wywołaniuaudio.speech.complete(). - Zdarzenia
speech.audio.deltazawierają fragmenty audio zakodowane w base64. - Format PCM oferuje najniższe opóźnienie dla strumieniowania (~0,7 s w porównaniu do ~2 s dla MP3).
- Do odtwarzania w czasie rzeczywistym użyj
pyaudiolub połączenia WebSocket z Web Audio API.