# ffmpeg-skill: chỉnh sửa video cục bộ — hướng dẫn cài đặt và dùng

> ffmpeg-skill là Agent Skill cung cấp 42 công cụ FFmpeg có cấu trúc cho Claude Code, Cursor, Codex và MCP client. Skill hỗ trợ cắt, ghép, phụ đề, đổi tỷ lệ, xử lý âm thanh và xuất video theo nền tảng. Cài khá đơn giản nếu máy đã có FFmpeg, ffprobe, Python và Node.js từ phiên bản 16.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-11-02 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/ffmpeg-skill-huong-dan-cai-dat-va-su-dung

ffmpeg-skill là một Agent Skill giúp coding agent chỉnh sửa video bằng FFmpeg ngay trên máy tính. Bạn có thể dùng với Claude Code, Cursor, Codex hoặc một MCP client tương thích để cắt, ghép, thêm phụ đề, đổi khung hình, xử lý âm thanh và xuất file cho nhiều nền tảng.

Điểm đáng giá nhất là skill không chỉ chạy lệnh FFmpeg tùy ý. Nó đo thông tin file trước, chọn công cụ có cấu trúc, kiểm tra khả năng của bản FFmpeg đang cài rồi xác minh file đầu ra. Video và âm thanh được xử lý cục bộ, không cần tải lên cloud và không cần API key.

Skill phù hợp với chủ shop làm video ngắn, nhân viên văn phòng cần xử lý bản ghi, người làm nội dung và lập trình viên mới muốn giao việc video cho coding agent. Nếu bạn cần một hệ thống tự quyết định nội dung nào nên cắt hoặc caption nên viết gì, đây chưa phải phần “não” đó. ffmpeg-skill là phần “tay”, chuyên thực hiện và kiểm tra các thao tác trên file.

```repo
- repo | kajisho5/ffmpeg-skill
- kind | Skill
- desc | Skill cho coding agent chỉnh sửa video bằng FFmpeg cục bộ, hỗ trợ cắt, phụ đề, đổi khung hình, âm thanh và xuất bản.
- stars | 5.4k
- lang | Python
- license | MIT
```

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

- **Đo thông tin video trước khi chỉnh sửa.** Công cụ `probe.py` đọc thời lượng, tốc độ khung hình, độ phân giải, chiều xoay, độ sâu màu, HDR, Dolby Vision, thông tin màu và các luồng âm thanh. Agent có dữ liệu thật để xử lý, thay vì đoán từ tên file.

- **Cắt và ghép video.** Bạn có thể giữ nhiều đoạn trong một file, nối các clip hoặc tạo bản cắt theo mốc thời gian. Khi có thể, công cụ dùng stream copy để tránh mã hóa lại không cần thiết.

- **Xóa khoảng lặng và điều chỉnh thời lượng.** Skill có công cụ phát hiện khoảng lặng, đồng thời có thể làm video đạt thời lượng mong muốn. Điều này hữu ích khi biến một bản ghi dài thành video ngắn.

- **Đổi tỷ lệ và khung hình.** Công cụ `fit.py` giúp chuyển video sang 9:16, 16:9 hoặc tỷ lệ khác, với cách crop phù hợp. Đây là bước thường cần khi chuẩn bị video dọc.

- **Tạo phụ đề và hiệu ứng karaoke.** `caption.py` có thể đốt cue text vào video, tạo kiểu xuất hiện theo từ và hỗ trợ karaoke. Nội dung cue được dùng đúng như bạn đưa vào, không tự viết lại để vừa khung.

- **Làm sạch và chuẩn hóa âm thanh.** Skill có các công cụ xử lý âm thanh, loudness, dynamics và kiểm tra mức âm lượng. Ví dụ, bạn có thể chuẩn hóa về -14 LUFS và giới hạn true peak ở -1.

- **Thêm overlay và motion graphics.** Các công cụ tương ứng hỗ trợ lớp hình ảnh, chữ hoặc chuyển động trên video. Khi hình ảnh thay đổi, quy trình có thể tạo contact sheet để agent kiểm tra trực quan.

