# ffmpeg-skill: Biến coding agent thành trình biên tập video — hướng dẫn cài đặt và dùng

> ffmpeg-skill là Agent Skill và MCP server giúp Claude Code, Cursor, Codex hoặc MCP client chỉnh sửa video bằng FFmpeg trên máy cục bộ. Công cụ có 42 thao tác, kiểm tra file trước và sau khi xử lý, không cần cloud hay API key; cài khá đơn giản nếu máy đã có FFmpeg, ffprobe và Python.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-11-04 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/ffmpeg-skill-bien-coding-agent-thanh-trinh-bien-tap-video

ffmpeg-skill là một Agent Skill giúp Claude Code, Cursor, Codex và các MCP client chỉnh sửa video bằng FFmpeg ngay trên máy của bạn. Repo cung cấp 42 công cụ có tham số rõ ràng để cắt, ghép, thêm phụ đề, đổi tỷ lệ khung hình, xử lý âm thanh và xuất video cho nhiều nền tảng.

Điểm đáng giá nhất là quy trình không chỉ chạy lệnh rồi báo xong. Skill sẽ đo thông tin file trước, chọn cách xử lý phù hợp, chạy công cụ, kiểm tra file đầu ra và có thể tạo contact sheet để agent nhìn lại phần hình ảnh. Mọi thứ chạy cục bộ, không cần tải video lên cloud và không cần API key.

Đây là lựa chọn phù hợp nếu bạn thường làm video ngắn, video phỏng vấn, nội dung cho mạng xã hội hoặc muốn giao việc hậu kỳ cho coding agent. Người mới cần biết cơ bản về terminal, nhưng có thể bắt đầu bằng lệnh `npx ffmpeg-skill` và để agent điều phối các bước tiếp theo.

```repo
- repo | kajisho5/ffmpeg-skill
- kind | Skill
- desc | ffmpeg-skill cung cấp 42 công cụ FFmpeg chạy cục bộ để cắt, ghép, thêm phụ đề, đổi khung hình và xuất video.
- stars | 5.4k
- lang | Python
- license | MIT
```

## ffmpeg-skill làm được gì

- **Cắt và ghép video:** Bạn có thể giữ lại nhiều đoạn trong một file, nối các clip hoặc tạo video mới từ những phần đã chọn. Công cụ cố gắng stream-copy khi có thể để tránh mã hóa lại không cần thiết.

- **Đổi thời lượng và tỷ lệ khung hình:** Skill có thể đưa video về thời lượng cụ thể, chẳng hạn 60 giây, đồng thời chuyển từ ngang sang dọc 9:16 bằng cách crop hoặc cách fit phù hợp. Đây là nhóm tính năng hữu ích khi chuẩn bị một video cho Reels, TikTok, Shorts hoặc nền tảng khác.

- **Phụ đề và karaoke:** Công cụ nhận cue text để chèn phụ đề, hỗ trợ hiệu ứng chữ xuất hiện theo từ và chế độ karaoke. Nội dung cue do bạn cung cấp sẽ được ghi nguyên văn, không tự viết lại để vừa khung.

- **Xử lý khoảng lặng:** `silence.py` có thể phát hiện và xử lý những đoạn im lặng. Với transcript và speech engine cục bộ phù hợp, bạn có thể dùng thêm các chế độ liên quan đến filler hoặc khoảng lặng theo câu.

- **Chuẩn hóa âm lượng:** Công cụ `loudness.py` hỗ trợ đặt mức loudness và true peak, ví dụ `-14 LUFS` và `-1 dBTP`. Điều này giúp bản xuất có âm lượng dễ kiểm soát hơn khi đưa lên nền tảng.

- **Chỉnh âm thanh:** Bộ công cụ bao gồm dọn âm thanh và xử lý dynamics theo kiểu có tham số rõ ràng. Agent có thể đo cấu trúc audio trước khi chọn cách làm.

- **Overlay và motion graphics:** Bạn có thể đặt lớp hình ảnh hoặc thành phần đồ họa lên video. Repo cũng có cơ chế đặt vị trí và xử lý lớp đồ họa thưa trong các quy trình liên quan.

