Mvmaker H3 Skill

MVMaker H3 Skill

Run the standard MV production pipeline without inventing intermediate creative rules. Treat the canonical master audio as the only global clock, mv-storyboard-director as the director, and h3-prompt-writing as the final H3 prompt author.

Before executing, read references/contracts.md. When preflighting, submitting, resuming, or monitoring through the local application, also read references/local-h3gen.md.

Immutable stage handoff

Persist the input and raw output of every creative stage. Pass the user's materials to the director without an agent-authored creative rewrite; pass the saved director segment, ordered media, exact segment WAV, and user constraints to the official H3 skill; save the H3 result verbatim and submit that saved result.

Do not insert a custom prompt rewrite, universal singing rule, universal non-singing rule, shot template, song-section template, fixed segment count, or test-project vocabulary between stages. Codex coordinates, validates, and packages; it does not become a third creative author.

Scope and authority

• Continue only through the stage requested by the user. If the user says “up to pre-submit,” stop after preflight and manual-package export.
• Treat RunningHub generation as paid external execution. Submit only after explicit user authorization; do not add a second confirmation after authorization already exists.
• Reuse the configured minimax-H3-GEN service and RunningHub credentials. Never expose or copy API keys into prompts, manifests, HTML, logs, or export packages.
• Before a client-dependent preflight, submission, monitor, or resume operation, verify the local service health. If the client is not installed, send the exact missing-client reminder and workflow links from references/local-h3gen.md. If it is installed but stopped, ask the user to start it instead of sending the download reminder.
• Submit through the local minimax-H3-GEN HTTP API. Do not substitute a generic RunningHub CLI, a canvas drag/import flow, or another service when this application is available.
• Do not invoke sync-runninghub-workflow; it is not part of this pipeline.
• Preserve successful artifacts and user changes. Retry only failed segments and use idempotency keys to prevent duplicate billing.

Required inputs

Use materials already supplied before requesting more:

• Complete song audio; required for executable timing and RunningHub submission.
• Lyrics, title, style, mood, and creative constraints when available.
• Character, wardrobe, scene, prop, art-direction, and composition references.
• Output ratio, resolution, compute tier, and requested stopping stage.

When only lyrics or style are available, director planning may proceed, but mark timing as provisional and do not generate executable audio segments or submit tasks.

Workflow

1. Establish the job and canonical audio

Create one job root without disturbing unrelated output. Copy source materials into the job assets area.

Save immutable snapshots for the user brief, director input, director output, H3 input, H3 output, submission manifest, preflight, task state, validation report, and assembly report. A later stage may reference a prior snapshot but must not silently overwrite it.

Decode the supplied master once to PCM WAV:

48 kHz · stereo · PCM s16le

Use this canonical WAV for every segment and for the final master. Never repeatedly cut an MP3.

Set usable_duration_seconds = floor(source_duration_seconds) when the only remainder is under one second and the user allows it to be discarded. Do not pad, repeat, stretch, or invent content.

2. Direct the MV

Use mv-storyboard-director for creative interpretation and storyboard design. Give it the song, lyrics, visual references, user constraints, and the following production override:

• Produce a continuous second-layer production timeline.
• Use integer global starts, ends, and durations.
• Keep every production segment between 10 and 15 seconds.
• Start the first segment at zero and make each next start equal the previous end.
• End at usable_duration_seconds; discard an allowed final fraction under one second rather than creating a padded container tail.
• Reset every independently submitted segment to local 0–duration time.
• Allow decimal shot cues only inside a segment.
• Do not hard-code song sections, fixed segment counts, singing, or non-singing behavior.

Record both creative structure and production segments. Do not let the production containers rewrite the song’s actual form.

Save the director response before extracting the production manifest. Extraction may normalize fields into the contract schema but must not add or remove creative decisions.

3. Validate and split audio

Before generating images, validate the timeline with the bundled validator:

python <skill-dir>/scripts/validate_production_manifest.py --job-root <job-root> --manifest <manifest.json>