- **Chuyển HDR sang SDR và áp dụng LUT.** Đây là lựa chọn cho quy trình cần đưa video về định dạng màu dễ phát trên nhiều thiết bị hơn.

- **Đồng bộ và xử lý multicam.** Skill có công cụ cho drift correction và multicam, phù hợp với nội dung quay nhiều nguồn hoặc có vấn đề lệch âm thanh-hình ảnh.

- **Xuất theo nền tảng.** Các template có sẵn cho TikTok, Reels, Shorts, YouTube, X, LinkedIn, Facebook, podcast và audiogram. Template chứa tỷ lệ, vùng an toàn, giới hạn và preset xuất tương ứng.

- **Làm việc qua MCP.** MCP server cung cấp các công cụ cho client. Mặc định `tools/list` công bố 12 công cụ lõi để giảm lượng ngữ cảnh; đặt `FFMPEG_SKILL_MCP_FULL=1` sẽ liệt kê đủ 42 công cụ. Dù danh sách mặc định ngắn hơn, cả 42 công cụ vẫn có thể gọi theo tên qua `tools/call`.

- **Trả kết quả có cấu trúc.** Tùy công cụ, tùy chọn `--json` trả về trạng thái, file đầu ra, lệnh đã dùng và thông tin probe. Điều này phù hợp với agent và các quy trình tự động.

- **Lập kế hoạch trước khi chạy.** `--dry-run` in lệnh mà không thực thi, còn `--plan FILE` lưu kế hoạch để chạy sau. Kế hoạch có fingerprint đầu vào và từ chối chạy nếu file nguồn đã thay đổi.

- **Không tự ghi đè file.** Việc thay thế file có sẵn cần tùy chọn `--overwrite`, giúp giảm rủi ro mất bản gốc. Công cụ cũng dừng FFmpeg bị treo theo `--timeout` và dọn file đầu ra chưa hoàn chỉnh.

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

Bạn cần FFmpeg và ffprobe nằm trong PATH. Bản FFmpeg cần có các thành phần mà thao tác bạn chọn yêu cầu, chẳng hạn `libx264`, `libass`, `zscale`, `loudnorm` hoặc `xfade`. Lệnh `doctor` sẽ kiểm tra các thành phần này.

Repo yêu cầu Node.js từ phiên bản 16 vì được cài qua gói npm `ffmpeg-skill`. Phần xử lý chính dùng Python standard library và không yêu cầu các gói Python cho những chức năng cơ bản.

Bạn không cần tài khoản, API key hay dịch vụ cloud. Video được xử lý trên máy và không được tải lên.

Nếu muốn tạo phụ đề trực tiếp từ giọng nói bằng `caption.py --transcribe`, bạn cần cài riêng một speech engine cục bộ. README nêu `faster-whisper` là lựa chọn đơn giản nhất. Engine có thể tải model lần đầu chạy. Đây là yêu cầu tùy chọn, không ảnh hưởng đến các chức năng còn lại.

Trên Windows, README lưu ý rằng trong Git Bash, Python có thể được gọi là `python` hoặc dùng launcher `py`, tùy cách bạn cài Python. Các ví dụ script thô trong README dùng `python3`, nên bạn cần thay bằng lệnh Python đang có trên máy nếu `python3` không tồn tại.

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

```steps
- Cài FFmpeg | Cài FFmpeg để có ffmpeg và ffprobe
- Cài skill | Dùng npx để cài ffmpeg-skill cho coding agent
- Kiểm tra máy | Chạy doctor để biết công cụ nào dùng được
- Đọc contract | Xuất hợp đồng máy đọc được cho agent hoặc MCP
- Chạy thử | Giao một yêu cầu chỉnh sửa video cho agent
```

### Cài FFmpeg

README đưa ví dụ cho Ubuntu và Debian. Mở terminal, chạy lệnh sau:

```bash
sudo apt install ffmpeg
```

Lệnh này cài FFmpeg. Bạn cần kiểm tra để chắc rằng cả `ffmpeg` và `ffprobe` có thể được gọi từ PATH. README chỉ nêu lệnh cài cho Ubuntu/Debian; với macOS và Windows, hãy xem bảng Install trong README của repo để chọn cách cài phù hợp.

