Realtime transcription
Stream live audio to HUMAIN Voice and show captions that settle into a final transcript and WebVTT file.
You stream PCM audio, print live captions as they change, and write recording.vtt from the final
words. Install the SDK and set API_URL and API_KEY as in the Quickstart.
Socket.IO examples also read the optional API_PATH
(Connection settings).
Prepare audio
Convert a recording to raw PCM16 little-endian, 16 kHz, mono:
ffmpeg -i recording.wav -f s16le -acodec pcm_s16le -ar 16000 -ac 1 recording.pcmThe command also resamples 8 kHz phone audio to the required 16 kHz. Each 3,200-byte chunk is 100 ms of audio. Send live audio chunk by chunk as it arrives; the example's 100 ms pause only replays a file at real-time pace.
Stream and show captions
The example streams recording.pcm in 3,200-byte chunks, prints each result as partial:,
speech-final:, or final:, waits up to 5 seconds for the final result, and writes
recording.vtt. A server error is printed as error: and ends the run with a non-zero exit.
import { readFile, writeFile } from 'node:fs/promises';
import {
type ErrorResponse,
Language,
RealtimeClient,
Subtitles,
type WordSegment,
} from '@humain-voice/sdk';
const CHUNK_BYTES = 3_200; // 100 ms of PCM16LE, 16 kHz, mono audio.
function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
const value = process.env[name];
if (!value) throw new Error(`${name} is required`);
return value;
}
function socketPath(): { api_path?: string } {
const value = process.env.API_PATH;
return value ? { api_path: value } : {};
}
async function pause(milliseconds: number): Promise<void> {
await new Promise<void>((resolve) => setTimeout(resolve, milliseconds));
}
async function main(): Promise<void> {
const inputPath = process.argv[2] ?? 'recording.pcm';
const outputPath = process.argv[3] ?? 'recording.vtt';
const client = new RealtimeClient({
api_url: requiredEnv('API_URL'),
api_key: requiredEnv('API_KEY'),
...socketPath(),
});
const finalizedWords: WordSegment[] = [];
let serverError: ErrorResponse | undefined;
let protocolFinalObserved = false;
try {
const stream = await client.startStream(Language.ArEn, {
onResponse: (response) => {
const kind = response.is_final
? 'final'
: response.is_speech_final
? 'speech-final'
: 'partial';
console.info(`${kind}:`, response.transcription);
if (response.is_final) protocolFinalObserved = true;
if (response.is_final || response.is_speech_final) {
// seq is not guaranteed to increase, so keep words in arrival order.
finalizedWords.push(...response.words);
}
},
onError: (error) => {
console.error('error:', error.code, error.message);
serverError = error;
},
});
const pcm = await readFile(inputPath);
try {
for (let offset = 0; offset < pcm.length; offset += CHUNK_BYTES) {
if (serverError) break;
await stream.send(pcm.subarray(offset, offset + CHUNK_BYTES));
await pause(100);
}
// Resolves (does not throw) if is_final has not arrived within 5 s.
if (!serverError) await stream.close(5);
} catch (error: unknown) {
// The SDK drops the stream on a server error, so send() and close() throw.
if (!serverError) throw error;
}
if (serverError) {
throw new Error(serverError.message ?? serverError.code ?? 'Realtime stream failed');
}
if (!protocolFinalObserved) {
throw new Error('Realtime stream ended before protocol is_final');
}
await writeFile(outputPath, Subtitles.fromWords(finalizedWords).toVtt(), 'utf8');
} finally {
await client.disconnect();
}
}
void main().catch((error: unknown) => {
console.error(error);
process.exitCode = 1;
});
Expected output (illustrative):
partial: Hello and
speech-final: Hello and welcome to the meeting.
partial: Let's start
final: Let's start with the agenda.Update your captions from the flags on each result (Streaming results are state, not a log):
| Flags | What to do |
|---|---|
is_final and is_speech_final both false | Replace the provisional caption text. |
is_speech_final: true, is_final false | Commit the utterance and keep streaming. |
is_final: true | The stream is finished; commit any remaining text. |
For a caption file, collect the words of each committed result in arrival order and pass them to
Subtitles (JavaScript, Python).
End the stream
When the audio ends, call close(5) in JavaScript or close(timeout_seconds=5.0) in Python; it
sends the final frame and waits for is_final. The 1-second default can return before
is_final arrives, and close returns without an error on timeout, so check the error your
onError / on_error handler recorded and whether is_final arrived.
Recover from a dropped stream
A dropped stream can't resume: keep the committed text, drop provisional text, and start a new stream.