Transkrypcje i strategie zatwierdzania

Omówienie

Podczas transkrypcji audio otrzymujesz transkrypcje częściowe i zatwierdzone.

• Transkrypcje częściowe - tymczasowe wyniki transkrypcji
• Transkrypcje zatwierdzone - końcowe wyniki segmentu transkrypcji wysyłane po otrzymaniu komunikatu „commit”. Sesja może zawierać wiele zatwierdzonych transkrypcji.

Zatwierdzona transkrypcja może opcjonalnie zawierać znaczniki czasu na poziomie słów. Otrzymasz je tylko wtedy, gdy opcja „include timestamps” jest ustawiona na true.

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

Strategie zatwierdzania

Podczas wysyłania fragmentów audio przez WebSocket segmenty transkrypcji można zatwierdzać na trzy sposoby: ręcznie, za pomocą wykrywania aktywności głosowej (VAD) lub przewidywania tury. Przewidywanie tury jest dostępne tylko w Scribe v3 Live.

Ręczne zatwierdzanie

W strategii ręcznego zatwierdzania to ty decydujesz, kiedy zatwierdzić segmenty transkrypcji. Jest to strategia używana domyślnie. Zatwierdzenie segmentu wyczyści przetworzoną, zgromadzoną transkrypcję i rozpocznie nowy segment bez utraty kontekstu. Aby skrócić opóźnienia, warto zatwierdzać segmenty co 20–30 sekund. Nawet jeśli nie zatwierdzisz ich ręcznie, model automatycznie robi to po około 36 sekundach zgromadzonego audio.

Aby uzyskać najlepsze wyniki, zatwierdzaj podczas ciszy lub w innym logicznym momencie, na przykład na końcu tury.

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

Wysyłanie kontekstu wcześniejszego tekstu

Podczas wysyłania audio do transkrypcji możesz wraz z pierwszym fragmentem audio wysłać kontekst wcześniejszego tekstu, aby pomóc modelowi zrozumieć kontekst wypowiedzi. Przydaje się to w kilku sytuacjach:

• Tekst agenta w zastosowaniach konwersacyjnej AI - pozwala modelowi łatwiej zrozumieć kontekst rozmowy i tworzyć lepsze transkrypcje.
• Ponowne połączenie po błędzie sieci - pozwala modelowi kontynuować transkrypcję, używając wcześniejszego tekstu jako wskazówki.
• Ogólne informacje kontekstowe - krótki opis tematu transkrypcji pomaga modelowi zrozumieć kontekst.

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

Wykrywanie aktywności głosowej (VAD)

W strategii VAD silnik transkrypcji automatycznie wykrywa segmenty mowy i ciszy. Po osiągnięciu progu ciszy silnik automatycznie zatwierdza segment transkrypcji.

Podczas transkrypcji audio z mikrofonu w integracji po stronie klienta zalecamy użycie strategii VAD.

vad_silence_threshold_secs przyjmuje wartości od 0.192 do 3.0 sekundy. SDK JavaScript i React przyjmują tylko wartości od 0.3 do 3.0.

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

Przewidywanie tury

Krótki próg ciszy VAD może urwać wypowiedź mówcy podczas pauzy, a długi dodaje opóźnienie przed każdym zatwierdzeniem. Przewidywanie tury wykorzystuje kontekst rozmowy, a nie tylko ciszę, aby ocenić, czy mówca zakończył swoją turę. Osoba, która robi pauzę w połowie podawania numeru telefonu, ma mniejsze ryzyko, że jej wypowiedź zostanie przerwana.

Scribe v3 Live zawiera turn_probability, czyli szacowane prawdopodobieństwo, że mówca zakończył swoją turę, w każdym komunikacie partial_transcript:

{
  "message_type": "partial_transcript",
  "text": "My phone number is 415",
  "turn_probability": 0.08
}

Przy commit_strategy=turn_prediction serwer zatwierdza bieżący segment, gdy częściowa transkrypcja osiągnie turn_probability równe 0.9 lub wyższe. VAD pozostaje aktywny, więc serwer zatwierdza segment także po osiągnięciu progu ciszy vad_silence_threshold_secs. Parametry VAD (vad_silence_threshold_secs, vad_threshold, min_speech_duration_ms i min_silence_duration_ms) działają przy przewidywaniu tury tak samo jak przy VAD.

Domyślną strategią zatwierdzania dla każdego modelu, w tym Scribe v3 Live, jest manual. Aby włączyć przewidywanie tury, ustaw jawnie commit_strategy=turn_prediction.

wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v3_live&audio_format=pcm_16000&commit_strategy=turn_prediction

turn_probability jest wysyłane przy każdej strategii zatwierdzania, gdy modelem jest Scribe v3 Live. Przy strategii manual możesz je odczytać, aby zdecydować, kiedy zatwierdzić segment we własnej aplikacji.

Filtrowanie audio w tle

Ustaw parametr zapytania filter_background_audio=true, aby ograniczyć fałszywe aktywacje wywołane mową w tle, na przykład pobliskimi rozmowami, oraz szumem otoczenia. Gdy filtrowanie jest włączone, wykrywanie aktywności głosowej używa modelu dostrojonego do ignorowania mowy w tle, a vad_threshold domyślnie wynosi 0.15, chyba że ustawisz go samodzielnie.

Filtrowanie nie zmienia rozliczenia: naliczamy opłatę za całe przesyłane strumieniowo audio, także to ignorowane przez filtr.

Utrzymywanie połączenia podczas ciszy

Oficjalne SDK nie zrywają połączenia, gdy nie przychodzą komunikaty, więc większość integracji tego nie potrzebuje. Jeśli twój własny klient WebSocket albo pośredniczący proxy lub load balancer zamyka połączenie, gdy przez pewien czas nie przychodzą ramki, podczas łączenia przekaż opcjonalny parametr zapytania keepalive_interval_ms. Ma to znaczenie podczas długich okresów ciszy, na przykład w rozmowie telefonicznej z pauzami 10–15 sekund. Mniej więcej raz na interwał serwer wysyła utrzymujący połączenie partial_transcript: pusty (text: ""), jeśli bieżący segment nie ma niezatwierdzonego tekstu, lub z powtórzonym najnowszym tekstem częściowym, jeśli go ma.

• Przyjmuje liczbę całkowitą od 500 do 10000 (milisekundy). Domyślnie jest wyłączony; pomiń parametr, aby zachować obecne działanie.
• Wartości spoza zakresu lub niecałkowite powodują, że serwer wysyła błąd invalid_request i zamyka połączenie.
• Keepalive zależą od faktycznego przetwarzania przez model wysyłanego przez ciebie cichego audio, a nie od niezależnego timera, więc potwierdzają też, że ścieżka transkrypcji działa.
• Audio jest przetwarzane w porcjach około 1-sekundowych, dlatego keepalive przychodzą mniej więcej raz na interwał zaokrąglony do tego rytmu (na przykład 1000 uruchamia się około raz na sekundę, a 3000 około raz na 3 sekundy). Pierwszy keepalive sesji przychodzi około 2 sekund po jej rozpoczęciu, ponieważ serwer buforuje pierwsze ~2 sekundy audio przed transkrypcją. Ustaw interwał na co najwyżej około jedną trzecią własnego limitu czasu odczytu, aby zachować margines.
• text keepalive jest pusty tylko wtedy, gdy bieżący segment nie ma jeszcze niezatwierdzonego tekstu. Jeśli pauza nastąpi po mowie, ale przed zatwierdzeniem — co jest najbardziej widoczne przy filter_background_audio=true lub w trybie ręcznego zatwierdzania bez zatwierdzania — keepalive zamiast tego powtarza najnowszy tekst częściowy, więc nigdy nie czyści tekstu tymczasowego. Po zatwierdzeniu keepalive znów są puste, aż pojawi się nowa mowa.
• Działa zarówno z commit_strategy=manual, jak i commit_strategy=vad, oraz z filter_background_audio=true. Nie wpływa na rozliczenie poza audio, które już przesyłasz strumieniowo.
• config w komunikacie session_started zwraca keepalive_interval_ms (null, gdy parametr jest wyłączony).

Dodaj parametr do adresu URL WebSocket:

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

Obsługiwane formaty audio

Dobre praktyki

Jakość audio

• Aby uzyskać najlepsze wyniki, używaj częstotliwości próbkowania 16 kHz, która zapewnia optymalną równowagę między jakością a przepustowością.
• Zadbaj o czysty dźwięk wejściowy z minimalnym szumem w tle.
• Używaj odpowiedniego wzmocnienia mikrofonu, aby uniknąć przesterowania.
• Obecnie obsługiwane jest tylko audio mono.

Rozmiar fragmentu

• Aby zapewnić płynne przesyłanie strumieniowe, wysyłaj fragmenty audio o długości 0.1–1 sekundy.
• Mniejsze fragmenty zmniejszają opóźnienie, ale zwiększają narzut.
• Większe fragmenty są wydajniejsze, ale mogą wprowadzać opóźnienie.

Kolejne kroki