capcut-cli 0.1.5 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # capcut-cli
 
-Stop reverse-engineering CapCut's JSON schema every time you need to change a subtitle.
+Create and edit CapCut projects from the command line. Build drafts from scratch, add media, modify subtitles, cut long-form to shorts.
 
 ## The problem
 
@@ -89,6 +89,27 @@ capcut material ./project a1b2c3             # Full detail for one material
 
 Progressive disclosure: `info` shows the shape, `materials` shows what's available, `segment`/`material` shows everything about one item. An AI agent navigates overview → list → detail, never gets more data than it needs.
 
+### Create (build projects from scratch)
+
+No need to open CapCut first. Create a draft, add media, then open in CapCut.
+
+```bash
+# Create an empty draft
+capcut init "My Short" --drafts ~/Movies/CapCut/User\ Data/Projects/com.lveditor.draft
+
+# Add media
+capcut add-video ./my-short ./clip.mp4 0s 10s
+capcut add-audio ./my-short ./voiceover.wav 0s 10s --volume 0.9
+capcut add-audio ./my-short ./music.mp3 0s 30s --volume 0.3
+
+# Add titles
+capcut add-text ./my-short 0s 5s "My Short" --font-size 24 --color "#FFD700"
+```
+
+`init` creates a valid `draft_content.json` from a built-in template. `add-video` and `add-audio` copy the file into the draft's assets directory so CapCut can find it. Open the project in CapCut and everything links up.
+
+Options for `add-video` / `add-audio`: `--volume <0-1>`, `--template <path>` (custom draft template).
+
 ### Add
 
 ```bash

package/dist/factory.js

@@ -1,10 +1,33 @@
 import { randomUUID } from "node:crypto";
-import { readFileSync, writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, cpSync, copyFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
 import { findMaterialGlobal } from "./draft.js";
 // --- UUID generation ---
 export function uuid() {
     return randomUUID();
 }
+export function initDraft(opts) {
+    const draftPath = resolve(opts.draftsDir, opts.name);
+    if (existsSync(draftPath)) {
+        throw new Error(`Draft already exists: ${draftPath}. Delete it first or use a different name.`);
+    }
+    cpSync(opts.templateDir, draftPath, { recursive: true });
+    // Find the draft file
+    const candidates = ["draft_info.json", "draft_content.json"];
+    for (const c of candidates) {
+        const fp = resolve(draftPath, c);
+        if (existsSync(fp)) {
+            // Update the draft name
+            const raw = readFileSync(fp, "utf-8");
+            const draft = JSON.parse(raw);
+            draft.name = opts.name;
+            draft.id = uuid();
+            writeFileSync(fp, JSON.stringify(draft, null, 0), "utf-8");
+            return { draftPath, filePath: fp };
+        }
+    }
+    throw new Error(`No draft_info.json or draft_content.json found in template: ${opts.templateDir}`);
+}
 export function createCompanionMaterials(trackType) {
     const speed = { id: uuid(), type: "speed", speed: 1, mode: 0, curve_speed: null };
     const placeholder = {
@@ -160,6 +183,163 @@ export function addText(draft, filePath, opts) {
     track.segments.push(seg);
     return { segmentId: segId, materialId: matId, trackId: track.id };
 }
+export function addAudio(draft, filePath, opts) {
+    const segId = uuid();
+    const matId = uuid();
+    const trackName = opts.trackName ?? "audio";
+    const volume = opts.volume ?? 1.0;
+    // Copy file into draft assets directory
+    const draftDir = dirname(filePath);
+    const filename = opts.path.split("/").pop() || "audio.mp3";
+    const assetsDir = resolve(draftDir, "assets", "audio");
+    mkdirSync(assetsDir, { recursive: true });
+    const destPath = resolve(assetsDir, filename);
+    if (!existsSync(destPath)) {
+        copyFileSync(opts.path, destPath);
+    }
+    // Use the local assets path — CapCut rewrites to placeholder on open
+    const localPath = destPath;
+    // Find or create audio track
+    let track = draft.tracks.find(t => t.type === "audio" && t.name === trackName);
+    if (!track) {
+        track = {
+            id: uuid(),
+            type: "audio",
+            name: trackName,
+            attribute: 0,
+            segments: [],
+            is_default_name: false,
+            flag: 0,
+        };
+        draft.tracks.push(track);
+    }
+    // Create companion materials
+    const companions = createCompanionMaterials("audio");
+    registerCompanions(draft, companions);
+    // Create audio material
+    const audioMaterial = {
+        id: matId,
+        path: localPath,
+        name: filename,
+        duration: opts.duration,
+        type: "extract_music",
+        category_id: "",
+        category_name: "local",
+        check_flag: 1,
+        music_id: "",
+        request_id: "",
+        source_platform: 0,
+        team_id: "",
+        text_id: "",
+        tone_category_id: "",
+        tone_category_name: "",
+        tone_effect_id: "",
+        tone_effect_name: "",
+        tone_platform: "",
+        tone_second_category_id: "",
+        tone_second_category_name: "",
+        tone_speaker: "",
+        tone_type: "",
+        wave_points: [],
+    };
+    draft.materials.audios.push(audioMaterial);
+    // Create segment
+    const timerange = { start: opts.start, duration: opts.duration };
+    const seg = baseSegment(segId, matId, track.id, timerange, companions.ids, 11000);
+    seg.volume = volume;
+    track.segments.push(seg);
+    // Update project duration if needed
+    const segEnd = opts.start + opts.duration;
+    if (segEnd > draft.duration) {
+        draft.duration = segEnd;
+    }
+    return { segmentId: segId, materialId: matId, trackId: track.id };
+}
+export function addVideo(draft, filePath, opts) {
+    const segId = uuid();
+    const matId = uuid();
+    const trackName = opts.trackName ?? "video";
+    const width = opts.width ?? 1920;
+    const height = opts.height ?? 1080;
+    // Infer type from extension if not provided
+    const ext = opts.path.split(".").pop()?.toLowerCase() || "";
+    const materialType = opts.type ?? (["jpg", "jpeg", "png", "webp", "bmp", "tiff"].includes(ext) ? "photo" : "video");
+    // Copy file into draft assets directory
+    const draftDir = dirname(filePath);
+    const filename = opts.path.split("/").pop() || "media";
+    const assetsDir = resolve(draftDir, "assets", "video");
+    mkdirSync(assetsDir, { recursive: true });
+    const destPath = resolve(assetsDir, filename);
+    if (!existsSync(destPath)) {
+        copyFileSync(opts.path, destPath);
+    }
+    // Use the local assets path — CapCut rewrites to placeholder on open
+    const localPath = destPath;
+    // Find or create video track
+    let track = draft.tracks.find(t => t.type === "video" && t.name === trackName);
+    if (!track) {
+        track = {
+            id: uuid(),
+            type: "video",
+            name: trackName,
+            attribute: 0,
+            segments: [],
+            is_default_name: false,
+            flag: 0,
+        };
+        draft.tracks.push(track);
+    }
+    // Create companion materials
+    const companions = createCompanionMaterials("video");
+    registerCompanions(draft, companions);
+    // Create video material
+    const videoMaterial = {
+        id: matId,
+        path: localPath,
+        material_name: filename,
+        type: materialType,
+        duration: opts.duration,
+        width,
+        height,
+        category_id: "",
+        category_name: "local",
+        check_flag: 7,
+        crop: { lower_left_x: 0, lower_left_y: 1, lower_right_x: 1, lower_right_y: 1, upper_left_x: 0, upper_left_y: 0, upper_right_x: 1, upper_right_y: 0 },
+        has_audio: materialType === "video",
+        extra_type_option: 0,
+        formula_id: "",
+        freeze: null,
+        intensifies_audio_path: "",
+        intensifies_path: "",
+        is_ai_generate_content: false,
+        is_copyright: false,
+        is_text_edit_overdub: false,
+        is_unified_beauty_mode: false,
+        local_id: "",
+        local_material_id: "",
+        material_url: "",
+        media_path: "",
+        object_locked: null,
+        origin_material_id: "",
+        request_id: "",
+        reverse_path: "",
+        source_platform: 0,
+        stable: { matrix_path: "", stable_level: 0, time_range: { duration: 0, start: 0 } },
+        team_id: "",
+        video_algorithm: { algorithms: [], deflicker: null, motion_blur_config: null, noise_reduction: null, path: "", quality_enhance: null, time_range: null },
+    };
+    draft.materials.videos.push(videoMaterial);
+    // Create segment
+    const timerange = { start: opts.start, duration: opts.duration };
+    const seg = baseSegment(segId, matId, track.id, timerange, companions.ids, 14000);
+    track.segments.push(seg);
+    // Update project duration if needed
+    const segEnd = opts.start + opts.duration;
+    if (segEnd > draft.duration) {
+        draft.duration = segEnd;
+    }
+    return { segmentId: segId, materialId: matId, trackId: track.id };
+}
 export function cutProject(draft, opts) {
     const { start, end } = opts;
     const duration = end - start;

package/dist/index.js

@@ -2,7 +2,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { loadDraft, saveDraft, extractText, updateTextContent, findSegment, findMaterial, findMaterialGlobal, getMaterialTypes, getTracksByType } from "./draft.js";
 import { formatTime, formatDuration, parseTimeInput, srtTime } from "./time.js";
-import { addText, cutProject, saveTemplate, applyTemplate } from "./factory.js";
+import { addText, addAudio, addVideo, cutProject, saveTemplate, applyTemplate, initDraft } from "./factory.js";
 const HELP = `capcut-cli -- fast edits to CapCut projects
 
 Usage: capcut <command> <project> [options]