Nếu FFmpeg được cài nhưng thiếu một filter hoặc encoder, toàn bộ skill không nhất thiết hỏng. Một số tool vẫn có thể chạy. Vì vậy, hãy dùng `doctor` ở bước tiếp theo thay vì chỉ kiểm tra phiên bản FFmpeg.

### Cài skill cho coding agent

Chạy lệnh chính thức của README:

```bash
npx ffmpeg-skill
```

Lệnh này cài hoặc làm mới skill. Theo README, mặc định là cài cho Claude Code. Bạn có thể dùng tùy chọn `--cursor` cho Cursor, `--codex` cho Codex hoặc `--all` cho cả ba:

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

Bạn cần chạy terminal tại nơi Node.js và `npx` hoạt động. Nếu đã cài từ trước, chạy lại cùng lệnh để làm mới bản sao trong `~/.claude/skills/ffmpeg-skill`; các bản sao không tự cập nhật.

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

Sau khi cài, chạy:

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

`doctor` kiểm tra `ffmpeg`, `ffprobe` và các thành phần FFmpeg mà các tool cần. Kết quả `ok` có thể là `false` nếu chỉ một thành phần tùy chọn bị thiếu. Điều đó không có nghĩa mọi tool đều không chạy được. Hãy xem trường `tools` nếu dùng dạng JSON để biết từng tool có thể dùng hay không.

Nếu muốn lấy kết quả có cấu trúc:

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

Một bản FFmpeg cài sẵn có thể thiếu `subtitles`, `libvidstab` hoặc thành phần khác. Khi đó, hãy cài bản FFmpeg có thành phần cần thiết hoặc chỉ dùng các tool không phụ thuộc vào thành phần bị thiếu.

### Đọc contract cho agent hoặc MCP

README cung cấp lệnh xuất contract:

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

Contract mô tả input schema, output schema, vai trò, khả năng FFmpeg bắt buộc, hỗ trợ dry-run và cách xác minh kết quả của 42 tool. MCP server lấy danh sách tool và input schema từ cùng contract này, nên CLI và MCP có thể theo cùng một định nghĩa.

Trong PowerShell, `head` không phải lúc nào cũng có sẵn như trong môi trường Unix. Nếu mục tiêu chỉ là xem contract, bạn có thể chạy phần trước của lệnh và bỏ `| head -40`; README chỉ cung cấp chính xác ví dụ trên cho môi trường có `head`.

### Chạy tool trực tiếp hoặc giao việc cho agent

Sau khi cài, bạn có thể nói với agent:

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

Theo README, agent sẽ lần lượt dùng `probe.py`, `cut.py --segments 0:45-3:10,5:00-6:30`, `fit.py --duration 60 --aspect 9:16 --fit crop`, `export.py --preset reels`, `check.py --platform reels` và `look.py`.

Bạn cũng có thể gọi script trực tiếp. Đặt biến thư mục script theo ví dụ README:

```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 gọn của file. `fit.py --dry-run` chỉ in kế hoạch và không chạy chỉnh sửa. `export.py --json` trả về kết quả có cấu trúc kèm probe của file đầu ra.

Trên Windows, nếu `python3` báo không tìm thấy lệnh, hãy thay `python3` bằng `python` hoặc launcher `py` mà máy bạn có. README nói các lệnh cài đặt và `doctor`/`contract` đã xử lý việc này; chỉ những ví dụ gọi script thô mới cần thay thủ công.

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

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

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

Nếu FFmpeg, ffprobe và các thành phần cần thiết được phát hiện, `doctor` sẽ báo khả năng của từng tool. Đừng chỉ nhìn trường `ok`: trường này có thể là `false` vì một thành phần bị thiếu, trong khi phần lớn tool vẫn có thể dùng.

Sau khi giao việc cho agent, kết quả mong đợi là một file đầu ra có thông tin được báo lại. Ví dụ trong README, file cuối có thể được báo là `59.98 s, 1080×1920, 30 fps, AAC stereo`, kèm contact sheet mà agent đã kiểm tra.

Bạn cũng có thể thử thao tác không ghi file:

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

Nếu lệnh in kế hoạch mà không tạo file mới, cơ chế dry-run đang hoạt động. Với bản xuất có cấu trúc, dùng `--json` và kiểm tra trạng thái, đường dẫn đầu ra cùng thông tin probe.

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

### Chủ shop biến video ngang thành video dọc

Chủ shop có một video giới thiệu sản phẩm và muốn đăng Reels. Bạn có thể giao cho agent yêu cầu giữ những đoạn cần thiết, chuyển sang tỷ lệ 9:16 và xuất theo preset Reels:

```text
Take `product-demo.mp4`, keep 0:10–0:35 and 1:05–1:40, fit it to 9:16 with crop, and export it for Reels.
```

Agent sẽ probe file trước, cắt các đoạn, dùng `fit.py --aspect 9:16 --fit crop`, sau đó xuất và kiểm tra theo nền tảng. Kết quả là file dọc đã được kiểm tra thông tin kỹ thuật trước khi bàn giao.

### Nhân viên văn phòng rút gọn bản ghi cuộc họp

Một nhân viên có bản ghi dài và muốn bỏ khoảng lặng. Có thể dùng công cụ silence để nhận diện đoạn cần xử lý. Nếu đã có transcript, README cho phép truyền transcript vào thay vì bắt buộc cài speech engine.

```text
Remove long silences from `meeting.mp4`, preserve the speech, and return a JSON result with the output probe.
```

Agent có thể chạy quy trình đo, xử lý và kiểm tra. Nếu muốn dùng nhận dạng giọng nói tự động, cần cài một engine cục bộ trước. Không có engine, các chức năng khác vẫn hoạt động nhưng tùy chọn `--transcribe` sẽ từ chối và in hướng dẫn cài.

### Người làm nội dung thêm caption karaoke

Bạn có thể chuẩn bị cue text rồi nhờ agent đốt caption vào video. Nội dung caption được ghi đúng theo cue bạn đưa, không tự viết lại:

```text
Add the supplied cues to `lesson.mp4` with animated pop captions and karaoke timing, then inspect the visual output.
```

README minh họa các tùy chọn như `caption.py --animate pop --karaoke`. Sau khi hình ảnh thay đổi, agent có thể dùng `look.py` để tạo contact sheet và kiểm tra vị trí, hiển thị của caption.

### Dev chuẩn hóa bản xuất cho nhiều nền tảng

Một dev có thể dùng template để tạo bản xuất cho một nền tảng hoặc cả nhóm nền tảng. Ví dụ README cung cấp:

```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, loudness -14 LUFS và preset TikTok. Bạn cũng có thể dùng `--template all` hoặc danh sách phân tách bằng dấu phẩy để tạo nhiều bản xuất từ cùng một edit. `--dry-run` cho biết các lệnh dự kiến mà chưa tạo kết quả.

> Khi agent chỉnh video, điều quan trọng không chỉ là “đã chạy xong”, mà là file đầu ra đã được đo và kiểm tra.
>
> — Ông T

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

### `ffmpeg` hoặc `ffprobe` không có trong PATH

`doctor` sẽ không thể kiểm tra đầy đủ nếu các lệnh này không được gọi từ terminal. Hãy cài FFmpeg theo hệ điều hành và bảo đảm thư mục chứa lệnh đã nằm trong PATH, sau đó chạy lại `npx ffmpeg-skill doctor`.

### `doctor` báo `ok: false` dù một số tool vẫn dùng được

Đây là hành vi đã được README giải thích. `ok` là tín hiệu tổng thể và sẽ thành `false` khi bất kỳ thành phần mà một tool cần bị thiếu. Hãy xem trường `tools` trong `doctor --json` để biết tool nào thực sự dùng được.

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

README ghi rõ Python trên Windows có thể được gọi là `python` hoặc dùng launcher `py`. Chỉ thay `python3` trong các lệnh gọi script thô. Các lệnh cài đặt bằng `npx`, cùng `doctor` và `contract`, đã có xử lý riêng.

### `caption.py --transcribe` từ chối chạy

Bạn chưa có speech engine cục bộ phù hợp. Cài `faster-whisper` theo hướng dẫn README bằng lệnh sau:

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

