| name | speech-to-text |
| description | Chuyển file audio/video thành text kèm timestamps qua Soniox API. Hỗ trợ 60+ ngôn ngữ, audio (mp3/wav/flac/ogg/aac/m4a) + video (mp4/mov/mkv/avi/webm). Output: text, timestamps, SRT (phụ đề). Dùng khi user nói 'transcribe', 'chuyển audio sang text', 'chuyển video sang text', 'gỡ băng', 'phiên âm', 'tạo phụ đề', 'speech to text', hoặc có file audio/video cần chuyển thành văn bản. Hỗ trợ podcast, họp, phỏng vấn, bài giảng, video. |
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ụ:
node skills/speech-to-text/scripts/transcribe.js recording.mp3
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
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
