Bắt đầu với VideoLingo

Bài này hướng dẫn cấu hình API, cài đặt và chạy VideoLingo, công cụ dùng LLM để dịch video, kèm lồng tiếng tùy chọn bằng TTS.

Cấu hình API

VideoLingo dùng LLM để dịch. TTS là tùy chọn, chỉ cần khi lồng tiếng. Bạn tự chọn nhà cung cấp và model.

1. Lấy API_KEY cho LLM

Đặt API URL, key và model trong thanh bên. Client dùng Chat Completions tương thích OpenAI, và một số bước xử lý yêu cầu JSON có cấu trúc. Hãy dùng model mà endpoint của bạn hỗ trợ; chỉ số lượng tham số không quyết định chất lượng dịch hay độ ổn định JSON. Chỉ bật JSON mode nếu endpoint hỗ trợ.

OpenLux là relay được khuyến nghị. Đặt API base URL là https://api.openlux.ai/v1. Chọn một trong ba model dưới đây. Giá là mức xấp xỉ theo nhóm định tuyến tự động của OpenLux, đo trên gateway (USD cho mỗi 1 triệu token; thay đổi theo nhóm định tuyến):

Các nhà cung cấp tương thích OpenAI khác cũng dùng được, ví dụ OpenRouter tại https://openrouter.ai/api/v1, hoặc một server tương thích chạy cục bộ. Ứng dụng yêu cầu ô key không được để trống kể cả khi server không xác thực yêu cầu (request); chỉ dùng giá trị giữ chỗ cho server nói rõ là bỏ qua key. Edge TTS cần kết nối mạng, không phải bộ tổng hợp giọng offline.

2. TTS API

VideoLingo có nhiều cách tích hợp (integration) TTS. Bảng so sánh dưới đây (bỏ qua nếu bạn chỉ dịch, không lồng tiếng):

• Với SiliconFlow FishTTS, lấy key từ SiliconFlow; lưu ý tính năng nhân bản cần credit trả phí.
• Với OpenAI TTS, dùng OpenLux với cùng key như LLM. Dịch vụ khác có endpoint speech của OpenAI cũng dùng được qua openai_tts.base_url và openai_tts.model trong config.yaml.
• Với Fish Audio, lấy key tại fish.audio. API tính phí theo mức dùng và tài khoản cần có credit; nhân bản giọng không tốn thêm.
• Với F5-TTS, dùng 302AI. Nó nhân bản giọng trong video.

Muốn có adapter TTS tùy chỉnh, sửa core/tts_backend/custom_tts.py.

Hướng dẫn SiliconFlow FishTTS

Hiện hỗ trợ 3 chế độ:

1. preset: dùng giọng cố định, nghe thử được trên Playground chính thức, mặc định là anna.
2. clone(stable): chế độ API custom; ghép các đoạn tham chiếu đủ điều kiện từ danh sách tác vụ, trong giới hạn độ dài văn bản và thời lượng, rồi tải lên một giọng dùng lại được. Đây không nhất thiết là mười giây đầu video.
3. clone(dynamic): chế độ API dynamic; dùng clip tham chiếu của câu hiện tại. Độ nhất quán và chất lượng giọng phụ thuộc vào đoạn tham chiếu và dịch vụ, không đảm bảo tốt hơn chế độ custom.

Chọn giọng OpenAI

Danh sách giọng có trên trang chính thức, ví dụ alloy, echo, nova… Sửa openai_tts.voice trong config.yaml. Model mặc định là gpt-4o-mini-tts.

Chọn giọng Fish Audio

Chọn nhà cung cấp Fish Audio trên trang. Có hai chế độ:

• Giọng trong video (nhân bản): mặc định. 15–30 giây lời nói đầu tiên của video làm tham chiếu cho mọi câu. Không có gì được lưu vào tài khoản Fish Audio của bạn. Chỉ nhân bản những giọng bạn được phép dùng.
• Giọng cố định: danh sách có hai giọng, 语彤 Yutong và 浩然 Haoran. Với giọng khác, chọn Another voice of fish.audio, tìm giọng bạn thích trên fish.audio, mở nó và dán địa chỉ trang hoặc ID của giọng.