- **HDR sang SDR và LUT:** Skill có công cụ cho việc chuyển HDR sang SDR và áp dụng LUT. Đây là phần hữu ích khi nguồn quay và chuẩn xuất không giống nhau.

- **Đồng bộ và multicam:** Repo hỗ trợ đồng bộ có hiệu chỉnh drift và các quy trình nhiều camera. Những tính năng này phù hợp với phỏng vấn, podcast hoặc buổi ghi hình có nhiều nguồn.

- **Kiểm tra file đầu ra:** Kết quả có thể được probe, kiểm tra theo thông số nền tảng và xem bằng contact sheet khi hình ảnh đã thay đổi. Agent không chỉ dựa vào việc FFmpeg thoát với mã thành công.

- **Chạy độc lập hoặc qua MCP:** Bạn có thể gọi CLI, dùng trực tiếp các script Python hoặc để MCP client gọi công cụ qua `tools/list` và `tools/call`. MCP mặc định quảng bá 12 công cụ cốt lõi để giảm lượng ngữ cảnh; đặt `FFMPEG_SKILL_MCP_FULL=1` để liệt kê toàn bộ 42 công cụ.

- **Hợp đồng máy đọc được:** `contract --json` mô tả input, output, khả năng FFmpeg cần có và cách xác minh kết quả. Schema được sinh từ parser `argparse`, nên tham số CLI và định nghĩa MCP được giữ đồng bộ.

- **Chạy thử an toàn:** Các công cụ có `--dry-run` để in kế hoạch mà không chạy FFmpeg, `--json` để lấy kết quả có cấu trúc, `--plan FILE` để lưu kế hoạch và `--overwrite` để xác nhận rõ việc thay file có sẵn.

## Cần chuẩn bị gì

- Máy đã cài **FFmpeg** và có cả `ffmpeg`, `ffprobe` trên PATH. README có lệnh cài FFmpeg mẫu cho Ubuntu/Debian; macOS và Windows có hướng dẫn trong bảng Install của repo.

- **Node.js phiên bản 16 trở lên**, vì `package.json` yêu cầu Node `>=16` và cách cài chính dùng npm/npx.

- **Python 3** để chạy các script xử lý và demo. Repo dùng Python standard library, không yêu cầu dependency Python cho phần cốt lõi.

- Một coding agent hoặc MCP client nếu bạn muốn giao việc bằng ngôn ngữ tự nhiên. Skill được mô tả cho Claude Code, Cursor, Codex và các agent đọc được `SKILL.md`.

- **Không cần tài khoản, API key hay cloud.** Video được xử lý cục bộ trên máy.

- Speech engine chỉ cần khi bạn muốn tạo phụ đề từ giọng nói bằng `caption.py --transcribe`, hoặc dùng các chế độ transcribe của `silence.py`. README nêu `faster-whisper` là lựa chọn cài đơn giản bằng pip. Model sẽ được tải ở lần chạy đầu tiên và audio không rời khỏi máy.

- Phần cứng cụ thể như GPU không được README yêu cầu. Vì vậy, chưa có cơ sở để khẳng định GPU là bắt buộc hoặc được hỗ trợ riêng.

## Cài đặt từng bước

```steps
- Cài FFmpeg | Đảm bảo ffmpeg và ffprobe có trên PATH
- Cài skill | Dùng npx để cài cho Claude Code, Cursor hoặc Codex
- Kiểm tra máy | Chạy doctor để xem các thành phần FFmpeg đang có
- Đọc contract | In schema máy đọc được cho agent hoặc MCP client
- Thử xử lý | Giao một yêu cầu video hoặc gọi script Python trực tiếp
```

### Cài FFmpeg

README đưa lệnh mẫu cho Ubuntu/Debian như sau:

```bash
sudo apt install ffmpeg
```

Lệnh này cài FFmpeg từ terminal. Bạn cần mở terminal trên chính máy sẽ xử lý video. Sau khi cài, `ffmpeg` và `ffprobe` phải gọi được từ PATH. Với macOS và Windows, README nói có bảng hướng dẫn riêng trong phần Install của repo, nhưng nội dung bảng đó không có trong tư liệu được cung cấp ở đây.

