hoangvantuan/speech-to-text

Speech-to-Text (Soniox)

Transcribe file audio/video thành text kèm timestamps qua Soniox async API.

Yêu cầu

• API key: Biến môi trường SONIOX_API_KEY phải được set. Nếu chưa có, hướng dẫn user tạo tài khoản tại https://console.soniox.com và lấy API key.
• Node.js: Cần Node.js >= 18.
• Package: @soniox/node (đã khai báo trong scripts/package.json).
• ffmpeg (tùy chọn): Cần khi transcribe file video. Script trích xuất audio trước khi gửi API để giảm dung lượng upload. Cài bằng brew install ffmpeg.

Workflow

Bước 1: Kiểm tra điều kiện

Kiểm tra SONIOX_API_KEY đã set chưa:

echo $SONIOX_API_KEY

Nếu chưa có, yêu cầu user tạo tài khoản tại https://console.soniox.com, lấy API key và set:

export SONIOX_API_KEY=<key>

Cài dependency (chỉ cần chạy lần đầu):

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

Bước 2: Chạy transcription

Chạy script transcribe với đường dẫn file audio hoặc video:

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

Script hỗ trợ các option:

| Flag | Mô tả | Mặc định | | ---------- | --------------------------------------------- | ------------ | | --lang | Gợi ý ngôn ngữ (mã ISO 639-1) | vi | | --output | Đường dẫn file output | stdout | | --format | Định dạng output: text, timestamps, srt | timestamps |

Ví dụ:

# 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

Bước 3: Xử lý kết quả

Script trả về text kèm timestamps dạng:

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

Nếu user cần, có thể chuyển đổi sang các format khác (markdown, SRT, plain text) từ output này.

Format hỗ trợ

Audio (gửi trực tiếp cho Soniox): aac, aiff, amr, asf, flac, mp3, ogg, wav, m4a

Video (trích xuất audio bằng ffmpeg trước khi gửi): mp4, webm, mov, mkv, avi, flv, wmv, ts, mts, 3gp

Xử lý lỗi thường gặp

| Lỗi | Nguyên nhân | Cách xử lý | | ------------------------ | ------------------------- | ----------------------------------- | | SONIOX_API_KEY not set | Chưa set biến môi trường | export SONIOX_API_KEY=<key> | | File not found | Đường dẫn file sai | Kiểm tra lại path | | Unsupported format | Format audio không hỗ trợ | Convert sang mp3/wav trước | | ffmpeg chưa được cài | Video format cần ffmpeg | brew install ffmpeg | | API error 401 | API key không hợp lệ | Kiểm tra key tại console.soniox.com | | API error 429 | Vượt rate limit | Chờ vài giây rồi thử lại |

Tham khảo

Chi tiết API và các option nâng cao, đọc: skills/speech-to-text/references/soniox-api.md