Để đưa các giọng yêu thích vào danh sách, thêm chúng kèm tên và ID vào fish_audio.voices trong config.yaml. Model là fish_audio.model, mặc định s2.1-pro.

Chọn giọng Edge TTS

Edge TTS là mặc định và không cần API key. Chạy edge-tts --list-voices để liệt kê giọng, ví dụ zh-CN-XiaoxiaoNeural hoặc en-US-JennyNeural, và chọn một giọng của ngôn ngữ đích. Sửa edge_tts.voice trong config.yaml hoặc trong thanh bên.

Hướng dẫn GPT-SoVITS-v2

1. Kiểm tra yêu cầu và tải gói từ tài liệu Yuque chính thức.

2. Đặt GPT-SoVITS-v2-xxx và VideoLingo trong cùng một thư mục. Lưu ý hai thư mục phải nằm song song.

3. Chọn một trong các cách cấu hình model sau:

   a. Model tự huấn luyện:

   • Sau khi huấn luyện, tts_infer.yaml trong GPT-SoVITS-v2-xxx\GPT_SoVITS\configs sẽ tự điền đường dẫn model. Sao chép và đổi tên nó thành your_preferred_english_character_name.yaml.
   • Cùng thư mục với file yaml, đặt audio tham chiếu tên your_preferred_english_character_name_reference_audio_text.wav hoặc .mp3, ví dụ Huanyuv2_Hello, this is a test audio.wav.
   • Trong thanh bên của VideoLingo, đặt GPT-SoVITS Character là your_preferred_english_character_name.

   b. Dùng model đã huấn luyện sẵn:

   • Tải model của tác giả từ đây, giải nén và ghi đè vào GPT-SoVITS-v2-xxx.
   • Đặt GPT-SoVITS Character là Huanyuv2.

   c. Dùng model đã huấn luyện khác:

   • Đặt xxx.ckpt vào thư mục GPT_weights_v2 và xxx.pth vào thư mục SoVITS_weights_v2.

   • Làm như cách a, đổi tên tts_infer.yaml và sửa t2s_weights_path, vits_weights_path trong mục custom để trỏ tới model của bạn, ví dụ:

     yaml

     Sao chép mã

     # Example config for method b:
     t2s_weights_path: GPT_weights_v2/Huanyu_v2-e10.ckpt
     version: v2
     vits_weights_path: SoVITS_weights_v2/Huanyu_v2_e10_s150.pth
     

   • Làm như cách a, đặt audio tham chiếu cùng thư mục với file yaml, tên your_preferred_english_character_name_reference_audio_text.wav hoặc .mp3, ví dụ Huanyuv2_Hello, this is a test audio.wav. Chương trình sẽ tự phát hiện và dùng nó.

   • Cảnh báo: hãy dùng tiếng Anh cho character_name để tránh lỗi. reference_audio_text có thể bằng tiếng Trung. Tính năng đang ở giai đoạn beta, có thể phát sinh lỗi.

   code

   Sao chép mã

   # Expected directory structure:
   .
   ├── VideoLingo
   │   └── ...
   └── GPT-SoVITS-v2-xxx
       ├── GPT_SoVITS
       │   └── configs
       │       ├── tts_infer.yaml
       │       ├── your_preferred_english_character_name.yaml
       │       └── your_preferred_english_character_name_reference_audio_text.wav
       ├── GPT_weights_v2
       │   └── [your GPT model file]
       └── SoVITS_weights_v2
           └── [your SoVITS model file]
   

Sau khi cấu hình, chọn Reference Audio Mode trong thanh bên (xem tài liệu Yuque để biết chi tiết). Khi lồng tiếng, VideoLingo tự mở cổng API suy luận của GPT-SoVITS trong cửa sổ dòng lệnh; bạn có thể tự đóng nó khi xong. Lưu ý độ ổn định phụ thuộc vào model gốc được chọn.

Bắt đầu nhanh

VideoLingo hỗ trợ Windows, macOS (Apple Silicon / Intel) và Linux.