@@ -27,7 +27,23 @@ Detail (drill into one item):
   segment    <project> <id>                     Full detail for one segment + its material
   material   <project> <id>                     Full detail for one material
 
+Create:
+  init       <name> [--template <dir>] [--drafts <dir>]
+             Create a new empty draft from template. Defaults:
+               --template   ../CapCutAPI/template (relative to capcut-cli)
+               --drafts     ~/Movies/CapCut/User Data/Projects/com.lveditor.draft
+
 Add:
+  add-audio  <project> <file> <start> <duration> [options]
+             Add an audio segment (VO, music, SFX). Options:
+               --volume <n>       Volume 0.0-1.0 (default: 1.0)
+               --track-name <s>   Track name (default: "audio")
+
+  add-video  <project> <file> <start> <duration> [options]
+             Add a video or image segment. Type auto-detected from extension.
+             Options:
+               --track-name <s>   Track name (default: "video")
+
   add-text   <project> <start> <duration> <text> [options]
              Add a text segment. Options:
                --font-size <n>    Font size (default: 15)
@@ -95,6 +111,15 @@ function parseFlags(args) {
         else if (a === "--track-name" && i + 1 < args.length) {
             flags.trackName = args[++i];
         }
+        else if (a === "--volume" && i + 1 < args.length) {
+            flags.volume = parseFloat(args[++i]);
+        }
+        else if (a === "--template" && i + 1 < args.length) {
+            flags.template = args[++i];
+        }
+        else if (a === "--drafts" && i + 1 < args.length) {
+            flags.drafts = args[++i];
+        }
         else
             positional.push(a);
     }
