Đang tải quảng cáo...
ffmpeg-skill: cho AI agent dựng video và tự kiểm tra đầu ra

ffmpeg-skill: cho AI agent dựng video và tự kiểm tra đầu ra

adminQuản trị viên
👁️ 0👍 0
Giới thiệu

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.

Đang tải quảng cáo...

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.py và loudness.py stream-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-run in ra lệnh ffmpeg sẽ chạy mà không ghi gì; --plan FILE lư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.py xuất contact sheet để chính agent nhìn bằng mắt

Năm bước xử lý video: kiểm tra file, cắt, đổi khung hình, chuẩn hoá âm lượng, kiểm tra đầu ra
Probe → cắt → đổi khung → chuẩn hoá âm lượng → kiểm tra: mỗi bước đều verify được

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.

Máy tính chạy kiểm tra tự động với checklist đạt chuẩn và các công cụ video xoay quanh
Vòng verify khép kín: file đầu ra được đo lại, sai chuẩn thì pipeline dừng

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.py phát hiện, và mọi tool re-encode tự ép về frame rate cố định. cut.py lấ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 --smart chỉ 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 trong smart.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 --json mô 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 ffmpeg và python3 trê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.py khô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ì đặt FFMPEG_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
  • doctor báo ok: false chỉ vì thiếu một filter mà vài tool cần. Phải xem doctor --json mục tools để 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.

Đang tải quảng cáo...
👁️0 lượt xem