Transkrypcje i strategie zatwierdzania

Omówienie

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

• Częściowe transkrypcje – tymczasowe wyniki transkrypcji
• Zatwierdzone transkrypcje – 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” ma wartość 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
))

Strategie zatwierdzania

Gdy wysyłasz fragmenty audio przez WebSocket, segmenty transkrypcji możesz zatwierdzać na dwa sposoby: ręcznie lub za pomocą wykrywania aktywności głosowej (VAD).

Ręczne zatwierdzanie

Przy ręcznej strategii 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. Dla lepszego opóźnienia warto zatwierdzać co 20–30 sekund. Nawet bez ręcznego zatwierdzania model automatycznie zatwierdzi tekst po około 36 sekundach zgromadzonego audio.

Aby uzyskać najlepsze wyniki, zatwierdzaj podczas ciszy lub w innym logicznym momencie, np. przy zmianie tury rozmowy.

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

Wysyłając 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 sieciowym – pozwala modelowi kontynuować transkrypcję, wykorzystując wcześniejszy tekst jako wskazówkę.
• 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)

Przy 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_v2_realtime",
  audioFormat: AudioFormat.PCM_16000,
  commitStrategy: CommitStrategy.VAD,
  vadSilenceThresholdSecs: 1.5,
  vadThreshold: 0.4,
  minSpeechDurationMs: 100,
  minSilenceDurationMs: 100,
});

Filtrowanie dźwięków w tle

Ustaw parametr zapytania filter_background_audio=true, aby ograniczyć fałszywe aktywacje powodowane mową w tle, na przykład rozmowami w pobliżu, oraz hałasem otoczenia. Przy włączonym filtrowaniu wykrywanie aktywności głosowej używa modelu dostrojonego do ignorowania mowy w tle, a vad_threshold ma domyślnie wartość 0.15, chyba że ustawisz ją samodzielnie.

Filtrowanie nie zmienia rozliczeń: naliczamy opłaty za całe przesyłane audio, także za audio 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 własny klient WebSocket, proxy lub load balancer po drodze zamyka połączenie, gdy przez jakiś czas nie nadejdą 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 10–15-sekundowymi przerwami. 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 powtórzenie najnowszego częściowego tekstu, jeśli go ma.

• Przyjmuje liczbę całkowitą od 500 do 10000 (milisekund). Domyślnie jest wyłączony; pomiń parametr, aby zachować obecne działanie.
• Wartości poza zakresem lub niecałkowite powodują, że serwer wysyła błąd invalid_request i zamyka połączenie.
• Keepalive zależą od rzeczywistego przetwarzania przesyłanego cichego audio przez model, a nie od niezależnego timera, więc potwierdzają też, że ścieżka transkrypcji działa.
• Audio jest przetwarzane w fragmentach trwających około 1 sekundy, więc keepalive docierają 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 dociera około 2 sekundy po jej rozpoczęciu, ponieważ serwer buforuje pierwsze ~2 sekundy audio przed transkrypcją. Ustaw interwał na maksymalnie 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 powtarza zamiast tego najnowszy częściowy tekst, więc nigdy nie czyści tekstu tymczasowego. Po zatwierdzeniu keepalive znów są puste, dopóki nie 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 rozliczenia poza audio, które już przesyłasz.
• Komunikat session_started w polu config zwraca keepalive_interval_ms (null, gdy jest wyłączony).

Dodaj parametr do adresu URL WebSocket:

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

Obsługiwane formaty audio

Dobre praktyki

Jakość audio

• Aby uzyskać najlepsze wyniki, użyj częstotliwości próbkowania 16 kHz — to optymalny balans jakości i przepustowości.
• Zadbaj o czysty sygnał audio z minimalnym hałasem w tle.
• Ustaw odpowiednie wzmocnienie mikrofonu, aby uniknąć przesterowania.
• Obecnie obsługiwane jest tylko audio mono.

Rozmiar fragmentów

• Dla płynnego streamingu wysyłaj fragmenty audio trwające od 0,1 do 1 sekundy.
• Mniejsze fragmenty dają niższe opóźnienie, ale większy narzut.
• Większe fragmenty są wydajniejsze, ale mogą zwiększyć opóźnienie.

Kolejne kroki