Nếu dùng Windows trong Git Bash, README lưu ý rằng Python có thể được gọi bằng `python` hoặc launcher `py` thay vì `python3`, tùy cách cài Python. Đây là điểm người mới thường vấp khi chuyển các lệnh script từ Linux sang Windows.

### Cài skill cho coding agent

Lệnh cài nhanh trong README là:

```bash
npx ffmpeg-skill
```

Lệnh này cài skill cho Claude Code. README ghi rõ có tùy chọn `--cursor` cho Cursor, `--codex` cho Codex và `--all` cho cả ba. Các tùy chọn này được dùng cùng lệnh cài:

```bash
npx ffmpeg-skill --cursor
npx ffmpeg-skill --codex
npx ffmpeg-skill --all
```

Bạn nên chạy lệnh trong terminal có Node.js 16 trở lên. Lệnh không cần API key. Nếu đã cài từ trước, chạy lại `npx ffmpeg-skill` để làm mới bản sao tại `~/.claude/skills/ffmpeg-skill`; bản sao cũ không tự cập nhật.

### Kiểm tra khả năng của máy

Sau khi cài skill, chạy:

```bash
npx ffmpeg-skill doctor
```

`doctor` kiểm tra FFmpeg, ffprobe và các thành phần mà từng công cụ cần. Nó có thể kiểm tra encoder, decoder, filter và bitstream filter như `libx264`, `libass`, `zscale`, `loudnorm` hoặc `xfade`.

Một điểm quan trọng: trạng thái `ok` tổng thể và trạng thái `usable` của từng tool không giống nhau. `ok` có thể là `false` nếu chỉ một filter tùy chọn bị thiếu, trong khi phần lớn tool vẫn chạy được. Khi đó, hãy xem trường `tools` trong kết quả JSON để biết chính xác tool nào dùng được.

Bạn có thể lấy kết quả có cấu trúc bằng:

```bash
npx ffmpeg-skill doctor --json
```

Nếu một layout FFmpeg không đọc được, `doctor` đánh dấu capability là `unknown`, không tự coi là thiếu hoặc có sẵn. Điều này giúp tránh hiểu nhầm khi kiểm tra máy.

### Đọc contract của 42 công cụ

Để in phần đầu của contract:

```bash
npx ffmpeg-skill contract --json | head -40
```

Contract cho biết mỗi tool nhận gì, tạo ra gì, cần capability FFmpeg nào, có hỗ trợ dry-run không và phải xác minh kết quả ra sao. MCP server lấy tên tool và `inputSchema` từ contract này khi khởi động.

Trên Windows, `head` có thể không phải lệnh mặc định trong PowerShell. Nếu mục tiêu của bạn là xem toàn bộ JSON, có thể bỏ phần `| head -40` và chạy:

```bash
npx ffmpeg-skill contract --json
```

### Gọi script Python trực tiếp

README cho phép gọi tool từ mọi shell bằng thư mục skill:

```bash
S=~/.claude/skills/ffmpeg-skill/scripts
python3 $S/probe.py input.mp4 --compact
python3 $S/fit.py input.mp4 --duration 60 --aspect 9:16 --dry-run
python3 $S/export.py input.mp4 --preset reels --json
```

`probe.py` đọc thông tin file ở dạng gọn. `fit.py` chỉ in kế hoạch vì có `--dry-run`, nên chưa tạo file. `export.py` xuất theo preset `reels` và trả về kết quả có cấu trúc kèm probe của file đầu ra.

Trên Windows, README lưu ý có thể thay `python3` bằng `python` nếu lệnh `python3` báo không tìm thấy. Các lệnh raw script cũng cần điều chỉnh biến đường dẫn theo shell đang dùng; phần cài đặt bằng `bin/install.js`, `doctor` và `contract` đã xử lý khác biệt này.

## Kiểm tra đã chạy được chưa

Cách kiểm tra cơ bản là chạy:

```bash
npx ffmpeg-skill doctor
```