Nhờ AI agent cục bộ

Nếu AI agent của bạn điều khiển được máy tính, hãy nói với nó:

Install and launch GitHub's Huanshere/VideoLingo on my computer.

Windows: nhấp đúp để cài

1. Tải Source code (zip) từ Release mới nhất, giải nén ra Desktop hoặc thư mục khác, rồi mở thư mục đó.
2. Nhấp đúp OneKeyStart.bat và giữ cửa sổ mở. Lần chạy đầu, nó tự cài uv, Python 3.12, dependency của ứng dụng và FFmpeg. Cần có kết nối internet.
3. Cài xong, VideoLingo tự mở trong trình duyệt. Nhập API URL, key và model vào thanh bên để bắt đầu dùng.

Nếu bạn dùng GPU NVIDIA, hãy cài driver tương thích trước; xem mục Runtime GPU bên dưới.

Cài từ mã nguồn (Windows, macOS, Linux)

git clone https://github.com/Huanshere/VideoLingo.git && cd VideoLingo
uv run start.py

Lần sau, chạy lại uv run start.py từ thư mục VideoLingo để khởi động. Apple Silicon dùng MLX; Mac Intel nhận dạng bằng CPU. Mặc định, khi lồng tiếng trên Mac Intel, video dùng giọng mới mà không giữ âm nền gốc.

Nhận dạng giọng nói (Qwen3-ASR + ForcedAligner)

Nhận dạng cục bộ chép lời bằng Qwen3-ASR rồi tạo timestamp theo từ bằng Qwen3-ForcedAligner-0.6B. Khi bật tách giọng, phần chép lời dùng audio gốc còn phần căn chỉnh dùng giọng đã tách.

• Kích thước model: whisper.qwen_model trong config.yaml (không có trong thanh bên). 1.7b (mặc định) chính xác hơn; 0.6b nhanh hơn và tốn ít bộ nhớ hơn. Aligner luôn là ForcedAligner-0.6B.
• Engine: whisper.qwen_engine: auto tự chọn; thường bạn không cần đổi.

