
ffmpeg-skill: cho AI agent dựng video và tự kiểm tra đầu ra
ffmpeg-skill: 42 công cụ FFmpeg cho coding agent, tự kiểm tra file sau khi dựng. Tôi cài và chạy thật, kèm thời gian đo được.
Một agent biết FFmpeg vẫn đoán: nó giả định frame rate, chọn codec mà container không chứa được, re-encode file chỉ cần copy stream, rồi báo "xong" mà không hề mở kết quả ra xem. ffmpeg-skill được xây đúng để bịt bốn lỗ đó.
Đây là Agent Skill cho Claude Code, Cursor, Codex — hoặc bất kỳ agent nào đọc được SKILL.md. Nó dạy agent một quy trình cố định (probe → sửa lossless khi có thể → check → verify) và đóng gói 42 công cụ làm việc thật với ffmpeg/ffprobe.
Tôi cài vào máy, tạo video mẫu, rồi chạy đúng chuỗi lệnh mà skill dạy để xem nó thực sự làm gì. Không đọc README suông — số liệu dưới đây đo tại chỗ.
Repo: github.com/kajisho5/ffmpeg-skill — 7.805 sao, 725 fork, MIT, cập nhật hôm nay.
Ý tưởng cốt lõi: verify sau khi render
Điểm khác biệt so với việc tự viết lệnh ffmpeg: mỗi bước đều có đầu ra có thể kiểm tra. Không phải "chạy xong là xong" mà là "chạy, rồi mở file ra xem có đúng không".
Quy trình gồm bốn lớp:
- Probe trước. Không công cụ nào quyết định dựa vào tên file.
probe.pyđo duration, fps (có phát hiện variable-frame-rate), độ phân giải, rotation, bit depth, định dạng HDR kể cả Dolby Vision, colour tags và từng stream audio - Lossless khi có thể.
cut.pyvàloudness.pystream-copy phần không cần đụng tới. Chỉ re-encode khi buộc phải: cắt chính xác từng frame, có filter, đổi format, hoặc keyframe xa quá ngưỡng - Lập kế hoạch trước khi render. Mọi tool đều có
--dry-runin ra lệnh ffmpeg sẽ chạy mà không ghi gì;--plan FILElưu kế hoạch kèm fingerprint đầu vào để render sau, từ chối nếu input đã đổi - Kiểm tra sau.
check.pyđối chiếu đầu ra với spec của nền tảng đích;look.pyxuất contact sheet để chính agent nhìn bằng mắt

Tôi chạy thật: từ video 40 giây đến Reel đạt chuẩn
Video mẫu: 1920×1080, 30 fps, 40 giây, có hai đoạn câm nhân tạo ở giây 5–12 và 25–32.
Bước 1 — probe.py đọc đúng mọi thứ: 40.0s, 30 fps, 1200 frame, h264 Constrained Baseline, yuv420p, không phải VFR, không HDR. Mất 1,96 giây.
Bước 2 — silence.py --threshold -35 tìm ra đúng 2 khoảng lặng và giữ 3 đoạn liền mạch: 26,77s từ 40,00s, tức cắt bỏ 13,23 giây. Bước này mất 74,92 giây vì phải re-encode toàn bộ.
Bước 3 — fit.py --aspect 9:16 --fit crop đổi khung dọc: 608×1080, mất 27,60 giây.
Bước 4 — export.py --preset reels xuất bản cuối 1080×1920, h264 High, mất 65,96 giây. Và đây là chỗ thú vị: nó tự cảnh báo ngay trong output:
warning: loudness -21.9 LUFS / -17.1 dBTP is outside reels's -14 LUFS / -1 dBTP; run loudness.py -I -14 --tp -1 on this file, or export with --normalize
Bước 5 — check.py --platform reels chạy 13 kiểm tra. Kết quả: 12 PASS, 1 FAIL — đúng cái loudness vừa cảnh báo. Exit code là 1, không phải 0. Nghĩa là pipeline sẽ dừng ở đây, không âm thầm đẩy một file sai chuẩn lên mạng.
Bước 6 — loudness.py -I -14 --tp -1 kéo về -14.0 LUFS, true peak -9.3 dBTP. Chạy lại check.py: 13/13 PASS.