Kết quả cần cho bạn biết FFmpeg, ffprobe và capability của từng tool. Đừng chỉ nhìn vào `ok`; hãy xem thêm `tools` hoặc chạy bản JSON để biết tool dự định dùng có `usable` hay không.

Tiếp theo, thử probe một video thật:

```bash
S=~/.claude/skills/ffmpeg-skill/scripts
python3 $S/probe.py input.mp4 --compact
```

Nếu chạy được, tool sẽ đọc các thông tin như thời lượng, fps, độ phân giải và cấu trúc audio. Đây là dấu hiệu skill có thể tiếp cận file đầu vào.

Bạn cũng có thể thử kế hoạch không ghi file:

```bash
python3 $S/fit.py input.mp4 --duration 60 --aspect 9:16 --dry-run
```

`--dry-run` phải chỉ in các lệnh FFmpeg dự kiến. README nêu các test của repo xác nhận rằng dry-run không gọi FFmpeg và không tạo file.

Khi giao việc cho agent, một yêu cầu mẫu là:

> Take `interview.mp4`, keep 0:45–3:10 and 5:00–6:30, and make it exactly 60 seconds for Reels.

Quy trình mong đợi là agent probe file, cắt các đoạn, fit về 60 giây và 9:16, xuất theo preset Reels, kiểm tra nền tảng rồi xem contact sheet. README minh họa kết quả dạng `final.mp4: 59.98 s, 1080×1920, 30 fps, AAC stereo`.

## Dùng vào việc thật

### Chủ shop tạo video dọc cho Reels

Bạn có một video giới thiệu sản phẩm ở dạng ngang và muốn đưa lên Reels. Hãy giao cho agent yêu cầu giữ các đoạn cần thiết, đưa video về 60 giây, crop sang 9:16 và xuất theo preset Reels.

```text
Take product-demo.mp4, keep 0:20–1:05 and 2:10–2:45, make it exactly 60 seconds for Reels, and check the final file.
```

Theo workflow của README, agent sẽ bắt đầu bằng `probe.py`, sau đó dùng `cut.py`, `fit.py --duration 60 --aspect 9:16 --fit crop`, `export.py --preset reels`, `check.py --platform reels` và `look.py`. Kết quả là một file đã đổi khung hình, có thông tin kiểm tra để bạn xem trước khi đăng.

### Nhân viên văn phòng cắt phần cần thiết từ buổi phỏng vấn

Bạn có một file phỏng vấn dài nhưng chỉ cần hai đoạn để gửi cho đồng nghiệp. Có thể yêu cầu agent cắt nhiều khoảng thời gian trong cùng một lần:

```text
Keep 0:45–3:10 and 5:00–6:30 from interview.mp4, join them, and report the output duration and audio layout.
```

Repo có `cut.py` cho các đoạn cắt và `join.py` cho việc nối clip. Agent được hướng dẫn probe trước để không đoán thời lượng hoặc frame rate từ tên file. Với những đoạn phù hợp, cắt có thể dùng stream copy; nếu cần cắt chính xác theo frame hoặc đổi định dạng, tool mới re-encode.

### Người làm nội dung tạo phụ đề karaoke

Nếu bạn đã có cue text hoặc transcript, hãy yêu cầu agent chèn phụ đề theo đúng nội dung cung cấp và dùng hiệu ứng karaoke:

```text
Add the supplied cue text to talk.mp4 with animated pop captions and karaoke timing. Keep the cue wording unchanged and verify the output.
```

`caption.py` hỗ trợ `--animate pop` và `--karaoke`. Nội dung cue sẽ được đốt vào video như bạn cung cấp; skill không tự viết lại câu để vừa phụ đề. Nếu muốn phụ đề tự tạo từ giọng nói, bạn cần cài speech engine cục bộ riêng.

### Người làm podcast chuẩn hóa âm lượng và xuất nhiều nền tảng

Bạn có một video nói chuyện cần đưa lên nhiều kênh. README có template cho `tiktok`, `reels`, `shorts`, `youtube-shorts`, `youtube`, `x`, `linkedin`, `facebook`, `podcast` và `audiogram`.