• Trên Apple Silicon, requirements mặc định cài mlx-audio chứ không phải qwen-asr; muốn dùng qwen_engine: transformers ở đó cần một môi trường riêng. Dưới macOS 14, bộ cài dừng và báo lỗi. Nếu môi trường cũ có WhisperX, chạy lại installer.py sẽ gỡ bộ WhisperX trước (whisperx, torchcodec, faster-whisper, ctranslate2, pyannote-*), vì nó xung đột với dependency của MLX.
• Tải model: model được tải từ Hugging Face ở lần dùng đầu (vài GB cho 1.7B cộng aligner). Đặt HF_ENDPOINT để dùng mirror. Nếu có _model_cache/<phần cuối của repo id>/config.json (ví dụ _model_cache/Qwen3-ASR-1.7B), bản cục bộ đó sẽ được dùng.
• Ngôn ngữ: mọi ngôn ngữ nhận dạng trong thanh bên đều được hỗ trợ (Qwen3-ASR hỗ trợ 30 ngôn ngữ). Với Auto, mỗi cửa sổ khoảng 3 phút được thăm dò trước bằng tối đa ba clip 20 giây, các clip bỏ phiếu chọn ngôn ngữ, rồi cửa sổ được chép lời với ngôn ngữ đó (nhận dạng lâu hơn khoảng một phần ba); với lời nói pha trộn, ngôn ngữ được báo đầu tiên được coi là chính. Nếu Auto phát hiện ngôn ngữ ngoài danh sách thanh bên (ví dụ tiếng Hàn, tiếng Việt, tiếng Thái), bước tách câu tự chọn cách nối có hoặc không có khoảng trắng và dùng pipeline spaCy tương ứng, hoặc chỉ tách theo dấu câu khi spaCy không có.
• Output thoái hoá: nếu bản chép lời của một cửa sổ chỉ lặp một cụm từ, hoặc ngắn hơn nhiều so với những gì clip thăm dò nghe được, nó được thử lại với cửa sổ 60 giây; nếu vẫn thoái hoá, nhận dạng dừng với lỗi yêu cầu bạn đặt ngôn ngữ, thay vì chuyển tiếp một bản chép lời hỏng. Với ngôn ngữ chọn thủ công, cửa sổ có bản chép lời thưa bất thường (dưới 2 chữ cái/chữ số mỗi giây) được đối chiếu với vài clip thăm dò ngôn ngữ tự động; nếu chúng nghe được nhiều hơn hẳn thì thất bại, còn nếu chúng nghe ra ngôn ngữ khác thì thất bại ngay kèm gợi ý rằng ngôn ngữ đã chọn có thể không khớp audio (dùng auto hoặc đổi kích thước model), thay vì để bước sau thử lại bằng ngôn ngữ khác. Bản chép lời có hệ chữ rõ ràng không khớp ngôn ngữ đã chọn (ví dụ chữ Hàn khi chọn tiếng Anh hoặc tiếng Trung, tiếng Nhật gần như không có kana) cũng thất bại như vậy; bước kiểm tra này chỉ đọc văn bản, không thêm thời gian nhận dạng và chạy sau mỗi cửa sổ, nên dừng ngay ở cửa sổ sai đầu tiên. Khoảng lặng và nhạc không bao giờ kích hoạt kiểm tra này.
• Giới hạn đã biết: chọn sai ngôn ngữ giữa các ngôn ngữ viết bằng chữ Latin (ví dụ chọn tiếng Tây Ban Nha cho video tiếng Anh) không phát hiện được. Model có thể dịch một số cửa sổ sang ngôn ngữ đã chọn thay vì chép đúng lời nói, khiến một phần là bản gốc, một phần là bản dịch. Hãy ưu tiên Auto, hoặc kiểm tra lại ngôn ngữ nhận dạng trước khi xử lý.
• Cache bản chép lời phân biệt backend, kích thước model và engine; đổi bất kỳ thứ nào sẽ chạy lại nhận dạng.
• WhisperX không phải lựa chọn trong bộ cài. Muốn dùng (kể cả model Belle cho tiếng Trung), bạn tự cài các gói: WhisperX (cài thủ công).
• Docker image chính thức qwenllm/qwen3-asr có thể chạy một dịch vụ Qwen3-ASR độc lập, nhưng VideoLingo không gọi trực tiếp tới nó.

MAI-Transcribe-2 tùy chọn (Azure Speech hoặc OpenRouter)

Chọn ASR Runtime → MAI-Transcribe-2 trong thanh bên, rồi chọn Azure Speech hoặc OpenRouter làm nhà cung cấp MAI. Azure dùng whisper.mai_api_key và whisper.mai_region (một region như eastus, một endpoint tài nguyên, hoặc để trống để tự phát hiện). OpenRouter dùng ô key riêng, whisper.mai_openrouter_api_key; không cần region Azure. Cấu hình cũ không có whisper.mai_provider tiếp tục dùng Azure. Runtime ASR mặc định vẫn là Qwen3-ASR cục bộ.

Azure MAI dùng API chép lời nhanh; OpenRouter dùng API chép lời audio riêng với model microsoft/mai-transcribe-2. Cả hai đều yêu cầu văn bản sạch và timestamp theo từ. Dữ liệu tải lên OpenRouter được chia thành các clip khoảng hai phút để vừa giới hạn thời gian xử lý của nó. Audio được gửi tới nhà cung cấp cloud đã chọn và có thể phát sinh phí. Azure MAI-Transcribe-2 đang ở public preview, không có SLA; hãy kiểm tra region tài nguyên của bạn có hỗ trợ không. Nhà cung cấp và phiên bản API phân biệt các bản chép lời trong cache; thông tin xác thực và region không thuộc định danh cache. Đánh giá của người đóng góp trong #618 so sánh MAI với WhisperX, không phải với Qwen3-ASR mặc định hiện tại.

Runtime GPU

