Hyperframes-media đóng vai trò là nhân tố xử lý âm thanh và tài nguyên media trong hệ sinh thái OpenMontage, bao gồm tổng hợp giọng nói từ văn bản (TTS), xử lý nhạc nền (BGM), hiệu ứng âm thanh, chuyển đổi giọng nói thành văn bản (Whisper) và tạo phụ đề. Tài liệu này tập trung vào quy trình triển khai TTS, bao gồm cơ chế tự động chuyển đổi giữa các nhà cung cấp (Provider), phương thức lấy dữ liệu thời gian từng từ (word-level timestamps) từ HeyGen Starfish, và cấu hình tối ưu cho model lồng tiếng nội bộ Kokoro.
Kiểm tra xác thực (Preflight) bắt buộc
Trước khi khởi động bất kỳ quy trình tạo giọng đọc (voiceover) nào, hệ thống yêu cầu thực hiện bước kiểm tra trạng thái đăng nhập thông qua lệnh npx hyperframes auth status.
Nguyên tắc cốt lõi là quy trình phải dừng lại và chờ người dùng tương tác nếu thiếu thông tin xác thực cho các dịch vụ đám mây (như HeyGen). Việc tự động chuyển đổi sang giải pháp nội bộ (như Kokoro) không nên diễn ra âm thầm khi có thể có ý định sử dụng chất lượng âm thanh cao cấp từ đám mây. Chỉ trong chế độ tự động (non-interactive), hệ thống mới ghi nhận trạng thái và tiếp tục chạy offline với model nội bộ.
Thuật toán lựa chọn Provider
Hệ thống sử dụng một chuỗi ưu tiên để xác định service TTS sẽ được sử dụng. Logic này được triển khai trong module lib/tts.mjs thông qua hàm xác định tính sẵn sàng của dịch vụ:
function determineActiveService(userConfig) {
const envVars = process.env;
// Ưu tiên 1: HeyGen nếu có API Key
if (userConfig.forceHeygen || (envVars.HGN_ACCESS_TOKEN && !userConfig.forceLocal)) {
return { provider: 'heygen', hasTimestamps: true };
}
// Ưu tiên 2: ElevenLabs (cần kiểm tra cả Python library)
if (envVars.ELEVEN_TOKEN && checkPythonLib('elevenlabs')) {
return { provider: 'elevenlabs', hasTimestamps: false };
}
// Ưu tiên 3: Kokoro (Luôn sẵn sàng làm phương án dự phòng)
return { provider: 'kokoro', hasTimestamps: false };
}Các đặc điểm kỹ thuật của từng Provider:
- HeyGen (Starfish): Yêu cầu biến môi trường
$HEYGEN_API_KEYhoặc file cấu hình. Hỗ trợ dữ liệu thời gian từng từ (word-level timestamps) trực tiếp trong phản hồi API. Đầu ra ban đầu là MP3 và cần chuyển đổi. - ElevenLabs: Yêu cầu
$ELEVENLABS_API_KEYvà thư viện Python cục bộ. Không hỗ trợ timestamps tích hợp sẵn. Đầu ra MP3. - Kokoro-82M: Chạy cục bộ hoàn toàn, không cần kết nối mạng. Không có timestamps. Đầu ra WAV trực tiếp. Định danh giọng đọc theo tiền tố ngôn ngữ (ví dụ:
af_heart).
Lưu ý quan trọng: Đối với các bản dựng CLI (Command Line Interface) chỉ hỗ trợ Kokoro, việc thiết lập Key cho HeyGen sẽ không tự động kích hoạt dịch vụ này. Để sử dụng tính năng nâng cao của HeyGen như timestamps, cần sử dụng script REST API độc lập.
Sử dụng CLI và Script tùy chỉnh
Lệnh cơ bản
Các ví dụ dưới đây minh họa cách gọi lệnh với các cấu hình khác nhau:
# Tự động chọn Provider dựa trên cấu hình sẵn có
npx hyperframes media synthesize "Chào mừng đến với HyperFrames" --dest voice_output.wav
# Ép buộc sử dụng Kokoro nội bộ
npx hyperframes media synthesize "Xin chào" --provider kokoro --voice am_michael
# Sử dụng HeyGen với Voice ID cụ thể
npx hyperframes media synthesize "Hello" --provider heygen --voice 05f19352e8f74b0392a8f411eba40de1Tham số --voice và --provider nên được sử dụng cặp để tránh việc giao diện chọn giọng đọc bị thay đổi ngầm định khi môi trường thay đổi. Nếu không chỉ định giọng đọc cho HeyGen (với tiếng Anh), hệ thống sẽ mặc định chọn giọng Marcia (UUID: 05f19352e8f74b0392a8f411eba40de1) để đảm bảo tính nhất quán.
Script độc lập cho HeyGen: heygen-tts.mjs
Để khai thác tối đa khả năng của HeyGen (đặc biệt là lấy timestamps trong một lần gọi), script scripts/heygen-tts.mjs được cung cấp để giao tiếp trực tiếp với REST API v3, bỏ qua cơ chế plugin của CLI.
# Thiết lập Token (nếu chưa đăng nhập qua CLI)
export HEYGEN_API_KEY="sk-your-api-key"
# Thực hiện tổng hợp và xuất dữ liệu thời gian từ (timestamps)
node skills/hyperframes-media/scripts/heygen-tts.mjs \
"Từ đây là giới thiệu về hệ thống." \
--target audio.wav \
--timestamps output_words.json
# Liệt kê danh sách giọng đọc Starfish
node skills/hyperframes-media/scripts/heygen-tts.mjs --listXử lý Timestamps: Script sẽ lọc bỏ các thẻ đánh dấu biên (<start>, <end>) trong phản hồi gốc của HeyGen và trả về một mảng JSON phẳng chuẩn:
[
{ "uid": "w0", "text": "Từ", "start": 0.0, "end": 0.25 },
{ "uid": "w1", "text": "đây", "start": 0.26, "end": 0.50 }
]Chiến lược triển khai và Tối ưu hóa
Xử lý âm thanh với FFmpeg
Cả HeyGen và ElevenLabs đều trả về định dạng MP3. Nếu đường dẫn đầu ra (--dest) có đuôi .wav (định dạng yêu cầu cho các pipeline xử lý tiếp theo như Whisper), hệ thống sẽ tự động kích hoạt FFmpeg để chuyển đổi mã hóa. Việc cài đặt FFmpeg là bắt buộc nếu muốn sử dụng các Provider đám mây với đầu ra WAV. Câu lệnh chuyển đổi cơ bản thường được dùng là ffmpeg -i input.mp3 -ar 44100 -ac 1 output.wav.
Tùy chỉnh Kokoro nội bộ
Kokoro hỗ trợ 54 giọng đọc khác nhau. Tên giọng đọc tuân theo quy tắc: [Tiền tố ngôn ngữ][Giới tính Tên]. Ví dụ: af_heart (American, Female, Heart).
- Tiền tố ngôn ngữ: Xác định bộ xử lý âm vị (phonemizer) sẽ sử dụng.
a: Tiếng Anh (Mỹ)b: Tiếng Anh (Anh)e: Tiếng Tây Ban Nhaf: Tiếng Phápj: Tiếng Nhậtz: Tiếng Trung (Quan Thoại)
Với các ngôn ngữ không phải tiếng Anh, việc cài đặt công cụ espeak-ng ở mức hệ thống là yêu cầu bắt buộc để Kokoro hoạt động chính xác.
Điều chỉnh tốc độ (Speed)
Tốc độ đọc được kiểm soát bởi tham số --speed:
0.7 - 0.8: Phù hợp cho tài liệu hướng dẫn, nội dung phức tạp.1.0: Tốc độ tự nhiên (Mặc định).1.1 - 1.2: Dành cho đoạn intro, chuyển cảnh nhanh.
Lưu ý: ElevenLabs bỏ qua tham số này từ phía client (cần cấu hình trực tiếp trên Dashboard). HeyGen và Kokoro hỗ trợ trực tiếp tham số này trong yêu cầu API.
Tích hợp Timestamps vào quy trình Phụ đề (Captions)
Tùy thuộc vào Provider được chọn, dữ liệu thời gian cho phụ đề được thu thập theo hai đường đi khác nhau:
Đường đi A: HeyGen (Tự động)
Sử dụng khi cần độ chính xác cao và giảm thiểu xử lý. Dữ liệu timestamps được lấy cùng lúc với audio.
npx hyperframes media synthesize script.txt --provider heygen --dest audio.wav --timestamps captions.json
# captions.json có thể được nạp thẳng vào bộ render phụ đề
Đường đi B: ElevenLabs/Kokoro (Qua trung gian Whisper)
Vì hai Provider này không trả về dữ liệu từ, ta cần dùng Whisper để transcribe lại file âm thanh vừa tạo ra.
# Bước 1: Tạo âm thanh
npx hyperframes media synthesize script.txt --voice af_heart --dest audio.wav
# Bước 2: Trích xuất timestamps bằng Whisper
npx hyperframes transcribe audio.wav --model small.en
Việc này đảm bảo thời điểm hiện thị của phụ đề khớp chính xác với giọng đọc thực tế được phát ra, đặc biệt quan trọng cho các hiệu ứng karaoke hoặc chiếu lời theo nhịp.