```bash
python3 $S/render.py talk.mp4 --template tiktok --cues cues.txt
```

Template TikTok thiết lập crop 9:16, caption pop theo từng từ, vùng an toàn, mức `-14 LUFS`, preset TikTok và bước check trên file đã tạo. Bạn cũng có thể dùng `--template all` hoặc danh sách cách nhau bằng dấu phẩy để tạo nhiều đích video từ cùng một edit. `--dry-run` cho xem mọi lệnh dự kiến, còn `-o` đổi nơi ghi file.


> Video đáng tin không phải là video chạy xong một lệnh, mà là video đã được đo, xử lý và kiểm tra lại.
>
> — Ông T

### Người dựng thử nhiều phiên bản trước khi ghi file

Khi chưa chắc cách crop hoặc preset phù hợp, hãy dùng dry-run:

```bash
python3 $S/fit.py input.mp4 --duration 60 --aspect 9:16 --dry-run
```

Bạn xem kế hoạch trước, rồi mới bỏ `--dry-run` khi đã rõ thao tác. Nếu cần lưu kế hoạch để chạy sau, các tool hỗ trợ `--plan FILE`; kế hoạch có fingerprint của input và sẽ từ chối nếu input đã thay đổi.

```note
Video vẫn được xử lý trên máy của bạn, nhưng file đầu ra có thể chứa nội dung nhạy cảm. Hãy kiểm tra đường dẫn đầu vào, thư mục đầu ra và quyền truy cập trước khi giao việc cho agent hoặc MCP client. Speech engine có thể tải model weights ở lần chạy đầu tiên; phần này có thể phát sinh thời gian tải và dung lượng lưu trữ.
```

## Lỗi hay gặp và cách xử lý

### `ffmpeg` hoặc `ffprobe` không được tìm thấy

Nguyên nhân thường là FFmpeg chưa cài hoặc chưa nằm trên PATH của terminal hiện tại. Hãy cài FFmpeg theo hệ điều hành và mở lại terminal, sau đó chạy `npx ffmpeg-skill doctor`.

Trên Windows, kiểm tra thêm Python: README cho biết Git Bash có thể nhận `python` hoặc `py` thay vì `python3`. Chỉ thay tên lệnh Python trong các ví dụ raw script; không tự đổi tên tham số của tool.

### `doctor` báo `ok: false` dù phần lớn tool vẫn dùng được

`ok` tổng thể sẽ thành `false` nếu bất kỳ thành phần cần cho một tool nào đó bị thiếu. Điều này không có nghĩa toàn bộ skill hỏng. Hãy xem trường `tools` trong `doctor --json` và kiểm tra riêng tool bạn cần.

Ví dụ, một bản FFmpeg thiếu filter có thể ảnh hưởng đến phụ đề hoặc ổn định hình ảnh, nhưng không nhất thiết chặn việc probe hoặc cắt đơn giản.

### Tool cần filter hoặc codec mà bản FFmpeg không có

Một số thao tác cần các thành phần như `libass`, `libx264`, `zscale`, `loudnorm` hoặc `xfade`. Chạy `doctor` trước để biết capability nào có sẵn. Nếu tool báo thiếu, hãy dùng thao tác khác phù hợp với capability hiện tại hoặc cài bản FFmpeg có thành phần đó; không nên cố ép một lệnh FFmpeg tự viết nếu bạn chưa kiểm tra contract.

### `python3` báo không tìm thấy trên Windows

Đây là khác biệt tên lệnh theo cách cài Python. Hãy thử thay `python3` bằng `python` hoặc `py` trong lệnh gọi script. README nói các lệnh cài đặt, `doctor` và `contract` đã xử lý việc chọn Python; phần cần sửa thủ công chủ yếu là các ví dụ raw script.

### `--transcribe` từ chối chạy

Tính năng transcribe cần một speech engine cục bộ và không được cài sẵn trong phần cốt lõi. README nêu `faster-whisper` là lựa chọn đơn giản:

```bash
pip install faster-whisper
```

