VN Flag VI
Liên hệ

Hướng Dẫn Cài Đặt Tool

⚡ Chạy ngay sau khi giải nén

Nếu mục tiêu là chạy nhanh nhất trên macOS hoặc Windows, hãy ưu tiên Dev Container trên Docker.

Cách 1 — Antigravity + Dev Container

Yêu cầu: Docker Desktop + Antigravity đã cài.

Cài Docker Desktop (nếu chưa có)

macOS:

  1. Tải Docker Desktop for Mac từ trang chính thức của Docker.
  2. Mở file cài đặt, kéo Docker vào Applications.
  3. Chạy Docker Desktop, chờ đến khi báo sẵn sàng.

Windows:

  1. Tải Docker Desktop for Windows từ trang chính thức của Docker.
  2. Chạy file cài đặt.
  3. Bật WSL 2 hoặc tính năng ảo hóa nếu được yêu cầu, khởi động lại máy nếu cần.
  4. Mở Docker Desktop, chờ đến khi báo sẵn sàng.

Kiểm tra Docker đã cài xong chưa:

docker --version
docker compose version
Nếu cả hai lệnh đều hiện version → tiếp tục được.

Mở project bằng Antigravity

  1. Mở Antigravity.
  2. Chọn Open Folder và mở thư mục video-pipeline.
  3. Chọn Reopen in Container hoặc Open in Dev Container.
  4. Chờ build môi trường lần đầu hoàn tất.
  5. Mở terminal trong Antigravity và chạy:
npm start
  1. Mở trình duyệt tại:
http://localhost:3000
Repo đã có sẵn .devcontainer/devcontainer.json — Antigravity sẽ dùng đúng môi trường trong container.

Cách 2 — Docker thuần, không cần Antigravity

Nếu chỉ cần chạy app mà không cần mở bằng Antigravity, sau khi giải nén hãy mở terminal tại thư mục video-pipeline và chạy:

docker compose build
docker compose up -d

Mở trình duyệt tại:

http://localhost:3000

Các lệnh hữu ích:

# Xem log
docker compose logs -f app

# Kiểm tra môi trường trong container
docker compose run --rm app npm run doctor

# Dừng app
docker compose down
Dữ liệu nằm ở đâu?
Docker dùng volume video-pipeline-data để giữ sessions/, uploads/, pipeline.db, và settings.json. Xóa container không làm mất dữ liệu nếu chưa xóa volume.

Yêu cầu tối thiểu

  • macOS (Intel hoặc Apple Silicon)
  • Kết nối Internet trong lúc chạy setup
  • Quyền cài Node / Python / FFmpeg trên máy

Cài lần đầu

chmod +x setup-mac.sh run-mac.sh
./setup-mac.sh

Script sẽ tự động:

  • Cài Homebrew nếu chưa có
  • Cài node@22
  • Cài python@3.11
  • Cài ffmpeg
  • Chạy npm install
  • Tạo .venv riêng trong project
  • Cài Python package từ requirements.txt
  • Chạy npm run doctor để kiểm tra

Kiểm tra môi trường

npm run doctor
Nếu thấy Moi truong da san sang. là OK.

Chạy app

./run-mac.sh

Mở trình duyệt tại: http://localhost:3000

API key vẫn nhập trên giao diện web như cũ, không cần file .env.

Yêu cầu tối thiểu

  • Windows 10 / 11
  • Kết nối Internet trong lúc chạy setup
  • Quyền cài Node / Python / FFmpeg trên máy

Cài lần đầu

setup-windows.bat

Script sẽ tự động:

  • Cài Node.js LTS
  • Cài Python 3.11
  • Cài FFmpeg
  • Chạy npm install
  • Tạo .venv riêng trong project
  • Cài Python package từ requirements.txt
  • Chạy npm run doctor để kiểm tra

Kiểm tra môi trường

npm run doctor

Chạy app

run-windows.bat

Mở trình duyệt tại: http://localhost:3000

API key vẫn nhập trên giao diện web như cũ, không cần file .env.

📦 Khi gửi source cho người khác

Nên gửi kèm các file này:

  • setup-mac.sh
  • setup-windows.bat / setup-windows.ps1
  • run-mac.sh / run-windows.bat
  • requirements.txt
  • package.json + package-lock.json
  • Dockerfile + docker-compose.yml

Không nên gửi:

  • node_modules/
  • .venv/
  • File database tạm hoặc session render (nếu không cần)

🏆 Thứ tự ưu tiên khi bàn giao

  1. Người dùng có Docker → dùng Docker.
  2. Không có Docker → dùng script setup native.
  3. Luôn yêu cầu chạy npm run doctor trước khi báo lỗi.

🐛 Lỗi thường gặp

doctor báo thiếu faster-whisper

Chạy lại script setup của hệ điều hành tương ứng. Package này phải nằm trong .venv của project.

Chạy app báo chưa có .venv

Máy đó chưa setup xong hoặc đã xóa .venv. Chạy lại script setup.

node đang là bản quá mới

Project khuyến nghị Node 20 đến <25. Chạy lại setup để dùng Node LTS ổn định hơn.

Cài xong vẫn lỗi PATH

Đóng terminal hiện tại, mở terminal mới, sau đó chạy lại:

npm run doctor

💡 Vì sao cách này ổn hơn cách cũ?

Cách cũ dễ lỗi vì:

  • Máy người khác có sẵn Python nhưng sai version.
  • pip install cài vào môi trường global, dễ đụng package cũ.
  • PATH giữa các máy không giống nhau.
  • Cài xong nhìn tưởng đủ, nhưng lúc chạy Whisper mới vỡ ra thiếu faster-whisper.

Cách mới xử lý đúng bằng cách:

  • Node cài theo package-lock.json của project.
  • Python không cài global nữa — tạo .venv riêng ngay trong project.
  • Lúc chạy app, project tự ưu tiên Python trong .venv, không phụ thuộc PATH của máy người dùng.