Eventos e ciclo de vida

Pergunta: "quando a sessão está pronta e quais eventos posso observar?"

A sessão oferece start, stop, pause, resume, on e off. start() resolve e emite ready somente com socket confirmado. pause() para a captura; resume() a retoma; stop() encerra a sessão e libera a captura. Remova listeners com a mesma função passada a on.

import { connectTranscription, type TranscriptionErrorEvent } from '@sofya-sdk/transcription';

const session = await connectTranscription({
  provider: 'sofya_as_service',
  endpoint: '<wss-url>',
});

const onError = (event: TranscriptionErrorEvent) => console.error(event.code, event.message);
session.on('ready', () => console.log('socket confirmado'));
session.on('recognizing', ({ text, offsetMs }) => console.log(text, offsetMs));
session.on('recognized', ({ text, offsetMs, durationMs }) => console.log(text, offsetMs, durationMs));
session.on('reconnecting', ({ attempt, reason }) => console.log(attempt, reason));
session.on('reconnected', ({ attempt }) => console.log(attempt));
session.on('disconnected', ({ reason, willRetry }) => console.log(reason, willRetry));
session.on('error', onError);

session.pause();
session.resume();
await session.stop();
session.off('error', onError);

recognizing é parcial e traz { text, offsetMs }; recognized é final e acrescenta durationMs. Os offsets desses eventos são milissegundos. Isso é independente das marcações em segundos do resultado batch, documentadas em batch-e-reprocessamento.md.

Erros públicos

TranscriptionError é a base única e expõe code e cause. Ela tem três subclasses:

• TranscriptionEnvironmentError: browser_unavailable, secure_context_required, microphone_unavailable;
• TranscriptionSessionError: microphone_access_failed, transport_connection_failed, transport_disconnected, session_start_failed;
• TranscriptionConnectionError: all_candidates_failed, com attempts.

O evento error expõe somente { code, message }; ele não transporta a causa original. Capture e trate TranscriptionError no ponto que chama start()/connectTranscription() quando precisar classificar a falha da jornada.