# SỔ TAY HƯỚNG DẪN SỬ DỤNG PHẦN MỀM VIDEODETECTION STUDIO
### Hệ Thống Đối Soát & Phát Hiện Trùng Lặp Bản Quyền Video Đa Phương Thức (V-JEPA 2 & NeuralFP)

---

## 1. GIỚI THIỆU TỔNG QUAN

**VideoDetection Studio** là phần mềm chuyên dụng hỗ trợ các nhà sáng tạo nội dung, đài truyền hình, kênh truyền thông và doanh nghiệp rà soát, phát hiện vi phạm bản quyền video tự động với độ chính xác cao.

### Điểm Vượt Trội Về Công Nghệ:
- **Thị giác máy tính (Visual AI - V-JEPA 2 từ Meta AI)**: Phân tích sâu ngữ nghĩa chuỗi chuyển động không-thời gian (Spatio-Temporal). Kháng mọi thủ thuật lách bản quyền tinh vi như: lật gương (horizontal flip), phóng to/cắt xén khung hình (zoom/crop), đổi tỷ lệ khung hình, chèn logo/watermark, làm mờ, đổi dải màu hoặc thay đổi nhẹ tốc độ phát.
- **Âm thanh kỹ thuật số (Audio AI - NeuralFP)**: Trích xuất dấu vân tay âm thanh 128-bit nhị phân cực nhạy. Nhận diện chuẩn xác ngay cả khi âm thanh bị nén, giảm chất lượng, thay đổi âm lượng hoặc bị chèn thêm nhạc nền/tiếng ồn môi trường.
- **Đối soát tức thì (< 0.1 giây)**: Nhờ cơ chế băm nén vector (Product Quantization PQ64 & Hamming Bit-Fingerprint) kết hợp cơ sở dữ liệu SQLite cục bộ, việc đối soát giữa một video dài với hàng nghìn giờ video gốc diễn ra trong chớp mắt.
- **Độc lập 100% (Portable Zero-Install)**: Chạy trực tiếp từ thư mục, không cần cài đặt Python, không yêu cầu thiết lập môi trường phức tạp trên hệ điều hành Windows 10/11.

---

## 2. CẤU TRÚC THƯ MỤC CÔNG VIỆC

Để sử dụng thuận tiện nhất, phần mềm đã chuẩn hóa các thư mục chức năng:

```text
VideoDetection/
│
├── VideoDetection.bat       <-- TẬP TIN KHỞI ĐỘNG CHÍNH (Nhấp đúp chuột để mở)
├── config.yaml              <-- Cấu hình hệ thống (ngưỡng nhận diện, thiết bị GPU/CPU)
├── main.py                  <-- Điểm vào chương trình (hỗ trợ cả GUI và CLI)
│
├── Data/                    <-- KHO VIDEO GỐC CỦA CHỦ SỞ HỮU (Video bản quyền cần bảo vệ)
│   ├── .features/           <-- Lưu trữ đặc trưng AI được nạp sẵn để đối soát nhanh
│   └── videodetection.db    <-- Cơ sở dữ liệu SQLite quản lý danh mục và lịch sử
│
├── Target/                  <-- THƯ MỤC CHỨA VIDEO MỤC TIÊU CẦN KIỂM TRA (Video nghi vấn)
│   └── .features/           <-- Đặc trưng của các video cần rà soát
│
├── Temp/                    <-- Thư mục chứa tệp trung gian khi giải mã (có thể dọn dẹp)
├── bin/                     <-- Bộ công cụ đa phương tiện nhúng sẵn (ffmpeg.exe, ffprobe.exe)
└── models/                  <-- Bộ trọng số mô hình trí tuệ nhân tạo (V-JEPA 2 & NeuralFP)
```

> **Định dạng video được hỗ trợ**: `.mp4`, `.mkv`, `.avi`, `.mov`, `.flv`, `.webm`, `.ts`, `.m4v`, `.wmv`.

---

## 3. HƯỚNG DẪN KHỞI ĐỘNG VÀ BẮT ĐẦU NHANH

### Cách 1: Khởi động giao diện đồ họa (Khuyên dùng cho người dùng cuối)
1. Mở thư mục phần mềm `VideoDetection`.
2. Nhấp đúp chuột vào tệp **`VideoDetection.bat`**.
3. Cửa sổ ứng dụng **VideoDetection Studio** với giao diện Fluent Dark Mode hiện đại (Windows 11) sẽ xuất hiện.
4. Ở lần mở đầu tiên hoặc khi có video mới, thanh trạng thái góc trên bên phải sẽ hiển thị quá trình tự động đồng bộ và trích xuất đặc trưng AI. Khi hoàn tất, huy hiệu chuyển sang màu xanh lá: **`Sẵn sàng (Số liệu đã nạp)`**.

