Plotloom Video Adapter

Plotloom Video Adapter

When to Use

Use when episodes/epXXX/video-prompts.md or video-prompts-en.md exists and a clip candidate should be produced or queried.

Inputs

• video-prompts.md / video-prompts-en.md
• Target clip id such as clip-01
• Adapter choice: fake adapter by default; Dreamina only for explicit real generation.

Outputs

• episodes/epXXX/videos/clip-YY/candidates/vNNN.mp4
• If queueing, a human-readable queue note near the clip folder containing submit_id, status, adapter, and next query command.

Read These Resources When...

• Read references/fake-adapter.md for contract tests and no-quota dry runs.
• Read references/dreamina-cli.md before any real Dreamina/即梦 submission or polling.
• Use templates/adapter-request.md to record preflight, command, status, and handoff.

Workflow

1. Read the prompt file and target clip id. 2. Choose fake adapter by default for contract tests. 3. Use Dreamina only when explicitly running real generation and preflight passes. 4. Submit one candidate at a time. 5. Save outputs to episodes/epXXX/videos/clip-YY/candidates/vNNN.mp4. 6. If the provider queues, preserve submit_id in a visible note near the clip folder, not a hidden runtime DB. 7. Hand off to plotloom-asset-selection after a candidate exists.

Adapter Rules

• Fail fast on missing prompt, missing clip id, invalid output path, missing login, missing maestro, missing quota, or provider error.
• Fake adapter proves file-path contracts and ffmpeg compatibility; it does not prove creative quality.
• Dreamina requires host pre-authentication. The adapter must not automate OAuth, store credentials, or copy tokens.
• Do not create a Python runtime client in the skill; keep this as a prompt and command contract plus the plotloom CLI.
• Do not batch-generate three candidates in MVP.

Reference Discipline

Reference handling is high risk. Do not assume that a local path written inside prompt prose is sent to the provider.

Before any image-to-video or reference-to-video submission: 1. Identify the exact intended first frame and reference images for this clip only. 2. Verify those files or asset://... ids are the actual request inputs, not just Markdown text. 3. Reject ambiguous phrasing such as Use Image 1 unless the Image mapping has been programmatically resolved for the target clip. 4. Record the submitted reference list in a visible receipt/handoff. If the CLI cannot show the actual refs, stop and add/patch the tool support before expensive generation.

For VolcEngine/Seedance identity work:

• Full character sheets may trigger InputImageSensitiveContentDetected.PrivacyInformation.
• Transparent face mesh, red topology, blur, or privacy mesh are not reliable bypasses.
• Prefer provider-approved asset://... virtual face anchors for faces, plus face-blocked costume/body sheets for clothing and silhouette.
• Treat asset://... as face-only. Hats, wardrobe, body type, props, and scene blocking still need text or non-sensitive visual refs.
• Face consistency smoke tests should start with medium close-up, front-left 3/4 face, visible eyes, no deep hat shadow, face occupying about 25-35% of frame, and minimal action.

Batch Safety

For repeated candidate or asset generation, use a manifest/resume pattern: skip outputs that already exist unless --force is explicit, record per-item status, and continue after timeouts. Do not restart a batch from item 1 after one successful expensive generation.

Stop Conditions

Stop after candidate creation, queue note, or provider failure report. Do not select or stitch.

Next Skill Handoff

Use plotloom-asset-selection to review and accept/reroll the candidate.

Failure Modes

• Fake adapter failure: check ffmpeg installation and output path.
• Dreamina not logged in: run dreamina user_credit manually on the host.
• Dreamina account not maestro: stop and report permission gap.
• Queueing: record submit_id, status, and query command visibly.
• Generation failed: preserve error and suggest prompt revision only if failure is prompt-related.

Dreamina CLI Adapter Reference

Verified Facts

• preflight: dreamina user_credit
• requires: vip_level = maestro
• text-only submit: dreamina text2video --prompt "..." --duration=15 --ratio=9:16 --model_version=seedance2.0fast_vip
• image/reference submit: prefer dreamina multimodal2video --image ... --prompt "..." ...; use image2video for one first-frame image, multiframe2video for frame-to-frame transitions
• query: dreamina query_result --submit_id=...
• download: dreamina query_result --submit_id=... --download_dir=...
• query_result has no --poll flag; query loop must be external.
• text2video, image2video, multimodal2video, and multiframe2video support --poll N immediately after submit.
• failure modes: not logged in / not maestro / quota insufficient / queueing / generation failed

Important Format Boundary

Plotloom video-prompts.md / video-prompts-en.md are internal human-readable artifacts. Do not pass the whole Markdown block to Dreamina CLI.

Dreamina CLI expects:

one prompt string via --prompt
plus command flags such as --duration, --ratio, --model_version, --image, --video, --audio

Bad adapter input:

## clip-01
- Duration hint: 15-20s
- Reference images:
- assets/cast/lin-qiao/character-grid.png — preserve identity
- Prompt: ...
- Ending frame / handoff point: ...

Good adapter input:

dreamina text2video \
  --prompt "A tense modern short-drama scene: in a glossy corporate boardroom on a rainy night, Lin Qiao steps out of an elevator carrying a delivery bag... End with her hand pausing over a hidden family seal. No subtitles, no watermark, no logo." \
  --duration=15 \
  --ratio=9:16 \
  --model_version=seedance2.0fast_vip

Current Environment Note

In the current Nova/Hermes host, the binary has been observed at:

/Users/wangguiping/.hermes/profiles/nova/home/.local/bin/dreamina

Recommended preflight shape in this environment:

HOME=/Users/wangguiping /Users/wangguiping/.hermes/profiles/nova/home/.local/bin/dreamina user_credit

Expected account permission:

vip_level: maestro

Command Selection

text2video

Use only when there are no actual local reference images/videos/audio to upload. Text mentions of assets/cast/.../character-grid.png are not used by this command unless their content is rewritten into the prompt.

Supported by current help:

model_version: seedance2.0, seedance2.0fast, seedance2.0_vip, seedance2.0fast_vip
ratio: 1:1, 3:4, 16:9, 4:3, 9:16, 21:9
duration: 4-15 seconds, default 5
video_resolution: 720p

Example:

HOME=/Users/wangguiping /Users/wangguiping/.hermes/profiles/nova/home/.local/bin/dreamina text2video \
  --prompt "$PROMPT" \
  --duration=15 \
  --ratio=9:16 \
  --model_version=seedance2.0fast_vip \
  --poll=30

image2video

Use when there is one first-frame/reference image.

dreamina image2video \
  --image ./first-frame.png \
  --prompt "$PROMPT" \
  --duration=15 \
  --model_version=seedance2.0fast_vip

multimodal2video

Use when Plotloom has character grids, scene references, prior clips, or audio references. This corresponds to Dreamina “全能参考”.

dreamina multimodal2video \
  --image ./assets/cast/lin-qiao/character-grid.png \
  --image ./assets/cast/shen-mo/character-grid.png \
  --prompt "$PROMPT" \
  --duration=15 \
  --ratio=9:16 \
  --video_resolution=720p \
  --model_version=seedance2.0fast_vip

Limits from current help:

image <= 9
video <= 3
audio <= 3
duration 4-15 seconds

multiframe2video

Use for frame-to-frame transitions. Inputs: 2-20 images. For N images, provide N-1 transition prompts/durations if using 3+ images.

Adapter Translation Rules

When converting video-prompts-en.md to CLI:

1. Select one clip-YY block. 2. Extract only the model-facing prose from Prompt, Continuity rules, Camera motion, Dialogue / audio window, and Ending frame. 3. Convert reference-image bullets into real CLI flags only if the files exist and the command supports them. 4. For Dreamina CLI with reference images, use multimodal2video, not text2video. 5. Translate Duration hint into --duration, clamped to 4-15 seconds. 6. Translate aspect ratio into --ratio; for short-drama default use 9:16 unless the user chooses otherwise. 7. Add negative constraints inside the prompt string: no subtitles, no watermark, no logo, no garbled text. 8. Store submit/query commands in a visible adapter note.

Submit / Query Skeleton

HOME=/Users/wangguiping /Users/wangguiping/.hermes/profiles/nova/home/.local/bin/dreamina <command> ... --poll=30
HOME=/Users/wangguiping /Users/wangguiping/.hermes/profiles/nova/home/.local/bin/dreamina query_result --submit_id=<submit_id> --download_dir=<candidate-dir>

Queue Note Shape

Store a visible Markdown note near the clip folder:

# Dreamina Queue Note

- adapter: dreamina-cli
- command: text2video | image2video | multimodal2video | multiframe2video
- clip: clip-01
- submit_id: <redacted-if-sharing>
- status: Queueing | Generating | Finish | Failed
- query command: `... query_result --submit_id=... --download_dir=...`
- last checked:
- next action:

Queue Handling

Dreamina may return gen_status: querying with queue_status: Queueing or Generating. Poll externally for long waits. Do not introduce a runtime DB, queue worker, or hidden state file.

Common Interpretations

• not logged in: host must complete manual login first.
• not maestro: account lacks CLI generation permission.
• output around 4-5 seconds: likely omitted --duration; default is 5 and observed fast output may be ~4.06s.
• queueing/generating: preserve submit id and wait/poll.
• generation failed: keep error, then decide whether to revise prompt or retry.

Security

Never commit tokens, credentials, OAuth links, device codes, QR contents, credential files, or raw account identifiers. Use [REDACTED] when documenting sensitive material.

Mock Video Adapter Reference

Purpose

The mock adapter runs Plotloom contract tests without spending quota or waiting for a real model. It creates a deterministic mp4 candidate through the normal plotloom video submit path.

Command Shape

plotloom --repo . video submit \
  --episode ep001 \
  --clip clip-01 \
  --adapter mock

What It Proves

• Prompt file path exists.
• Candidate output path can be created.
• Selection and stitching helpers can consume the candidate.
• ffprobe/ffmpeg are available.

What It Does Not Prove

• Prompt quality.
• Character continuity.
• Model/provider availability.
• Commercial quality.

When to Use

Use mock by default in tests, CI-like checks, and examples. Use real Dreamina or VolcEngine only when the user explicitly asks for real generation and preflight passes.

Adapter Request

• Episode: ep{{episode_number}}
• Clip: clip-{{clip_number}}
• Adapter: fake | dreamina | other
• Source prompt file:
• Source prompt excerpt / hash:
• Reference images:
• Candidate output path:

Preflight Checks

• Prompt exists:
• Clip id exists:
• Output directory writable:
• Adapter available:
• Login / permission / quota:

Commands

• Submit command:
• Submit id:
• Query command:
• Download command:

Status

• State: pending | queueing | generated | failed
• Queue info:
• Error notes:

Next Handoff

• Candidate review path:
• Notes for plotloom-asset-selection: