Skip to main content
Trang này dành cho bạn nào muốn dùng full pipeline — có cả tạo voice tự động bằng AI, render video Remotion, chứ không chỉ index asset. Nếu bạn chỉ cần Asset Index (drop ảnh/video → search), dùng Bắt đầu nhanh sẽ nhẹ hơn (auto installer làm hộ phần lớn).Toàn bộ lệnh trong trang này gõ trong PowerShell as Administrator. Mở: nhấn Win + X → chọn Terminal (Admin) hoặc Windows PowerShell (Admin).
Bật Long Paths nếu đường dẫn repo > 260 ký tự (Windows mặc định cấm path quá dài, gặp khi cài trong OneDrive / Desktop sâu):Mở gpedit.msc → Computer Configuration → Administrative Templates → System → Filesystem → bật Enable Win32 long paths → restart.

​
Bạn sẽ cài 4 phần mềm

Phần mềmVai trò (dùng để làm gì?)Bắt buộc?
Python 3.10+Ngôn ngữ chạy mọi tool & skills trong repo (asset index, audio dedupe, semantic mapper…)Có
ffmpeg + ffprobeBộ công cụ chuẩn để đọc/cắt/ghép audio và video. Mọi pipeline media đều cầnCó
Node.js 20+ + npmChạy renderer Remotion (viết video bằng React) khi tới bước render cuốiCần nếu sẽ render
GitTải code mới về (git clone) và update sau này (git pull)Có (trừ khi tải ZIP)
Không cần nhớ hết. Mỗi phần mềm đều có 1 lệnh ngắn ở dưới — chép-dán là xong.

​
Các bước

1

Cài 4 phần mềm bằng winget

winget là gì? Là “Microsoft Store cho terminal” — đi kèm sẵn Windows 10/11, gõ 1 lệnh là cài xong, không phải tải .msi từng cái.Mở PowerShell as Administrator, dán lần lượt:
winget install Python.Python.3.12
winget install Gyan.FFmpeg
winget install OpenJS.NodeJS
winget install Git.Git
Python.Python.3.12 — Python bản ổn định nhất hiện tại. Gyan.FFmpeg — package ffmpeg phổ biến cho Windows, kèm luôn ffprobe. OpenJS.NodeJS — Node.js, kèm luôn npm. Git.Git — Git CLI chính thức.
Cài xong, đóng PowerShell và mở lại (để PATH cập nhật), rồi verify:
python --version    # phải >= 3.10, ví dụ Python 3.12.1
ffmpeg -version     # in nhiều dòng config
node --version      # phải >= 20, ví dụ v20.11.0
git --version       # ví dụ git version 2.43.0
Không có winget? (Win 10 cũ) — dùng Chocolatey thay:
choco install python ffmpeg nodejs git -y
2

Tải repo về máy

Chọn 1 trong 2 cách (xem chi tiết trong Bắt đầu nhanh — Bước 1):Cách nhanh (Git, khuyến nghị):
cd $HOME
git clone https://github.com/bachdyon/video-automator-skills
cd video-automator-skills
Sau lệnh này, PowerShell đang đứng trong thư mục C:\Users\<bạn>\video-automator-skills\. Mọi lệnh phía dưới đều chạy ở đây.
3

Tạo môi trường Python riêng (.venv) + cài thư viện

Tại sao cần .venv? Để cài đặt thư viện Python của repo này không đè lên Python hệ thống — sau này muốn xoá repo chỉ cần xoá folder, không ảnh hưởng máy.
python -m venv .venv
.venv\Scripts\python -m pip install --upgrade pip
.venv\Scripts\pip install -r tools\asset_index\requirements.txt
  • python -m venv .venv — tạo folder ẩn .venv\ chứa bản Python riêng cho repo.
  • .venv\Scripts\python -m pip install --upgrade pip — nâng cấp pip (trình quản lý thư viện) trong .venv lên bản mới.
  • pip install -r tools\asset_index\requirements.txt — đọc danh sách thư viện trong file requirements.txt rồi cài tự động.
Bước này tải mạng nhiều, cần ~30-60 giây tuỳ tốc độ internet.
4

Tạo file .env và điền API keys

API key là gì? Là “mật khẩu” để repo gọi dịch vụ AI (OpenAI, Gemini). Mỗi lần phân tích ảnh/video, repo gửi yêu cầu đến server OpenAI/Gemini — server kiểm tra key trước khi trả lời.Tạo file .env từ template có sẵn:
copy env.example .env
Mở .env bằng Notepad:
notepad .env
Không điền key theo ví dụ copy rời trong trang này để tránh lệch cấu hình.Hãy mở Cấu hình API keys và làm đúng theo trang đó (nguồn chuẩn duy nhất, luôn cập nhật).Trang đó có đầy đủ:
  • Biến nào bắt buộc / tuỳ chọn
  • Cách tạo từng key
  • Ví dụ .env mới nhất
  • Cách verify key hoạt động
File .env chứa “mật khẩu” — không share, không commit lên Git public. Repo đã có sẵn .gitignore để tránh accident, nhưng vẫn nên cẩn thận.
5

Cài Remotion skill (chỉ khi sẽ render Remotion)

Bước này bỏ qua nếu bạn chưa render video Remotion. Lệnh chạy bằng Git Bash hoặc WSL (vì là .sh):
bash scripts/ensure-remotion-skill.sh
Script này tự cài skill $remotion-best-practices vào folder .agents\skills\ — khi agent (Cursor, Claude Code) đụng tới Remotion sẽ đọc skill này để biết best practice.
Không có Git Bash? Khi cài Git ở bước 1, mặc định đã có Git Bash trong Start Menu. Hoặc bạn có thể tự chạy lệnh npx skills add remotion-dev/skills --yes (lệnh thay thế) trong PowerShell.
6

Đăng ký watcher chạy nền (luôn bật)

Watcher là gì? Là chương trình chạy ngầm — mỗi khi bạn drop file vào raw_assets\, watcher tự phát hiện, gọi AI phân tích, lưu vào DB. Không cần bật/tắt thủ công.Đăng ký watcher với Windows để tự bật mỗi khi đăng nhập:
.venv\Scripts\python -m tools.asset_index.service install
Lệnh này tạo task VideoAgentAssetIndex trong Task Scheduler (cơ chế chuẩn của Windows để chạy chương trình ngầm).Kiểm tra watcher đã bật:
.venv\Scripts\python -m tools.asset_index.service status
type .asset_index\state.json
state.json phải có pid (số > 0) và last_error: null. Nếu fail, xem Khắc phục sự cố.
7

Verify — test cuối

Test cả pipeline đã sẵn sàng:
  1. Copy 1 ảnh bất kỳ vào folder raw_assets\images\.
  2. Đợi ~5-10 giây (watcher debounce + Gemini phân tích + OpenAI embed).
  3. Search bằng từ khoá khớp nội dung ảnh:
.venv\Scripts\python -m tools.asset_index.search "<từ khoá liên quan ảnh>" --top 5
Phải trả về ≥ 1 kết quả với score > 0.5. Nếu không → đọc Khắc phục sự cố.

​
Lưu ý đặc thù Windows

Tất cả .bat đã có chcp 65001 để dùng UTF-8. Nếu chạy thủ công trong PowerShell và thấy chữ vỡ:
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
chcp 65001
Hoặc set vĩnh viễn cho PowerShell session:
$env:PYTHONIOENCODING = "utf-8"
Nếu Windows Defender chặn setup\Install.bat: chuột phải file → Properties → tick Unblock → Apply.
Có. Trong WSL (Ubuntu trong Windows), làm theo hướng dẫn Linux. Nhưng nếu đặt repo ở /mnt/c/... (filesystem Windows mount sang Linux), watcher không nhận file mới — phải dùng --polling hoặc đặt repo trong filesystem WSL native (~/).

​
Xong rồi! Tiếp theo làm gì?

Hiểu các API keys

Vai trò từng key, link tạo, giới hạn quota miễn phí.

Sử dụng cơ bản

Drop file → search → status — workflow hằng ngày.

Cấu trúc dự án

Hiểu vai trò các thư mục skills\, jobs\, tools\.

Khắc phục sự cố

8 lỗi hay gặp + cách xử lý.