---

## 4. QUY TRÌNH ĐỐI SOÁT CHI TIẾT TRÊN GIAO DIỆN

Giao diện ứng dụng được chia thành 3 thẻ chức năng chính:

### Thẻ 1: 🎯 Trung Tâm Đối Soát & So Sánh (Compare Center)

Đây là không gian làm việc chính để thực hiện rà soát vi phạm.

#### Bước 1: Chọn Video Mục Tiêu (Target Video)
- Ở khung **1. Chọn Video Mục Tiêu (Target)** bên tay trái, danh sách toàn bộ các video có trong thư mục `Target/` sẽ được liệt kê kèm thời lượng và trạng thái.
- Nhấp chuột vào tên video mà bạn muốn kiểm tra.

#### Bước 2: Lựa chọn phạm vi đối soát
Ở khung **2. Chọn Đối Tượng Tham Chiếu (Kho Data)** bên phải, chọn 1 trong 2 chế độ:
- **Chế độ 1: So sánh với TOÀN BỘ kho Data/ (Khuyên dùng)**: Phần mềm sẽ đem video mục tiêu đối chiếu với toàn bộ kho video gốc của chủ sở hữu.
- **Chế độ 2: Chỉ so sánh với các video được chọn bên dưới**: 
  - Kích hoạt chế độ này khi bạn nghi ngờ video mục tiêu chỉ cắt ghép từ một vài video cụ thể.
  - Sử dụng danh sách hộp kiểm (checkbox) bên dưới để tích chọn các video gốc cần so sánh.
  - Có sẵn hai nút tiện ích: **`✓ Chọn Tất Cả`** và **`✗ Bỏ Chọn Hết`**.

#### Bước 3: Bấm nút Đối Soát
- Nhấn nút màu xanh nổi bật: **`⚡ BẮT ĐẦU ĐỐI SOÁT (TỨC THÌ < 0.1s)`**.
- Quá trình đối soát diễn ra chỉ trong vài mili-giây (do đặc trưng đã được tính toán sẵn).

#### Bước 4: Đọc kết quả và Cảnh báo
Kết quả xuất hiện ngay tại bảng **3. Bảng Kết Quả Đối Soát Trùng Lặp**:
- **Trường hợp An Toàn**: Bảng thông báo `AN TOÀN - Không có trùng khớp`. Điều này đồng nghĩa video mục tiêu hoàn toàn độc lập, không vi phạm bản quyền kho của bạn.
- **Trường hợp Phát hiện Trùng Lặp**: Dòng kết quả chuyển trạng thái cảnh báo màu đỏ (`TRÙNG LẶP`), hiển thị rõ ràng:
  - **Video Mục Tiêu**: Tên file đang kiểm tra.
  - **Video Gốc Trùng Khớp**: Tên video gốc bị sao chép trong kho `Data/`.
  - **Khoảng Target**: Khung giờ đoạn cắt trên video mục tiêu (VD: `00:03 - 00:22`).
  - **Khoảng Gốc**: Khung giờ đoạn gốc tương ứng (VD: `00:08 - 00:27`).
  - **Thời Lượng**: Tổng thời gian trùng lặp tính theo giây (VD: `17.0s`).
  - **Độ Trùng**: Tỷ lệ tương đồng (%) (VD: `91.4%`).
  - **Dạng Nhận Diện**: 
    - `Hình ảnh & Âm thanh` (Khớp cả hình và tiếng - sao chép nguyên bản).
    - `Chỉ Hình ảnh` (Khớp hình nhưng đã tắt tiếng hoặc thay nhạc nền).
    - `Chỉ Âm thanh` (Khớp tiếng nhưng thay thế hình ảnh khác).

#### Bước 5: Xuất báo cáo chứng cứ vi phạm
- Nhấn nút **`💾 Xuất Báo Cáo JSON`** ở góc phải bảng kết quả.
- Chọn vị trí lưu file (mặc định tên `ket_qua_doi_soat.json`). Tệp này chứa đầy đủ mốc thời gian chi tiết từng giây, độ tin cậy và căn cứ kỹ thuật để bạn dùng làm bằng chứng khiếu nại bản quyền lên các nền tảng (YouTube, Facebook, TikTok,...).

---

### Thẻ 2: 📥 Tải Video YouTube (YouTube Downloader)

Đây là tính năng tích hợp trực tiếp giúp bạn tải video hoặc **trích xuất chính xác một phân đoạn chỉ định** từ YouTube mà không tốn dung lượng hay thời gian tải cả video dài:

1. **Nhập Link hoặc Video ID**:
   - Chấp nhận mọi định dạng: Mã ID 11 ký tự (VD: `aqz-KE-bpKQ`), Link đầy đủ `https://www.youtube.com/watch?v=...`, Link rút gọn `https://youtu.be/...`, Link Shorts, Embed hoặc Live.
   - Có nút **`📋 Dán Clipboard`** để nhập nhanh từ bộ nhớ tạm.
2. **Chọn phân đoạn thời gian tải (Section Range)**:
   - **Mặc định**: Tự động tải **1 Giờ đầu tiên** (`00:00:00 - 01:00:00`). Nếu video ngắn hơn 1 giờ, phần mềm tải trọn vẹn đến hết video.
   - **Các nút chọn nhanh**: `⏱️ 1 Giờ Đầu`, `⏱️ 30 Phút Đầu`, `⏱️ 15 Phút Đầu`, hoặc `🎬 Toàn Bộ Video`.
   - **Tùy chỉnh tự do**: Bạn có thể nhập bất kỳ khoảng thời gian nào theo định dạng `HH:MM:SS - HH:MM:SS` (Ví dụ: `00:05:30 - 00:20:00`).
3. **Chọn thư mục lưu trữ**:
   - `🎯 Thư mục Target/ (Mặc định)`: Dành cho các video nghi ngờ vi phạm cần rà soát.
   - `📁 Thư mục Data/`: Dành cho các video gốc của chủ sở hữu cần lưu vào kho bản quyền.
4. **Tự động xử lý AI**:
   - Tích chọn `✅ Tự động trích xuất đặc trưng AI (V-JEPA 2 & NeuralFP) ngay sau khi tải xong`. Video tải về sẽ lập tức xuất hiện trong danh sách đối soát và sẵn sàng so sánh ngay trong 0.1 giây.
5. **Nhật ký tiến độ thời gian thực**:
   - Khung nhật ký bên dưới cập nhật trực tiếp tiến độ tải, tốc độ mạng (MB/s) và quá trình đóng gói MP4.

---

### Thẻ 3: 📁 Quản Lý File Data/ & Target/

Thẻ này giúp việc thêm bớt video vào kho dữ liệu trở nên cực kỳ đơn giản:

1. **Kho Video Gốc Chủ Sở Hữu (`Data/`)**:
   - Nhấn **`📂 Mở Thư Mục Data/`**: Thư mục sẽ được mở trực tiếp trong Windows Explorer.
   - Bạn chỉ cần Copy & Paste video gốc của mình vào đây.
2. **Thư Mục Video Mục Tiêu (`Target/`)**:
   - Nhấn **`📂 Mở Thư Mục Target/`**: Thư mục đích mở ra trong Windows Explorer.
   - Copy & Paste các video tải về từ mạng hoặc video nghi ngờ vi phạm vào đây.
3. **Cập nhật dữ liệu mới**:
   - Sau khi copy video vào các thư mục trên, quay lại phần mềm và nhấn nút **`🔄 Quét & Đồng Bộ Video Mới`** trên thanh tiêu đề phía trên cùng bên phải.
   - Phần mềm sẽ tự động tính toán đặc trưng cho các video mới bổ sung mà không làm ảnh hưởng đến dữ liệu cũ.

---

### Thẻ 4: ⚙️ Cấu Hình & Tiện Ích

- **Thông tin kỹ thuật**: Xem thiết bị phần cứng đang hoạt động (NVIDIA GPU CUDA hoặc CPU), các mô hình AI đang nạp.
- **Tiện ích dọn dẹp dung lượng**: Nhấn **`🧹 Dọn Dẹp File Tạm Trong Temp/`** để xóa sạch các đoạn clip và âm thanh tạm thời phát sinh trong quá trình phân tích, giúp giải phóng bộ nhớ ổ đĩa.

---

## 5. DÀNH CHO KỸ THUẬT VIÊN & TỰ ĐỘNG HÓA (DÒNG LỆNH CLI)

Ngoài giao diện đồ họa, VideoDetection Studio hỗ trợ đầy đủ giao diện dòng lệnh (CLI) phục vụ việc lập lịch tự động (cron/task scheduler) hoặc tích hợp vào hệ thống backend:

### Mở Terminal (PowerShell hoặc CMD) tại thư mục `VideoDetection`:

1. **Tải video YouTube (Mặc định tải 1 giờ đầu vào thư mục `Target/`)**:
   ```powershell
   python main.py download "https://www.youtube.com/watch?v=ID_VIDEO"
   ```

