> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Transkrypcje i strategie zatwierdzania

> **Note**
>
> **Przewodnik krok po kroku** · Zakłada, że masz już za sobą przewodnik dotyczący
> [streamingu po stronie klienta](/docs/pl/eleven-api/guides/how-to/speech-to-text/realtime/client-side-streaming) lub
> [streamingu po stronie serwera](/docs/pl/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming).

## 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`.

```python
# 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
))
```

```typescript
// Initialize the connection
const connection = await elevenlabs.speechToText.realtime.connect({
  modelId: "scribe_v2_realtime",
  includeTimestamps: true, // Include this to receive the RealtimeEvents.COMMITTED_TRANSCRIPT_WITH_TIMESTAMPS event with word-level timestamps
});
```

**`React`**

```typescript title="React"
const connection = useScribe({
  modelId: "scribe_v2_realtime",
  // Configuring this callback will automatically set the `includeTimestamps` option to `true`
  onCommittedTranscriptWithTimestamps: (data) => {
    console.log("Committed with timestamps:", data.text);
    console.log("Timestamps:", data.words);
  },
});
```

**`JavaScript`**

```typescript title="JavaScript"
const connection = Scribe.connect({
  modelId: "scribe_v2_realtime",
  includeTimestamps: 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.

> **Info**
>
> Przetwarzanie transkrypcji zaczyna się po wysłaniu pierwszych 2 sekund audio.

```python
await connection.send({
  "audio_base_64": audio_base_64,
  "sample_rate": 16000,
})

# When ready to finalize the segment
await connection.commit()
```

```typescript
connection.send({
  audioBase64: audioBase64,
  sampleRate: 16000,
});

// When ready to finalize the segment
connection.commit();
```

> **Warning**
>
> Kilkukrotne ręczne zatwierdzanie w krótkim czasie może pogorszyć działanie modelu.

#### 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.

> **Warning**
>
> Kontekst `previous_text` możesz wysłać tylko z pierwszym fragmentem audio przez
> `connection.send()`. Wysłanie go w kolejnych fragmentach spowoduje błąd. Wcześniejszy tekst działa
> najlepiej, gdy ma mniej niż *50* znaków.

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

```typescript
connection.send({
  audioBase64: audioBase64,
  previousText: "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](/docs/pl/eleven-api/guides/how-to/speech-to-text/realtime/client-side-streaming) 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.

**`Klient`**

```typescript title="Klient"
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,
});
```

```python
from dotenv import load_dotenv
from elevenlabs import AudioFormat, CommitStrategy, ElevenLabs, RealtimeAudioOptions

load_dotenv()

elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY"))

connection = await elevenlabs.speech_to_text.realtime.connect(
    RealtimeAudioOptions(
        model_id="scribe_v2_realtime",
        audio_format=AudioFormat.PCM_16000,
        commit_strategy=CommitStrategy.VAD,
        vad_silence_threshold_secs=1.5,
        vad_threshold=0.4,
        min_speech_duration_ms=100,
        min_silence_duration_ms=100,
    )
)
```

**`TypeScript`**

```typescript title="TypeScript"
import { ElevenLabsClient, AudioFormat, CommitStrategy } from '@elevenlabs/elevenlabs-js';

const elevenlabs = new ElevenLabsClient();

const connection = await elevenlabs.speechToText.realtime.connect({
  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.

> **Warning**
>
> `filter_background_audio` nie można łączyć z `include_timestamps`. Jeśli ustawisz oba parametry, serwer
> wyśle błąd `invalid_request` i zamknie połączenie.

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.

> **Warning**
>
> Keepalive nie jest niezależnym pingiem: musisz nadal przesyłać audio (ramki ciszy są w porządku).
> Jeśli przestaniesz wysyłać audio, keepalive nie będą wysyłane, a serwer zamknie połączenie po 15
> sekundach bez komunikatów klienta. Tego limitu serwera nie można skonfigurować.

* 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).

> **Info**
>
> Pusty `partial_transcript` (`text: ""`) oznacza „brak mowy w bieżącym segmencie”. Powtórzony,
> identyczny `partial_transcript` podczas pauzy także jest keepalive — klienci powinni po prostu wyświetlać
> częściowe transkrypcje jak dotąd, zamiast specjalnie obsługiwać powtórzenie.

Dodaj parametr do adresu URL WebSocket:

```text
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

| Format    | Częstotliwość próbkowania | Opis                                    |
| --------- | ------------------------- | --------------------------------------- |
| pcm_8000  | 8 kHz                     | 16-bitowy PCM, little-endian            |
| pcm_16000 | 16 kHz                    | 16-bitowy PCM, little-endian (zalecane) |
| pcm_22050 | 22.05 kHz                 | 16-bitowy PCM, little-endian            |
| pcm_24000 | 24 kHz                    | 16-bitowy PCM, little-endian            |
| pcm_44100 | 44.1 kHz                  | 16-bitowy PCM, little-endian            |
| pcm_48000 | 48 kHz                    | 16-bitowy PCM, little-endian            |
| ulaw_8000 | 8 kHz                     | 8-bitowe kodowanie μ-law                |

## 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

#### [Streaming po stronie serwera](/docs/pl/eleven-api/guides/how-to/speech-to-text/realtime/server-side-streaming)

Skonfiguruj transkrypcję audio po stronie serwera za pomocą WebSocket API.

#### [Dokumentacja zdarzeń](/docs/pl/eleven-api/guides/how-to/speech-to-text/realtime/event-reference)

Pełna lista zdarzeń i typów błędów z API STT w czasie rzeczywistym.