speech-to-text

Speech-to-Text (Soniox)

Transcribe audio/video files to text with timestamps via the Soniox async API.

Requirements

• API key: Environment variable SONIOX_API_KEY must be set. If you don't have one yet, instruct the user to create an account at https://console.soniox.com and get an API key.
• Node.js: Requires Node.js >= 18.
• Package: @soniox/node (already declared in scripts/package.json).
• ffmpeg (optional): Required when transcribing video files. The script extracts audio before sending to the API to reduce upload size. Install with brew install ffmpeg.

Workflow

Step 1: Check prerequisites

Check whether SONIOX_API_KEY is set:

echo $SONIOX_API_KEY

If not, ask the user to create an account at https://console.soniox.com, get an API key and set:

export SONIOX_API_KEY=<key>

Install dependencies (only needs to be run the first time):

cd skills/speech-to-text/scripts && npm install && cd -

Step 2: Run transcription

Run the transcribe script with the path to the audio or video file:

node skills/speech-to-text/scripts/transcribe.js <đường-dẫn-file>

The script supports the following options:

Flag	Description	Default
--lang	Language hint (ISO 639-1 code)	vi
--output	Output file path	stdout
--format	Output format: text, timestamps, srt	timestamps

Example:

# Transcribe file audio tiếng Việt
node skills/speech-to-text/scripts/transcribe.js recording.mp3

# Transcribe video (mp4 gửi trực tiếp, mov/mkv/avi trích xuất audio qua ffmpeg)
node skills/speech-to-text/scripts/transcribe.js lecture.mp4 --output transcript.txt
node skills/speech-to-text/scripts/transcribe.js meeting.mov --lang en --output notes.txt

# Xuất ra định dạng SRT (phụ đề)
node skills/speech-to-text/scripts/transcribe.js podcast.mp3 --format srt --output subtitle.srt

Step 3: Process results

The script returns text with timestamps in the form:

[00:00.000 -> 00:03.500] Xin chào các bạn, hôm nay chúng ta sẽ nói về AI.
[00:03.500 -> 00:07.200] Đây là một chủ đề rất thú vị trong thời đại hiện nay.

If the user needs it, you can convert to other formats (markdown, SRT, plain text) from this output.

Supported formats

Audio (sent directly to Soniox): aac, aiff, amr, asf, flac, mp3, ogg, wav, m4a

Video (audio extracted with ffmpeg before sending): mp4, webm, mov, mkv, avi, flv, wmv, ts, mts, 3gp

Common error handling

Error	Cause	How to handle
SONIOX_API_KEY not set	Environment variable not set	export SONIOX_API_KEY=<key>
File not found	Wrong file path	Check the path again
Unsupported format	Unsupported audio format	Convert to mp3/wav first
ffmpeg chưa được cài	Video format requires ffmpeg	brew install ffmpeg
API error 401	Invalid API key	Check the key at console.soniox.com
API error 429	Rate limit exceeded	Wait a few seconds and try again

Reference

For API details and advanced options, read: skills/speech-to-text/references/soniox-api.md