Lần chạy đầu có thể tải model. Nếu không muốn cài engine, hãy cung cấp transcript có sẵn; những chức năng không dùng `--transcribe` vẫn hoạt động.

### Lệnh chỉnh sửa tạo lỗi vì thiếu filter hoặc encoder

Một số bản FFmpeg không có đủ `subtitles`, `libvidstab`, `libx264`, `zscale`, `loudnorm` hoặc `xfade`. Chạy `doctor` để biết capability nào thiếu, sau đó đổi sang tool không yêu cầu capability đó hoặc cài bản FFmpeg đầy đủ hơn. Không nên bỏ qua cảnh báo rồi đoán rằng file đầu ra hợp lệ.

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

Bạn nên dùng ffmpeg-skill nếu muốn xử lý video cục bộ bằng coding agent, cần 42 thao tác có input rõ ràng và muốn có bước probe, check, verify sau khi chạy. Skill không cần cloud, API key hay thư viện Python bên ngoài cho phần cơ bản. MIT cũng là giấy phép thuận tiện cho nhiều dự án.

Thiết kế `contract --json` và MCP là điểm mạnh lớn nếu bạn đang xây workflow tự động. Mỗi tool có schema, kết quả có thể trả JSON, và contract được sinh từ parser CLI để giảm nguy cơ CLI với MCP hiểu khác nhau. Việc hỗ trợ `--dry-run`, `--plan`, `--timeout` và `--overwrite` cũng phù hợp với quy trình cần kiểm soát.

Giới hạn là skill không tự quyết định video nào đáng cắt, highlight nào hay, deliverable đã được duyệt chưa hoặc caption nên nói gì. Nó thực hiện chỉ dẫn và cue text đã có. Nhận dạng giọng nói cũng không phải tính năng bắt buộc đi kèm; bạn phải cài engine và model riêng nếu cần.

Nếu bạn chỉ cần một lệnh FFmpeg đơn giản cho một file và đã quen tự kiểm tra kết quả, dùng FFmpeg trực tiếp có thể nhanh hơn. Nếu cần agent lập kế hoạch nội dung, phân tích media hoặc quản lý toàn bộ quy trình sản xuất, bạn sẽ cần thêm công cụ “phần não” bên ngoài. Còn nếu mục tiêu là một engine chỉnh sửa video local, có contract rõ ràng và biết tự kiểm tra đầu ra, ffmpeg-skill là lựa chọn đáng cân nhắc.

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

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

Tư liệu cho biết repo dùng giấy phép MIT và không cần cloud hay API key. README không nêu thêm chi phí sử dụng dịch vụ; phần xử lý chính chạy cục bộ bằng FFmpeg.

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

Tư liệu không nói rằng cần GPU. Skill được mô tả là chạy cục bộ với FFmpeg và Python standard library. Một số speech engine có thể tải model, nhưng README không xác nhận yêu cầu phần cứng GPU.

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

Có thể dùng trên Windows. README lưu ý rằng Python có thể được gọi bằng `python` hoặc launcher `py` thay cho `python3` trong các ví dụ gọi script thô.

### Có cần tài khoản hoặc API key không?

Không. README nêu rõ skill không cần tài khoản, cloud hoặc API key; video được xử lý trên máy.

### Dữ liệu video có an toàn không?

Theo tư liệu, video được xử lý cục bộ và không được tải lên. Nếu bạn dùng speech engine như faster-whisper, model có thể được tải lần đầu, nhưng audio vẫn không rời máy theo mô tả của README.

### Có bắt buộc cài speech engine để tạo phụ đề không?

Không bắt buộc cho toàn bộ skill. Chỉ các tùy chọn nhận dạng giọng nói như `caption.py --transcribe` cần speech engine; bạn cũng có thể cung cấp transcript đã có sẵn.

### ffmpeg-skill khác gì so với chạy lệnh FFmpeg trực tiếp?

Skill cung cấp 42 tool có input có cấu trúc, probe trước, contract máy đọc được và bước xác minh sau khi chạy. Nó cũng hỗ trợ CLI, MCP, dry-run, JSON và các template xuất theo nền tảng, thay vì chỉ nhận chuỗi lệnh FFmpeg tùy ý.
