word-timestamps-extractor

name	word-timestamps-extractor
description	Trích xuất transcript narration có timestamp cấp câu và cấp từ; script mặc định dùng local faster-whisper, có fallback OpenAI Whisper khi cần.

Word Timestamps Extractor

Quy tắc đầu ra (BẮT BUỘC)

• Mọi nội dung do AI/LLM sinh ra từ transcribe (sentence, word) bắt buộc giữ tiếng Việt CÓ DẤU nếu audio là tiếng Việt — không asciify, không bỏ dấu.
• Cấm asciify (vd KHÔNG được viết "song cham" thay cho "sống chậm" trong transcript).
• Tên trường (audio_path, sentence_id, confidence...), tên model (large-v3, whisper-1...), CLI flag, file path giữ nguyên tiếng Anh — không dịch.
• Mọi ghi chú/lý do warning do agent thêm vào TOML cũng phải là tiếng Việt có dấu.

Quy tắc môi trường script

Trước khi chạy bất kỳ script nào của skill này, đọc file .env ở repo-root trước. File này nằm cạnh jobs/, skills/, và env.example. Luồng mặc định --backend faster-whisper không cần OPENAI_API_KEY, nhưng vẫn truyền .env qua --env-file để giữ workflow nhất quán. Chỉ xác nhận OPENAI_API_KEY tồn tại khi chạy --backend openai; tuyệt đối không in giá trị secret. Chỉ dùng --env-file không phải repo-root khi user yêu cầu rõ ràng.

Nếu faster-whisper chưa có trong Python environment đang chạy, cài một lần ở repo-root trước khi transcribe:

.venv/bin/python -m pip install faster-whisper

Mục tiêu

Trích xuất audio narration thành transcript có timestamp câu và từ để sinh subtitle, căn cảnh, và semantic asset mapping.

Dùng skill này khi user cung cấp file audio và cần timing cấp từ.

Đầu vào

• File audio, thường là source/voice.wav hoặc source/voice.mp3.
• Hint ngôn ngữ tùy chọn.
• Script text tùy chọn để sửa lỗi/align.
• Nếu narration vừa được hậu xử lý tốc độ (skill ausynclab-voice, speed-pydub / voice_speed_pydub.py) và ghi đè voice.wav, phải chạy lại bước transcribe trên file âm thanh mới trước khi dùng transcript cho subtitle hoặc semantic mapping.

Đầu ra

Ghi hoặc trả về TOML. Đường dẫn mặc định:

source/transcript_word_level.toml

Khi đã có video job, ghi vào:

jobs/<job_id>/source/transcript_word_level.toml

Quy trình

1. Định vị file audio và giữ nguyên path.
2. Dùng local faster-whisper mặc định để lấy word timestamps nhanh hơn API.
3. Chỉ dùng OpenAI Whisper bằng --backend openai khi user yêu cầu cloud/API hoặc local thiếu tài nguyên.
4. Gom từ thành câu đọc được.
5. Nếu có script gốc, chỉ dùng để sửa lỗi chính tả/dấu câu hiển nhiên, không bịa timing.
6. Validate timestamp tăng đều và phủ đủ câu.

Hợp đồng TOML

[metadata]
audio_path = "source/voice.wav"
language = "vi"
duration_seconds = 45.0
model = "whisper-compatible"
backend = "faster-whisper"

[[sentences]]
id = "S_001"
start = 0.12
end = 4.8
sentence = "..."
word_ids = ["W_0001", "W_0002"]

[[words]]
id = "W_0001"
word = "..."
start = 0.12
end = 0.38
sentence_id = "S_001"
confidence = 0.0

Nếu yêu cầu nested words thay thế, cũng hỗ trợ:

[[sentences]]
start = 0.12
end = 4.8
sentence = "..."
words = [
  { word = "...", start = 0.12, end = 0.38 }
]

Quy tắc chất lượng

• Timestamp là số thực (giây).
• Từ phải có thứ tự và không overlap trong cùng 1 câu.
• Không silently drop từ có timing không chắc chắn; giữ chúng kèm warning khi cần.
• Giữ dấu câu trong sentence, nhưng word giữ nguyên token được nói khi có thể.

Script tiện ích

Dùng script đi kèm để chạy local faster-whisper và normalize TOML:

python skills/word-timestamps-extractor/scripts/transcribe_word_timestamps.py \
  --audio source/voice.wav \
  --output source/transcript_word_level.toml \
  --env-file .env \
  --language vi

Cho job-scoped run:

python skills/word-timestamps-extractor/scripts/transcribe_word_timestamps.py \
  --audio jobs/<job_id>/source/voice.wav \
  --output jobs/<job_id>/source/transcript_word_level.toml \
  --env-file .env \
  --language vi

Mặc định script dùng:

--backend faster-whisper --model large-v3 --device auto --compute-type default --beam-size 5

Để ưu tiên tốc độ hơn nữa trên máy yếu, có thể hạ model:

python skills/word-timestamps-extractor/scripts/transcribe_word_timestamps.py \
  --audio source/voice.wav \
  --output source/transcript_word_level.toml \
  --env-file .env \
  --language vi \
  --model small \
  --compute-type int8

Fallback OpenAI vẫn được giữ để tương thích:

python skills/word-timestamps-extractor/scripts/transcribe_word_timestamps.py \
  --audio source/voice.wav \
  --output source/transcript_word_level.toml \
  --env-file .env \
  --language vi \
  --backend openai

Với --backend openai, script dùng whisper-1 với response_format=verbose_json và timestamp_granularities[]=word, vì OpenAI word timestamp granularities chỉ áp dụng cho whisper-1.