videodraft 0.3.7 → 0.4.0
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/README.md +25 -21
- package/dist/index.js +800 -96
- package/package.json +1 -1
- package/skills/index.json +9 -9
- package/skills/videodraft/SKILL.md +46 -14
- package/skills/videodraft/references/examples.md +68 -5
- package/skills/videodraft/references/models.md +107 -12
- package/skills/videodraft/references/pipeline.md +34 -19
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "videodraft",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Official VideoDraft CLI — create AI videos, images and audio from your terminal. Agent-friendly: --json everywhere, stable exit codes, async job polling.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
package/skills/index.json
CHANGED
|
@@ -3,27 +3,27 @@
|
|
|
3
3
|
"skills": [
|
|
4
4
|
{
|
|
5
5
|
"name": "videodraft",
|
|
6
|
-
"description": "Create AI videos, images, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos and product/ad videos with VideoDraft. Use when the user mentions VideoDraft, or asks to generate/make a video, video ad, explainer, storyboard, talking-head/avatar video, AI image, voiceover/TTS, background music, sound effects, dialogue audio, voice changing, or
|
|
6
|
+
"description": "Create AI videos, images, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos, media upscales and product/ad videos with VideoDraft. Use when the user mentions VideoDraft, or asks to generate/make a video, video ad, explainer, storyboard, talking-head/avatar video, AI image, voiceover/TTS, background music, sound effects, dialogue audio, voice changing, dubbing, or image/video enhancement and upscaling, including batch/programmatic video generation in scripts or CI. Works via the `videodraft` CLI (preferred in terminals) or the VideoDraft MCP connector.",
|
|
7
7
|
"files": [
|
|
8
8
|
{
|
|
9
9
|
"path": "references/examples.md",
|
|
10
|
-
"sha256": "
|
|
11
|
-
"bytes":
|
|
10
|
+
"sha256": "91cc9aa5a49c34e9a73fdfd224eaf5ce46588c22bd72a951810ae73544efed25",
|
|
11
|
+
"bytes": 6254
|
|
12
12
|
},
|
|
13
13
|
{
|
|
14
14
|
"path": "references/models.md",
|
|
15
|
-
"sha256": "
|
|
16
|
-
"bytes":
|
|
15
|
+
"sha256": "a871eeec1dc1cc164718f1f52ea40cc90510c2f4c3b71fb57bd6a25981ad06a0",
|
|
16
|
+
"bytes": 17138
|
|
17
17
|
},
|
|
18
18
|
{
|
|
19
19
|
"path": "references/pipeline.md",
|
|
20
|
-
"sha256": "
|
|
21
|
-
"bytes":
|
|
20
|
+
"sha256": "054109a6ab556bcace1ff843b001afe9bc3a0aac389667e979ac7b77a7200a50",
|
|
21
|
+
"bytes": 10644
|
|
22
22
|
},
|
|
23
23
|
{
|
|
24
24
|
"path": "SKILL.md",
|
|
25
|
-
"sha256": "
|
|
26
|
-
"bytes":
|
|
25
|
+
"sha256": "8796e157a835f17edcd8c8345c2668042fdcd793781eace573a570825b6440c6",
|
|
26
|
+
"bytes": 15094
|
|
27
27
|
}
|
|
28
28
|
]
|
|
29
29
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: videodraft
|
|
3
|
-
description: Create AI videos, images, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos and product/ad videos with VideoDraft. Use when the user mentions VideoDraft, or asks to generate/make a video, video ad, explainer, storyboard, talking-head/avatar video, AI image, voiceover/TTS, background music, sound effects, dialogue audio, voice changing, or
|
|
3
|
+
description: Create AI videos, images, voiceovers, music, sound effects, dialogue, dubbing, storyboards, avatar videos, media upscales and product/ad videos with VideoDraft. Use when the user mentions VideoDraft, or asks to generate/make a video, video ad, explainer, storyboard, talking-head/avatar video, AI image, voiceover/TTS, background music, sound effects, dialogue audio, voice changing, dubbing, or image/video enhancement and upscaling, including batch/programmatic video generation in scripts or CI. Works via the `videodraft` CLI (preferred in terminals) or the VideoDraft MCP connector.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# VideoDraft
|
|
@@ -9,7 +9,7 @@ VideoDraft is an AI video creation platform where asset generation is the priori
|
|
|
9
9
|
|
|
10
10
|
- **Asset generation**: standalone images, video clips, 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
|
-
- **Project production**: idea → script → storyboard (scenes + shot images) → project data → production timeline → exported MP4. Use
|
|
12
|
+
- **Project production**: idea → script → storyboard (scenes + shot images) → project data → production timeline → exported MP4. Use it for a multi-scene video, story, ad, explainer, storyboard, editable timeline, or final export, even when the user does not say "project." A script-only request also creates a script-stage project but stops at the script.
|
|
13
13
|
|
|
14
14
|
## How to connect
|
|
15
15
|
|
|
@@ -22,7 +22,7 @@ Two equivalent surfaces (same backend, same credits, same projects):
|
|
|
22
22
|
• SECURITY: never ask the user to paste a `vd_mcp_...` token into the chat — use browser `login` or the env var so the token never lands in the transcript.
|
|
23
23
|
- Every command accepts `--json` (parse this, don't scrape text). Exit codes: 0 ok, 1 error, 2 usage, 3 auth (see Auth above), 4 insufficient credits (→ tell the user, don't retry).
|
|
24
24
|
- Tool discovery: start with `videodraft tools list` for the grouped catalog, then narrow with `videodraft tools list --lane assets`, `--lane asset_io`, `--lane project_data`, or `--lane production`.
|
|
25
|
-
- Asset lane: `videodraft generate
|
|
25
|
+
- Asset lane: `videodraft generate ...`, `videodraft edit video|motion`, `videodraft avatar ...`, `videodraft upscale ...`, `videodraft upload`, and `videodraft download`.
|
|
26
26
|
- Full API access: `videodraft tools schema <name>`, `videodraft call <tool> --args '<json>'`.
|
|
27
27
|
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.
|
|
28
28
|
|
|
@@ -30,23 +30,56 @@ Two equivalent surfaces (same backend, same credits, same projects):
|
|
|
30
30
|
|
|
31
31
|
- **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.
|
|
32
32
|
- `videodraft generate image "a red fox in snow, cinematic" --ar 16:9 --download ./out/`
|
|
33
|
-
- `videodraft generate video "slow dolly over a misty lake" --model
|
|
34
|
-
- **A small set of related assets**: still stay in the asset lane. Use an AI Studio session if you need to group related generations
|
|
33
|
+
- `videodraft generate video "slow dolly over a misty lake" --model gemini-omni-flash --duration 6 --download ./out/`
|
|
34
|
+
- **A small set of related assets**: still stay in the asset lane. Use an AI Studio session if you need to group related generations. Switch to a project only when the deliverable matches the project criteria below or the user asks to attach the assets to one.
|
|
35
35
|
- **A multi-scene video / ad / explainer, storyboard, timeline, or final exported video**: create a project so the work stays organized, editable in the web app, and exportable.
|
|
36
36
|
- `videodraft create "30s launch video for our espresso machine" --ar 9:16`
|
|
37
37
|
- **Just a script** (no video asked for): `videodraft create "..." --script-only`. Stop at the script — do not build a storyboard the user didn't ask for.
|
|
38
38
|
- **Iterating on existing work**: find it first (`videodraft projects list`) and reuse that project. Never create a new project to change an existing one.
|
|
39
39
|
|
|
40
|
-
##
|
|
40
|
+
## Choose the model from the task
|
|
41
41
|
|
|
42
|
-
|
|
42
|
+
If the user names a model, use it when compatible. If it cannot handle the request, explain why and recommend alternatives instead of silently switching. Otherwise inspect the inputs, duration, audio, quality, speed, and cost, check the live catalog, and pass an explicit model.
|
|
43
43
|
|
|
44
|
-
|
|
45
|
-
2. `videodraft generate video "..." --estimate` or `videodraft costs <model> --duration 8 --resolution 1080p` — get the quote. For ElevenLabs audio, use `--type audio` plus `--duration`, `--length`, or `--chars`.
|
|
46
|
-
3. Tell the user the model + settings + rough cost and get a go-ahead. Ask rather than assume aspect ratio, duration, and model when they matter.
|
|
47
|
-
4. Honor the user's stated preference on confirmation. If they tell you to stop asking (e.g. "don't ask me", "just go", "stop confirming cost"), proceed without a go-ahead for the rest of the session. If they say to always confirm, confirm every spend. Default when unspecified: confirm the first spend of a session and any unusually large one (a shot-image batch, a long or 1080p video).
|
|
44
|
+
**Images:**
|
|
48
45
|
|
|
49
|
-
|
|
46
|
+
- `nano-banana-2`: general default, editing, consistency, and references.
|
|
47
|
+
- `nano-banana-pro`: maximum quality. `nano-banana-2-lite`: fast, inexpensive drafts.
|
|
48
|
+
- `gpt-image-2`: posters, logos, signs, title cards, readable text, or precise composition/editing.
|
|
49
|
+
|
|
50
|
+
**Videos:**
|
|
51
|
+
|
|
52
|
+
- `gemini-omni-flash`: general default up to 10s, first frame/image references, or editing one source video without extra media references. Fixed 720p with audio.
|
|
53
|
+
- `seedance-2`: 11-15s, video/audio/mixed references, wider ratios, selectable audio, or first/last frames. Use `mini` for cost, `fast` for speed, `standard` for quality or 1080p/4K.
|
|
54
|
+
- `kling-v3-turbo`: fast polished 3-15s with first frame, multi-prompt, and audio. `kling-o3`: image references, first/last frames, multi-prompt, audio control, or 4K. `kling-3.0`: similar without reference-image mode.
|
|
55
|
+
- Existing-video edits use `videodraft edit video`, not generic generation. Choose from the `video_edit` catalog category: Grok for simple prompt edits, Wan 2.7 for one style reference or source-matching duration, Happy Horse for up to 5 references, and Kling O3 for controlled reference-image edits.
|
|
56
|
+
- Kling O3 and Wan 2.7 Ref/Edit also have reference-generation modes. Use `videodraft generate video --model <ref-edit-id>` with `--ref-video`/`--ref` to generate a new guided clip; use `videodraft edit video` when changing the source itself.
|
|
57
|
+
- 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.
|
|
58
|
+
- Use Veo 3.1 when explicitly requested or as a fallback.
|
|
59
|
+
|
|
60
|
+
**Audio and utilities:**
|
|
61
|
+
|
|
62
|
+
- Prefer ElevenLabs for voiceover, dialogue, voice changing, dubbing, and sound effects. Honor an explicitly selected supported TTS voice/provider. Use Lyria for instrumental music and ElevenLabs Music for vocals, lyrics, or exact timing.
|
|
63
|
+
- Talking head/presenter: choose by source. Use managed `avatar create` then `avatar render` when the user wants a reusable avatar record and bundled speech. Use `avatar fabric` for a one-off portrait plus text or existing audio. Use `avatar lipsync` when both the source video and replacement audio already exist.
|
|
64
|
+
- Enhancement: use Topaz image/video upscaling only when the content is already correct. Use image 1x for cleanup, 2x by default, 4x when justified; use video 2x by default. Edit or regenerate creative errors.
|
|
65
|
+
|
|
66
|
+
See [references/models.md](references/models.md) for the detailed routing table and exact capability limits.
|
|
67
|
+
|
|
68
|
+
## Prefer references when continuity matters
|
|
69
|
+
|
|
70
|
+
Pure text-to-image or text-to-video is fine for a generic one-off asset. When a specific character, product, location, style, composition, or brand identity must survive generation, use references instead of hoping the prompt recreates it.
|
|
71
|
+
|
|
72
|
+
- If the user supplies reference media, preserve and pass it. Never reduce the request to text alone.
|
|
73
|
+
- When continuity matters, generate/select a strong still first with the selected image model (`nano-banana-2` by default), wait for its URL, then animate it as a start frame/reference. Confirm the combined image and video cost.
|
|
74
|
+
- For multiple shots, use `videodraft shots <project_id> --model <selected-image-model> --grid`, then animate the decoded shots. Preserve explicit models. A requested non-Seedance video model must use manual per-shot generation instead of Seedance full-video mode.
|
|
75
|
+
|
|
76
|
+
## Cost and credits
|
|
77
|
+
|
|
78
|
+
Do not call `videodraft credits` before routine generations. Paid endpoints validate and deduct atomically; if the balance is insufficient, the request is rejected before the provider job starts (CLI exit code 4). Check the balance only when the user asks, gives a credit budget, or a large workflow needs budget planning.
|
|
79
|
+
|
|
80
|
+
For expensive work, estimate with `--estimate` or `videodraft costs`, state the selected model/settings/cost, and get a go-ahead. This matters most for shot-image batches, long or high-resolution video, AI Production, and paid audio batches. Honor the user's confirmation preference for the session.
|
|
81
|
+
|
|
82
|
+
`videodraft models image|video` lists the live image and video catalogs with supported inputs. Video entries are grouped as `generation`, `video_edit`, `motion_control`, `avatar_lipsync`, and `upscale`, and each reports the exact tool. Use `videodraft models video --category video_edit` to narrow the list. `videodraft models audio` lists Google Lyria and ElevenLabs audio/media tools, while `videodraft models voices` lists TTS voices. Consult them instead of guessing capabilities.
|
|
50
83
|
|
|
51
84
|
## Async jobs
|
|
52
85
|
|
|
@@ -90,7 +123,6 @@ Use the path you saved to: a **workspace-relative** path (`./media/clip.mp4`, or
|
|
|
90
123
|
## The full pipeline (idea → MP4)
|
|
91
124
|
|
|
92
125
|
```bash
|
|
93
|
-
videodraft credits
|
|
94
126
|
videodraft create "<idea>" --ar 9:16 # project: script → visual assets → storyboard
|
|
95
127
|
videodraft shots <project_id> --grid --estimate # cost preview, confirm with user
|
|
96
128
|
videodraft shots <project_id> --grid # batch shot images (waits, writes onto shot cards)
|
|
@@ -100,7 +132,7 @@ videodraft export <project_id> --download final.mp4
|
|
|
100
132
|
|
|
101
133
|
Optional between produce and export: per-shot motion clips (`videodraft generate video ... --project <id>` then place it with `videodraft attach <project> --scene N --shot M --media <url|file> --type video --duration <s>`), music (`videodraft generate music "..." --attach <project_id>`), and standalone audio assets (`generate sound-effect`, `generate dialogue`, `generate voice-changer`, `generate dub`). Details, per-step tools and editing rules: [references/pipeline.md](references/pipeline.md).
|
|
102
134
|
|
|
103
|
-
Avatar/talking-head videos
|
|
135
|
+
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>`. For an existing video plus replacement audio, use `videodraft avatar lipsync <video> --audio <file>`. Managed script/creation is bundled/free; direct Fabric, Sync, the managed Fabric render, and optional portrait generation/upscaling are paid. Confirm expensive steps first.
|
|
104
136
|
|
|
105
137
|
## Working with project data
|
|
106
138
|
|
|
@@ -14,7 +14,7 @@ mkdir -p outputs
|
|
|
14
14
|
while IFS=, read -r name image tagline; do
|
|
15
15
|
job=$(videodraft generate video \
|
|
16
16
|
"Premium product shot of ${name}: ${tagline}. Slow orbit, studio lighting." \
|
|
17
|
-
--model
|
|
17
|
+
--model gemini-omni-flash --ar 9:16 --duration 6 \
|
|
18
18
|
--start-image "$image" \
|
|
19
19
|
--no-wait --json | jq -r .job_id)
|
|
20
20
|
echo "$name,$job" >> outputs/jobs.csv
|
|
@@ -26,12 +26,11 @@ videodraft wait $(cut -d, -f2 outputs/jobs.csv) \
|
|
|
26
26
|
# map job ids back to product names via outputs/jobs.csv
|
|
27
27
|
```
|
|
28
28
|
|
|
29
|
-
Submit-then-collect parallelizes server-side generation; the single multi-id `wait` keeps it to one local process and one batched poll request per tick no matter how many jobs. Estimate first: `videodraft costs
|
|
29
|
+
Submit-then-collect parallelizes server-side generation; the single multi-id `wait` keeps it to one local process and one batched poll request per tick no matter how many jobs. Gemini Omni Flash is selected because these are six-second first-frame product clips. Estimate first: `videodraft costs gemini-omni-flash --type video --duration 6 --resolution 720p --audio` × rows, and confirm with the user.
|
|
30
30
|
|
|
31
31
|
## 2. Full marketing video from one idea
|
|
32
32
|
|
|
33
33
|
```bash
|
|
34
|
-
videodraft credits --json
|
|
35
34
|
videodraft create "30-second launch video for Solace, a sleep-tracking ring. Calm, premium, dark palette." \
|
|
36
35
|
--ar 9:16 --style cinematic --json > project.json
|
|
37
36
|
PROJECT=$(jq -r .project_id project.json)
|
|
@@ -47,10 +46,61 @@ The project stays editable at the URL in `project.json` (`.urls`) — hand it to
|
|
|
47
46
|
|
|
48
47
|
## 3. Talking-head (avatar) video
|
|
49
48
|
|
|
49
|
+
When the user has no portrait, generate a clear front-facing avatar image first. Skip this step when they supplied one or an existing character should be reused.
|
|
50
|
+
|
|
50
51
|
```bash
|
|
52
|
+
videodraft generate image \
|
|
53
|
+
"Front-facing head-and-shoulders portrait of a friendly coffee expert, direct eye contact, natural expression, clean studio background" \
|
|
54
|
+
--model nano-banana-2 --ar 9:16 --download ./media/avatar.png
|
|
55
|
+
|
|
51
56
|
SCRIPT=$(videodraft avatar script "why our espresso subscription saves you money" --style ad-style --json | jq -r .script)
|
|
52
|
-
AVATAR=$(videodraft avatar create ./
|
|
53
|
-
videodraft avatar render "$AVATAR" --resolution 720p # paid step
|
|
57
|
+
AVATAR=$(videodraft avatar create ./media/avatar.png --script "$SCRIPT" --voice elevenlabs-kPzsL2i3teMYv0FxEYQ6 --ar 9:16 --json | jq -r .avatar_video_id)
|
|
58
|
+
videodraft avatar render "$AVATAR" --resolution 720p # VEED Fabric paid step; confirm cost first (~20 credits/sec)
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`avatar script` and `avatar create` (including speech) are bundled/free. In this example only the optional portrait generation and Fabric render spend credits.
|
|
62
|
+
|
|
63
|
+
If the portrait is low resolution, enhance it before `avatar create`:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
videodraft upscale image ./founder-small.jpg --scale 2x --download ./media/founder-upscaled.png
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
For a one-off portrait animation without creating a managed avatar record:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
videodraft avatar fabric ./founder.jpg \
|
|
73
|
+
--text "Welcome to the weekly product update." \
|
|
74
|
+
--voice-description "warm, confident American presenter" \
|
|
75
|
+
--resolution 720p --download ./media/presenter.mp4
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
When the user already has both the video and replacement speech:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
videodraft avatar lipsync ./presenter.mp4 \
|
|
82
|
+
--audio ./localized-voiceover.mp3 \
|
|
83
|
+
--sync-mode loop --download ./media/presenter-localized.mp4
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Edit an existing video with a dedicated edit model:
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
videodraft models video --category video_edit
|
|
90
|
+
videodraft edit video ./product-demo.mp4 \
|
|
91
|
+
"Turn the room into a warm evening scene while preserving the product and camera motion" \
|
|
92
|
+
--model wan-2.7-ref-edit --ref ./evening-style.jpg \
|
|
93
|
+
--preserve-audio --download ./media/product-demo-evening.mp4
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Transfer motion from a reference clip onto a character image:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
videodraft edit motion ./character.png \
|
|
100
|
+
"Apply the dancer's movement to this character while preserving identity" \
|
|
101
|
+
--motion-video ./dance-reference.mp4 \
|
|
102
|
+
--model kling-v3-motion-control --quality pro \
|
|
103
|
+
--download ./media/character-dance.mp4
|
|
54
104
|
```
|
|
55
105
|
|
|
56
106
|
## 4. Changelog video in CI
|
|
@@ -82,3 +132,16 @@ videodraft call attach_media_to_shot --args '{"project_id":"...","scene_index":0
|
|
|
82
132
|
```
|
|
83
133
|
|
|
84
134
|
Anything the VideoDraft MCP exposes — character studio, product studio, timeline editing — is reachable this way even before it gets a curated command.
|
|
135
|
+
|
|
136
|
+
## 7. Enhance an existing asset without changing it
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
# Light image cleanup, no enlargement
|
|
140
|
+
videodraft upscale image ./poster.png --scale 1x --download ./media/poster-enhanced.png
|
|
141
|
+
|
|
142
|
+
# General image and video enlargement
|
|
143
|
+
videodraft upscale image ./frame.png --scale 2x --download ./media/frame-2x.png
|
|
144
|
+
videodraft upscale video ./clip.mp4 --scale 2x --download ./media/clip-2x.mp4
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Use these when the content is correct and only quality or resolution needs improvement. If the poster text, composition, subject, or motion is wrong, edit or regenerate instead.
|
|
@@ -10,13 +10,106 @@ videodraft models voices --json # TTS voices
|
|
|
10
10
|
videodraft models styles --json # visual style presets
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
##
|
|
13
|
+
## Task-based model selection
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
15
|
+
Honor an explicitly named model when it supports the request. Otherwise choose from the task's inputs, duration, audio, quality, speed, and cost. Pass the chosen model explicitly instead of relying on a blind platform fallback.
|
|
16
|
+
|
|
17
|
+
### Images
|
|
18
|
+
|
|
19
|
+
| Need | Choose | Why |
|
|
20
|
+
| -------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------- |
|
|
21
|
+
| Most generation, editing, character consistency, or reference work | `nano-banana-2` | Best general default; 1K/2K/4K and up to 14 reference images |
|
|
22
|
+
| Highest-quality complex generation or reasoning | `nano-banana-pro` | Premium Nano Banana quality and reasoning |
|
|
23
|
+
| Fast, inexpensive drafts and iteration | `nano-banana-2-lite` | Fastest/cheapest Nano Banana option; 1K only, up to 14 references |
|
|
24
|
+
| Posters, title cards, signs, logos, or any image with important readable text | `gpt-image-2` | Strong text rendering; up to 16 image inputs and 1K/2K/4K output |
|
|
25
|
+
| Complex multi-image composition, precise editing, or a strong alternate interpretation | `gpt-image-2` | Strong non-Nano alternative with multi-image input |
|
|
26
|
+
|
|
27
|
+
Use `--num 1..4` for variations of one prompt in a single call. Never loop separate paid calls for variations that fit in one request.
|
|
28
|
+
|
|
29
|
+
### Videos
|
|
30
|
+
|
|
31
|
+
| Need | Choose | Important limits |
|
|
32
|
+
| ---------------------------------------------------------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------- |
|
|
33
|
+
| Most text, first-frame, image-reference, or source-video-edit requests up to 10s | `gemini-omni-flash` | 720p, 3-10s or auto, audio always on, up to 10 total image inputs, one source video |
|
|
34
|
+
| Video/audio references, mixed reference media, broad aspect ratios, frame-mode first+last frame, or 11-15s | `seedance-2` | 4-15s or auto; up to 9 image, 3 video, and 3 audio refs; audio toggle; Mini/Fast are 480p/720p only |
|
|
35
|
+
| Fast polished 3-15s video with first frame, multi-prompt, and native audio | `kling-v3-turbo` | Audio always on; Pro default; no end frame or reference-media mode |
|
|
36
|
+
| Cinematic 3-15s with image references, first+last frame, multi-prompt, audio control, or 4K | `kling-o3` | Up to 7 image refs; Standard/Pro/4K; audio toggle |
|
|
37
|
+
| Kling 3-15s with first+last frame, multi-prompt, optional audio, or 4K, without reference-image mode | `kling-3.0` | Standard/Pro/4K; audio toggle |
|
|
38
|
+
| User explicitly requests Veo, or the selected workflow specifically needs Veo | `google-veo3.1` | Good fallback, but not the preferred general model |
|
|
39
|
+
|
|
40
|
+
Routing rules:
|
|
41
|
+
|
|
42
|
+
- Around 11-15 seconds with native audio: use Kling or Seedance, not Gemini.
|
|
43
|
+
- One existing source video that should be edited, with an output up to 10 seconds and no additional media references to preserve: use Gemini Omni Flash.
|
|
44
|
+
- Video or audio supplied as creative reference: use Seedance 2.0.
|
|
45
|
+
- A video plus any image/audio references that must all be preserved: use Seedance 2.0. Do not promise that Gemini will preserve mixed source media; its Fal BYOK edit mode accepts only the source video and prompt.
|
|
46
|
+
- First and last frame control: use Seedance, Kling O3, or Kling 3.0. Gemini supports a first frame but not a last frame.
|
|
47
|
+
- Seedance reference mode and first-plus-last-frame mode are separate. Do not promise reference video/audio plus a last frame in one generation.
|
|
48
|
+
- Multi-prompt sequencing: use Kling 3.0 Turbo, Kling O3, or Kling 3.0.
|
|
49
|
+
- Seedance quality: `mini` for the lowest cost, `fast` for speed, `standard` for maximum quality and for 1080p/4K.
|
|
50
|
+
|
|
51
|
+
### Video edit and motion-control categories
|
|
52
|
+
|
|
53
|
+
Use `videodraft models video --category video_edit` for existing-video transforms and `--category motion_control` for motion transfer.
|
|
54
|
+
|
|
55
|
+
| Need | Command/model | Important limits |
|
|
56
|
+
| ------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
|
|
57
|
+
| Simple prompt edit of one video | `videodraft edit video <video> "..." --model grok-imagine-video-edit` | No image refs; source truncated to 8s; auto/480p/720p |
|
|
58
|
+
| Edit with one style/reference image | `--model wan-2.7-ref-edit --ref <image>` | One image ref; 2-10s or match source |
|
|
59
|
+
| Edit with several image references | `--model happy-horse-video-edit --ref ...` | Up to 5 refs; 720p/1080p; source capped at 15s |
|
|
60
|
+
| Controlled Kling edit | `--model kling-o3-video-ref-edit --ref ...` | Up to 4 refs; Standard/Pro; source clamped to 3-10s |
|
|
61
|
+
| Transfer reference motion to an image | `videodraft edit motion <image> "..." --motion-video <video>` | Kling V3 default; image orientation caps motion at 10s, video orientation at 30s |
|
|
62
|
+
|
|
63
|
+
If the user explicitly names one of these models, preserve it. The CLI uploads local source videos and reference images automatically. Editing returns an async job and waits by default.
|
|
64
|
+
|
|
65
|
+
Kling O3 and Wan 2.7 Ref/Edit are dual-mode cards. `videodraft edit video` uses edit mode. `videodraft generate video --model kling-o3-video-ref-edit` requires exactly one `--ref-video` and generates a new reference-guided clip. `--model wan-2.7-ref-edit` generates a new clip from one or more `--ref`/`--ref-video` inputs.
|
|
66
|
+
|
|
67
|
+
### Reference-first video workflow
|
|
68
|
+
|
|
69
|
+
- Prefer a start frame or reference image whenever a specific character, product, location, style, composition, or brand identity must stay recognizable.
|
|
70
|
+
- If the user gives a reference, pass it. Never silently replace it with a text description.
|
|
71
|
+
- If no reference exists and continuity matters, generate a still first with the user's explicitly requested compatible image model, otherwise use Nano Banana 2. Wait for the image URL, then animate it with the selected video model. Confirm the combined image plus video cost before starting.
|
|
72
|
+
- For multi-shot scenes, generate shot images with `videodraft shots <project_id> --model <selected-image-model> --grid`. Preserve an explicitly requested compatible image model; otherwise use `nano-banana-2`. The grid establishes the scene and characters together, then decodes into individual shot images.
|
|
73
|
+
- Animate the decoded shot images as per-shot start frames or references. Do not independently text-generate each video clip when the shots need to match.
|
|
74
|
+
- Pure text-to-video remains appropriate for generic one-off footage where no subject, composition, or continuity needs to be preserved.
|
|
75
|
+
|
|
76
|
+
### Audio
|
|
77
|
+
|
|
78
|
+
- **Voiceover/TTS**: prefer ElevenLabs. Brittney is the platform default voice; under ElevenLabs BYOK, use a compatible voice from the user's account. Honor another supported voice/provider when the user explicitly selects it.
|
|
79
|
+
- **Dialogue, voice changing, and dubbing**: ElevenLabs only.
|
|
80
|
+
- **Sound effects**: ElevenLabs Sound Effects only.
|
|
81
|
+
- **Music**: use `lyria-3-clip-preview` for a short instrumental/background score, `lyria-3-pro-preview` for a longer or higher-quality instrumental score, and `elevenlabs-music` when vocals/lyrics or a specified 10-120 second length matter.
|
|
82
|
+
- Voice Changer and Dubbing require the source media duration and currently accept source media up to 300 seconds.
|
|
83
|
+
|
|
84
|
+
### Avatar / talking head
|
|
85
|
+
|
|
86
|
+
Choose the dedicated path from the media the user already has:
|
|
87
|
+
|
|
88
|
+
| Starting media | Command | Use |
|
|
89
|
+
| ----------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------- |
|
|
90
|
+
| Portrait + script, reusable avatar record | `videodraft avatar create <portrait> --script "..."` then `avatar render` | Managed avatar flow with bundled speech preparation |
|
|
91
|
+
| Portrait + text | `videodraft avatar fabric <portrait> --text "..."` | One-off direct VEED Fabric text mode |
|
|
92
|
+
| Portrait + existing audio | `videodraft avatar fabric <portrait> --audio <audio>` | One-off direct VEED Fabric audio lip sync |
|
|
93
|
+
| Existing video + existing audio | `videodraft avatar lipsync <video> --audio <audio>` | Sync Labs Lipsync 2 |
|
|
94
|
+
|
|
95
|
+
The managed renderer is VEED Fabric Fast (`veed/fabric-1.0/fast`). Direct Fabric and Sync Labs are paid AI Studio generations and return async job IDs.
|
|
96
|
+
|
|
97
|
+
1. Obtain the avatar image. Prefer the user's supplied portrait or an existing character. If none exists, use the user's explicitly requested compatible image model, otherwise generate a front-facing head-and-shoulders portrait with `nano-banana-2`, direct eye contact, a natural expression, and a clean background. Match the intended video aspect ratio when practical.
|
|
98
|
+
2. If the portrait is visibly soft or too small, run Topaz image enhancement/upscaling before animation.
|
|
99
|
+
3. Generate a script only if needed: `videodraft avatar script "<idea>"`.
|
|
100
|
+
4. Create the avatar record and speech: `videodraft avatar create <portrait-url-or-file> --script "..." --voice <id> --ar 9:16`. Prefer ElevenLabs when unspecified, but honor another explicitly selected supported voice/provider.
|
|
101
|
+
5. Render with VEED Fabric: `videodraft avatar render <avatar_video_id> --resolution 720p`.
|
|
102
|
+
|
|
103
|
+
The portrait is passed as the avatar's character image, not as a generic video's start frame. Prefer rendering directly at 720p. Use 480p only when the user prioritizes lower cost. Avatar script generation and `avatar create` (including speech) are bundled/free. Confirm the Fabric render cost, plus portrait generation or upscaling when needed.
|
|
104
|
+
|
|
105
|
+
Direct Fabric text/audio and Sync Labs do not use the managed avatar record. The CLI uploads local portrait, video, and audio files automatically. `avatar fabric --speed fast` applies only to audio mode. Sync costs 5 credits per verified audio second; under Fal BYOK, `sync_mode` remains available but `temperature` and `active_speaker` are ignored by the provider.
|
|
106
|
+
|
|
107
|
+
### Upscaling / enhancement
|
|
108
|
+
|
|
109
|
+
- **Images**: Topaz via `videodraft upscale image <url-or-file> --scale 1x|2x|4x`. Use 1x for light enhancement without enlargement, 2x as the general default, and 4x only when the source quality and target size justify it. The result is synchronous.
|
|
110
|
+
- **Videos**: Topaz via `videodraft upscale video <url-or-file> --scale 2x`. Use 2x by default. The job is asynchronous; the CLI waits by default, while MCP callers poll `check_generation_status`. MCP video input must be VideoDraft-hosted, so upload local or external sources first.
|
|
111
|
+
- Use upscaling to preserve the image/video while improving detail, resolution, or cleanup. It cannot fix the wrong subject, misspelled text, bad framing, unwanted objects, broken continuity, or incorrect motion. Use an edit or regeneration for those problems.
|
|
112
|
+
- For a new Fabric avatar, render directly at 720p instead of rendering at 480p and then upscaling. Upscale the source portrait first only when the portrait itself is low quality.
|
|
20
113
|
|
|
21
114
|
## Capability gotchas
|
|
22
115
|
|
|
@@ -25,16 +118,18 @@ videodraft models styles --json # visual style presets
|
|
|
25
118
|
- `--seed` reproduces a specific output on models that support it (e.g. Flux, Ideogram V4); everything else ignores it. You do not need a seed for variation — `--num` already varies.
|
|
26
119
|
- `--rendering-speed` applies to Ideogram (V3: `Default`/`Turbo`/`Quality`; V4: `Turbo`/`Balanced`/`Quality`) and affects image cost — pass it to `videodraft costs ... --rendering-speed <tier>` for an accurate estimate. Always trust `videodraft models image --json` over this list; new models and tiers appear there the moment the platform ships them, with no CLI update.
|
|
27
120
|
- `seedream-v5-pro` supports unified text-to-image and reference-image editing with up to 10 image references. Use `--resolution 1K` for 7 credits/image or `--resolution 2K` for 14 credits/image.
|
|
28
|
-
- Reference inputs: `--ref <img>` (images), `--ref-video <v>` (Gemini Omni Flash, Seedance 2,
|
|
121
|
+
- Reference inputs: `--ref <img>` (images), `--ref-video <v>` (Gemini Omni Flash, Seedance 2, Wan 2.7), `--ref-audio <a>` (Seedance 2). The CLI uploads local files for all of these, so you can pass a path or a URL. `--segment "<prompt>:<seconds>"` (repeatable) drives multi-prompt models (Kling 3.0 / 3.0 Turbo / O3); total 3-15s. `generate image --video-ref` is the nano-banana-2 video reference.
|
|
29
122
|
- The top-level prompt is OPTIONAL for `generate video` with multi-prompt models and for Kling 3.0 Turbo (`--model kling-v3-turbo`) image-to-video — a `--segment`-only or `--start-image`-only call is valid. Every other model still needs a prompt; the server enforces per-model rules.
|
|
30
|
-
- AI Production: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene; poll with `videodraft generations`, then `videodraft finalize <project>` swaps them into the timeline before `export`.
|
|
123
|
+
- AI Production: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene; poll with `videodraft generations`, then `videodraft finalize <project>` swaps them into the timeline before `export`. If the user explicitly requests another compatible video model, do not use this fixed Seedance path. Generate the project shots manually with the requested model and attach them to the timeline.
|
|
31
124
|
|
|
32
125
|
## Cost model
|
|
33
126
|
|
|
34
127
|
- Images: per image (× `--num`). Matrix-priced models (GPT-Image, Nano Banana Pro, Seedream v5 Pro) vary by resolution/quality.
|
|
35
128
|
- Video: usually credits/second × duration; rate depends on model + resolution + quality + native audio on/off.
|
|
36
129
|
- Shot-image batches: one image per shot (+1 grid image per scene in `--grid` mode) — the largest single spend in the pipeline.
|
|
37
|
-
-
|
|
130
|
+
- VEED Fabric avatar renders: ~10 credits/sec at 480p, ~20/sec at 720p. Avatar creation and its speech are bundled/free; only optional portrait generation/upscaling adds cost before the render.
|
|
131
|
+
- Direct VEED Fabric: text or normal audio is 8 credits/sec at 480p and 15/sec at 720p; fast audio is 10/sec at 480p and 20/sec at 720p.
|
|
132
|
+
- Sync Labs Lipsync 2: 5 credits per verified audio second.
|
|
38
133
|
- Voiceover TTS: 10 credits per 1000 characters for standard voices, 30 per 1000 for cloned `custom-*` voices (min 1, pro-rated); applies to standalone voiceovers AND per-scene narration during `produce`. Silent tracks are free. Voice cloning itself is a flat 150 credits per clone.
|
|
39
134
|
- Lyria music: flat per track, 10 credits (clip) / 15 credits (pro).
|
|
40
135
|
- ElevenLabs audio: sound effects are per second, dialogue is per character, music/voice-changer/dubbing are per started minute. Voice changer and dubbing reject source media above 300s in the current synchronous flow.
|
|
@@ -43,10 +138,10 @@ videodraft models styles --json # visual style presets
|
|
|
43
138
|
Quote before spending:
|
|
44
139
|
|
|
45
140
|
```bash
|
|
46
|
-
videodraft costs
|
|
141
|
+
videodraft costs gemini-omni-flash --type video --duration 8 --resolution 720p --audio
|
|
142
|
+
videodraft costs seedance-2 --type video --duration 15 --resolution 720p --quality standard --audio
|
|
47
143
|
videodraft costs elevenlabs-dubbing --type audio --duration 60
|
|
48
144
|
videodraft costs elevenlabs-dialogue --type audio --chars 350
|
|
49
145
|
videodraft costs voiceover --type audio --chars 800 # TTS: 10 cr / 1000 chars
|
|
50
|
-
videodraft generate video "..." --estimate
|
|
51
|
-
videodraft credits # current balance
|
|
146
|
+
videodraft generate video "..." --model gemini-omni-flash --estimate # same quote, inline
|
|
52
147
|
```
|
|
@@ -2,34 +2,49 @@
|
|
|
2
2
|
|
|
3
3
|
Everything here works through the CLI (`videodraft <command>` / `videodraft call <tool>`) or the MCP connector (tool names in backticks). One backend; pick the surface you have.
|
|
4
4
|
|
|
5
|
+
Use direct asset tools for standalone images, clips, audio, upscales, and descriptions. Use a project for any multi-scene video, story, ad, explainer, storyboard, editable timeline, or final export even when the request does not use the word "project." Script-only uses a script-stage project and stops at the script.
|
|
6
|
+
|
|
5
7
|
## Stages and their tools
|
|
6
8
|
|
|
7
|
-
| Stage
|
|
8
|
-
|
|
9
|
-
| Idea → full storyboard project
|
|
10
|
-
| Idea → script only (stop there)
|
|
11
|
-
| Footage IS the video
|
|
12
|
-
| Batch shot images
|
|
13
|
-
| One shot image
|
|
14
|
-
| Produce (voiceover, captions, timeline) | `videodraft produce <project>`
|
|
15
|
-
| Per-shot motion prompts
|
|
16
|
-
| Motion clip for a shot
|
|
17
|
-
| Attach a finished clip to the timeline
|
|
18
|
-
| Background music
|
|
19
|
-
| Sound effect
|
|
20
|
-
| Dialogue audio
|
|
21
|
-
| Voice changer
|
|
22
|
-
| Dubbing
|
|
23
|
-
| Scene voiceover
|
|
24
|
-
|
|
|
9
|
+
| Stage | CLI | Underlying tool |
|
|
10
|
+
| --------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------ |
|
|
11
|
+
| Idea → full storyboard project | `videodraft create "<idea>"` | `generate_storyboard_from_idea` |
|
|
12
|
+
| Idea → script only (stop there) | `videodraft create "<idea>" --script-only` | `generate_script_from_idea` |
|
|
13
|
+
| Footage IS the video | `videodraft call generate_storyboard_from_media` | `generate_storyboard_from_media` |
|
|
14
|
+
| Batch shot images | `videodraft shots <project>` | `generate_shot_images` |
|
|
15
|
+
| One shot image | `videodraft generate image --project <id> --scene N --shot M` | `generate_image` |
|
|
16
|
+
| Produce (voiceover, captions, timeline) | `videodraft produce <project>` | `produce_project` |
|
|
17
|
+
| Per-shot motion prompts | `videodraft video-prompts <project>` | `generate_video_prompts` |
|
|
18
|
+
| Motion clip for a shot | `videodraft generate video --project <id>` | `generate_video` |
|
|
19
|
+
| Attach a finished clip to the timeline | `videodraft attach <project> --scene N --shot M --media <url> --type video` | `attach_media_to_shot` |
|
|
20
|
+
| Background music | `videodraft generate music --attach <project>` | `generate_music` / `set_background_music` |
|
|
21
|
+
| Sound effect | `videodraft generate sound-effect "..."` | `generate_sound_effect` |
|
|
22
|
+
| Dialogue audio | `videodraft generate dialogue --line "voice:text"` | `generate_dialogue` |
|
|
23
|
+
| Voice changer | `videodraft generate voice-changer <audio>` | `change_voice` |
|
|
24
|
+
| Dubbing | `videodraft generate dub <audio_or_video>` | `dub_media` |
|
|
25
|
+
| Scene voiceover | `videodraft generate voiceover --project <id> --scene N` | `generate_voiceover` |
|
|
26
|
+
| Avatar script | `videodraft avatar script "<idea>"` | `generate_avatar_script` |
|
|
27
|
+
| Avatar + speech | `videodraft avatar create <portrait> --script "..."` | `create_avatar_video` |
|
|
28
|
+
| Talking-head render | `videodraft avatar render <avatar_video_id>` | `render_avatar_video` + `get_avatar_video` |
|
|
29
|
+
| Direct portrait + text/audio | `videodraft avatar fabric <portrait> --text "..."` or `--audio <file>` | `generate_veed_fabric_video` |
|
|
30
|
+
| Existing video + replacement audio | `videodraft avatar lipsync <video> --audio <file>` | `generate_sync_lipsync_video` |
|
|
31
|
+
| Existing-video AI edit | `videodraft edit video <video> "<change>" --model <video-edit-model>` | `edit_video` |
|
|
32
|
+
| Motion transfer | `videodraft edit motion <image> "<direction>" --motion-video <video>` | `generate_motion_control_video` |
|
|
33
|
+
| Image enhancement/upscale | `videodraft upscale image <image>` | `upscale_image` |
|
|
34
|
+
| Video enhancement/upscale | `videodraft upscale video <video>` | `upscale_video` |
|
|
35
|
+
| Final MP4 | `videodraft export <project>` | `export_video` + `check_export_status` |
|
|
25
36
|
|
|
26
37
|
## Rules that prevent broken results
|
|
27
38
|
|
|
28
39
|
- **The storyboard is generated FROM the script**, never from the raw idea. `videodraft create` runs the whole chain correctly. Don't call `generate_storyboard_scenes` with a raw idea as the "script".
|
|
29
|
-
- **Visual consistency**: never generate a storyboard shot in isolation. Shot prompts carry `[[asset:Name]]` / `[[shot:X-Y]]` tags that `generate_shot_images` resolves against the project's visual assets and prior shots. When generating a single shot whose prompt has no tags, pass `--ref` images yourself (the project's visual assets and/or the previous shot's image
|
|
40
|
+
- **Visual consistency**: never generate a storyboard shot in isolation. Shot prompts carry `[[asset:Name]]` / `[[shot:X-Y]]` tags that `generate_shot_images` resolves against the project's visual assets and prior shots. When generating a single shot whose prompt has no tags, pass `--ref` images yourself (the project's visual assets and/or the previous shot's image; `projects get` exposes both). For scenes with multiple shots or recurring characters, prefer `videodraft shots <project> --model <selected-image-model> --grid`: preserve an explicitly requested compatible image model, otherwise use `nano-banana-2`. It creates one coherent scene grid, then decodes it into individual shot images.
|
|
41
|
+
- **Reference-first video**: when identity, styling, or composition matters, do not generate each motion clip from text alone. Generate or select the shot still first, then pass the decoded shot image as `--start-image` or `--ref` to the selected video model. AI Production already composes scene grids and sends them to Seedance as references. If the user explicitly requests another compatible video model, bypass fixed Seedance full-video mode and generate the per-shot clips with the requested model, using the individual decoded shot images as anchors.
|
|
30
42
|
- **Hold off generating shot images while the user is still iterating** on storyboard structure.
|
|
31
43
|
- **produce → export ordering**: `export` requires a produced project where every production scene has timeline media. If `produce` returns `generating_shot_images`, poll the job ids it returns, then re-run produce.
|
|
32
44
|
- **Generated motion clips do not auto-attach**: after `generate video` completes, attach the clip with `attach_media_to_shot` (`media_type:"video"`, include `duration_seconds`) — it replaces the production timeline clip while keeping the storyboard still.
|
|
45
|
+
- **Talking heads use dedicated avatar tools**: do not use `generate video`. Use managed `avatar create` and `avatar render` for reusable avatars, direct `avatar fabric` for a portrait plus text/audio, and `avatar lipsync` for an existing video plus replacement audio. Reuse a supplied person image or generate a clear front-facing portrait with the explicitly requested compatible image model, otherwise Nano Banana 2. Managed avatar creation and speech are bundled/free; direct Fabric, Sync, and render are paid.
|
|
46
|
+
- **Existing-video edits use their own category**: call `edit_video` or `videodraft edit video` with a `video_edit` model when transforming the source itself. Kling O3 and Wan 2.7 Ref/Edit are dual-mode: their reference-generation modes may use generic `generate_video` to create a new guided clip. Motion transfer similarly uses `generate_motion_control_video` or `videodraft edit motion` with a `motion_control` model.
|
|
47
|
+
- **Upscaling preserves rather than redesigns**: use Topaz when resolution, detail, or cleanup is the problem. Regenerate or edit when the subject, text, framing, continuity, or motion is wrong. Upscale a low-quality avatar portrait before Fabric; do not render a new avatar at 480p just to upscale the result.
|
|
33
48
|
- **Timeouts on the one-shot create**: if `create` times out at the transport layer, the project was still created server-side — `videodraft projects list`, take the most recent, and resume with its id. Don't start a duplicate.
|
|
34
49
|
|
|
35
50
|
## User-attached media: classify roles first
|