Transkrypcja na żywo

Transkrypcja na żywo zamienia strumień audio w linie napisów, kiedy ludzie jeszcze mówią. Twój klient wysyła surowe audio PCM przez WebSocket, a transcript1 odsyła linie, które najpierw są wstępnym rozpoznaniem, a potem stają się ostateczne. Dodaj translate_to, a każda linia dostanie też tłumaczenie. Po zakończeniu sesji wynik zapisuje się jako zwykła transkrypcja.

Nie ma osobnych planów dla transkrypcji na żywo: korzysta ona z tego samego salda minut co wszystko inne. Jak liczy się czas połączenia, opisuje sekcja Rozliczenia.

Kiedy używać transkrypcji na żywo

Transkrypcja na żywo przyjmuje wyłącznie dźwięk, jako surowe PCM. Nie przyjmuje linków do wideo, plików przesłanych, WebM, Opus ani MP3. Nagraj dźwięk po stronie klienta i najpierw zamień go na PCM. Jak to zrobić, pokazuje sekcja Przechwytywanie dźwięku w przeglądarce.

Szybki start z SDK

Zainstaluj SDK w wersji 1.5.0 lub nowszej: npm i @transcript1/sdk@latest. t1.live.start tworzy sesję, łączy się i kończy się, gdy sesja wystartuje, więc od razu możesz wysyłać dźwięk.

import { createReadStream } from 'node:fs';
import { setTimeout as sleep } from 'node:timers/promises';
import { Transcript1 } from '@transcript1/sdk';
 
const t1 = new Transcript1(); // reads TRANSCRIPT1_API_KEY
 
const live = await t1.live.start({ language: 'en', translateTo: 'es', sampleRate: 16000 });
 
live.on('line', line => {
  const mark = line.final ? 'final  ' : 'partial';
  console.log(mark, line.text, '→', line.translation?.text ?? '');
});
live.on('warning', warning => console.warn(warning.code));
 
// speech.pcm: 16 kHz, mono, signed 16-bit little-endian, no header
for await (const chunk of createReadStream('./speech.pcm', { highWaterMark: 3200 })) {
  live.send(chunk);
  await sleep(100); // 3,200 bytes are 100 ms of audio: send at real-time speed
}
 
const result = await live.end();
console.log(result.reason, result.transcriptionId, result.minutesCharged);

Linie aktualizują się w miejscu. Gdy przyjdzie linia z tym samym id, zastąp tę, którą już masz, albo odczytaj wszystkie z live.lines. end() kończy sesję, czeka na ostatnie linie i zapisuje transkrypcję. Wszystkie metody i zdarzenia opisuje SDK dla Node.js.

Szybki start z czystym WebSocketem

Bez SDK są dwa kroki: utwórz sesję przez HTTPS, a potem otwórz WebSocket z jednorazowym tokenem, który dostaniesz w odpowiedzi.

Utwórz sesję

curl -X POST https://api.transcript1.com/v1/live/sessions \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language": "en", "translate_to": "es", "sample_rate": 16000}'

API odpowiada kodem 201:

{
  "id": "lv_8fK2Lm0PqRsTuVwXyZaBcD",
  "status": "waiting",
  "transcription_id": "tr_3NcQvXy7BtHjKd5ErFgLmA",
  "websocket_url": "wss://api.transcript1.com/v1/live/sessions/lv_8fK2Lm0PqRsTuVwXyZaBcD/stream",
  "token": "Zk3x...",
  "token_expires_at": "2026-11-02T12:01:00Z",
  "rate": 1
}

Gdy save ma wartość false, transcription_id to null. Token jest jednorazowy i wygasa po 60 sekundach, więc połącz się od razu. rate to liczba minut salda pobieranych za każdą rozpoczętą minutę tej sesji; zobacz Rozliczenia.

Ciało żądania przyjmuje te pola. Wszystkie są opcjonalne, a wymagany zakres to transcriptions:write:

Połącz się i przesyłaj dźwięk

Otwórz WebSocket z tokenem jako drugim podprotokołem. Działa to w przeglądarkach i w Node 22+ bez własnych nagłówków. Zanim wyślesz dźwięk, poczekaj na session.started: ramki binarne wysłane wcześniej są odrzucane i dostajesz ostrzeżenie audio_dropped.

import { createReadStream } from 'node:fs';
import { setTimeout as sleep } from 'node:timers/promises';
 
const session = await fetch('https://api.transcript1.com/v1/live/sessions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TRANSCRIPT1_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ language: 'en', translate_to: 'es', sample_rate: 16000 }),
}).then(response => response.json());
 
const ws = new WebSocket(session.websocket_url, ['t1-live', session.token]);
const lines = new Map();
 
ws.addEventListener('message', async message => {
  const event = JSON.parse(message.data);
 
  if (event.type === 'session.started') {
    for await (const chunk of createReadStream('./speech.pcm', { highWaterMark: 3200 })) {
      ws.send(chunk);
      await sleep(100);
    }
    ws.send(JSON.stringify({ type: 'end' }));
  } else if (event.type === 'line') {
    lines.set(event.line.id, event.line); // the full current state: replace by id
    console.log(event.line.final, event.line.text, event.line.translation?.text);
  } else if (event.type === 'session.ended') {
    console.log('ended:', event.reason, event.minutes_charged);
  }
});
 
ws.addEventListener('close', event => console.log('closed', event.code));

W Node 20 nie ma wbudowanego WebSocket: użyj pakietu ws, który ma tę samą formę new WebSocket(url, protocols).

Na poprawny token serwer odpowiada podprotokołem t1-live i niczym więcej. Zły token nigdy nie psuje handshake'u: gniazdo się otwiera, dostajesz zdarzenie error, a gniazdo zamyka się kodem 4xxx, więc przeglądarka pokazuje prawdziwy powód zamiast ogólnego 1006. Zobacz Kody zamknięcia.

Przechwytywanie dźwięku w przeglądarce

Dźwięk na żywo musi być monofonicznym PCM 16-bit signed little-endian z częstotliwością sample_rate sesji. Przeglądarki dają próbki zmiennoprzecinkowe, więc zamień je w AudioWorklet. Ten fragment przechwytuje mikrofon jako PCM 16 kHz w porcjach po 100 ms i wysyła go przez wejście SDK dla przeglądarek. getAccessToken zwraca token dostępu OAuth; nigdy nie umieszczaj klucza API w przeglądarce. Zobacz Bezpieczeństwo.

import { createLiveClient } from '@transcript1/sdk/live';
 
const workletSource = `
class Pcm16Processor extends AudioWorkletProcessor {
  constructor() {
    super();
    this.buffer = new Int16Array(1600); // 100 ms at 16 kHz
    this.filled = 0;
  }
 
  process(inputs) {
    const channel = inputs[0][0];
    if (!channel) return true;
    for (let i = 0; i < channel.length; i++) {
      const sample = Math.max(-1, Math.min(1, channel[i]));
      this.buffer[this.filled++] = sample < 0 ? sample * 0x8000 : sample * 0x7fff;
      if (this.filled === this.buffer.length) {
        this.port.postMessage(this.buffer.slice());
        this.filled = 0;
      }
    }
    return true;
  }
}
registerProcessor('pcm16', Pcm16Processor);
`;
 
const client = createLiveClient({ getAccessToken: () => myApp.getOAuthAccessToken() });
 
const stream = await navigator.mediaDevices.getUserMedia({ audio: { channelCount: 1 } });
const context = new AudioContext({ sampleRate: 16000 });
const moduleUrl = URL.createObjectURL(new Blob([workletSource], { type: 'text/javascript' }));
await context.audioWorklet.addModule(moduleUrl);
 
// the context's real rate: a browser that cannot do 16 kHz picks its own
const live = await client.start({ language: 'auto', sampleRate: context.sampleRate });
live.on('line', renderLine);
 
const microphone = context.createMediaStreamSource(stream);
const capture = new AudioWorkletNode(context, 'pcm16');
capture.port.onmessage = event => live.send(event.data); // an Int16Array
const mute = context.createGain();
mute.gain.value = 0;
microphone.connect(capture).connect(mute).connect(context.destination);
 
async function stop() {
  stream.getTracks().forEach(track => track.stop());
  await context.close();
  return live.end();
}

Worklet jest napisany pod 16 kHz. Jeśli kontekst działa z inną częstotliwością, porcja nie ma już 100 ms, ale PCM pozostaje poprawne, bo sampleRate zgadza się z kontekstem. Żeby przechwycić dźwięk karty lub filmu zamiast mikrofonu, utwórz MediaStream przez getDisplayMedia albo z captureStream() elementu multimedialnego i podłącz go tak samo.

Tłumaczenie na żywo

Dodaj translate_to do sesji, a transcript1 będzie tłumaczyć każdą linię w trakcie mówienia.

• Jeden język docelowy na sesję. Kolejne języki dodasz później do zapisanej transkrypcji endpointem tłumaczeń.
• Każda line ma oryginał (text, final) i obiekt translation (language, text, final). translation to null, gdy translate_to nie jest ustawione.
• Oryginał i tłumaczenie stają się ostateczne niezależnie od siebie: linia może mieć ostateczny oryginał, a jej tłumaczenie wciąż się zmienia. Pokaż linię jako ostateczną dopiero, gdy oba są ostateczne.
• Linia, która jest już w języku docelowym, używa własnego tekstu jako tłumaczenia i jest ostateczna, gdy się zamknie.
• Linia zamyka się, gdy mówca zrobi pauzę, zmieni się mówca, przerwa między słowami przekroczy 0,9 sekundy, linia osiągnie dwa wiersze napisów (84 znaki) albo 15 sekund, albo wyślesz finalize. Przy włączonym tłumaczeniu zamknięcie linii może potrwać o około 3 sekundy dłużej, bo czeka na tłumaczenie. Wtedy tłumaczenie może pozostać otwarte (final: false) i dalej rosnąć, gdy oryginał jest już ostateczny.
• Tłumaczenie jest darmowe. Nie zużywa minut.

To, jakie języki docelowe i pary językowe są dostępne, zależy od dostawcy rozpoznawania mowy na żywo. Zamiast wpisywać reguły na sztywno, czytaj możliwości. Nieobsługiwany język docelowy kończy się błędem 422 unsupported_translation. Dostawca może na przykład wymagać jawnego language zamiast auto albo dopuszczać tylko pary zawierające angielski.

Protokół WebSocket

Łączenie

new WebSocket(websocket_url, ['t1-live', token]);

Token podróżuje jako podprotokół WebSocket. Nigdy nie trafia do URL-a ani do logów dostępu. Nie wysyłaj nagłówka Authorization: poświadczeniem jest token. Serwer wysyła ping co 30 sekund; przeglądarki i pakiet ws odpowiadają automatycznie. Gniazdo, które przez 60 sekund nie wyśle pong, zostaje rozłączone.

Poprawne połączenie z sesją, która ma już gniazdo, zastępuje stare. Zobacz Wznawianie i przejęcie.

Komunikaty klienta

Ramka o nieparzystej długości albo zbyt duża to naruszenie protokołu i zamyka gniazdo kodem 4008.

Zacznij wysyłać dźwięk po session.started. Klient, który wysyła dźwięk szybciej niż w czasie rzeczywistym, jest rozliczany za czas dźwięku zamiast czasu połączenia (zobacz Rozliczenia), więc wysyłaj w tempie, w jakim dźwięk powstaje.

Zdarzenia serwera

Każde zdarzenie to tekstowa ramka JSON z polem type.

session.started mówi, czy to wznowienie, i ile dźwięku sesja już przetworzyła:

{
  "type": "session.started",
  "session_id": "lv_8fK2Lm0PqRsTuVwXyZaBcD",
  "transcription_id": "tr_3NcQvXy7BtHjKd5ErFgLmA",
  "resumed": false,
  "offset_ms": 0
}

line zawiera pełny aktualny stan jednej linii, więc zastąp nim linię z tym samym id. Zobacz Obiekt line.

{
  "type": "line",
  "line": {
    "id": 12,
    "start_ms": 53120,
    "end_ms": 56040,
    "speaker": null,
    "language": "en",
    "text": "Welcome back to the stream",
    "final": true,
    "translation": { "language": "es", "text": "Bienvenidos de nuevo", "final": false }
  }
}

usage jest wysyłane po każdym pobraniu opłaty, z czasem połączenia, czasem dźwięku, liczbą minut salda pobranych do tej pory i minutami, które ci zostały:

{
  "type": "usage",
  "connected_ms": 61240,
  "audio_ms": 60100,
  "minutes_charged": 2,
  "minutes_remaining": 898
}

warning ma pole code:

{ "type": "warning", "code": "idle_timeout_soon" }

error ma code i message. Na gnieździe live mogą pojawić się te kody:

{ "type": "error", "code": "invalid_message", "message": "Expected {\"type\":\"finalize\"} or {\"type\":\"end\"}" }

reconnect przychodzi, zanim serwer zamknie gniazdo kodem 1012, na przykład podczas wdrożenia. Pobierz nowy token i wznów sesję.

{ "type": "reconnect", "reason": "server_restart" }

session.ended to ostatnie zdarzenie każdej sesji. Liczby to końcowe sumy:

{
  "type": "session.ended",
  "reason": "client_ended",
  "transcription_id": "tr_3NcQvXy7BtHjKd5ErFgLmA",
  "minutes_charged": 3,
  "connected_ms": 142500,
  "audio_ms": 141900
}

Obiekt line

Linie z final: false pokazuj jaśniejszym stylem: ich tekst może się jeszcze zmienić. Tekst linii z final: true nigdy się już nie zmienia, a ostateczna linia nigdy nie jest usuwana.

SDK używa camelCase dla pól linii: startMs, endMs.

Powody zakończenia

session.ended i GET /v1/live/sessions/:id podają end_reason:

Kody zamknięcia

Podczas restartu API nowe żądanie WebSocket może dostać odpowiedź HTTP 503. Spróbuj ponownie za chwilę.

Wznawianie i przejęcie

Sesja przetrwa zerwaną sieć, wdrożenie API i awarię. Po zerwaniu połączenia czeka na ciebie 2 minuty; potem kończy się jako disconnected i jest zapisywana.

1. Wywołaj POST /v1/live/sessions/:id/token. Odpowiedź zawiera token, token_expires_at i websocket_url, czyli te same pola co przy tworzeniu sesji. Gdy sesja już się zakończyła, kończy się to błędem 409 session_ended.
2. Otwórz nowy WebSocket z tym tokenem.
3. Przychodzi session.started z resumed: true. offset_ms to ilość dźwięku, którą sesja już przetworzyła: kontynuuj od tego miejsca. Identyfikatory linii liczą się dalej.

Linie, które były już ostateczne, zostają. Niedokończony koniec z chwili zerwania przepada, więc jeśli buforujesz dźwięk, odtwórz ponownie kilka sekund od offset_ms. Przerwy na ponowne łączenie nie są rozliczane.

Przejęcie to to samo wywołanie. Jeśli serwer nadal uważa, że gniazdo jest otwarte, nowe poprawne połączenie je zastępuje, a stare gniazdo zamyka się kodem 4010 po zapisaniu jego linii. Limit równoczesnych sesji nigdy nie blokuje wznowienia.

SDK robi to wszystko za ciebie: po zerwaniu połączenia albo zdarzeniu reconnect pobiera token i łączy się ponownie z opóźnieniem rosnącym od 0,5 do 8 sekund, przez maksymalnie 2 minuty, a ostatnie 10 sekund dźwięku wysłanego w czasie przerwy odtwarza ponownie.

Rozliczenia

Transkrypcja na żywo korzysta z tego samego salda minut co transkrypcje wsadowe.

• Rozliczany jest czas połączenia, od przyjęcia gniazda do jego zamknięcia. Cisza i wstrzymany film się liczą. Czas między zerwaniem a wznowieniem już nie.
• Za każdą rozpoczętą minutę, minimum 1. Pierwsza minuta jest pobierana, gdy pierwsze połączenie zostanie przyjęte, a każda następna, gdy się zaczyna.
• Szybciej niż w czasie rzeczywistym rozlicza się jako czas dźwięku. Jeśli wysłany dźwięk jest dłuższy niż czas połączenia, rozliczany jest czas dźwięku.
• Stawkę odczytujesz z API. Jedna rozpoczęta minuta kosztuje rate minut salda, zaokrąglone w górę. Stawka to zwykle 1 i może mieć części dziesiętne. Stawkę live odczytasz z rates.live w GET /v1/account, z rate w GET /v1/live/capabilities oraz z rate w tworzonej sesji. Stawka sesji jest stała od jej utworzenia.
• Tłumaczenie jest darmowe.
• Brak połączenia oznacza brak opłaty. Sesja, która nie połączy się w ciągu 5 minut, kończy się jako not_connected.
• Błędy są zwracane. Jeśli sesja kończy się z upstream_error lub internal_error, zanim wytworzy choć jedną linię, wszystkie opłaty wracają na konto. Pusta sesja z powodu ciszy jest rozliczana i zapisywana jako pusta.
• Gdy saldo się skończy i włączone jest automatyczne doładowanie, transcript1 obciąża zapisaną kartę, nie przerywając strumienia, i sesja trwa dalej. Jeśli automatyczne doładowanie jest wyłączone lub wstrzymane albo obciążenie się nie powiedzie, sesja jest finalizowana, zapisywana i kończy się z balance_exhausted na granicy minuty. Ostrzeżenie balance_low pojawia się wcześniej, chyba że automatyczne doładowanie jest włączone.

Utworzenie sesji zwraca 402 insufficient_minutes, gdy twoje dostępne saldo jest niższe niż jedna rozpoczęta minuta przy bieżącej stawce. Jeśli włączone jest automatyczne doładowanie, transcript1 najpierw próbuje doładować konto. Zobacz Rozliczenia i limity.

Limity

• Sesja liczy się, dopóki jest w stanie waiting, connected lub disconnected (w ramach 2-minutowego okna). Po przekroczeniu limitu POST /v1/live/sessions zwraca 429 too_many_live_sessions z nagłówkiem Retry-After: 30.
• Sesje na żywo nie liczą się do limitu aktywnych zadań.
• Sesja trwa najwyżej 300 minut czasu połączenia. Potem kończy się z max_duration.
• Sesja bez dźwięku przez 5 minut kończy się z idle_timeout; po 4 minutach dostajesz idle_timeout_soon. Wstrzymany strumień nadal nalicza czas połączenia i liczy się jako bezczynny, więc przy długiej przerwie zakończ sesję.
• transcript1 ogranicza też łączną liczbę wszystkich sesji na żywo. Gdy wszystkie miejsca są zajęte, POST /v1/live/sessions zwraca 503 live_capacity, co można ponowić. Poczekaj na Retry-After (30 sekund) i spróbuj jeszcze raz. Sprawdzamy to tylko przy tworzeniu sesji, nigdy w jej trakcie.
• Tworzenie sesji i pobieranie tokenów liczą się do limitu żądań na minutę.
• Dźwięk to wyłącznie surowe PCM: pcm_s16le, mono, od 8000 do 48000 Hz.

Możliwości

GET /v1/live/capabilities opisuje, co transkrypcja na żywo obsługuje w tej chwili, żeby klienci nie musieli wpisywać reguł dostawcy na sztywno. Wymagany zakres to transcriptions:read.

{
  "available": true,
  "auto_language": true,
  "languages": ["en", "es"],
  "translation": {
    "targets": ["es", "de"],
    "pairs": "any",
    "requires_language": false
  },
  "diarize": true,
  "audio_formats": ["pcm_s16le"],
  "sample_rate": { "min": 8000, "max": 48000 },
  "max_session_minutes": 300,
  "rate": 1
}

Listy są tu skrócone. Odczytaj je z API.

• translation.pairs to "any" (dowolny wykryty język na dowolny język docelowy) albo lista obiektów z polami from i to.
• translation.requires_language ma wartość true, gdy tłumaczenie wymaga jawnego language zamiast auto.
• Gdy transkrypcja na żywo nie jest skonfigurowana, odpowiedź to available: false tylko z polem rate, a utworzenie sesji zwraca 503 live_unavailable.

W SDK: await t1.live.capabilities().

Odczyt sesji

GET /v1/live/sessions/:id zwraca stan sesji. Wymagany zakres to transcriptions:read.

curl https://api.transcript1.com/v1/live/sessions/lv_8fK2Lm0PqRsTuVwXyZaBcD \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY"

{
  "id": "lv_8fK2Lm0PqRsTuVwXyZaBcD",
  "status": "ended",
  "end_reason": "client_ended",
  "transcription_id": "tr_3NcQvXy7BtHjKd5ErFgLmA",
  "options": {
    "language": "en",
    "translate_to": "es",
    "diarize": false,
    "audio_format": "pcm_s16le",
    "sample_rate": 16000,
    "save": true
  },
  "connected_ms": 142500,
  "audio_ms": 141900,
  "minutes_charged": 3,
  "rate": 1,
  "created_at": "2026-11-02T11:58:12Z",
  "ended_at": "2026-11-02T12:00:35Z"
}

status to waiting, connected, disconnected albo ended. end_reason to null, dopóki sesja się nie zakończy. W SDK: await t1.live.get(id).

Błędy

Błędy żądań używają zwykłej koperty błędu. Oto te, które zwracają POST /v1/live/sessions i pokrewne endpointy:

Problemy na gnieździe docierają jako zdarzenia error i kody zamknięcia.

Zapisane transkrypcje

Przy save: true (domyślnie) sesja po zakończeniu zapisuje się jako zwykła transkrypcja. Dźwięk nigdy nie jest przechowywany.

• transcription_id dostajesz przy tworzeniu sesji. Jego status to live, gdy sesja trwa, i completed po jej zakończeniu. Sesja, która nigdy się nie połączyła, zostawia transkrypcję ze statusem canceled.
• Transkrypcja ma source: { "platform": "live", "session_id": "lv_…" }. Nie ma linku ani pliku. Panel wyświetla ją jako sesję na żywo.
• Każda linia staje się jednym segmentem o tym samym indeksie co id linii. Transkrypcję odczytasz jako JSON, tekst, SRT lub VTT, tak jak każdą inną: zobacz dokumentację API.
• Tłumaczenie na żywo zapisuje się razem z nią. Odczytasz je parametrem translation, jak opisano w sekcji Tłumaczenie.
• Kolejne języki tłumaczenia dodasz później przez POST /v1/transcriptions/:id/translations, gdy transkrypcja ma status completed. Zobacz Tłumaczenie.

Przy save: false po zakończeniu sesji nic nie zostaje: nie powstaje transkrypcja, a transcription_id to null. Nadal dostajesz każdą linię przez gniazdo i obowiązuje zwykła opłata.

Bezpieczeństwo

• Token, który dostajesz przy tworzeniu sesji, jest jednorazowy i wygasa po 60 sekundach. Jest przesyłany jako podprotokół WebSocket, a nie w URL-u, więc nie trafia do logów dostępu. Wyciekły token jest bezużyteczny, gdy został użyty albo wygasł.
• Klucza API używaj tylko na serwerze, który kontrolujesz. Nigdy nie umieszczaj klucza API na stronie internetowej ani w rozszerzeniu.
• W przeglądarce lub rozszerzeniu loguj użytkowników przez OAuth i przekaż token dostępu OAuth do getAccessToken w createLiveClient. Do rozpoczynania sesji token potrzebuje zakresu transcriptions:write. Tokeny dostępu OAuth wygasają po 1 godzinie, a przy każdym wznowieniu SDK prosi getAccessToken o świeży token.
• Twój serwer może też utworzyć sesję kluczem API i przekazać przeglądarce tylko websocket_url oraz token. Klient łączy się wtedy bezpośrednio. Bez nowego tokena od ciebie nie może wznowić sesji.