Sprekerdiarisatie

Overzicht

Sprekerdiarisatie wijst spreker-ID’s toe aan woorden, zodat je kunt onderscheiden wie wat heeft gezegd. Als diarisatie is ingeschakeld, bevatten gedeeltelijke transcripten voorlopige sprekerlabels en wordt elk vastgelegd transcript gevolgd door een afzonderlijke diarized_transcript-gebeurtenis. Sprekerlabels kunnen veranderen wanneer er meer audio binnenkomt.

Diarisatie inschakelen

Stel de booleaanse queryparameter diarize=true in wanneer je een WebSocket-verbinding opent met model_id=scribe_v3_live. Diarisatie staat standaard op false.

De volgende server-side voorbeelden openen een verbinding en ontvangen gebeurtenissen. Installeer websockets voor Python, of ws en de ontwikkelingsafhankelijkheid @types/ws voor TypeScript. Stel ELEVENLABS_API_KEY in de omgeving van je server in; de voorbeelden versturen deze in de header xi-api-key. Bewaar deze sleutel op de server, niet in browsercode.

Deze voorbeelden sturen geen audio. Integreer ze met je audiobron uit de handleiding voor server-side streaming: stuur input_audio_chunk-berichten via dezelfde verbinding terwijl je gebeurtenissen ontvangt. De voorbeelden selecteren pcm_16000, dus gebruik overeenkomende audio. Voer in Python de taak voor het versturen van audio gelijktijdig uit met de ontvanglus; stuur in TypeScript audio nadat de verbinding is geopend.

import asyncio
import json
import os
from websockets.asyncio.client import connect
async def main():
    url = (
        "wss://api.elevenlabs.io/v1/speech-to-text/realtime"
        "?model_id=scribe_v3_live&audio_format=pcm_16000&diarize=true"
    )
    headers = {"xi-api-key": os.environ["ELEVENLABS_API_KEY"]}
    async with connect(url, additional_headers=headers) as websocket:
        async for message in websocket:
            event = json.loads(message)
            print(event)
if __name__ == "__main__":
    asyncio.run(main())

Gebeurtenissen verwerken

Gedeeltelijke transcripten

Als diarisatie is ingeschakeld, bevat elk partial_transcript voorlopige words met dezelfde woordstructuur als batchtranscriptie. De speaker_id van elk woord is speaker_0, speaker_1, enzovoort zodra een spreker is geïdentificeerd, of null zolang dit nog niet is vastgesteld.

Behandel deze woorden als voorlopig: spreker-ID’s en tijdstempels kunnen veranderen met meer audio. Woorden die nog niet zijn uitgelijnd, hebben geen tijdstempels (start en end zijn null of ontbreken).

Vastgelegde en gediariseerde transcripten

Diarisatie vertraagt committed_transcript niet. Als diarisatie is ingeschakeld, voegt deze gebeurtenis een op nul gebaseerde gehele segment_index toe:

{
  "message_type": "committed_transcript",
  "segment_index": 0,
  "text": "Hello."
}

Elke vastlegging wordt gevolgd door een afzonderlijke diarized_transcript-gebeurtenis met de overeenkomende segment_index, text en words:

{
  "message_type": "diarized_transcript",
  "segment_index": 0,
  "text": "Hello.",
  "words": [
    {
      "text": "Hello.",
      "speaker_id": "speaker_0"
    }
  ]
}

Het woord hierboven toont alleen de tekst en het sprekerlabel. De volledige woordstructuur gebruikt dezelfde velden start, end, type, logprob en characters als batchtranscriptie, naast speaker_id. Een niet-vastgestelde spreker heeft een null-spreker-ID.

Gediariseerde transcripten worden in de volgorde van vastlegging verstuurd. Koppel ze aan vastgelegde transcripten met segment_index, niet op basis van tekst of de volgende ontvangen gebeurtenis. Voor elke vastlegging wordt altijd een diarized_transcript verstuurd, zelfs als sprekeridentificatie mislukt; in dat geval zijn niet-vastgestelde spreker-ID’s null.

Sprekers samenvoegen

Een speakers_merged-gebeurtenis betekent dat twee spreker-ID’s naar dezelfde persoon verwijzen:

{
  "message_type": "speakers_merged",
  "from_speaker_id": "speaker_1",
  "to_speaker_id": "speaker_0"
}

Vervang elk eerder gebruik van from_speaker_id door to_speaker_id in zowel gedeeltelijke als gediariseerde transcripten. Spreker-ID’s worden nooit opnieuw gebruikt. Samenvoegingen kunnen worden gekoppeld, dus pas ze toe in de volgorde waarin je ze ontvangt: als speaker_2 wordt samengevoegd met speaker_1 en daarna speaker_1 met speaker_0, moeten alle eerdere woorden van beide ID’s uiteindelijk het label speaker_0 krijgen.

Roep bijvoorbeeld deze handler aan voor elke ontvangen gebeurtenis. Hier bewaart transcript_history elk gedeeltelijk en gediariseerd transcript dat door de applicatie wordt bewaard, inclusief eerdere gedeeltelijke snapshots. Elke samenvoeging werkt alle opgeslagen woorden ter plaatse bij, zodat gekoppelde samenvoegingen ook eerder samengevoegde woorden bijwerken. Geef sprekerlabels weer vanuit deze bijgewerkte opslag; null-labels blijven null.

transcript_history = []
def handle_event(event):
    if event["message_type"] in ("partial_transcript", "diarized_transcript"):
        transcript_history.append(event)
    elif event["message_type"] == "speakers_merged":
        for transcript in transcript_history:
            for word in transcript.get("words") or []:
                if word.get("speaker_id") == event["from_speaker_id"]:
                    word["speaker_id"] = event["to_speaker_id"]

Beperkingen

• Diarisatie wordt alleen ondersteund door scribe_v3_live. Andere modellen retourneren een invalid_request-fout met het bericht "The 'diarize' parameter is only supported by scribe_v3_live.", waarna de verbinding wordt gesloten.
• Diarisatie kan niet worden gecombineerd met filter_background_audio. Deze combinatie retourneert een invalid_request-fout met een bericht dat "cannot be combined with filter_background_audio" bevat, waarna de verbinding wordt gesloten.
• Sprekerlabels kunnen niet-vastgesteld blijven (null) en latere speakers_merged-gebeurtenissen kunnen eerdere labels aanpassen. Deze samenvoeggebeurtenissen worden alleen verstuurd wanneer diarisatie is ingeschakeld.