2. **Tải một phân đoạn chỉ định và tự động trích xuất đặc trưng AI ngay**:
   ```powershell
   python main.py download "ID_VIDEO" --section "00:05:00-00:20:00" --dest target --sync
   ```

3. **Tải video YouTube trực tiếp vào kho bản quyền `Data/`**:
   ```powershell
   python main.py download "https://youtu.be/ID_VIDEO" --dest data --sync
   ```

4. **Tải toàn bộ video (không giới hạn 1 giờ đầu)**:
   ```powershell
   python main.py download "ID_VIDEO" --section all
   ```

5. **Đồng bộ toàn bộ kho video mới**:
   ```powershell
   python main.py sync
   ```

6. **Đối soát một video cụ thể với toàn bộ kho Data/**:
   ```powershell
   python main.py compare "target_composite_mashup.mp4"
   ```

7. **Đối soát một video với các video tham chiếu chỉ định**:
   ```powershell
   python main.py compare "target_composite_mashup.mp4" --refs "ref_sintel_15m.mp4" "sample_ref_bunny.mp4"
   ```

8. **Quét toàn bộ thư mục Target/ và xuất kết quả dạng JSON**:
   ```powershell
   python main.py scan --json
   ```

9. **Đăng ký một video gốc mới vào kho bản quyền**:
   ```powershell
   python main.py index "D:\Videos\PhimGoc2026.mp4"
   ```

10. **Dọn dẹp thư mục file tạm**:
    ```powershell
    python main.py clean
    ```

---

## 6. CÂU HỎI THƯỜNG GẶP & XỬ LÝ SỰ CỐ (FAQ & TROUBLESHOOTING)

### ❓ 1. Sau khi chép video mới vào `Data/` hoặc `Target/`, tại sao phần mềm chưa hiển thị?
👉 **Cách khắc phục**: Nhấp vào nút **`🔄 Quét & Đồng Bộ Video Mới`** ở góc trên bên phải giao diện ứng dụng. Hệ thống sẽ quét thư mục, phân tích đặc trưng AI và cập nhật danh sách ngay lập tức.

### ❓ 2. Video bị lật ngược (Mirror), cắt viền đen (Crop), chèn logo hoặc đổi màu thì phần mềm có nhận biết được không?
👉 **Trả lời**: **CÓ**. Mô hình V-JEPA 2 (Meta AI) học đặc trưng ở cấp độ cấu trúc không gian và chuyển động động lực học, không phụ thuộc vào màu sắc hay vị trí tĩnh pixel. Các thử nghiệm thực tế chứng minh phần mềm nhận diện chính xác 100% video đã qua lật gương (hflip), cắt cúp viền hoặc chèn biểu tượng logo.

### ❓ 3. Video chỉ lấy âm thanh (audio) nhưng thay đổi toàn bộ hình ảnh thì có phát hiện được không?
👉 **Trả lời**: **CÓ**. Module NeuralFP sẽ độc lập bắt dấu vân tay âm thanh và gắn nhãn dạng nhận diện là `Chỉ Âm thanh` (Audio only) kèm khung giờ vi phạm chuẩn xác đến từng giây.

### ❓ 4. Máy tính văn phòng không có card đồ họa NVIDIA rời có dùng được không?
👉 **Trả lời**: **ĐƯỢC**. Hệ thống tích hợp cơ chế tự thích ứng: nếu phát hiện GPU NVIDIA hỗ trợ CUDA sẽ tự động tăng tốc; nếu không có GPU, phần mềm tự động chạy bằng CPU. Quá trình tính toán ban đầu cho video mới trên CPU sẽ lâu hơn một chút, nhưng khi đã lưu đặc trưng xong thì tốc độ đối soát vẫn đạt mức mili-giây.

### ❓ 5. Làm thế nào để điều chỉnh độ nhạy hoặc thời lượng tối thiểu của đoạn trùng?
👉 **Cách làm**: Mở tệp `config.yaml` bằng Notepad và điều chỉnh các thông số:
- `min_match_duration_sec: 3.0`: Độ dài tối thiểu của đoạn trùng (mặc định 3 giây). Nếu muốn chỉ cảnh báo các đoạn cắt từ 5 giây trở lên, bạn đổi thành `5.0`.
- `similarity_threshold: 0.78`: Ngưỡng độ tương đồng thị giác (từ 0.0 đến 1.0).
- Sau khi chỉnh sửa, lưu file lại và khởi động lại phần mềm.

---
*Bản quyền tài liệu thuộc về dự án VideoDetection Studio. Hỗ trợ kỹ thuật 24/7.*