--- name: capcut-retention-subtitles description: | Tạo phụ đề giữ chân cao cấp cho CapCut PC theo quy trình AI phân tích ngữ nghĩa, người dùng duyệt, Python thực thi chính xác. Dùng khi cần sửa ASR tiếng Việt, chọn từ khóa vàng neon, chia phụ đề 1 dòng/2 tầng/multiline, gắn animation chữ, đồng bộ project CapCut giữa C: và D:, tạo phiên bản mới hoặc kiểm tra phụ đề TikTok/Reels/Shorts. --- # CapCut Retention Subtitles Tạo phụ đề Phudu Bold có từ khóa vàng, nhịp hiển thị rõ và timeline liền mạch. Giữ quyết định ngữ nghĩa ở AI; dùng Python cho thao tác kỹ thuật có thể kiểm chứng. ## Hợp đồng bắt buộc - **AI Agent chọn nội dung:** đọc bối cảnh, sửa ASR, chia ngữ đoạn, chọn từ khóa, chọn animation và giải thích lý do. - **Người dùng duyệt:** phải xem toàn bộ bảng câu/từ khóa trước khi ghi CapCut. - **Python không được tự chọn từ khóa:** chỉ trích xuất dữ liệu, kiểm tra plan, backup, render JSON, đồng bộ và verify. - Không đánh dấu plan là `approved` trước khi người dùng trả lời `OK`, `Duyệt` hoặc `Làm đi` sau bảng phân tích. - Không chạy `apply` với plan `pending`. - Không ghi khi CapCut đang chạy. Không force-kill ứng dụng vì có thể làm mất thay đổi chưa lưu. - Không tự xóa hoặc ghi đè project cũ. Mọi cleanup phải có danh sách đích chính xác, backup và xác nhận rõ ràng. ## Tài nguyên - `scripts/apply_retention_subtitles.py`: `extract`, `validate`, `apply`, `verify`. - `scripts/create_clean_sub_project.py`: tạo version mới hoặc cleanup có xác nhận. - `references/plan.schema.json`: schema plan được AI soạn và người dùng duyệt. Đọc file này khi tạo hoặc sửa plan. - `references/24_anims.json`: 24 animation đã xác thực. Chỉ dùng tên có trong file này. ## Kiến trúc lưu trữ chính thức (Canonical Workspace) - **Đường dẫn lưu trữ duy nhất:** `D:\CapCut\User Data\Projects\com.lveditor.draft` - **Cơ chế hệ thống:** Thư mục `C:\Users\adminMoi\AppData\Local\CapCut` trên Windows là một **Directory Junction** (liên kết thư mục cứng) trỏ trực tiếp về `D:\CapCut`. Dữ liệu vật lý thực tế 100% nằm trên ổ `D:`. - **Nguyên tắc thao tác:** Tất cả script Python, sao lưu, trích xuất và ghi timeline can thiệp trực tiếp vào đường dẫn ổ `D:`. Không ghi đè hay tạo bản sao thừa nhằm tránh tình trạng CapCut quét trùng lặp x2 project trên màn hình chính. ## Chuẩn đặt tên dự án & Versioning - Quy ước đặt tên: `{Chủ_Đề_2_Từ} - v{Phiên_Bản}` (ví dụ: `Chi Phí - v3`, `Nỗi Lo - v1`). - Khi tạo phiên bản hoặc đổi tên, phải cập nhật đồng bộ để CapCut chỉ nhận 1 nguồn duy nhất trên ổ D: (tránh bị lặp x2 thẻ dự án): 1. Tên thư mục: `D:\CapCut\User Data\Projects\com.lveditor.draft\{Tên_Dự_Án}` 2. File `draft_meta_info.json` (thuần 100% ổ D:, tuyệt đối không trỏ về ổ C:): - `"draft_name": "{Tên_Dự_Án}"` - `"draft_fold_path": "D:/CapCut/User Data/Projects/com.lveditor.draft/{Tên_Dự_Án}"` - `"draft_root_path": "D:/CapCut/User Data/Projects/com.lveditor.draft"` - `"draft_removable_storage_device": "D:"` ## Quy tắc Âm thanh Hiệu ứng (SFX Transition Sync) - **2 Track SFX song song:** SFX chuyển cảnh được chia thành 2 track audio riêng biệt: - **Track 3 (SFX Track 1):** Đồng bộ tuyệt đối theo mốc xuất hiện (In-Animation) của Phụ đề Tầng Trên (Track 1). - **Track 4 (SFX Track 2):** Đồng bộ tuyệt đối theo mốc xuất hiện (In-Animation) của Phụ đề Tầng Dưới (Track 2). - **Phân loại âm thanh ngữ cảnh:** Chọn âm thanh phù hợp ngữ nghĩa câu nói (Click/Pop cho từ khóa ngắn, Typing cho xuất hiện từng chữ, Swoosh/Glitch/Bass cho chuyển đoạn hoặc từ khóa nhấn mạnh). - **Micro-timing:** Điểm bắt đầu `start` của SFX phải trùng khớp từng micro-giây với điểm `start` của segment phụ đề tương ứng. Độ dài SFX ngắn gọn (300ms - 800ms) để không đè lẫn nhau. ## Visual tokens | Thuộc tính | Giá trị | |---|---| | Font | `C:/Users/adminMoi/AppData/Local/Microsoft/Windows/Fonts/Phudu-Bold.ttf` | | Chữ nền | Trắng `#FFFFFF`, size `8.0` | | Từ khóa | Vàng neon `#F0FF00`, size `12.0` | | Viền | Đen `#000000`, width `0.06` | | Scale | `x=1.23`, `y=1.23` | | Pair top | `y=0.60` | | Pair bottom | `y=0.49` | | Single/multiline | `y=0.54` | | Animation | `500000us` (0.5s) | | Độ dài | Tối đa 28 ký tự mỗi dòng | Mọi dòng phải có cả trắng và vàng. Chỉ cho phép full vàng khi layer có `punchline: true`, là một dòng và ngắn hơn 4 từ. ## Quy tắc ngữ nghĩa 1. Sửa lỗi ASR theo toàn bộ câu chuyện, không sửa bằng đối chiếu từ đơn lẻ. 2. Giữ nguyên từ ghép như `nhân sự`, `doanh thu`, `mặt bằng`, `hòa vốn`. 3. Ưu tiên thực thể, nỗi đau, hành động, số liệu và kết luận làm từ khóa. 4. Không chọn hư từ hoặc khẩu ngữ đệm như `là`, `và`, `của`, `thì`, `bao gồm`, `cho em hỏi là`. 5. Với câu 5–8 từ, giữ tỷ lệ vàng khoảng 30–60%; không tô toàn bộ câu. 6. Đọc lướt riêng các từ vàng phải hiểu được mạch nội dung chính. 7. Mỗi dòng là một ngữ đoạn trọn nghĩa; không cắt đôi từ ghép. ## Bố cục và timing - `pair`: top và bottom là hai dòng riêng, cấm `\n`; top bắt đầu đúng từ đầu vế 1, bottom bắt đầu đúng từ đầu vế 2, cùng kết thúc tại `end_us`. - `single`: một dòng tại `y=0.54`. - `multiline`: đúng hai dòng trong một layer tại `y=0.54`; mỗi dòng phải có trắng và vàng. - Không ước lượng `bottom_start_us` bằng phần trăm thời lượng. Dùng word timestamp của ASR hoặc mốc segment đã được xác thực. - Khối đầu bắt đầu tại `0`; `end_us` của khối trước bằng `start_us` của khối sau; khối cuối kết thúc đúng `duration_us`. - Phân bổ tham khảo: pair 55–65%, single 20–25%, multiline 10–15%. Ưu tiên ngữ nghĩa hơn việc ép tỷ lệ. ## Quy trình bắt buộc ### 1. Trích xuất nguồn Chạy từ thư mục skill: ```powershell python scripts/apply_retention_subtitles.py extract ` --project "TEN_PROJECT" ` --output "C:\duong-dan\subtitle-plan.json" ``` Lệnh chỉ đọc CapCut và tạo plan `pending` gồm `source_captions`; nó không tạo từ khóa và không ghi project. ### 2. AI phân tích và lập plan Đọc `references/plan.schema.json`, điền `blocks` bằng microsecond chính xác. Với mỗi block, xác định: - `mode`, `start_us`, `end_us`; thêm `bottom_start_us` cho `pair`. - `top.text`, `top.keywords`, `top.animation`. - `bottom` cho `pair`. - `reason`: một câu ngắn giải thích lựa chọn ngữ nghĩa. Giữ `approval.status: pending` ở bước này. ### 3. Trình bảng duyệt và dừng Trình toàn bộ block theo mẫu: ```markdown ### PHẦN X: Mạch nội dung (start_s–end_s) * Đoạn Y (start_s–end_s) - Câu: Vế 1 `[VÀNG: TỪ KHÓA]` / Vế 2 `[VÀNG: TỪ KHÓA]` - Hiệu ứng: `Top` / `Bottom` - Ý nghĩa: Lý do chọn từ khóa. ``` Dừng và chờ xác nhận. Sau khi người dùng duyệt, cập nhật: ```json "approval": { "status": "approved", "approved_by": "user", "approved_at": "ISO-8601 timestamp" } ``` ### 4. Tạo phiên bản an toàn Giữ nguyên project gốc. Đặt tên bản mới theo `{Chủ đề 2 từ} - vN`: ```powershell python scripts/create_clean_sub_project.py create ` --source-project "TEN_PROJECT_GOC" ` --version-name "Phí Sàn - v1" ` --dry-run ``` Đọc kết quả dry-run, sau đó chạy lại không có `--dry-run`. Script từ chối ghi đè nếu version đã tồn tại, lưu trực tiếp vào thư mục gốc `D:\CapCut\User Data\Projects\com.lveditor.draft`. Sau khi tạo version, chỉ đổi trường `project` trong plan sang đúng tên version mới (ví dụ `Phí Sàn - v1`). Không thay đổi `blocks`, từ khóa, timing hoặc quyết định ngữ nghĩa đã được duyệt. ### 5. Validate, dry-run và apply ```powershell python scripts/apply_retention_subtitles.py validate ` --plan "C:\duong-dan\subtitle-plan.json" python scripts/apply_retention_subtitles.py apply ` --project "Phí Sàn - v1" ` --plan "C:\duong-dan\subtitle-plan.json" ` --backup-dir "D:\CapCut\Backups\retention-subtitles" ` --dry-run ``` Nếu cả hai lệnh đạt, lưu công việc đang mở và đóng CapCut rồi apply. Script sẽ từ chối chạy nếu CapCut còn mở; không có tùy chọn force-kill: ```powershell python scripts/apply_retention_subtitles.py apply ` --project "Phí Sàn - v1" ` --plan "C:\duong-dan\subtitle-plan.json" ` --backup-dir "D:\CapCut\Backups\retention-subtitles" ``` Script ghi trực tiếp vào `D:\CapCut\User Data\Projects\com.lveditor.draft`. ### 6. Verify và mở lại CapCut ```powershell python scripts/apply_retention_subtitles.py verify ` --project "Phí Sàn - v1" ` --plan "C:\duong-dan\subtitle-plan.json" ``` Chỉ bàn giao khi validate, apply và verify đều thành công. Mở lại CapCut, xác nhận project hiển thị chính xác tên version mới và báo đường dẫn backup. ## Cleanup phiên bản cũ Không chạy cleanup mặc định. Chỉ chạy sau khi người dùng yêu cầu xóa các version cụ thể và đã thấy danh sách đường dẫn đích. Cleanup di chuyển project vào backup thay vì xóa vĩnh viễn: ```powershell python scripts/create_clean_sub_project.py cleanup ` --project "Phí Sàn - v1" ` --backup-dir "D:\CapCut\Backups\retention-subtitles" ` --confirm ``` ## Điều kiện hoàn tất - Plan có xác nhận người dùng và không chứa lựa chọn từ khóa tự động từ Python. - Không có dòng quá 28 ký tự, full trắng hoặc full vàng ngoài punchline hợp lệ. - Font, màu, stroke, scale, vị trí và animation đúng token. - Top track liền mạch từ `0` đến `duration_us`; bottom đúng mốc phát âm. - SFX đồng bộ chuẩn theo In-Animation của phụ đề trên 2 track riêng biệt (Track 3 & Track 4). - Project lưu tại canonical workspace `D:\CapCut\User Data\Projects\com.lveditor.draft`, metadata khớp chuẩn tên version `{Chủ_Đề_2_Từ} - v{N}`. - Project gốc còn nguyên; version mới có ID riêng, một metadata entry và backup phục hồi được.