• Cài driver tương thích với GPU NVIDIA của bạn. nvidia-smi báo khả năng (capability) CUDA của driver, không phải phiên bản Toolkit đã cài.
• Trên máy host, bộ cài chọn PyTorch cu128 khi capability được báo >=12.8, còn lại chọn cu126 khi phát hiện NVIDIA. Capability không đọc được thì dùng cu126, điều này không đảm bảo tương thích với driver cũ. Không có NVIDIA thì chọn gói CPU. Gói tương thích đã có sẵn có thể được dùng lại.
• Qwen3-ASR mặc định chạy trên PyTorch và dùng CUDA runtime đi kèm wheel PyTorch; không cần cài riêng cuBLAS/cuDNN. Cài WhisperX thủ công thì cần cuBLAS của CUDA 12 và cuDNN 9; xem WhisperX (cài thủ công).

Bộ cài chọn wheel Python; nó không cài CUDA Toolkit hệ thống. Driver mới hỗ trợ CUDA 13 không đòi gói Python CUDA 13 cho dự án này.

HTTP API

HTTP API cục bộ thay thế chế độ batch Excel và dùng chung pipeline Streamlit. Xem hướng dẫn API.

Lỗi thường gặp và cạm bẫy

1. 'All array must be of the same length' hoặc 'Key Error' khi dịch:

   • Nguyên nhân 1: model yếu tuân thủ định dạng JSON kém, làm lỗi phân tích phản hồi (response).
   • Nguyên nhân 2: LLM có thể từ chối dịch nội dung nhạy cảm.

   Kiểm tra resp_content, resp và message trong output/gpt_log/error.json. Lỗi kiểm tra hợp lệ được ghi log tách khỏi cache phản hồi thành công. Hãy chẩn đoán bước bị lỗi trước khi xoá kết quả cache của bước đó.

2. 'Retry Failed', 'SSL', 'Connection', 'Timeout': thường là lỗi mạng. Cách xử lý: người dùng ở Trung Quốc đại lục hãy đổi node mạng rồi thử lại.

3. Qwen ASR engine '...' needs the 'qwen-asr' package (hoặc mlx-audio): thiếu gói nhận dạng. Đóng VideoLingo rồi khởi động lại để sửa: nhấp đúp OneKeyStart.bat trên Windows, hoặc chạy uv run start.py với bản cài từ mã nguồn. Trên Apple Silicon, nếu bạn tự đặt qwen_engine: transformers, hãy đổi lại thành auto.

4. Qwen3-ASR could not detect the language hoặc ... is still degenerate after retrying: Auto không xác định được ngôn ngữ, hoặc bản chép lời bị thoái hoá (lặp một cụm, quá ít chữ). Chọn rõ ngôn ngữ nhận dạng trong thanh bên rồi thử lại, hoặc thử kích thước model còn lại.

5. CUDA out of memory: đặt whisper.qwen_model thành 0.6b trong config.yaml, hoặc đóng các chương trình khác đang dùng GPU.

6. mlx cannot be resolved / no matching distribution trên macOS: mlx chỉ phát hành wheel cho Apple Silicon trên macOS 14 trở lên. Hãy nâng cấp macOS trước.

7. Lỗi WhisperX (cublas64_12.dll not found, segfault, Weights only load failed, TorchCodec…): chỉ xảy ra khi chọn backend WhisperX; xem WhisperX (cài thủ công).

8. Thiếu model spaCy: VideoLingo thường tự tải model khi cần lần đầu. Kiểm tra kết nối internet rồi chạy lại bước đó.

9. Phiên bản các gói Torch không khớp nhau: đóng VideoLingo rồi khởi động lại để sửa: nhấp đúp OneKeyStart.bat trên Windows, hoặc chạy uv run start.py với bản cài từ mã nguồn. Mac Intel dùng Torch/torchaudio 2.2.2 với torchvision 0.17.2; các nền tảng khác dùng 2.8.0 với 0.23.0. Giữ ba gói khớp nhau. Demucs không được cài tự động trên Mac Intel.

Nguồn

• Dịch và biên tập từ Huanshere/VideoLingo · docs/pages/docs/start.en-US.md, giấy phép Apache-2.0.