Split the canonical WAV at exact integer boundaries. For each segment:

• use sample-accurate atrim and reset PTS;
• output PCM WAV at 48 kHz stereo;
• require exactly duration × 48000 samples per channel;
• do not use apad, MP3 output, silence insertion, or independent rounding.

Verify that concatenated segment PCM equals the canonical master over the usable range.

4. Generate storyboard images

Generate one complete 16:9 four-panel storyboard for each production segment. Use the configured image provider; in the current project, prefer the configured BananaRouter channel. Request 2K unless the user overrides it.

The four panels are ordered temporal anchors, not four final split-screen frames. Keep the storyboard intact as Picture 1; do not split it before H3 or RunningHub upload.

Use only the character and scene references needed by that segment. Multi-character convergence segments may include all required references dynamically.

5. Write official H3 prompts

Use h3-prompt-writing in Ref2VA mode. Pass the director handoff plus ordered reference roles, local timeline, segment lyrics or audio events, and output constraints.

Require:

• Picture 1 = complete storyboard;
• Picture 2…N = required character or scene references in upload order;
• Audio 1 = exact segment WAV;
• H3 timing = local 0–duration, never global time;
• visible readable mouths may follow real vocals with accurate phonemes, breath, expression, and intensity;
• instrumental, silent, distant, rear-view, insert, or empty shots do not receive forced lip movement;
• no global ban on singing and no global command that every visible character must sing;
• no audio replacement, recomposition, retiming, padding, or truncation.

Save one H3 input snapshot and one raw H3 output file per segment. Do not add a separate custom prompt-rewrite stage before or after the official H3 skill. If an H3 result is invalid, rerun the official skill with corrected source inputs; never patch its creative content downstream.

6. Build the extra manual-upload package

After images, WAV files, and H3 prompts are complete, create the additional user-facing package:

python <skill-dir>/scripts/build_manual_upload_package.py `
  --job-root <job-root> `
  --manifest <h3-manifest.json> `
  --output <job-root>/manual-upload-package

This is an extra export only. It must not replace or alter the automatic pipeline. Each segment folder contains physical copies of its ordered images, audio, prompt, and a short parameter file so a user can upload it manually. Also create manual-upload-package.zip.

7. Preflight RunningHub

Call the local POST /api/tasks/preview route with confirm_paid: false for every segment and verify:

• prompt, ordered media, duration, ratio, megapixels, and instance tier;
• local SHA-256 versus uploaded remote filename or receipt;
• one-to-one segment-to-task mapping;
• no missing or cross-segment assets;
• all required nodes and output node are present.

Persist the preflight result. A failed segment must not advance.

8. Submit and monitor

After authorization, submit through the configured minimax-H3-GEN RunningHub API path.

• Default to at most five active tasks from this job unless the user changes it. Treat the RunningHub account as shared: other user tasks may leave fewer real slots.
• Derive the idempotency key from segment ID plus the complete payload hash.
• Count a segment as submitted only after the local API returns a local task ID and RunningHub task ID.
• Treat TASK_QUEUE_MAXED as pending, not failed. Leave unaccepted segments in the pending set and retry them when a real slot opens.
• Allow accepted segment numbers to become temporarily non-sequential under concurrent slot contention; assemble only by manifest order.
• Treat running-status responses as normal and continue polling the same task.
• Persist state atomically after every accepted task and status transition.
• If the monitor process stops or times out, resume from the saved local/RunningHub task IDs and idempotency keys. Never regenerate or resubmit merely because polling or download was interrupted.
• Save task ID, status, usage, result URL, timestamps, and error details.

Use the bundled queue runner when the local API and manifest follow the documented adapter:

python <skill-dir>/scripts/h3gen_queue.py `
  --job-root <job-root> `
  --manifest <manifest.json> `
  --state <runninghub-submission.json> `
  --confirm-paid

Running the same command again resumes the same records. Use --resume-only to poll accepted tasks without attempting pending segments. Never pass --confirm-paid until authorization exists.

9. Validate outputs

For each downloaded result, verify automatically:

• expected video and audio streams exist;
• dimensions, ratio, codec, and task identity are correct;
• output duration is not shorter than requested;
• returned audio aligns with the exact uploaded WAV using normalized waveform plus spectral/fingerprint alignment;
• the result is not a duplicate or another segment’s audio.

RunningHub frame quantization may make outputs longer than requested. Treat the requested integer duration as authoritative. A clear audio mismatch is a generation failure even when RunningHub reports success; retry only that segment with a new attempt record.

Do not require manual quality control as a pipeline gate. Produce inspectable reports for user review when requested.

Use the bundled assembler when the manifest and task-state schema match the contract:

python <skill-dir>/scripts/download_validate_assemble.py `
  --job-root <job-root> `
  --manifest <manifest.json> `
  --submission <runninghub-submission.json> `
  --output-dir <job-root>/delivery

10. Assemble the master

For every successful segment:

1. Trim video to exactly its requested segment duration.
2. Remove the RunningHub audio track.
3. Concatenate the duration-correct video-only segments in timeline order.
4. Attach the canonical master audio once over 0–usable_duration_seconds.
5. Encode final delivery audio once.

Never concatenate untrimmed RunningHub clips or their per-segment AAC tracks. If a generated video is shorter than requested, fail and retry; do not freeze, pad, or stretch it.

Verify final video duration, final audio duration, and summed segment duration agree within one output frame and one audio sample.

Do not diagnose segment lip-sync from a concatenation that includes quantized RunningHub tails or concatenated AAC tracks. First assemble with this procedure, then evaluate the resulting master.

11. Publish the archive

Generate the HTML summary only from real artifacts. Include:

• inputs and director statement;
• timeline and segment cards;
• storyboard, ordered references, WAV, and H3 prompt;
• RunningHub parameters, task IDs, usage, raw duration, trimmed duration, and validation status;
• per-segment result and final master;
• link to the extra manual-upload directory or ZIP.

Failed or missing outputs must remain visibly failed or pending; never publish placeholders as success.

Read the segment count, personas, timeline, paths, task IDs, usage, and validation fields dynamically. Do not embed a test song title, fixed number of segments, fixed cast size, revision name, or previous task IDs in a reusable HTML generator. Validate desktop and narrow-screen rendering, all local links, and absence of API-key patterns before publishing.

Completion gates

Do not call the requested stage complete until all applicable gates pass:

• Timeline: integer, continuous, 10–15 seconds, and source-authoritative.
• Audio: sample-exact WAV slices with no padding or MP3 boundary artifacts.
• Storyboards: one intact 16:9 four-panel image per segment.
• Prompts: produced by h3-prompt-writing, local time, ordered references, audio-aware performance.
• Package: one self-contained manual-upload folder per segment plus ZIP.
• RunningHub: preflighted, idempotent, traceable, and no duplicate billing.
• Results: media and audio-identity checks pass.
• Assembly: trimmed video-only segments plus one canonical master audio track.
• Archive: HTML reflects actual inputs, parameters, tasks, validation, and outputs.
• Recovery: restarting an interrupted monitor or downloader reuses recorded tasks and does not create paid duplicates.

Prohibited shortcuts

• Do not hard-code one test song’s segment count, lyrics, roles, or section names.
• Do not make every character sing or forbid characters from singing.
• Do not split the four-panel storyboard into four upload images.
• Do not use decimal production durations.
• Do not pad the final audio fraction or any segment.
• Do not use raw RunningHub output duration as the edit decision list.
• Do not substitute hand-written prompt rules for either required creative skill.
• Do not submit paid retries without checking whether a task already exists.
• Do not mark queue-capacity responses as failed or skipped.
• Do not concatenate per-segment RunningHub audio tracks.
• Do not use a generic CLI when the configured local H3-GEN service is the project execution boundary.