How to Auto-Link lost Media in CapCut projects using Python

choco install ffmpeg

brew install ffmpeg

CapCutProject/
├── draft_content.json
├── draft_info.json
├── material/
│   ├── import/
│   ├── video/
│   └── audio/

#!/usr/bin/env python3
"""
Auto-link lost media in CapCut projects with filename and duration matching.
Author: Muhammad Ali | Updated: 2025
"""

import argparse, json, os, shutil, subprocess, time
from pathlib import Path

FILE_EXTENSIONS = {'.mp4', '.mov', '.mkv', '.avi', '.webm', '.png', '.jpg', '.jpeg', '.gif', '.aac', '.mp3', '.wav', '.m4a', '.flac'}

def get_duration(file_path):
    """Return media duration in seconds using ffprobe (if available)."""
    try:
        cmd = [
            'ffprobe', '-v', 'error', '-show_entries', 'format=duration',
            '-of', 'default=noprint_wrappers=1:nokey=1', str(file_path)
        ]
        output = subprocess.check_output(cmd, stderr=subprocess.DEVNULL).decode().strip()
        return round(float(output), 1)
    except Exception:
        return None

def build_file_index(search_dirs):
    """Build an index of filename -> [paths]"""
    index = {}
    for d in search_dirs:
        for root, _, files in os.walk(d):
            for f in files:
                fn = f.lower()
                if any(fn.endswith(ext) for ext in FILE_EXTENSIONS):
                    full_path = Path(root) / f
                    index.setdefault(fn, []).append(full_path)
    return index

def find_best_match(filename, expected_duration, index):
    """Find the best match by filename and (if possible) duration."""
    matches = index.get(filename.lower(), [])
    if not matches:
        return None
    if expected_duration is None:
        return matches[0]
    best = None
    smallest_diff = float('inf')
    for path in matches:
        dur = get_duration(path)
        if dur is None:
            continue
        diff = abs(dur - expected_duration)
        if diff < smallest_diff:
            smallest_diff = diff
            best = path
    return best or matches[0]

def extract_durations(json_data):
    """Extract known durations from JSON (CapCut stores durations in seconds or ms)."""
    durations = {}
    def walk(o):
        if isinstance(o, dict):
            if 'duration' in o and isinstance(o['duration'], (int, float)):
                if 'path' in o and isinstance(o['path'], str):
                    durations[o['path']] = round(float(o['duration']) / 1000, 1)
            for v in o.values(): walk(v)
        elif isinstance(o, list):
            for v in o: walk(v)
    walk(json_data)
    return durations

def main(project_dir, search_dirs, dry_run=False):
    project_dir = Path(project_dir)
    json_file = next(project_dir.glob('draft_*.json'), None)
    if not json_file:
        print("❌ No project JSON found.")
        return
    data = json.loads(json_file.read_text(encoding='utf-8', errors='ignore'))
    backup = json_file.with_suffix(json_file.suffix + f'.bak.{int(time.time())}')
    shutil.copy2(json_file, backup)
    print(f"🧾 Backup created: {backup}")

    durations = extract_durations(data)
    index = build_file_index(search_dirs)
    import_dir = project_dir / 'material' / 'import'
    import_dir.mkdir(parents=True, exist_ok=True)

    fixed, missing = 0, 0
    def walk_json(obj):
        nonlocal fixed, missing
        if isinstance(obj, dict):
            for k, v in obj.items():
                if isinstance(v, str) and any(v.lower().endswith(ext) for ext in FILE_EXTENSIONS):
                    orig_path = Path(v)
                    if not orig_path.exists():
                        dur = durations.get(v)
                        best = find_best_match(orig_path.name, dur, index)
                        if best:
                            dest = import_dir / best.name
                            if not dry_run:
                                shutil.copy2(best, dest)
                            obj[k] = f"material/import/{best.name}"
                            fixed += 1
                            print(f"✅ Fixed: {orig_path} → {dest}")
                        else:
                            missing += 1
                            print(f"❌ Missing: {orig_path}")
                else:
                    walk_json(v)
        elif isinstance(obj, list):
            for i, v in enumerate(obj):
                if isinstance(v, (dict, list)):
                    walk_json(v)

    walk_json(data)
    if not dry_run:
        json_file.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding='utf-8')
    print(f"\n✅ {fixed} media files relinked. ❌ {missing} still missing.")

if __name__ == '__main__':
    parser = argparse.ArgumentParser(description="Auto-link lost CapCut media by filename & duration")
    parser.add_argument('--project', required=True, help='CapCut project folder path')
    parser.add_argument('--search', nargs='+', required=True, help='Folders to search for missing media')
    parser.add_argument('--dry-run', action='store_true', help='Simulate actions without modifying files')
    args = parser.parse_args()
    main(args.project, args.search, args.dry_run)