videodraft 0.28.0 → 0.28.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.js +4 -4
- package/package.json +1 -1
- package/skills/index.json +11 -11
- package/skills/videodraft/SKILL.md +23 -17
- package/skills/videodraft/references/editor.md +5 -3
- package/skills/videodraft/references/examples.md +9 -6
- package/skills/videodraft/references/models.md +2 -2
- package/skills/videodraft/references/pipeline.md +2 -2
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "videodraft",
|
|
3
|
-
"version": "0.28.
|
|
3
|
+
"version": "0.28.2",
|
|
4
4
|
"description": "Official VideoDraft CLI for AI videos, images, audio and 3D assets. Agent-friendly: --json everywhere, stable exit codes, async job polling.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
package/skills/index.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"skills": [
|
|
4
4
|
{
|
|
5
5
|
"name": "videodraft",
|
|
6
|
-
"description": "Create and edit AI videos, images, 3D meshes, Seed Audio, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos, media upscales, and product/ad videos with VideoDraft. Use whenever the user mentions VideoDraft; asks to generate a video, image, 3D asset, audio asset, ad, explainer, storyboard, avatar, upscale, or batch/CI workflow; wants to download a video from YouTube, Instagram, TikTok, X or another site; or wants to assemble, cut, caption, mix, lay out, inspect, or export a native VideoDraft Editor timeline. Covers
|
|
6
|
+
"description": "Create and edit AI videos, images, 3D meshes, Seed Audio, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos, media upscales, and product/ad videos with VideoDraft. Use whenever the user mentions VideoDraft; asks to generate a video, image, 3D asset, audio asset, ad, explainer, storyboard, avatar, upscale, or batch/CI workflow; wants to download a video from YouTube, Instagram, TikTok, X or another site; or wants to assemble, cut, caption, mix, lay out, inspect, or export a native VideoDraft Editor timeline. Covers cloud `videodraft` CLI/MCP, local `videodraft_editor` MCP, and creative-app routing. Honor the chosen app and existing project; otherwise prefer the native editor when available. Hosted production/export is an explicit choice or fallback when no local editing route is selected or available.",
|
|
7
7
|
"files": [
|
|
8
8
|
{
|
|
9
9
|
"path": "references/3d.md",
|
|
@@ -12,28 +12,28 @@
|
|
|
12
12
|
},
|
|
13
13
|
{
|
|
14
14
|
"path": "references/editor.md",
|
|
15
|
-
"sha256": "
|
|
16
|
-
"bytes":
|
|
15
|
+
"sha256": "e35a86088e211d22521325245aa848b18eceef6952d8bbdae6fdc8c2269833c0",
|
|
16
|
+
"bytes": 25381
|
|
17
17
|
},
|
|
18
18
|
{
|
|
19
19
|
"path": "references/examples.md",
|
|
20
|
-
"sha256": "
|
|
21
|
-
"bytes":
|
|
20
|
+
"sha256": "bc9ab98cfb3a654103b4282cdc8ef00e0bc05a2bfe85e40dc7ad7f10411d08d8",
|
|
21
|
+
"bytes": 10276
|
|
22
22
|
},
|
|
23
23
|
{
|
|
24
24
|
"path": "references/models.md",
|
|
25
|
-
"sha256": "
|
|
26
|
-
"bytes":
|
|
25
|
+
"sha256": "e27189da4367fd832b636f42fb057cd3d878c549bbea5c9a06976cc2e18a0307",
|
|
26
|
+
"bytes": 46474
|
|
27
27
|
},
|
|
28
28
|
{
|
|
29
29
|
"path": "references/pipeline.md",
|
|
30
|
-
"sha256": "
|
|
31
|
-
"bytes":
|
|
30
|
+
"sha256": "0f3dfd38df6cfdc6ce29073dbcb8645ced1f610c08730deec078d45a53957528",
|
|
31
|
+
"bytes": 14473
|
|
32
32
|
},
|
|
33
33
|
{
|
|
34
34
|
"path": "SKILL.md",
|
|
35
|
-
"sha256": "
|
|
36
|
-
"bytes":
|
|
35
|
+
"sha256": "17b76858e18ddae2e456635bc51accf44225728f47c707102269919245fbfa43",
|
|
36
|
+
"bytes": 49919
|
|
37
37
|
}
|
|
38
38
|
]
|
|
39
39
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: videodraft
|
|
3
|
-
description: Create and edit AI videos, images, 3D meshes, Seed Audio, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos, media upscales, and product/ad videos with VideoDraft. Use whenever the user mentions VideoDraft; asks to generate a video, image, 3D asset, audio asset, ad, explainer, storyboard, avatar, upscale, or batch/CI workflow; wants to download a video from YouTube, Instagram, TikTok, X or another site; or wants to assemble, cut, caption, mix, lay out, inspect, or export a native VideoDraft Editor timeline. Covers
|
|
3
|
+
description: Create and edit AI videos, images, 3D meshes, Seed Audio, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos, media upscales, and product/ad videos with VideoDraft. Use whenever the user mentions VideoDraft; asks to generate a video, image, 3D asset, audio asset, ad, explainer, storyboard, avatar, upscale, or batch/CI workflow; wants to download a video from YouTube, Instagram, TikTok, X or another site; or wants to assemble, cut, caption, mix, lay out, inspect, or export a native VideoDraft Editor timeline. Covers cloud `videodraft` CLI/MCP, local `videodraft_editor` MCP, and creative-app routing. Honor the chosen app and existing project; otherwise prefer the native editor when available. Hosted production/export is an explicit choice or fallback when no local editing route is selected or available.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# VideoDraft
|
|
@@ -10,12 +10,13 @@ VideoDraft is an AI video creation platform where asset generation is the priori
|
|
|
10
10
|
- **Asset generation**: standalone images, video clips, Seed Audio, voiceovers, music, sound effects, dialogue, voice-changed audio, dubbed media, upscales, and image descriptions. This is the fastest and most important lane. Treat these as complete deliverables when the user asks for assets.
|
|
11
11
|
- **Asset I/O**: upload local files, download outputs, auto-upload local references, and save generated media where the user can see it.
|
|
12
12
|
- **3D assets**: standalone Meshy 7.1 and Tripo H3.1 meshes, multi-view generation, complete artifact downloads, and Meshy humanoid rigging through MCP/CLI. Read [references/3d.md](references/3d.md), or `videodraft skills show 3d`. These assets have their own saved library and do not require an AI Studio session or web viewer.
|
|
13
|
-
- **Native editing**: local `.vdproject` timelines, cuts, layouts, captions, effects, audio, and exports through the headless VideoDraft Editor. Inside VideoDraft ADE, this is the default production and export lane
|
|
14
|
-
- **Hosted project production**: idea → script → storyboard → hosted production timeline → exported MP4. Use the early stages for scripts, storyboards, and generated assets when useful. Treat hosted production and export as a fallback when the native editor is unavailable, or as an explicit destination when the user asks for an editable web project or hosted workflow.
|
|
13
|
+
- **Native editing**: local `.vdproject` timelines, cuts, layouts, captions, effects, audio, and exports through the headless VideoDraft Editor. Inside VideoDraft ADE, this is the default production and export lane when `videodraft_editor` is available and no chosen app or existing external project takes precedence.
|
|
14
|
+
- **Hosted project production**: idea → script → storyboard → hosted production timeline → exported MP4. Use the early stages for scripts, storyboards, and generated assets when useful. Treat hosted production and export as a fallback when the native editor is unavailable and no external app is selected, or as an explicit destination when the user asks for an editable web project or hosted workflow.
|
|
15
15
|
|
|
16
16
|
## How to connect
|
|
17
17
|
|
|
18
|
-
Generation billing is selected in VideoDraft Settings → API
|
|
18
|
+
Generation billing is selected in VideoDraft Settings → API Keys on the web, or
|
|
19
|
+
Settings → Media providers in VideoDraft ADE. Where enabled,
|
|
19
20
|
**VideoDraft routing** chooses an equivalent provider internally without changing
|
|
20
21
|
the quoted customer credit price. A selected personal key is exclusive: never
|
|
21
22
|
switch to VideoDraft credits or another key after an unsupported-model or
|
|
@@ -40,25 +41,30 @@ Cloud generation has two equivalent surfaces (same backend, credits, and hosted
|
|
|
40
41
|
- Asset lane: `videodraft generate ...`, `videodraft edit video|motion`, `videodraft avatar ...`, `videodraft upscale ...`, `videodraft interpolate ...`, `videodraft upload`, and `videodraft download`.
|
|
41
42
|
- Full API access: `videodraft tools schema <name>`, `videodraft call <tool> --args '<json>'`.
|
|
42
43
|
2. **MCP connector**: if VideoDraft MCP tools (e.g. `generate_storyboard_from_idea`) are available, call them directly — the CLI's curated commands map 1:1 onto these tools.
|
|
43
|
-
3. **Native editor MCP** (`videodraft_editor`): prefer this for project production, timeline assembly, cutting, layouts, transitions, captions, audio placement, and final export. Inside VideoDraft ADE on a supported Mac, Claude, Codex, OpenCode and Grok receive it automatically in both Code and VideoDraft modes. It runs headlessly, so an Open Editor click is not required. Start with `project_manage` (`operation: "project"`, action `list`, `open`, or `create`); standalone asset generation remains in the cloud CLI or MCP.
|
|
44
|
+
3. **Native editor MCP** (`videodraft_editor`): prefer this for project production, timeline assembly, cutting, layouts, transitions, captions, audio placement, and final export when no chosen app or existing external project takes precedence. Inside VideoDraft ADE on a supported Mac, Claude, Codex, OpenCode and Grok receive it automatically in both Code and VideoDraft modes. It runs headlessly, so an Open Editor click is not required. Start with `project_manage` (`operation: "project"`, action `list`, `open`, or `create`); standalone asset generation remains in the cloud CLI or MCP.
|
|
44
45
|
|
|
45
46
|
Send native editor edits serially, batching everything a request needs into one `edit_apply` recipe. Pass the latest `context` when a person may be editing at the same time, so a stale write is refused. See [references/editor.md](references/editor.md) for project selection, media import, timing units, edit recipes, verification, export, and the `videodraft-editor` terminal bridge.
|
|
46
47
|
|
|
47
48
|
If you are reading this skill through `videodraft skills show skill`, run `videodraft skills show editor` before native editor work to load that reference.
|
|
48
49
|
|
|
49
|
-
**VideoDraft ADE routing rule:** the
|
|
50
|
+
**VideoDraft ADE routing rule:** honor the app named in the current request and the editing surface of an existing project. A `<creative_routes>` block selects the chat's routes and overrides this skill's generic tool defaults; an explicit current request takes precedence over that block. Work directly in the chosen app, combining its supported scripting, CLI, verified MCP and Computer Use wherever useful. Do not turn a chosen-app request into a native-editor handoff or silently switch destinations after an error. Keep the editable source and dependencies, preserve unsaved work, and verify the saved project and output. Generation model, payer and spending limits remain separate from the editing app.
|
|
51
|
+
|
|
52
|
+
When `creative_apps` is actually exposed, read the chosen app's bundled guide before using it. App topics include `after-effects`, `blender`, `resolve`, `premiere`, `final-cut`, `capcut`, `unity`, `remotion` and `hyperframes`. These app guides belong to VideoDraft ADE and describe installed-version setup and supported routes; users do not need personal per-app skills. When `creative_mcp` is also exposed, use its live discovery and the app guide for connected tools, and retain request IDs to recover uncertain operations. Computer Use is available only when its tools and permissions are present. These are VideoDraft ADE workspace tools, not public `videodraft` CLI commands. If they are absent, use the available app tools or explain the missing route without inventing commands or assuming a connector is installed.
|
|
53
|
+
|
|
54
|
+
With no chosen external app or existing external project, the presence of `videodraft_editor` means the native editor is ready, even when no editor window is visible. Use cloud tools to generate or source assets and, when helpful, scripts or storyboards. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` by default. Import the assets into the native project, assemble there, and export with native `delivery_manage` `submit`. Use hosted production/export when the user explicitly asks for the web workflow, or when the native editor is unavailable and no external app is selected. Do not silently fall back to hosted production after a local tool error.
|
|
50
55
|
|
|
51
56
|
## First decision: asset, hosted project, or native edit?
|
|
52
57
|
|
|
53
58
|
- **One standalone asset** (image, clip, voiceover, music track, sound effect, dialogue track, voice-changed file, dubbed media file, upscale, or description): generate it directly. Do NOT create a project.
|
|
54
59
|
- `videodraft generate image "a red fox in snow, cinematic" --ar 16:9 --download ./out/`
|
|
55
60
|
- `videodraft generate video "slow dolly over a misty lake" --model gemini-omni-1.1-flash --duration 6 --download ./out/`
|
|
56
|
-
- **
|
|
61
|
+
- **A chosen creative app or existing external project**: continue in that app using the routing rule above. Keep its project editable; use handoff only for a requested transfer or accepted fallback.
|
|
62
|
+
- **Any final video, production timeline, existing footage, local `.vdproject`, or hands-on edit with no other app selected**: use `videodraft_editor` when available. List or open the intended local project, or create a native project for a new production. The editor can work without showing its UI.
|
|
57
63
|
- **A small set of related assets**: still stay in the asset lane. They are grouped automatically (see [AI Studio sessions](#ai-studio-sessions)); give the current group one useful task-specific name with `videodraft sessions name "<name>"`. Switch to a project only when the deliverable matches the project criteria below or the user asks to attach the assets to one.
|
|
58
|
-
- **A generated multi-scene video / ad / explainer**:
|
|
59
|
-
- **A hosted web project or hosted export**: use the hosted pipeline
|
|
64
|
+
- **A generated multi-scene video / ad / explainer**: use hosted tools for any needed script, storyboard, shot planning, or generated assets, then build/export in the selected editing app. With no app selected and the native editor available, stop before hosted production, import the assets, and build/export the native timeline. A hosted project is optional unless the user wants the web project or its storyboard workflow.
|
|
65
|
+
- **A hosted web project or hosted export**: use the hosted pipeline when the user explicitly asks for it, or the native editor is unavailable and no external app is selected.
|
|
60
66
|
- **Just a script** (no video asked for): A script-only request creates a script-stage project but stops at the script. Use `videodraft create "..." --script-only`; do not build a storyboard the user didn't ask for.
|
|
61
|
-
- **Iterating on existing work**: identify the surface first. Use `project_manage` `project` with `action: "list"` for native projects and `videodraft projects list` only for hosted work. Never create a replacement project just to change an existing one.
|
|
67
|
+
- **Iterating on existing work**: identify the surface first and preserve an external project's app unless the user requests a transfer. Use `project_manage` `project` with `action: "list"` for native projects and `videodraft projects list` only for hosted work. Never create a replacement project just to change an existing one.
|
|
62
68
|
|
|
63
69
|
## Choose the model from the task
|
|
64
70
|
|
|
@@ -101,7 +107,7 @@ Every `videodraft models image|video|audio --json` entry carries `tier` (1 or 2)
|
|
|
101
107
|
- `seedance-2.5`: 4-30s single takes and up to 50 references (30 image, 10 video, 10 audio). Same modes as 2.0, one quality tier, 480p/720p/1080p. Reach for it when a shot must run past 15s or carry more references than 2.0 allows.
|
|
102
108
|
- `kling-o3`: reference images plus structured image/video elements, first/last frames, multi-prompt, audio control, or 4K. O3 allows 7 combined image references and image-backed elements, reduced to 4 combined items when a video-backed element is present. `kling-3.0`: image-to-video can use structured image/video elements and bind a custom Kling voice ID to either element form. Tier 2, by name: `kling-v3-turbo` (fast polished 3-15s with first frame, multi-prompt, and audio, but no elements) and Kling 2.6 Pro (top-level voice IDs cited as `<<<voice_1>>>` and `<<<voice_2>>>`).
|
|
103
109
|
- Existing-video edits use `videodraft edit video`, not generic generation. `gemini-omni-1.1-flash` is the preferred edit model and is chosen automatically when you omit `--model`: source up to 10s, up to 10 reference images, 360p/720p/1080p/4K with audio. Creative `--ref-video` inputs are NOT accepted on an edit, because an edit takes exactly one input video; use `generate video --video-task generate` to guide a new clip with video references instead. Omitting `--model` on a longer or unmeasurable source spends nothing and prints a priced menu (what each model edits, what it drops, what it costs) so you can put the choice to the user. **Truncation:** only Gemini refuses an over-length source. Happy Horse silently edits just the first 15s, Kling O3 the first 10s, and Grok the first 8s. The command warns you when that will happen; always relay it to the user. Gemini regenerates the audio track, so use Happy Horse or Kling O3 with `--preserve-audio` when the source audio must survive. Choose Grok for the cheapest prompt-only edit, Happy Horse for up to 5 image references, or Kling O3 for controlled reference-image edits.
|
|
104
|
-
- To edit a source longer than 10s without losing its tail, cut it into <=10s pieces in the
|
|
110
|
+
- To edit a source longer than 10s without losing its tail, cut it into <=10s pieces in the selected editing app (`videodraft_editor` by default), edit each with Gemini, and reassemble in that app. VideoDraft has no server-side split/concat, so this path needs a local editing route.
|
|
105
111
|
- Kling O3 also has a reference-generation mode. Use `videodraft generate video --model kling-o3-video-ref-edit` with exactly one `--ref-video` to generate a new guided clip; use `videodraft edit video` when changing the source itself. For new mixed-reference generation use Seedance 2 / 2.5.
|
|
106
112
|
- Motion transfer uses `videodraft edit motion` with Kling V3 by default, or Kling 2.6 when explicitly requested or lower cost matters. It requires a subject image and a motion-reference video.
|
|
107
113
|
- Veo 3.1, Grok Video 1.5, Happy Horse and the other Tier 2 video models: only when explicitly requested or when no Tier 1 model fits.
|
|
@@ -146,7 +152,7 @@ Pure text-to-image or text-to-video is fine for a generic one-off asset. When a
|
|
|
146
152
|
|
|
147
153
|
- If the user supplies reference media, preserve and pass it. Never reduce the request to text alone.
|
|
148
154
|
- When continuity matters, generate/select a strong still first with the selected image model (`nano-banana-2.1` by default), wait for its URL, then animate it as a start frame/reference. Confirm the combined image and video cost.
|
|
149
|
-
- When using a hosted storyboard stage for multiple shots, use `videodraft shots <project_id> --model <selected-image-model> --grid`, then animate the decoded shots. Preserve explicit models. In VideoDraft ADE, import the resulting assets into the native editor instead of continuing into hosted production. A requested non-Seedance video model must use manual per-shot generation instead of Seedance full-video mode.
|
|
155
|
+
- When using a hosted storyboard stage for multiple shots, use `videodraft shots <project_id> --model <selected-image-model> --grid`, then animate the decoded shots. Preserve explicit models. In VideoDraft ADE, import the resulting assets into the selected editing app (the native editor by default) instead of continuing into hosted production. A requested non-Seedance video model must use manual per-shot generation instead of Seedance full-video mode.
|
|
150
156
|
|
|
151
157
|
## Cost and credits
|
|
152
158
|
|
|
@@ -272,7 +278,7 @@ Use the path you saved to: a **workspace-relative** path (`./media/clip.mp4`, or
|
|
|
272
278
|
|
|
273
279
|
## Native-first VideoDraft ADE pipeline (idea → MP4)
|
|
274
280
|
|
|
275
|
-
When `videodraft_editor` is present:
|
|
281
|
+
When `videodraft_editor` is present and no chosen app or existing external project takes precedence:
|
|
276
282
|
|
|
277
283
|
1. Generate or source the script, storyboard, shot images, clips, voiceovers, music, and other assets through the cloud CLI/MCP as needed.
|
|
278
284
|
2. Call native `project_manage` (`project`, action `open` or `create`) to open or create the `.vdproject`.
|
|
@@ -283,8 +289,8 @@ Do not run the hosted production or export steps in this path unless the user ex
|
|
|
283
289
|
|
|
284
290
|
## Hosted fallback pipeline (idea → MP4)
|
|
285
291
|
|
|
286
|
-
Use this
|
|
287
|
-
|
|
292
|
+
Use this when the user explicitly requests the hosted web workflow, or there is NO native editor
|
|
293
|
+
and no external app is selected. The native surface is not only the injected `videodraft_editor` MCP: a `videodraft-editor`
|
|
288
294
|
executable on PATH is the same editor reached through its terminal bridge, and
|
|
289
295
|
[references/editor.md](references/editor.md) covers driving it that way. Treating a missing MCP as
|
|
290
296
|
"no editor" sends sessions that have the binary into hosted production for no reason.
|
|
@@ -301,13 +307,13 @@ Optional between produce and export: per-shot motion clips (`videodraft generate
|
|
|
301
307
|
|
|
302
308
|
## Avatar and talking-head videos (both surfaces)
|
|
303
309
|
|
|
304
|
-
Avatar generation is cloud-only
|
|
310
|
+
Avatar generation is cloud-only, so this applies whether or not `videodraft_editor` is present. Generate the avatar in the cloud; when a larger edit is requested, import the rendered clip into the selected editing app (the native editor by default) and cut it like any other footage.
|
|
305
311
|
|
|
306
312
|
Avatar/talking-head videos use dedicated commands. For a reusable managed avatar, obtain or generate a clear portrait → `videodraft avatar script` when needed → `videodraft avatar create` → `videodraft avatar render --resolution 720p`. For a one-off portrait, use `videodraft avatar fabric <portrait> --text "..."` or `--audio <file>`, or `videodraft avatar h3-lipsync <portrait> --audio <file>` for a short high-resolution clip from existing audio. For an existing video plus replacement audio, use `videodraft avatar lipsync <video> --audio <file>`. Managed script/creation is bundled/free; direct Fabric, H3 Max Lip Sync, Sync, the managed Fabric render, and optional portrait generation/upscaling are paid. Confirm expensive steps first.
|
|
307
313
|
|
|
308
314
|
## Working with hosted project data
|
|
309
315
|
|
|
310
|
-
A hosted project is one JSON blob (script, storyboard scenes, shot cards, visual assets, production timeline). To inspect: `videodraft projects get <id>`. To edit: fetch `--raw`, modify, then `videodraft call update_project` — objects deep-merge, **arrays replace wholesale** (send the complete `storyboard.scenes` array to change one scene). Snapshot first with `videodraft checkpoint create <id>` before risky edits. Schema reference: `videodraft call get_project_schema`. This does not replace
|
|
316
|
+
A hosted project is one JSON blob (script, storyboard scenes, shot cards, visual assets, production timeline). To inspect: `videodraft projects get <id>`. To edit: fetch `--raw`, modify, then `videodraft call update_project` — objects deep-merge, **arrays replace wholesale** (send the complete `storyboard.scenes` array to change one scene). Snapshot first with `videodraft checkpoint create <id>` before risky edits. Schema reference: `videodraft call get_project_schema`. This does not replace the chosen app's project or the native editor's `.vdproject` for the production itself.
|
|
311
317
|
|
|
312
318
|
## More
|
|
313
319
|
|
|
@@ -4,9 +4,11 @@ Use this reference when the user wants to assemble, cut, caption, mix, lay out,
|
|
|
4
4
|
|
|
5
5
|
## VideoDraft ADE preference rule
|
|
6
6
|
|
|
7
|
-
When `videodraft_editor` tools are exposed, treat the native editor as available and make it the default surface for production, timeline assembly, and final export. It is headless by design, so a hidden window or an untouched Open Editor button does not justify using hosted production instead.
|
|
7
|
+
When `videodraft_editor` tools are exposed and no chosen app or existing external project takes precedence, treat the native editor as available and make it the default surface for production, timeline assembly, and final export. It is headless by design, so a hidden window or an untouched Open Editor button does not justify using hosted production instead.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Honor the user's chosen app, an existing project's editing surface, and VideoDraft ADE's `<creative_routes>` before applying this native-editor reference. An explicit current request takes precedence over the saved route. For a chosen external app, work directly there with its available scripting, CLI, verified MCP and Computer Use, preserving the editable project. When `creative_apps` is actually exposed, read that app's bundled guide; when `creative_mcp` is exposed, use its live discovery and the guide's connection/recovery rules. Neither tool is a public `videodraft` CLI command or guaranteed outside VideoDraft ADE. Do not create a `.vdproject` merely to hand an external-app task back to the chosen application.
|
|
10
|
+
|
|
11
|
+
For a native production, use cloud tools for asset generation and optional script/storyboard work, then import the results. Do not call hosted `produce_project` / `videodraft produce` or `export_video` / `videodraft export` unless the user explicitly requests an editable web production, or the native editor is unavailable and no external app is selected. If a native tool call fails after the editor was available, report or recover that native failure rather than silently switching surfaces. The editing destination does not change the generation model, payer or spending limits.
|
|
10
12
|
|
|
11
13
|
## Choose the correct surface
|
|
12
14
|
|
|
@@ -185,7 +187,7 @@ A dependable sequence:
|
|
|
185
187
|
Call `delivery_manage` with `operation: "submit"`. Submission is not completion: it returns a job, destination, and `started` or `queued` status.
|
|
186
188
|
|
|
187
189
|
- Use `mode: "video"` for H.264, H.265, or ProRes.
|
|
188
|
-
- Use `mode: "xml"` (XMEML) for Premiere Pro **and DaVinci Resolve
|
|
190
|
+
- Use `mode: "xml"` (XMEML) for Premiere Pro **and DaVinci Resolve**; Resolve reads XMEML natively. Use `mode: "fcpxml"` with `fcpxmlTarget: "fcp"` for Final Cut Pro: the default target writes the Resolve flavor. `fcpxmlTarget: "resolve"` stays for older Resolve workflows, but new Resolve handoffs use `xml`.
|
|
189
191
|
- Use `mode: "videodraft"` for a self-contained project package.
|
|
190
192
|
- Use `mode: "srt"` or `mode: "vtt"` for a subtitle file of the captions: words and timing only, without styling. `captionGroupId` picks a caption group; `wordTiming: true` adds each word's start to a `vtt`.
|
|
191
193
|
- Omit `outputPath` unless the user named a destination; the default is `~/Downloads`. The editor does not create folders, so a named destination's folder must already exist.
|
|
@@ -2,11 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
Working patterns for common asks. All assume auth (`videodraft login` once, or `VIDEODRAFT_API_KEY` in the environment) and use `--json` for parsing.
|
|
4
4
|
|
|
5
|
-
Inside VideoDraft ADE,
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
5
|
+
Inside VideoDraft ADE, use these recipes for asset generation and optional script/storyboard stages.
|
|
6
|
+
Honor the chosen app, existing project and `<creative_routes>` as described in SKILL.md. Hand the
|
|
7
|
+
results to that app for production and export ONLY when the user asked for a composed production;
|
|
8
|
+
the native editor is the default when available and no other app takes precedence. A standalone
|
|
9
|
+
output, such as the batch product clips in recipe 1 or the upscale in recipe 7, is finished when
|
|
10
|
+
generated. Recipes below that call `videodraft produce` or `videodraft export` are hosted fallbacks
|
|
11
|
+
only. Use them when explicitly requested, or when the native editor is unavailable and no external
|
|
12
|
+
app is selected. Do not switch an external-app request to a hosted or native production silently.
|
|
10
13
|
|
|
11
14
|
## 1. Batch product videos from a CSV
|
|
12
15
|
|
|
@@ -69,7 +72,7 @@ videodraft generate audio "Extend @Audio1 into a 20-second transition" --ref-aud
|
|
|
69
72
|
videodraft export "$PROJECT" --download solace-launch.mp4
|
|
70
73
|
```
|
|
71
74
|
|
|
72
|
-
Use this complete hosted path only when the user requested a web project or the native editor is unavailable. Otherwise stop after the storyboard/assets
|
|
75
|
+
Use this complete hosted path only when the user requested a web project, or the native editor is unavailable and no external app is selected. Otherwise stop after the storyboard/assets and finish in the selected editing app; for the default native `.vdproject`, export with `delivery_manage`. The hosted project stays editable at the URL in `project.json` (`.urls`).
|
|
73
76
|
|
|
74
77
|
## 3. Talking-head (avatar) video
|
|
75
78
|
|
|
@@ -117,7 +117,7 @@ If the user explicitly names one of these models, preserve it. The CLI uploads l
|
|
|
117
117
|
|
|
118
118
|
**Truncation is the trap here.** Only Gemini refuses a source it cannot fully consume. Every other edit model accepts a 30s clip and returns an edit of its first 8-15 seconds with no error. `videodraft edit video` now warns when this will happen and the tool response carries `source.truncated` / `source.dropped_seconds`; relay it to the user rather than letting them discover it in the output.
|
|
119
119
|
|
|
120
|
-
To edit a longer source without losing its tail, cut it into <=10s pieces
|
|
120
|
+
To edit a longer source without losing its tail, cut it into <=10s pieces in the selected editing app (`videodraft_editor` by default), edit each with Gemini, then reassemble and export in that app. VideoDraft has no server-side split/concat, so this needs a local editing route.
|
|
121
121
|
|
|
122
122
|
Kling O3 is also exposed for reference generation. `videodraft generate video --model kling-o3-video-ref-edit` requires exactly one `--ref-video` and generates a new reference-guided clip. Wan 3.0 handles new text, frame, and mixed-reference generation, but is not an existing-source edit model.
|
|
123
123
|
|
|
@@ -195,7 +195,7 @@ Direct Fabric text/audio, H3 Max Lip Sync, and Sync Labs do not use the managed
|
|
|
195
195
|
- `seedream-v5-pro` supports unified text-to-image and reference-image editing with up to 10 image references. Use `--resolution 1K` or `--resolution 2K` (2K costs more per image).
|
|
196
196
|
- Reference inputs: `--ref <img>` (images, including up to 10 total for Gemini Omni 1.1 Flash and Wan 3.0, and 7 for Grok 1.5), `--source-video <v>` (Gemini uploaded edit/extension source), `--ref-video <v>` (up to 3 creative videos <=3s each for Gemini Omni 1.1 Flash; also Wan 3.0, MiniMax H3, MiniMax H3 Max, and Seedance 2), `--ref-audio <a>` (Wan 3.0, MiniMax H3, MiniMax H3 Max, Seedance 2), and `--element '<json>'` or `--element @elements.json` for Kling V3/O3. For an exact Seedance 2.x reference-video `--estimate`, add `--ref-video-seconds <combined-seconds>`; Seedance bills input seconds alongside output. Wan 3.0 and MiniMax H3 do not bill input reference seconds; MiniMax H3 Max bills them as pooled reference tokens. The CLI uploads local media references and every structured element without flattening the source/reference roles. `--segment "<prompt>:<seconds>"` (repeatable) drives Kling 3.0, Kling 3.0 Turbo, and O3 multi-prompt generation. Use 1-6 segments of 1-15 whole seconds each, with 3-15 seconds total. `generate image --video-ref` is the nano-banana-2 video reference.
|
|
197
197
|
- The top-level prompt is OPTIONAL for Gemini Omni 1.1 Flash media-input or continuation calls, Wan 3.0 frame/reference modes, `generate video` with multi-prompt models, and Kling 3.0 Turbo (`--model kling-v3-turbo`) image-to-video. Text-only Gemini and Wan calls still require a prompt unless their live schema says otherwise.
|
|
198
|
-
- Hosted AI Production fallback: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene. The MCP equivalent is `produce_project` with `mode: "full_video"`. Poll with `videodraft generations`, then `videodraft finalize <project>` swaps them into the hosted timeline before `export`. In VideoDraft ADE, do not choose this path while `videodraft_editor` is available unless the user explicitly requests hosted production. Generate or download the scene assets, import them, and assemble/export
|
|
198
|
+
- Hosted AI Production fallback: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene. The MCP equivalent is `produce_project` with `mode: "full_video"`. Poll with `videodraft generations`, then `videodraft finalize <project>` swaps them into the hosted timeline before `export`. In VideoDraft ADE, do not choose this path while `videodraft_editor` is available unless the user explicitly requests hosted production. A selected external app or existing external project also takes precedence over this hosted fallback. Generate or download the scene assets, import them, and assemble/export in the selected app (the native editor by default). If the user explicitly requests another compatible video model for a hosted production, do not use this fixed Seedance path; generate the project shots manually with the requested model and attach them to the hosted timeline.
|
|
199
199
|
|
|
200
200
|
## Cost model
|
|
201
201
|
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
# VideoDraft pipeline reference
|
|
2
2
|
|
|
3
|
-
Everything here describes the hosted fallback pipeline through the CLI (`videodraft <command>` / `videodraft call <tool>`) or hosted MCP connector (tool names in backticks).
|
|
3
|
+
Everything here describes the hosted fallback pipeline through the CLI (`videodraft <command>` / `videodraft call <tool>`) or hosted MCP connector (tool names in backticks). Honor the chosen app, existing project's editing surface and VideoDraft ADE's `<creative_routes>` as described in SKILL.md. Use hosted tools for asset generation and optional script/storyboard stages, then finish in the selected editing app. With no external app selected and the local `videodraft_editor` MCP available, use the native editor reference linked from SKILL.md. Continue through `produce_project` and `export_video` only when the user explicitly requests a hosted web production, or the native editor is unavailable and no external app is selected.
|
|
4
4
|
|
|
5
|
-
Use direct asset tools for standalone images, clips, audio, upscales, and descriptions. Use a hosted project when the user explicitly wants the editable web project, when a hosted storyboard stage is useful, or when the native editor is unavailable. Script-only uses a script-stage project and stops at the script.
|
|
5
|
+
Use direct asset tools for standalone images, clips, audio, upscales, and descriptions. Use a hosted project when the user explicitly wants the editable web project, when a hosted storyboard stage is useful, or when the native editor is unavailable and no external app is selected. Script-only uses a script-stage project and stops at the script. For a local production, stop before hosted production, import the generated assets into the selected app, and build/export there; the native editor remains the default when available and no other app or existing project takes precedence.
|
|
6
6
|
|
|
7
7
|
## Stages and their tools
|
|
8
8
|
|