Lần chạy đầu có thể tải model. Nếu chưa có engine, các chức năng khác vẫn hoạt động; `doctor` báo engine là optional missing và `--transcribe` sẽ trả về dòng hướng dẫn cài engine được hỗ trợ. Bạn cũng có thể cung cấp transcript đã có thay vì yêu cầu tool tự nhận dạng.

## Có nên dùng không

Nếu bạn muốn một coding agent chỉnh sửa video bằng các thao tác có cấu trúc, ffmpeg-skill là lựa chọn đáng cân nhắc. Repo có 42 tool, chạy cục bộ, không cần API key, hỗ trợ CLI lẫn MCP và có quy trình probe, plan, execute, check, look rõ ràng. Việc contract được sinh từ parser cũng giúp agent biết đúng tham số thay vì đoán chuỗi shell.

Skill đặc biệt hợp với các việc lặp lại: cắt nhiều đoạn, đổi video sang 9:16, tạo phụ đề, chuẩn hóa âm lượng, xuất nhiều preset và kiểm tra file giao hàng. Người dùng kỹ thuật có thể gọi script Python trực tiếp, còn người mới có thể giao việc cho Claude Code, Cursor hoặc Codex.

Giới hạn là bạn vẫn phải có FFmpeg tương thích và hiểu sơ bộ thư mục, terminal cùng file đầu vào. Một số tool phụ thuộc capability cụ thể của bản FFmpeg. Transcription không thuộc phần cốt lõi và cần cài speech engine, trong đó model có thể tải lần đầu. README cũng nói rõ repo là “hands”: nó thực hiện cắt, đo và xuất file, chứ không tự quyết định đoạn nào hấp dẫn, caption nên nói gì hoặc deliverable đã được duyệt hay chưa.

Nếu bạn cần agent phân tích nội dung, quyết định điểm cắt, lập kế hoạch toàn bộ video hoặc phê duyệt sản phẩm cuối, nên dùng thêm một lớp “brain” phù hợp. Nếu bạn chỉ cần một lệnh FFmpeg đơn giản và không cần agent, gọi FFmpeg trực tiếp có thể nhẹ hơn. Còn nếu mục tiêu là hậu kỳ cục bộ có kiểm tra và giao tiếp được với coding agent, ffmpeg-skill là một nền tảng thực tế và minh bạch.

## Câu hỏi thường gặp

### ffmpeg-skill có miễn phí không?

Tư liệu cung cấp cho biết repo dùng giấy phép MIT. README không nêu phí sử dụng; công cụ chạy cục bộ và không cần cloud hay API key.

### Có cần GPU để chạy không?

README không yêu cầu GPU và cũng không mô tả GPU là bắt buộc. Phần cốt lõi dùng FFmpeg và Python standard library; chưa có thông tin chi tiết về hiệu năng theo phần cứng.

### Có chạy được trên Windows không?

Có thể dùng trên Windows. README lưu ý trong Git Bash, Python có thể được gọi bằng `python` hoặc `py` thay cho `python3`; phần cài FFmpeg cho Windows nằm trong bảng Install của repo.

### Dữ liệu video có bị tải lên mạng không?

Phần xử lý video chạy cục bộ, không cần cloud và không cần API key. Khi dùng transcription, speech engine cũng chạy trên máy và audio không được tải lên, nhưng model weights có thể được tải ở lần chạy đầu.

### Có thể dùng mà không cần Claude Code, Cursor hoặc Codex không?

Có. README mô tả đây là một local FFmpeg engine có thể chạy standalone bằng `npx ffmpeg-skill` hoặc gọi trực tiếp các script Python. Coding agent và MCP client là các cách tích hợp thêm.

### Vì sao `doctor` báo không ổn dù một số lệnh vẫn chạy?

Trạng thái `ok` tổng thể là false nếu một capability cần cho bất kỳ tool nào bị thiếu. Hãy xem trường `tools` trong `doctor --json` để biết từng tool có `usable` hay không.

### Repo có tự viết lại nội dung phụ đề không?

Không. README nói cue text của người dùng được đốt vào video như đã cung cấp và không được viết lại để vừa cue. Skill có thể tạo phụ đề từ speech engine nếu bạn bật transcribe, nhưng engine đó cần cài riêng.