@@ -462,6 +487,45 @@ function cmdMaterialDetail(draft, matId, flags) {
     }
 }
 // --- Add commands ---
+function cmdAddAudio(draft, filePath, positional, flags) {
+    const audioPath = positional[2];
+    const startStr = positional[3];
+    const durationStr = positional[4];
+    if (!audioPath || !startStr || !durationStr)
+        die("Usage: capcut add-audio <project> <file> <start> <duration>");
+    const absPath = audioPath.startsWith("/") ? audioPath : process.cwd() + "/" + audioPath;
+    const start = parseTimeInput(startStr);
+    const duration = parseTimeInput(durationStr);
+    const opts = {
+        path: absPath,
+        start,
+        duration,
+        volume: flags.volume,
+        trackName: flags.trackName,
+    };
+    const result = addAudio(draft, filePath, opts);
+    saveDraft(filePath, draft);
+    out({ ok: true, segment_id: result.segmentId, material_id: result.materialId, track_id: result.trackId, path: absPath, start_us: start, duration_us: duration }, flags);
+}
+function cmdAddVideo(draft, filePath, positional, flags) {
+    const videoPath = positional[2];
+    const startStr = positional[3];
+    const durationStr = positional[4];
+    if (!videoPath || !startStr || !durationStr)
+        die("Usage: capcut add-video <project> <file> <start> <duration>");
+    const absPath = videoPath.startsWith("/") ? videoPath : process.cwd() + "/" + videoPath;
+    const start = parseTimeInput(startStr);
+    const duration = parseTimeInput(durationStr);
+    const opts = {
+        path: absPath,
+        start,
+        duration,
+        trackName: flags.trackName,
+    };
+    const result = addVideo(draft, filePath, opts);
+    saveDraft(filePath, draft);
+    out({ ok: true, segment_id: result.segmentId, material_id: result.materialId, track_id: result.trackId, path: absPath, start_us: start, duration_us: duration }, flags);
+}
 function cmdAddText(draft, filePath, positional, flags) {
     const startStr = positional[2];
     const durationStr = positional[3];
@@ -614,6 +678,20 @@ function main() {
     const { positional, flags } = parseFlags(raw);
     const cmd = positional[0];
     const projectPath = positional[1];
+    // init doesn't need an existing project
+    if (cmd === "init") {
+        const name = projectPath; // positional[1] is the name for init
+        if (!name)
+            die("Missing name. Usage: capcut init <name> [--template <dir>] [--drafts <dir>]");
+        const cliDir = new URL(".", import.meta.url).pathname.replace(/\/dist\/$/, "");
+        const templateDir = flags.template ?? cliDir + "/../CapCutAPI/template";
+        const draftsDir = flags.drafts ?? (process.env.HOME || "~") + "/Movies/CapCut/User Data/Projects/com.lveditor.draft";
+        const result = initDraft({ name, templateDir, draftsDir });
+        out({ ok: true, name, draft_path: result.draftPath, file_path: result.filePath }, flags);
+        if (!flags.quiet)
+            process.stderr.write(`Created: ${result.draftPath}\n`);
+        process.exit(0);
+    }
     if (!projectPath)
         die("Missing project path. Run 'capcut --help' for usage.");
     const { draft, filePath } = loadDraft(projectPath);
@@ -672,6 +750,14 @@ function main() {
             requireArgs(positional, 3, "capcut material <project> <id>");
             cmdMaterialDetail(draft, positional[2], flags);
             break;
+        case "add-audio":
+            requireArgs(positional, 5, "capcut add-audio <project> <file> <start> <duration>");
+            cmdAddAudio(draft, filePath, positional, flags);
+            break;
+        case "add-video":
+            requireArgs(positional, 5, "capcut add-video <project> <file> <start> <duration>");
+            cmdAddVideo(draft, filePath, positional, flags);
+            break;
         case "add-text":
             requireArgs(positional, 5, "capcut add-text <project> <start> <duration> <text>");
             cmdAddText(draft, filePath, positional, flags);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "capcut-cli",
-  "version": "0.1.5",
-  "description": "CLI to edit CapCut and JianYing project files — subtitles, timing, speed, volume, templates, cut long-form to shorts. Reads and writes draft_content.json / draft_info.json directly.",
+  "version": "0.2.0",
+  "description": "CLI to create and edit CapCut projects — build drafts from scratch, add video/audio/text, subtitles, timing, speed, volume, templates, cut long-form to shorts. No API needed.",
   "type": "module",
   "bin": {
     "capcut": "dist/index.js",