Transcripten en commitstrategieën

Overzicht

Tijdens het transcriberen van audio ontvang je gedeeltelijke en vastgelegde transcripten.

• Gedeeltelijke transcripten - de tussentijdse resultaten van de transcriptie
• Vastgelegde transcripten - de definitieve resultaten van het transcriptiesegment die worden verzonden wanneer een “commit”-bericht wordt ontvangen. Een sessie kan meerdere vastgelegde transcripten hebben.

Het vastgelegde transcript kan optioneel tijdstempels op woordniveau bevatten. Dit ontvang je alleen als de optie “include timestamps” is ingesteld op true.

# Initialize the connection
connection = await elevenlabs.speech_to_text.realtime.connect(RealtimeUrlOptions(
  model_id="scribe_v2_realtime",
  include_timestamps=True, # Include this to receive the RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS event with word-level timestamps
))

Commitstrategieën

Wanneer je audioblokken via de WebSocket verstuurt, kunnen transcriptsegmenten op twee manieren worden vastgelegd: handmatige commit of Voice Activity Detection (VAD).

Handmatige commit

Met de handmatige commitstrategie bepaal je zelf wanneer je transcriptsegmenten vastlegt. Dit is de standaardstrategie. Door een segment vast te leggen, wordt het verwerkte verzamelde transcript gewist en begint een nieuw segment zonder context te verliezen. Om de latentie te verbeteren, kun je het beste elke 20 tot 30 seconden vastleggen. Ook als je niet handmatig vastlegt, legt het model automatisch vast na ongeveer 36 seconden verzamelde audio.

Voor de beste resultaten leg je vast tijdens stiltes of op een ander logisch moment, zoals een beurtwisseling.

await connection.send({
  "audio_base_64": audio_base_64,
  "sample_rate": 16000,
})
# When ready to finalize the segment
await connection.commit()

Eerdere tekstcontext verzenden

Wanneer je audio voor transcriptie verzendt, kun je samen met het eerste audioblok eerdere tekstcontext meesturen om het model te helpen de context van de spraak te begrijpen. Dit is nuttig in enkele scenario’s:

• Agenttekst voor use cases met conversationele AI - Hiermee kan het model de context van het gesprek gemakkelijker begrijpen en betere transcripties maken.
• Opnieuw verbinding maken na een netwerkfout - Hiermee kan het model doorgaan met transcriberen, waarbij de eerdere tekst als richtlijn wordt gebruikt.
• Algemene contextuele informatie - Een korte beschrijving van waar de transcriptie over gaat, helpt het model de context te begrijpen.

await connection.send({
  "audio_base_64": audio_base_64,
  "previous_text": "The previous text context",
})

Voice Activity Detection (VAD)

Met de VAD-strategie detecteert de transcriptie-engine automatisch spraak- en stiltefragmenten. Wanneer een stiltedrempel wordt bereikt, legt de transcriptie-engine het transcriptsegment automatisch vast.

Bij het transcriberen van microfoonaudio in de client-side-integratie raden we aan de VAD-strategie te gebruiken.

import { Scribe, AudioFormat, CommitStrategy } from "@elevenlabs/client";
const connection = Scribe.connect({
  token: "sutkn_1234567890",
  modelId: "scribe_v2_realtime",
  audioFormat: AudioFormat.PCM_16000,
  commitStrategy: CommitStrategy.VAD,
  vadSilenceThresholdSecs: 1.5,
  vadThreshold: 0.4,
  minSpeechDurationMs: 100,
  minSilenceDurationMs: 100,
});

De verbinding tijdens stiltes actief houden

De officiële SDK’s verbreken de verbinding niet als er geen berichten binnenkomen, dus de meeste integraties hebben dit niet nodig. Als je eigen WebSocket-client, of een proxy of load balancer daartussen, de verbinding sluit wanneer er enige tijd geen frames binnenkomen, geef dan bij het verbinden de optionele queryparameter keepalive_interval_ms door. Dit is belangrijk tijdens lange stiltes, bijvoorbeeld bij een telefoongesprek met pauzes van 10 tot 15 seconden. Ongeveer eenmaal per interval stuurt de server een keepalive-partial_transcript: leeg (text: "") als het huidige segment geen niet-vastgelegde tekst heeft, of een herhaling van de meest recente gedeeltelijke tekst als dat wel het geval is.

• Accepteert een geheel getal tussen 500 en 10000 (milliseconden). Standaard is deze optie uitgeschakeld; laat de parameter weg om het bestaande gedrag te behouden.
• Waarden buiten het bereik of niet-gehele waarden zorgen ervoor dat de server een invalid_request-fout stuurt en de verbinding sluit.
• Keepalives worden aangestuurd doordat het model de stille audio die je verzendt daadwerkelijk verwerkt, niet door een vrijlopende timer. Ze bevestigen dus ook dat het transcriptiepad actief is.
• Audio wordt verwerkt in blokken van ongeveer 1 seconde, dus keepalives komen ongeveer eenmaal per interval binnen, afgerond op die cadans (bijvoorbeeld: 1000 wordt ongeveer eenmaal per seconde geactiveerd, 3000 ongeveer eenmaal per 3 seconden). De eerste keepalive van een sessie komt ongeveer 2 seconden na het begin binnen, omdat de server de eerste ~2 seconden audio buffert voordat hij transcribeert. Stel je interval in op maximaal ongeveer een derde van je eigen read timeout, zodat je marge overhoudt.
• De text van een keepalive is alleen leeg wanneer het huidige segment nog geen niet-vastgelegde tekst heeft. Als er een pauze is na spraak maar vóór een commit — vooral zichtbaar met filter_background_audio=true of in de handmatige commitmodus zonder vast te leggen — herhaalt de keepalive in plaats daarvan de meest recente gedeeltelijke tekst, zodat tussentijdse tekst nooit wordt gewist. Na een commit zijn keepalives weer leeg totdat er nieuwe spraak binnenkomt.
• Werkt met zowel commit_strategy=manual als commit_strategy=vad, en met filter_background_audio=true. Heeft geen invloed op de facturering, behalve voor de audio die je al streamt.
• De config in het bericht session_started geeft keepalive_interval_ms terug (null wanneer uitgeschakeld).

Voeg de parameter toe aan de WebSocket-URL:

wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v2_realtime&commit_strategy=vad&keepalive_interval_ms=1000

Ondersteunde audioformats

Best practices

Audiokwaliteit

• Gebruik voor de beste resultaten een samplefrequentie van 16 kHz voor een optimale balans tussen kwaliteit en bandbreedte.
• Zorg voor een schone audio-input met minimale achtergrondruis.
• Gebruik een geschikte microfoonversterking om clipping te voorkomen.
• Op dit moment wordt alleen mono-audio ondersteund.

Blokgrootte

• Verzend audioblokken met een duur van 0,1 tot 1 seconde voor soepel streaming.
• Kleinere blokken zorgen voor lagere latentie, maar meer overhead.
• Grotere blokken zijn efficiënter, maar kunnen latentie veroorzaken.

Volgende stappen