Transcripten en commitstrategieën

Overzicht

Bij het transcriberen van audio ontvang je gedeeltelijke en gecommitte transcripten.

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

Het committranscript kan optioneel tijdstempels op woordniveau bevatten. Je ontvangt dit alleen wanneer 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 audiochunks via de WebSocket verstuurt, kun je transcriptsegmenten op twee manieren committen: Manual Commit of Voice Activity Detection (VAD).

Handmatig committen

Met de handmatige commitstrategie bepaal je zelf wanneer je transcriptsegmenten commit. Dit is de standaardstrategie. Door een segment te committen, wis je het verwerkte verzamelde transcript en start je een nieuw segment zonder context te verliezen. Committen elke 20-30 seconden is een goede gewoonte om de latentie te verbeteren. Ook als je niet handmatig commit, commit het model automatisch na ongeveer 36 seconden verzamelde audio.

Voor de beste resultaten commit je tijdens stiltes of op een ander logisch moment, zoals bij 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 verstuurt, kun je samen met de eerste audiochunk eerdere tekstcontext versturen om het model te helpen de context van de spraak te begrijpen. Dit is nuttig in een aantal scenario’s:

• Agenttekst voor toepassingen met conversationele AI - Hiermee kan het model de context van het gesprek gemakkelijker begrijpen en betere transcripties maken.
• Opnieuw verbinden na een netwerkfout - Hierdoor kan het model doorgaan met transcriberen, waarbij de eerdere tekst als leidraad wordt gebruikt.
• Algemene contextuele informatie - Een korte beschrijving waar de transcriptie over zal gaan, 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 stiltsegmenten. Wanneer een stiltedrempel wordt bereikt, commit de transcriptie-engine het transcriptsegment automatisch.

Wanneer je audio vanaf de microfoon transcribeert in de client-side-integratie, raden we aan de VAD-strategie te gebruiken.

vad_silence_threshold_secs accepteert 0.192 tot 3.0 seconden. De JavaScript- en React-SDK’s accepteren alleen 0.3 tot 3.0.

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,
});

Achtergrondaudio filteren

Stel de queryparameter filter_background_audio=true in om valse activeringen door achtergrondspraak, zoals gesprekken in de buurt, en omgevingsgeluid te verminderen. Als filtering is ingeschakeld, gebruikt spraakactiviteitsdetectie een model dat is afgestemd op het negeren van achtergrondspraak en is vad_threshold standaard ingesteld op 0.15, tenzij je dit zelf instelt.

Filtering verandert niets aan de facturering: alle audio die je streamt, wordt gefactureerd, inclusief audio die het filter negeert.

De verbinding actief houden tijdens stilte

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 ertussen, de verbinding sluit wanneer er een tijdlang geen frames binnenkomen, geef dan bij het verbinden de optionele queryparameter keepalive_interval_ms mee. Dit is belangrijk tijdens lange stiltes, bijvoorbeeld bij een telefoongesprek met pauzes van 10-15 seconden. Ongeveer eenmaal per interval verzendt de server een keepalive-partial_transcript: leeg (text: "") als het huidige segment geen niet-gecommitte tekst bevat, of een herhaling van de nieuwste gedeeltelijke tekst als dat wel zo is.

• Accepteert een geheel getal tussen 500 en 10000 (milliseconden). Standaard is dit 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 verstuurt en de verbinding sluit.
• Keepalives worden aangestuurd doordat het model de stille audio die je verstuurt daadwerkelijk verwerkt, niet door een vrijlopende timer. Daardoor bevestigen ze ook dat het transcriptiepad actief is.
• Audio wordt verwerkt in chunks van ongeveer 1 seconde, dus keepalives arriveren ongeveer eenmaal per interval, afgerond op dat ritme (bijvoorbeeld: 1000 wordt ongeveer eenmaal per seconde geactiveerd, 3000 ongeveer eenmaal per 3 seconden). De eerste keepalive van een sessie arriveert ongeveer 2 seconden nadat deze is gestart, omdat de server de eerste ~2 seconden audio buffert voordat deze wordt getranscribeerd. Stel je interval in op maximaal ongeveer een derde van je eigen leestime-out om marge over te laten.
• De text van een keepalive is alleen leeg wanneer het huidige segment nog geen niet-gecommitte tekst bevat. Als er een pauze plaatsvindt na spraak maar vóór een commit — het duidelijkst zichtbaar met filter_background_audio=true of in de handmatige commitmodus zonder te committen — herhaalt de keepalive in plaats daarvan de nieuwste gedeeltelijke tekst, zodat tussentijdse tekst nooit wordt gewist. Na een commit zijn keepalives weer leeg totdat 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 buiten de audio die je al streamt.
• De config in het bericht session_started geeft keepalive_interval_ms terug (null wanneer dit is 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 audioformaten

Best practices

Audiokwaliteit

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

Chunkgrootte

• Verstuur audiochunks met een lengte van 0,1 - 1 seconde voor soepele streaming.
• Kleinere chunks zorgen voor lagere latentie, maar meer overhead.
• Grotere chunks zijn efficiënter, maar kunnen latentie veroorzaken.

Volgende stappen