Phụ đề tiếng Việt: render đúng dấu, không cần cấu hình
Đây là điều tôi muốn kiểm nhất, vì phụ đề tiếng Việt hay vỡ dấu hoặc lệch vị trí. Tôi tạo file SRT ba dòng có đủ dấu (Dòng đầu tiên của phụ đề, Dòng thứ hai dài hơn một chút, Dòng thứ ba) rồi burn vào video:
caption.py reel_fixed.mp4 --srt sub/vi.srt --mode burn \
--platform reels --animate pop -o captioned.mp4
Kết quả kiểm bằng contact sheet 12 frame: dấu tiếng Việt hiện đầy đủ và đúng — ò, đ, ầ, ê, ủ, ụ, ề, ứ, à, ơ, ộ không cái nào bị mất hay cắt. Vị trí nằm ở vùng dưới-giữa, chừa khoảng trống phía dưới đúng như UI của Reels cần.
Một chi tiết tôi thích: nó nói rõ "caption text unchanged: the cues were burned exactly as given". Skill này không tự viết lại phụ đề cho vừa khung — chữ của bạn vào đúng như bạn gõ.
Vài thứ hay ho khác
42 công cụ chia theo việc: cut, join, silence, fit, caption, overlay, color, loudness, sync, multicam, check, look... Điểm đáng chú ý:
- Chống VFR. Video quay bằng điện thoại hoặc screen recording thường có frame rate thay đổi.
probe.pyphát hiện, và mọi tool re-encode tự ép về frame rate cố định.cut.pylấy mẫu timing trước khi copy và chuyển sang chế độ frame-accurate nếu nguồn là VFR — vì cắt copy trên VFR sẽ rơi sai frame - Cắt thông minh.
cut.py --smartchỉ re-encode từ điểm cắt tới keyframe kế tiếp rồi copy các GOP ở giữa, khớp profile/level/pixel format/B-frame depth/colour tags của nguồn. Nguồn không khớp được (HEVC, 10-bit, interlaced, VFR, open GOP) thì re-encode toàn bộ và nói rõ lý do trongsmart.reason - HDR giữ nguyên HDR. Không tự động hạ xuống SDR trừ khi được yêu cầu
- Giao kèo máy đọc được.
contract --jsonmô tả cả 42 tool: input schema sinh từ parser, output schema, role, FFmpeg component cần, cách verify. MCP surface lấy từ đây nên thêm flag mới là MCP tự có, không phải sửa hai chỗ - Không có API key, không cloud. Chỉ cần
ffmpegvàpython3trên PATH — chạy offline trên footage bạn không muốn upload
Những gì tôi thấy chưa tiện
Nói thẳng mấy điểm cấn:
- Chậm hơn viết lệnh tay cho việc đơn giản. Cắt một đoạn 40 giây mất 75 giây vì nó re-encode với preset medium crf 18 để đảm bảo chất lượng. Nếu chỉ cần cắt nhanh một clip, lệnh ffmpeg trần vẫn thắng
- Năm bước cho một video ngắn. silence → fit → export → check → loudness → check lại. Mỗi bước là một lần đọc/ghi file, cộng lại hơn 3 phút CPU cho 40 giây footage. Với video một giờ thì phải tính bằng chục phút
caption.pykhông có flag--cues. Tôi thử theo ví dụ trong README phần render template thì bịunrecognized arguments— phải dùng--srt. README và code lệch nhau chỗ này- MCP mặc định chỉ quảng cáo 12 tool trong
tools/listđể tiết kiệm context. Muốn thấy cả 42 thì đặtFFMPEG_SKILL_MCP_FULL=1. Tool nào cũng gọi được bằng tên, nhưng agent không tự biết là có nếu không được bảo doctorbáook: falsechỉ vì thiếu một filter mà vài tool cần. Phải xemdoctor --jsonmụctoolsđể biết tool nào thực sự dùng được
Cài và chạy
# 1. FFmpeg (một lần)
# Windows: winget install ffmpeg | macOS: brew install ffmpeg
# Ubuntu/Debian: sudo apt install ffmpeg
# 2. Cài skill cho agent
npx ffmpeg-skill # Claude Code
npx ffmpeg-skill --cursor # Cursor
npx ffmpeg-skill --codex # Codex
npx ffmpeg-skill --all # cả ba
# 3. Kiểm tra máy có đủ thành phần FFmpeg mà các tool cần
npx ffmpeg-skill doctor
# 4. Đọc giao kèo máy đọc được
npx ffmpeg-skill contract --json | head -40
Rồi nói với agent bằng tiếng người:
"Lấy interview.mp4, giữ 0:45–1:20 và 5:00–5:25, làm thành Reel 60 giây."
Agent sẽ chạy probe.py → cut.py → fit.py → export.py → check.py → look.py, rồi báo lại "final.mp4: 60.00s, 1080×1920, 30 fps, AAC stereo" kèm contact sheet nó đã xem.
Lưu ý: bản cài không tự cập nhật. Chạy lại npx ffmpeg-skill để làm mới.
Nên và không nên dùng
Nên khi bạn dựng video hàng loạt và cần đầu ra đúng chuẩn nền tảng mỗi lần, khi làm việc với footage không được upload lên cloud, khi cần một pipeline lặp lại được (plan + fingerprint input), hoặc khi muốn agent tự phát hiện file hỏng thay vì báo "xong" sai.
Không nên khi bạn chỉ cắt một đoạn ngắn — lệnh ffmpeg trần nhanh hơn nhiều. Cũng không phù hợp nếu bạn cần dựng đồ hoạ động phức tạp (repo này chỉ là "bàn tay", phần quyết định thuộc về một repo khác trong hệ sinh thái của tác giả) hay khi máy thiếu nhiều FFmpeg component mà không muốn cài thêm.
Kết luận
Giá trị thật của ffmpeg-skill không nằm ở 42 con số, mà ở chỗ nó từ chối báo thành công khi file chưa đạt. Lần chạy đầu của tôi, check.py trả exit code 1 vì loudness lệch chuẩn Reels — đó chính là hành vi đúng. Một agent tự viết lệnh ffmpeg sẽ không làm vậy; nó sẽ nói "đã xuất reel.mp4" và bạn phát hiện ra vấn đề khi video đã đăng.
Đổi lại là tốc độ: chậm hơn cắt tay, nhiều bước hơn, và có vài chỗ README lệch code. Nhưng nếu công việc của bạn là xuất video đều đặn cho nhiều nền tảng, cái vòng verify khép kín đáng giá hơn thời gian tiết kiệm được.
Repo: github.com/kajisho5/ffmpeg-skill — MIT, Python standard library, không cloud, không API key.