Build Capcut Editable Project

Build CapCut Editable Project

Create versioned, recoverable CapCut drafts while treating CapCut's undocumented project format and media database conservatively.

Safety Rules

1. Read references/capcut-8.9.1.md before building, repairing, or installing a project.
2. Never edit a draft in place when it is the user's only working copy. Clone to a new version.
3. Never install or replace root_meta_info.json while CapCut is running.
4. Back up the live root metadata immediately before installation.
5. Do not claim media is online merely because JSON validation passes. Confirm by opening the project in CapCut; use Link Media if the private media database does not recognize generated IDs.
6. Preserve approved SRT timing exactly unless the user explicitly requests timing changes.
7. For a CapCut version other than macOS v8.9.1, first obtain a small sample draft containing one photo, one video, one text clip, and one audio clip. Build and open a 30-second test before making a full project.

Choose the Workflow

• For a new editable project, use Build from manifest.
• For a project that opens with missing media, use Diagnose and relink.
• For subtitles that are visually too large, use Resize subtitles.
• For a user-edited CapCut project that needs further work, copy it to a new version, inspect and validate it, then continue from that copy.

Build from Manifest

1. Confirm the editorial inputs are approved:

   • timeline TSV
   • photo and video index TSV files
   • synchronized SRT
   • final audio
   • title card, if the manifest uses title
   • rendered reference MP4

2. Ask the user to create a four-track sample project if no compatible template is available.

3. Quit CapCut and snapshot its live root_meta_info.json.

4. Create a flat media pack with:

   node scripts/build_media_pack.mjs <template-or-existing-draft_info.json> <new-media-pack-directory>

   Add any new timeline or reference media not present in that source draft before building, or build the media pack after creating a first offline draft and rebuild using the pack.

5. Create a JSON configuration using references/project-config.md.

6. Run:

   node scripts/build_from_manifest.mjs <config.json>

7. Validate the offline output:

   node scripts/validate_project.mjs <output-project-directory>

8. Review AI_BUILD_REPORT.json. Confirm duration, main segment count, subtitle count, media paths, mirror equality, and chapter labels.

9. Install only after all offline checks pass:

   zsh scripts/install_project.zsh <output-project-directory> <CapCut-draft-root> <root-meta-snapshot> <patched-root-meta>

10. Open CapCut and confirm:

    • project appears in the library
    • timeline opens
    • media is online
    • audio and lyrics remain synchronized
    • reference track is hidden

Diagnose and Relink

1. Run validate_project.mjs on the affected project.
2. Compare every missing path with the media pack. Do not rewrite paths by basename if duplicate basenames exist.
3. If JSON paths exist but CapCut still reports missing media, treat this as a private-database registration issue. Use CapCut's Link Media command and select the media-pack directory.
4. If the user provides a working CapCut revision, copy it to a new version before further automated edits. Preserve CapCut-assigned local material IDs.

Resize Subtitles

1. Quit CapCut.

2. Copy the project to a new version and update its project name/path registration separately.

3. Run:

   node scripts/resize_subtitles.mjs <copied-project-directory> <scale>

   A scale of 0.6 changes 15-point text to 9-point text while preserving cue timing and position.

4. Validate all mirrors and visually check representative long lyric lines in CapCut.

Handoff

Report:

• project name and installed path
• CapCut version used for calibration
• segment, subtitle, and duration totals
• media-pack path
• validation result
• whether CapCut itself has been opened successfully
• any remaining Link Media or manual style work

Do not describe an offline JSON-only result as a confirmed working CapCut project.