faceless-video
The channel factory for faceless, narrator-led video: five channel types on one
motion pipeline (plus a stills pipeline and a song mode), any non-photoreal look,
one voiceover, one finished file. Voice → the narrator skill; captions → the
subtitles skill; a selected cover → the thumbnail-generation skill.
In a hands-off run, an unanswered cover choice locks to thumbnail: yes. A request
for exactly one finished MP4 constrains the video deliverable only; it is not a cover
decline. Lock thumbnail: no only when the user explicitly declines a thumbnail or cover.
HOW TO READ THIS FILE: execute the Phases 0→8b IN ORDER. Do not skip a phase, do not
reorder. Each phase has a GATE you must satisfy before the next. Long templates
live in the resolved helper skills — open them when the phase says so. Obey
every GOLDEN RULE.
RUNTIME CONTRACT — Higgsfield sandbox only
sandbox_exec is required for every download, probe, validator, audio
measurement, assembly, transcription, caption burn, and upload PUT. Never run
these commands in a client-local or built-in shell.
- Before any paid generation, verify that
sandbox_exec, media_upload, and
media_confirm are callable. If the direct upload pair is unavailable, stop:
media_upload_and_confirm cannot export a file that exists only in the
sandbox.
- Preflight once in Phase 0:
sandbox_exec({
restart:true,
command:"set -e; for b in ffmpeg ffprobe python3 curl jq awk; do command -v \"$b\" >/dev/null; done; test -n \"$HF_WORKFLOWS\"; test -r \"$HF_WORKFLOWS/faceless-video/scripts/finish_video.sh\"; mkdir -p work/{blocks,voices,frames,output}"
})
Before a narrated motion run, check python3 -c 'import faster_whisper' and retry
once. When available, Gate 5 must verify what every take says regardless of the
subtitle toggle. If it is still unavailable, record the degraded route before paid
generation: treat subtitles as off, pass --allow-unverified-audio to the one
finish_video.sh call, and disclose that the delivered clean cut's take content could
not be transcribed for verification. Never use that flag when the import succeeds,
and never claim the audio-content gate passed. Any other failed preflight blocks the
run.
- Faceless validators, both assemblers, and
finish_video.sh are preinstalled at
${HF_WORKFLOWS}/faceless-video/scripts/. Narration helpers live at
${HF_WORKFLOWS}/narrator/scripts/, and caption helpers at
${HF_WORKFLOWS}/subtitles/scripts/. Pass these paths verbatim inside
sandbox_exec; never paste, copy, or execute a helper skill's local scripts/ copy.
- The sandbox is ephemeral. Keep each command self-contained and idempotent:
re-download missing inputs behind
[ -s file ] || curl …, run the script,
verify outputs, and export the deliverable before the sandbox expires.
- Use
background:true for assembly/captioning and poll the returned
log_path immediately with the next sandbox_exec call. Never start a
duplicate process while the first is alive.
- Preserve deterministic manifest order (
block01, voice01, frame001);
never infer order from ls or job completion order.
media_upload_and_confirm is only for files attached by the ChatGPT user; it
cannot read a sandbox path. To export a sandbox-created deliverable, call
media_upload first, then append curl -f -X PUT --upload-file … to the SAME
sandbox_exec command that creates the file. Call media_confirm only after
that command reports HTTP 200. Deliver only the confirmed hosted URL.
GOLDEN RULES (read first — violating any of these breaks the video)
Before intake, resolve a structured animation_mode when present:
fully_animated means motion_mode:animated; scene_based means
motion_mode:stills. Record the resolved mode and skip the motion-mode question.
This mapping is transport-independent and a supplied scene_based value must never
fall back to Animated.
Before any voice lock, resolve Kids sound intent from the complete request, including
channel_subject, topic, and supplied script. An explicit kids song, nursery song,
sing-along, sung/music video, or local-language equivalent locks SONG MODE. In that
mode supplied voice_id, voice_type, or voice_name is inert metadata: ignore it,
never create voice.lock, and follow references/kids-song.md. Background music or a
soundtrack alone is not song intent; keep narration and add the normal instrumental bed.
- Models are LOCKED. Never substitute. Assets/style key →
seedream_v5_pro
(image), always with resolution:"1k".
Clips → minimax_h3 at resolution:"2K" (video). Fixed-window narration → text2speech_v2 with
variant:"elevenlabs"; seed_audio stays only for Kids song and Picture Story's
continuous read. Music bed (when one is
due: Kids default, Fairy Tale & Myth default, or the user asked) → submit it
through generate_audio_batch with model:"sonilo_music", no voice id, and the exact video
duration; instrumental only (mood by channel: Kids playful, Fairy Tale &
Myth mysterious-calm — ${FACELESS_STYLES_DIR}/references/kids-styles.md §Kids music bed,
${FACELESS_STYLES_DIR}/references/style-cinematic-storybook.md §Music). No other model, ever.
- Every clip is ONE 10s shot-group of FIVE hard-cut shots (~2s each) written into
a single prompt (see Phase 4) — NO shot longer than 2.5s: a frame that hangs 3–5s
reads as a slideshow. Kids blocks use the FOUR-cut interplay pattern (2.5s)
(
${FACELESS_STYLES_DIR}/references/kids-styles.md). Degradation on generation failure: a block that
fails twice at its cut count drops ONE cut (5→4; Kids 4→3) — never the whole video.
One minimax_h3 call = one 10s block. Do NOT make separate clips per cut.
COUNT THE CUTS THAT CAME BACK — the model under-delivers. Probe each completed
block with the preinstalled ffprobe scene detector:ffprobe -v error -select_streams v:0 -show_entries frame=pkt_pts_time \
-of csv=p=0 -f lavfi "movie=blockNN.mp4,select=gt(scene\,0.3)" | wc -l
A block with fewer cuts than asked, or any shot at least 3s long, is regenerated
ONCE with every cut spelled out shot by shot. For flat looks (Editorial, Paper
Diorama, Pastel Flat 2D, Poster Vector, Stickman), re-measure at scene,0.15 and
treat a low count as a suspicion: inspect the block before spending a retry. If
the second attempt still under-delivers, keep it and say which blocks are slow.
Degradation after generation failure remains automatic: 5→4; Kids 4→3.
- Compose from the approved assets. Every clip references the Phase-2 asset images
(
medias, role image), in the order location → characters → props. NEVER
generate a clip/still from the style key alone. Frames are full staged scenes, never
an object on a blank/white background.
- Pass
aspect_ratio EXPLICITLY on every video call (the chosen aspect; default
16:9). It does NOT inherit from the style key.
- Preset-recommender handling: a
minimax_h3 call (usually the first) may return a
preset RECOMMENDATION instead of a job. Immediately resubmit the SAME call with
declined_preset_id = that recommended preset's id (taken from the response). Never
ask the user about it, never stop on a recommendation.
- NSFW is a ~50% probabilistic false-positive. Use the RETRY LADDER (see below) —
resubmit, then reword; change
seed only when the live model schema declares it. NEVER drop a block, NEVER deliver a gap.
- Characters never talk on screen (no lip-sync). The voice is an external narrator
added in post. Prompts say "characters only emote and gesture, they do NOT talk."
Kids characters visibly react to the narrator through gestures only. The one
exception is a Kids run with
talking_characters:true: odd blocks keep the external
narrator and closed mouths; even blocks contain cast dialogue and use the clip's own
lip-synced audio. Read references/kids-talking-characters.md for that branch.
- Subtitle timing comes ONLY from Whisper on the final audio. Never estimate from
the script, never time-by-generating-per-phrase.
- Assembly fps = source fps (probe
r_frame_rate); never hardcode 30.
- Banned in prompts: the tokens
child / kid / childlike (use naive /
small / simple); any real brand / studio / IP name (describe the look instead).
- Never expose mechanics to the user — no model names, phase names, or studio
names in chat, and no third-party brand/studio names inside
ask_user_input
texts either. The user sees only creative substance + the approval gates.
- Wait every job to a terminal state. For OpenAI batch submissions use
jobs_wait on the returned {index, job_id} pairs; completed = good,
failed/nsfw = retry. Do not proceed on a non-completed job.
- Deliver ONE whole video file (
final.mp4). Concatenate ALL blocks + VO (+ subs)
into a single file. NEVER split the output into part1/part2 or hand back separate
clips — the deliverable is exactly one video.
- Throughput: bulk media uses the headless batch tools. Submit independent
images, video blocks, and narration takes in ordered groups of at most SIX, then
wait for that group together with
jobs_wait. Never fan out parallel singleton
generate_* calls in an OpenAI run.
- Duration is FIXED = N×10s (the target). NEVER shorten the video to fit short audio
(the "2:00 → 1:35" bug). Each block stays 10s. Write one dense voice line that
naturally fills most of each block, then let the assembler center its detected
speech. After each narrated motion wave, run
${HF_WORKFLOWS}/faceless-video/scripts/measure_narration_takes.py --script script_manifest.json --voice-dir work/voices --duration-seconds {requested_seconds}
in the same call that materializes the takes. It binds exact text to numbered
files and returns the retry set. Measured overlong blocks alone may shorten
below the authoring floor via validate_motion_script.py --duration-retry-blocks N,....
Keep the cumulative measured block set on revalidation; never lower every line's floor.
Never trim the video to fit a take.
- Sync is by construction: one line lives inside its own 10s block, so a line never
bleeds into the next scene. Never
atempo/speed-change/pitch-shift audio to fit —
rewrite + regenerate instead.
- ONE voice everywhere. Every audio chunk uses the SAME
voice_id + voice_type
(the one locked at intake). Never let chunks come out in different voices.
- NO time-stretching in post. Never
atempo/speed-up/slow-down/pitch-shift the
audio to fit. If length is wrong, REWRITE + regenerate the beat. (speech_rate also
untouched unless the user asks.)
- Style fidelity — clips MUST match the asset sheets 1:1. Same character design,
same palette, same background treatment (if assets are white/clean-bg webcomic,
the video stays white/clean-bg webcomic). ONE consistent style across the whole video
— no per-shot restyle, no object drift, no style scatter.
- Captions are compact (if on): ≤5 words / ≤32 chars, bottom ~12%, NEVER
covering the subject or filling the frame. Clean CAPS + outline, no plate. Three-word
captions flicker too quickly and must not be forced through a smaller override.
- No leading freeze. Every block prompt demands motion from frame 1; the assembler
adds no head padding and WARNS when a block's opening looks static — on that warning
REGENERATE the block (never ship a still that "starts playing" a second later).
- No samey footage. Vary shot SIZE and ANGLE on EVERY cut (WIDE / MEDIUM / CU / OTS
/ low / high) — do NOT reopen every block on the same establishing WIDE. OTS is
legal ONLY when a named on-screen character's shoulder/head is deliberately visible
in the foreground. For an object-only, diagram, empty-location, or otherwise
characterless shot, OTS is FORBIDDEN — use overhead/top-down, low/high angle, macro,
lateral, or another coverage angle instead. Never use OTS as a synonym for an angled
view; it makes the video model invent a person. Max ~20s
(≈2 blocks) per location/distance, then move (new location / coverage angle / variety
insert). Rotate locations; never park the character back at the opening wide.
- Voice and subtitles are DELEGATED to installed skills; reference
instructions are bundled into this skill. All executable work runs in
sandbox_exec. Phase 5 invokes narrator; Phase 7 invokes subtitles.
Before Phase 0 resolve the directory containing this SKILL.md as
FACELESS_SKILL_DIR, then set FACELESS_FLOW_DIR,
FACELESS_STYLES_DIR, and FACELESS_MODES_DIR to that same directory.
Their documents are all under ${FACELESS_SKILL_DIR}/references/.
Executable scripts always
come from ${HF_WORKFLOWS}/faceless-video/scripts/ inside the
Higgsfield sandbox. For ordinary motion-video runs use
finish_video.sh (internally assemble_final.sh); Picture Story uses its
--stills route (internally assemble_slides.sh). These FFmpeg scripts are
the canonical assembly paths, not fallbacks. Never call explainer_video merely to
stitch completed clips and narration. Never hand-roll another FFmpeg path around
the scripts; if an assembler errors, fix the inputs and rerun it.
- Generation widgets are stage summaries, never progress indicators. Batch
submission and waiting stay headless. Persist every
{index, job_id} immediately
and trust jobs_wait, not widget chrome. After the complete media stage is
terminal, display its exact final ledger with show_generation_by_ids; never
browse history with show_generations.
- Narration target is 7.8–9.5s of speech per full 10s block. The narrator
measures speech and rate rather than padded file length, requires
rate=ok,
rewrites out-of-window or rushed lines,
and allows at most three attempts per line, with changed text before a third.
Accept 7.2–7.8s only after one retry; hard reject outside 7.2–9.5s. Stop with
AUDIO_GEN_FAILED and the exact slot/metrics when a take still fails; never
ship the closest failed take or time-stretch it.
Types & format
Output = ONE video file: a motion-clip montage for Explainer / History / Kids, or
narrated STILLS for the Picture Story direction (${FACELESS_MODES_DIR}/references/picture-flow.md).
Kids additionally has Talking Characters — alternating narrated and cast-dialogue
blocks (references/kids-talking-characters.md) — and SONG MODE, a music video built on a real sung children's
song (${FACELESS_MODES_DIR}/references/kids-song.md: song generated FIRST via seed_audio prompt-only,
blocks choreographed to it, assembly via the assembler's --song mode; no narrator,
no bed, no subtitles). These two Kids sound modes are mutually exclusive. Standalone image deliverables (slide decks, image sets)
remain REMOVED — every direction ships a single video.
| Channel type |
Default style |
Pacing |
VO tone |
| Kids |
Baked-in Kids set (${FACELESS_STYLES_DIR}/references/kids-styles.md, Studio 3D recommended; Fluffy Toy via preset widget) |
FAST — 4 cuts per block (WIDE → CU character → ECU detail → MEDIUM), varied every block |
warm teacher, direct address, catchphrases; the QUESTION-FIRST skeleton and picture-storytelling in kids-styles.md are MANDATORY, as is narrator↔character↔viewer interplay |
| History |
Editorial Motion Graphics (house style — ${FACELESS_STYLES_DIR}/references/style-editorial-collage.md); named alternates: Paper Diorama (${FACELESS_STYLES_DIR}/references/style-paper-diorama.md), Mannequin (${FACELESS_STYLES_DIR}/references/style-mannequin.md); LONG-FORM direction: Documentary 10+ min, Watercolor Chronicle (${FACELESS_MODES_DIR}/references/history-longform.md) |
slower, chronological (long-form: cold open → rewind → chapters) |
witty, sarcastic, anachronistic storyteller (Mannequin: dry British; long-form: measured documentary narrator) |
| Explainer |
TWO main directions, offer both: Editorial Motion Graphics (first, recommended) / Stickman Cartoon (generic webcomic formula) |
fast, rapid cuts |
casual 2nd-person, deadpan, hook + promise |
| Picture Story |
Narrated STILLS (${FACELESS_MODES_DIR}/references/picture-flow.md): Flat 2D Papercraft (recommended) / Stickman / Hand-drawn Ink — one continuous narration drives a dense Whisper-timed microframe sequence |
set by the audio timeline |
free (kids-warm, history-witty, deadpan slice-of-life — tone follows the topic) |
| Fairy Tale & Myth |
Cinematic Storybook (${FACELESS_STYLES_DIR}/references/style-cinematic-storybook.md): lush hand-painted 2D-animation fairytale look, ANIMATED ON TWOS (--stepped 12); optional book-spread inserts |
slower, atmospheric; 2–3 min default (12–18 blocks); 5 ~2s cuts per block |
enchanting storyteller — hushed, warm, mysterious, unhurried, mythic (no jokes); MANDATORY mysterious-calm music bed |
Editorial Motion Graphics is the flagship house style — the default for BOTH
History and Explainer, pinned in ${FACELESS_STYLES_DIR}/references/style-editorial-collage.md (STYLE
FORMULA, palette lock, {MOTION} mapping, asset guidance) — no preset id, no
picker needed. Alternates stay one chip away: Paper Diorama (History's named
alternate — geopolitics/money/power or a "cinematic" ask;
${FACELESS_STYLES_DIR}/references/style-paper-diorama.md), 3D Papercraft (History) via the preset
widget, and on Explainer the second MAIN direction Stickman Cartoon —
described GENERICALLY in every prompt ("crude paint-program webcomic: thin wobbly
black outlines, flat solid fills, egg-head dot-eye stick figures, plain
flat-color backgrounds") and never naming a real comic/brand/IP.
PIPELINE (Phases 0→7, in order)
Resolve FACELESS_SKILL_DIR and the three reference aliases from rule 23 before
reading bundled Markdown. Every executable command uses the sandbox-provided
$HF_WORKFLOWS; never resolve a local scripts directory.
PICTURE STORY runs use this same pipeline with the deltas in
${FACELESS_MODES_DIR}/references/picture-flow.md: voice is one continuous narration generated
BEFORE the final frames; Whisper word timestamps create a dense ~0.7–1.2s
microframe timeline, and Phase 6 uses ${HF_WORKFLOWS}/faceless-video/scripts/assemble_slides.sh inside sandbox_exec (never
assemble_final.sh, never minimax_h3 — nothing is animated). Rules 2/21/22
(10s blocks, cuts, freeze probes) do not apply there; every other GOLDEN RULE does.
Its review order is necessarily AUDIO → IMAGES and it has no video checkpoint.
OpenAI batch generation + stage review contract
Use this contract for workflow stages. A direct, single user-facing generation uses
the ordinary generate_image, generate_video, or generate_audio tool so its widget
can render immediately. Batch tools are for two or more independent jobs, or for one
internal/headless dependency (such as a style key) that must stay hidden until its
stage gallery. Multiple variants of the SAME prompt use the ordinary tool's count
instead of a batch. Batch tools never improve quality or cost by themselves.
- Submit independent workflow work with
generate_image_batch,
generate_video_batch, or generate_audio_batch. Every request is
{index, params}, every index is a stable non-negative script/asset number,
and every params.count is 1. Indices are unique across the ENTIRE media
stage and never reset when a new submission group starts. A call carries 1–6
requests.
- BATCH-WAVE LAW: for more than six ready items, precompute the complete logical
wave, split it into the minimum number of groups of at most six, and submit every
group before the first wait. Then wait each accepted group. If a later group hits
the workspace concurrency limit, finish accepted jobs and retry only its rejected
indices at the reported smaller size. A real dependency starts a new wave; array
length alone does not.
- Persist successful
{index, job_id} pairs immediately. Never pass a
submission_failed item without a job_id to jobs_wait. If submission
fails with a concurrent-job/rate-limit error, finish the active group and retry
only the rejected indices in a smaller later group. Honor a reported
concurrent_jobs_limit as the next group size.
- Call
jobs_wait with the current group's pairs and
timeout_seconds:15. If all_terminal:false, wait
poll_after_seconds, then call it again only for active jobs and retryable
lookup_failed jobs. Freeze completed indices. The 15 seconds are a per-call
long-poll budget, not the total wait; repeat until terminal. If a group shows
no status change for 20 minutes, stop and surface its pending indices/job ids
instead of looping silently. A permanent lookup failure is terminal for that
attempt and enters the normal retry/failure ladder.
- Do not call
show_generation_by_ids, show_generations, job_display, or
job_status while the stage is running. The batch tools and jobs_wait are
intentionally headless. Never use history-based show_generations for a
batch stage.
- After the ENTIRE media stage and its bounded retries are complete, build the
final ledger with exactly one
completed {index, job_id} per stage item.
A successful retry replaces the failed job id at that same index. Sort the
ledger by index, then interactive runs call show_generation_by_ids with
those exact pairs. For 1–24 items call it once; the widget paginates locally
in groups of 12. Only stages larger than 24 use consecutive display groups
of at most 24. Never pass history arguments such as type, size, or
cursor.
- In interactive mode, immediately render one
ask_user_input review question
after that list and END THE TURN:
- images: “The images are ready. Continue to video?”
- videos: “The videos are ready. Continue to voiceover?” (SONG MODE:
“The videos are ready. Assemble the final video?”)
- audios: “The voiceover is ready. Assemble the final video?”
Use two options:
Continue (recommended) and Stop here. Localize the text
to the user's language and use the same callable/raw GenUI fallback mechanism
defined in Phase 0. Never start the next media stage in the turn that displays
this question.
- Explicit hands-off/auto runs skip both
show_generation_by_ids and the review question, then continue automatically
after the stage is terminal. They use headless batches throughout.
The standard animated route therefore reviews IMAGES → VIDEOS → AUDIOS.
Dependencies override presentation order only in documented special modes:
Picture Story reviews AUDIO → IMAGES; SONG MODE reviews the song/audio before
the videos choreographed to it and has no narrator stage.
Phase 0 — Intake and platform dispatch
Read ${FACELESS_FLOW_DIR}/references/intake-and-dispatch.md completely before starting Phase 0 and follow it exactly. Return here at Phase 1 after its gate passes.
Phase 1 — Style anchor
Get ONE look anchor, by the path chosen in Phase 0:
- Authoritative reference images (headless CMS preset or upload) → import every
style_reference_url, then make ONE seedream_v5_pro style SAMPLE with
resolution:"1k" using all imported
images and the verbatim style-only prefix from ${FACELESS_STYLES_DIR}/references/prompts.md §1. Write the
80–100-word locked formula from the donors' visible line/surface work, shading,
palette, background treatment and motion implication only; paste it byte-identical in
every later prompt. Ignore any accompanying preset id and do not open a house-style
file. Keep the new style-key job_id as the sole Phase-2 look anchor. The imported
donor medias are IMMUTABLE across the complete retry ladder: every retry carries
the same donor media ids. If all donor-bound retries fail, report
STYLE_ANCHOR_FAILED; generating a prompt-only key or silently dropping the donors is
forbidden.
- House style (Editorial Motion Graphics — default for History & Explainer; Paper
Diorama when picked; Stickman via the generic §0 formula) →
open the style's reference file, take its STYLE FORMULA verbatim (Editorial and
Paper Diorama: first LOCK the one {ACCENT} color per the style file and write it into
the formula + PALETTE LOCK; Mannequin: import its canonical ref URLs for the key and
generate the LOCKED CAST with the identity chain per the style file), and generate the
look anchor with
seedream_v5_pro (aspect_ratio = chosen aspect,
resolution:"1k") as a pretty, readable style SAMPLE (§1 template with the
formula), attaching the card's resolved media_id and every canonical donor from
its style file as medias with role image. Keep its job_id — that is the
anchor for every Phase-2 asset. A pinned house style needs no STYLE-LOCK approval
round (record the key without a separate widget and move on). If the render visibly
missed the formula (wrong palette / photoreal drift), use the bounded retry ladder;
do not open a separate approval gate.
- Named preset without reference URLs (interactive flow only) → map the name to its
style file and pinned canonical refs from Phase 0. A card with NO style file (legacy
explainer cards) →
resolve_faceless_channel_preset → use the returned media_id as the look
anchor and derive the locked formula from its visible traits.
- Custom (uploaded images / free description) → generate ONE pretty, readable style
SAMPLE with
seedream_v5_pro (aspect_ratio = chosen aspect,
resolution:"1k"): a small representative
vignette — one simple recognizable subject rendered so the line weight, shading and
colours read at a glance — NOT formless blobs. Never draw a palette strip, colour
chips, swatch bar, labels or a reference-sheet layout: the style key is attached to
every later asset and block, so anything drawn into it can propagate into the video.
Add all of those elements to this call's negative prompt. Keep its job_id. For uploads use the verbatim style-only prefix in
${FACELESS_STYLES_DIR}/references/prompts.md §1. Record it (STYLE LOCK notification only; do not
render a separate widget — it appears in the final image-stage list) and tell the
user plainly: "this style sample can
look a little odd — that's normal, it's only a look reference, not a final frame."
For every newly generated style key, use a one-request generate_image_batch
call with stable index:0, then jobs_wait; it stays headless because the key
is an internal dependency, not a separate review. Keep it in the later image-stage
display ledger; reserve asset indices 1..N so the final ledger stays unique.
GATE 1: a look anchor exists (preset media_id OR approved custom style_key_job_id).
Phase 2 — Asset roster (MANDATORY — characters, locations, props)
Tool: image (seedream_v5_pro, always resolution:"1k"). Pass the look anchor (preset style-reference
media_id OR custom style_key_job_id) as medias (role image). Embed the ONE style
formula BYTE-IDENTICAL in every asset prompt (this is the entire consistency mechanism).
Generate one image per asset through the grouped batch requests below:
- Characters —
aspect_ratio 2:3: full body, plain flat backdrop, distinctive readable design.
Long-form History: one variant PER ERA the character appears in (identity
invariants verbatim in every variant prompt + the era's aging/costume changes;
henry_young / henry_old). Later era variants ALWAYS attach the character's
FIRST incarnation as an image reference ("the SAME person as in the reference,
now {aged/changed}") — never from the style ref alone; see the IDENTITY CHAIN in
${FACELESS_MODES_DIR}/references/history-longform.md.
- Locations — MULTIPLE, not one (
aspect_ratio = chosen aspect): a real DRESSED
environment with one named anchor object, NO people. Generate enough distinct
locations that no single one carries more than ~2 CONSECUTIVE blocks (a location may
return later in the video; a 2-min / 12-block video wants ~4–6 locations). For each location also generate 1–2 coverage angles
(reverse / lateral / detail crop) so blocks in the same place aren't the identical plate.
- Props —
aspect_ratio 1:1: single isolated object, no hands/scene.
- Variety inserts (optional, esp. Kids): a subject on a clean solid color card, a
pop-up diagram, an anthropomorphized object with a face — for cutaway shots.
Generate the roster through
generate_image_batch in sequential groups of at
most six. Keep one stable asset index through retries; wait each group with
jobs_wait and save (index, job_id) per asset + coverage view. After every
image is completed, interactive mode displays the exact final image ledger with
show_generation_by_ids, renders the IMAGE review question, and ends the turn; continue
to Phase 3 only after Continue. Picture Story exception: its Phase-2
assets are internal dependencies, so defer the single IMAGE list/review until
all final timeline frames are complete. In auto/headless mode post the full
roster (ASSET LOCK) and continue without the list.
GATE 2: every character + location + prop the script needs has a completed,
approved asset. Do NOT enter Phase 4 with a missing asset (that beat would drift).
Prompt templates → ${FACELESS_STYLES_DIR}/references/prompts.md §2.
Phase 3 — Script + block plan
Read ${FACELESS_STYLES_DIR}/references/prompts.md § Scriptwriter first — it is not optional: pick the
through-line (one physical object that appears in every block, escalates
monotonically, resolves in the payoff — and gets its own Phase-2 prop asset so it
never morphs), research factual topics to its target list (hook stat · 3–5 concretes ·
the counterintuitive turn; Sources line kept), and run its rewrite pass before showing
anything.
Long-form History runs FIRST do OUTLINE LOCK (${FACELESS_MODES_DIR}/references/history-longform.md) as
a notification that posts and proceeds:
chapter outline + ERA MAP (characters×eras asset math, shown with the roster count) +
through-line + vignettes — finalized BEFORE any asset generation; then the standard flow
below per chapter (assets may be generated era-by-era alongside chapters).
Write the story as N blocks. Each block = 10s = FIVE hard-cut shots, ~2s each
(Kids: FOUR — the kids-styles.md interplay pattern, order varied every block). Kids scripts are built on the
MANDATORY interplay: the narrator addresses characters and the viewer by name, the
shots stage the visible reactions (wave/nod/look-to-camera), questions sit at the END
of a line so the block boundary is the answer beat and the next block opens with the
payoff. Build an arc
(hook → build → turn → payoff): cold-open hook stated flat and SHORT — block 1 opens
on a ≤8-word punchy line, then fills to normal density (History/Explainer — no
greetings, no throat-clearing; Kids keeps its warm host manner), ONE idea per block
(the shots are angles on it), build blocks escalating (if they can be
reordered without loss, rewrite), a turn that surprises rather than summarizes, a
payoff whose kicker reframes the hook. Humor = deadpan setup → absurd
punch, Barnum lines, confirmation-bias gags.
Shot-variety rules (enforce per block — this is what stops the "samey" problem):
- EVERY shot in a block differs in SIZE and ANGLE from its neighbours (e.g. MEDIUM →
CU → OTS → low WIDE → ECU). Only the FIRST block of a new location may open on a
full establishing WIDE — later blocks in the same location must NOT re-establish; open
on a fresh close/medium/coverage angle.
- OTS requires a named visible character whose shoulder/head is intentionally in the
foreground. If the shot's subject list has no character (object, diagram, empty
location), OTS is invalid and must be replaced before Phase 4.
- ≤2 consecutive blocks per location. Then change: next location, a coverage angle,
or a variety insert. Plan the location rotation up front so no place repeats back-to-back
for long. Kids especially: rotate locations + drop in object-with-face / diagram inserts.
- Vary the character's distance and screen position; don't reset to the opening framing.
For each block write: the shots (size+angle each) + which assets/location/coverage appear
(≤7 refs per block — plan the roster so no block needs more; rule of Phase 4)
- one VO line. Save the canonical machine-readable version to
script_manifest.json using this exact shape:
{topic,genre,animation_mode:"fully_animated",channel_type,style,through_line:{name,asset,progression,resolution}, arc:{hook,build:[...],turn,payoff},blocks:[{n,arc_role,vo_line,location, through_line_state,shots,assets_used}],sources:[absolute research URLs]}.
Map genre deterministically: Explainer → education, History → history, Kids
→ kids, Fairy Tale & Myth → storytelling. Do not put the display label into
the validator field.
Every assets_used array includes through_line.asset; source labels without URLs are
invalid. vo_line contains ONLY the authored words spoken by the narrator — never put
delivery brackets or [00:00-00:09] timecodes in the manifest. Construct that wrapper
only when making the corresponding Phase-5 TTS call. Lock NARRATION_LANGUAGE here as
the two-letter language code inferred from the actual authored vo_line / phrase text
(en, ru, es, …), never from the topic or a hard-coded default. Pass that same
literal to take verification, assembly and captions; update it before any new audio call
if the authored language changes. For videos ≥60s run
SCRIPT LOCK as a notification: post the FULL
script IN CHAT (every block: VO line + shots + location; plus the through-line named in
one sentence and each block's arc role) and PROCEED in the same turn — no
approve/tweak question in any mode; the user replies only if they want changes. Never
claim a script was approved that the user hasn't been shown.
Picture Story runs the FRAME-BY-FRAME model — ${FACELESS_MODES_DIR}/references/picture-flow.md is the
source of truth (ONE continuous narration → Whisper timeline → frames; NOT per-beat
takes). Write the frame plan to script_manifest.json before any audio, then run the
SCRIPT gate:
sandbox_exec({
command:"python3 ${HF_WORKFLOWS}/faceless-video/scripts/validate_picture_story.py --script script_manifest.json --duration-seconds {requested_seconds}"
})
Exit code 1 BLOCKS Phase 5. Every frame entry declares image_mode:"new"|"variation";
The top-level manifest uses genre and animation_mode:"scene_based".
Variations also declare variation_of = the immediately previous frame and one concise
change_only detail. ~2 of every 3 frames must be variation — and a variation
is a literal EDIT of the previous rendered frame (that frame's job_id as the ONLY
image reference, NO asset sheets/location/props on the call), not a fresh render from
assets. Sending assets on a variation rebuilds the scene and produces a different
picture — the #1 picture-story bug. Full KIND-A/KIND-B recipe in
${FACELESS_MODES_DIR}/references/picture-flow.md Phase 4. Rewrite only the invalid_beats reported,
rerun until valid:true. Final delivery may enrich this already-validated manifest with
durable frame URLs, but never rewrites its phrases or ordering.
Motion-video hard gate: for Explainer, History and Kids, run:
sandbox_exec({
command:"python3 ${HF_WORKFLOWS}/faceless-video/scripts/validate_motion_script.py --script script_manifest.json --duration-seconds {requested_seconds}"
})
Exit code 1 BLOCKS every later generation phase. Rewrite only the fields listed in
invalid_blocks/errors, then rerun until valid:true. This deterministically enforces
the exact block count, the per-full-10s-line word budget (proportional for a short last
block), structured through-line/arc, per-block through-line state, shot/ref limits,
absolute source URLs and ≤2 consecutive blocks per location. It also writes
script.lock; assembly verifies that lock so edited narration cannot silently reach
the cut. Never generate clips or voice from a script that has not passed this command.
Initial validation enforces 20–23 words per full 10s line and 17–21 for Kids.
After measured overlong speech, --duration-retry-blocks permits 17–19 words only
for those full blocks (proportional for a short final block); it never relaxes
unmeasured blocks. The validator also enforces at most two sentences, digit-free narration, and these
non-negotiable gates: no verbatim phrase of five or more words shared by two blocks;
framing size on every shot with adjacent sizes different; no re-establishing a visited
location; OTS only over a named visible shoulder; no repeated eight-word shot
description; no two blocks with the same location plus same ordered assets; and for
Explainer/History a cold open of at most eight words before its first full stop.
For a Kids Talking Characters run, read
${FACELESS_MODES_DIR}/references/kids-talking-characters.md before writing. Add
top-level talking_characters:true; alternate block_kind:"narration"|"dialogue"
starting with narration. Narration blocks keep vo_line at 17–21 words. Dialogue
blocks carry 16–22 words total across at most two named speakers and use the generated
clip audio rather than a narrator take. SONG MODE never sets this flag.
GATE 3: N blocks, each with 5 varied shots (Kids: 4) + assets + a VO line; through-line present
in every block and resolved in the payoff; rewrite pass done; location rotation
respects ≤2 blocks/place; no block after the first in a place re-opens on the establishing WIDE.
Phases 4–8b — Generate, narrate, assemble, subtitle, cover, and deliver
After Gate 3 passes, read ${FACELESS_FLOW_DIR}/references/generation-and-delivery.md completely and follow Phases 4–8b exactly before using the retry ladder and final QC below.
RETRY LADDER (use on every nsfw/failed image or clip)
- Resubmit the SAME prompt — attempt 2, then attempt 3. Change
seed only
if the live model schema declares it; never invent a seed field for H3.
- Still failing → reword: remove risky tokens (
child/kid/childlike, tight
animal-face close-ups, aggressive/intimate poses); resubmit up to 2 more times.
- Still failing → change that beat's framing (different shot size / staging).
- NEVER drop the block, NEVER leave a gap, NEVER substitute a neighbouring block.
- Budget cap: if ONE block is still failing after ~8 total attempts, STOP and surface
it to the user (which beat, what was tried) instead of burning credits in a loop.
- References are immutable. Every retry keeps the exact same ordered
medias as
the failed call. Reword prompt text or framing only. Never turn a reference-bound
style key, asset, frame, or clip into text-to-image/text-to-video to get around
moderation. For a donor-bound style key, exhaustion is STYLE_ANCHOR_FAILED.
(A preset recommendation is not a failure — resubmit with declined_preset_id per rule 5.)
FINAL QC CHECKLIST (before delivering)
…(truncated)
1---2name: faceless-video3description: |4 Use only when the user asks to produce a finished multi-scene narrator-led5 video and explicitly requests a faceless channel, YouTube automation, narrated6 explainer/story/education, documentary, Picture Story, narrated stills,7 frame-by-frame story, storybook or myth retelling, or kids song video. Topic alone is never enough: a generic video of/about something,8 including a historical topic, uses ordinary video generation. Do not use for9 browsing or listing faceless presets: call get_faceless_channel_presets directly10 without loading this skill. Also exclude planning or ideas, single clips, silent animation, image-to-video, footage11 edits, ads, product demos, UGC, or any video with a visible on-camera presenter12 or talking head. This workflow requires a consistent13 non-photoreal style, reusable assets, narrator voiceover, and burned subtitles.14metadata:15 source: https://skillmd.com/skills/jhamidun/faceless-video16---1718# faceless-video1920The channel factory for faceless, narrator-led video: five channel types on one21motion pipeline (plus a stills pipeline and a song mode), any non-photoreal look,22one voiceover, one finished file. Voice → the `narrator` skill; captions → the23`subtitles` skill; a selected cover → the `thumbnail-generation` skill.2425In a hands-off run, an unanswered cover choice locks to `thumbnail: yes`. A request26for exactly one finished MP4 constrains the video deliverable only; it is not a cover27decline. Lock `thumbnail: no` only when the user explicitly declines a thumbnail or cover.2829> HOW TO READ THIS FILE: execute the Phases 0→8b IN ORDER. Do not skip a phase, do not30> reorder. Each phase has a **GATE** you must satisfy before the next. Long templates31> live in the resolved helper skills — open them when the phase says so. Obey32> every GOLDEN RULE.3334---3536## RUNTIME CONTRACT — Higgsfield sandbox only3738`sandbox_exec` is required for every download, probe, validator, audio39measurement, assembly, transcription, caption burn, and upload PUT. Never run40these commands in a client-local or built-in shell.4142- Before any paid generation, verify that `sandbox_exec`, `media_upload`, and43 `media_confirm` are callable. If the direct upload pair is unavailable, stop:44 `media_upload_and_confirm` cannot export a file that exists only in the45 sandbox.46- Preflight once in Phase 0:47 ```48 sandbox_exec({49 restart:true,50 command:"set -e; for b in ffmpeg ffprobe python3 curl jq awk; do command -v \"$b\" >/dev/null; done; test -n \"$HF_WORKFLOWS\"; test -r \"$HF_WORKFLOWS/faceless-video/scripts/finish_video.sh\"; mkdir -p work/{blocks,voices,frames,output}"51 })52 ```53 Before a narrated motion run, check `python3 -c 'import faster_whisper'` and retry54 once. When available, Gate 5 must verify what every take says regardless of the55 subtitle toggle. If it is still unavailable, record the degraded route before paid56 generation: treat subtitles as off, pass `--allow-unverified-audio` to the one57 `finish_video.sh` call, and disclose that the delivered clean cut's take content could58 not be transcribed for verification. Never use that flag when the import succeeds,59 and never claim the audio-content gate passed. Any other failed preflight blocks the60 run.61- Faceless validators, both assemblers, and `finish_video.sh` are preinstalled at62 `${HF_WORKFLOWS}/faceless-video/scripts/`. Narration helpers live at63 `${HF_WORKFLOWS}/narrator/scripts/`, and caption helpers at64 `${HF_WORKFLOWS}/subtitles/scripts/`. Pass these paths verbatim inside65 `sandbox_exec`; never paste, copy, or execute a helper skill's local `scripts/` copy.66- The sandbox is ephemeral. Keep each command self-contained and idempotent:67 re-download missing inputs behind `[ -s file ] || curl …`, run the script,68 verify outputs, and export the deliverable before the sandbox expires.69- Use `background:true` for assembly/captioning and poll the returned70 `log_path` immediately with the next `sandbox_exec` call. Never start a71 duplicate process while the first is alive.72- Preserve deterministic manifest order (`block01`, `voice01`, `frame001`);73 never infer order from `ls` or job completion order.74- `media_upload_and_confirm` is only for files attached by the ChatGPT user; it75 cannot read a sandbox path. To export a sandbox-created deliverable, call76 `media_upload` first, then append `curl -f -X PUT --upload-file …` to the SAME77 `sandbox_exec` command that creates the file. Call `media_confirm` only after78 that command reports HTTP 200. Deliver only the confirmed hosted URL.7980---8182## GOLDEN RULES (read first — violating any of these breaks the video)8384Before intake, resolve a structured `animation_mode` when present:85`fully_animated` means `motion_mode:animated`; `scene_based` means86`motion_mode:stills`. Record the resolved mode and skip the motion-mode question.87This mapping is transport-independent and a supplied `scene_based` value must never88fall back to Animated.8990Before any voice lock, resolve Kids sound intent from the complete request, including91`channel_subject`, topic, and supplied script. An explicit kids song, nursery song,92sing-along, sung/music video, or local-language equivalent locks **SONG MODE**. In that93mode supplied `voice_id`, `voice_type`, or `voice_name` is inert metadata: ignore it,94never create `voice.lock`, and follow `references/kids-song.md`. Background music or a95soundtrack alone is not song intent; keep narration and add the normal instrumental bed.96971. **Models are LOCKED. Never substitute.** Assets/style key → `seedream_v5_pro`98 (image), always with `resolution:"1k"`.99 Clips → `minimax_h3` at `resolution:"2K"` (video). Fixed-window narration → `text2speech_v2` with100 `variant:"elevenlabs"`; `seed_audio` stays only for Kids song and Picture Story's101 continuous read. Music bed (when one is102 due: Kids default, Fairy Tale & Myth default, or the user asked) → submit it103 through `generate_audio_batch` with `model:"sonilo_music"`, no voice id, and the exact video104 duration; instrumental only (mood by channel: Kids playful, Fairy Tale &105 Myth mysterious-calm — `${FACELESS_STYLES_DIR}/references/kids-styles.md §Kids music bed`,106 `${FACELESS_STYLES_DIR}/references/style-cinematic-storybook.md §Music`). No other model, ever.1072. **Every clip is ONE 10s shot-group of FIVE hard-cut shots (~2s each)** written into108 a single prompt (see Phase 4) — NO shot longer than 2.5s: a frame that hangs 3–5s109 reads as a slideshow. **Kids blocks use the FOUR-cut interplay pattern (2.5s)**110 (`${FACELESS_STYLES_DIR}/references/kids-styles.md`). Degradation on generation failure: a block that111 fails twice at its cut count drops ONE cut (5→4; Kids 4→3) — never the whole video.112 One `minimax_h3` call = one 10s block. Do NOT make separate clips per cut.113 **COUNT THE CUTS THAT CAME BACK — the model under-delivers.** Probe each completed114 block with the preinstalled `ffprobe` scene detector:115 ```116 ffprobe -v error -select_streams v:0 -show_entries frame=pkt_pts_time \117 -of csv=p=0 -f lavfi "movie=blockNN.mp4,select=gt(scene\,0.3)" | wc -l118 ```119 A block with fewer cuts than asked, or any shot at least 3s long, is regenerated120 ONCE with every cut spelled out shot by shot. For flat looks (Editorial, Paper121 Diorama, Pastel Flat 2D, Poster Vector, Stickman), re-measure at `scene,0.15` and122 treat a low count as a suspicion: inspect the block before spending a retry. If123 the second attempt still under-delivers, keep it and say which blocks are slow.124 Degradation after generation failure remains automatic: 5→4; Kids 4→3.1253. **Compose from the approved assets.** Every clip references the Phase-2 asset images126 (`medias`, role `image`), in the order **location → characters → props**. NEVER127 generate a clip/still from the style key alone. Frames are full staged scenes, never128 an object on a blank/white background.1294. **Pass `aspect_ratio` EXPLICITLY on every video call** (the chosen aspect; default130 `16:9`). It does NOT inherit from the style key.1315. **Preset-recommender handling:** a `minimax_h3` call (usually the first) may return a132 preset RECOMMENDATION instead of a job. Immediately resubmit the SAME call with133 `declined_preset_id` = that recommended preset's id (taken from the response). Never134 ask the user about it, never stop on a recommendation.1356. **NSFW is a ~50% probabilistic false-positive.** Use the RETRY LADDER (see below) —136 resubmit, then reword; change `seed` only when the live model schema declares it. NEVER drop a block, NEVER deliver a gap.1377. **Characters never talk on screen** (no lip-sync). The voice is an external narrator138 added in post. Prompts say "characters only emote and gesture, they do NOT talk."139 Kids characters visibly react to the narrator through gestures only. **The one140 exception is a Kids run with `talking_characters:true`**: odd blocks keep the external141 narrator and closed mouths; even blocks contain cast dialogue and use the clip's own142 lip-synced audio. Read `references/kids-talking-characters.md` for that branch.1438. **Subtitle timing comes ONLY from Whisper on the final audio.** Never estimate from144 the script, never time-by-generating-per-phrase.1459. **Assembly fps = source fps** (probe `r_frame_rate`); never hardcode 30.14610. **Banned in prompts:** the tokens `child` / `kid` / `childlike` (use `naive` /147 `small` / `simple`); any real brand / studio / IP name (describe the look instead).14811. **Never expose mechanics to the user** — no model names, phase names, or studio149 names in chat, and no third-party brand/studio names inside `ask_user_input`150 texts either. The user sees only creative substance + the approval gates.15112. **Wait every job to a terminal state.** For OpenAI batch submissions use152 `jobs_wait` on the returned `{index, job_id}` pairs; `completed` = good,153 `failed`/`nsfw` = retry. Do not proceed on a non-`completed` job.15413. **Deliver ONE whole video file** (`final.mp4`). Concatenate ALL blocks + VO (+ subs)155 into a single file. NEVER split the output into `part1`/`part2` or hand back separate156 clips — the deliverable is exactly one video.15714. **Throughput: bulk media uses the headless batch tools.** Submit independent158 images, video blocks, and narration takes in ordered groups of at most SIX, then159 wait for that group together with `jobs_wait`. Never fan out parallel singleton160 `generate_*` calls in an OpenAI run.16115. **Duration is FIXED = N×10s (the target). NEVER shorten the video to fit short audio**162 (the "2:00 → 1:35" bug). Each block stays 10s. Write one dense voice line that163 naturally fills most of each block, then let the assembler center its detected164 speech. After each narrated motion wave, run165 `${HF_WORKFLOWS}/faceless-video/scripts/measure_narration_takes.py --script script_manifest.json --voice-dir work/voices --duration-seconds {requested_seconds}`166 in the same call that materializes the takes. It binds exact text to numbered167 files and returns the retry set. Measured overlong blocks alone may shorten168 below the authoring floor via `validate_motion_script.py --duration-retry-blocks N,...`.169 Keep the cumulative measured block set on revalidation; never lower every line's floor.170 Never trim the video to fit a take.17116. **Sync is by construction:** one line lives inside its own 10s block, so a line never172 bleeds into the next scene. **Never `atempo`/speed-change/pitch-shift** audio to fit —173 rewrite + regenerate instead.17417. **ONE voice everywhere.** Every audio chunk uses the SAME `voice_id` + `voice_type`175 (the one locked at intake). Never let chunks come out in different voices.17618. **NO time-stretching in post.** Never `atempo`/speed-up/slow-down/pitch-shift the177 audio to fit. If length is wrong, REWRITE + regenerate the beat. (`speech_rate` also178 untouched unless the user asks.)17919. **Style fidelity — clips MUST match the asset sheets 1:1.** Same character design,180 same palette, **same background treatment** (if assets are white/clean-bg webcomic,181 the video stays white/clean-bg webcomic). ONE consistent style across the whole video182 — no per-shot restyle, no object drift, no style scatter.18320. **Captions are compact (if on):** ≤5 words / ≤32 chars, bottom ~12%, NEVER184 covering the subject or filling the frame. Clean CAPS + outline, no plate. Three-word185 captions flicker too quickly and must not be forced through a smaller override.18621. **No leading freeze.** Every block prompt demands motion from frame 1; the assembler187 adds no head padding and WARNS when a block's opening looks static — on that warning188 REGENERATE the block (never ship a still that "starts playing" a second later).18922. **No samey footage.** Vary shot SIZE and ANGLE on EVERY cut (WIDE / MEDIUM / CU / OTS190 / low / high) — do NOT reopen every block on the same establishing WIDE. **OTS is191 legal ONLY when a named on-screen character's shoulder/head is deliberately visible192 in the foreground.** For an object-only, diagram, empty-location, or otherwise193 characterless shot, OTS is FORBIDDEN — use overhead/top-down, low/high angle, macro,194 lateral, or another coverage angle instead. Never use OTS as a synonym for an angled195 view; it makes the video model invent a person. **Max ~20s196 (≈2 blocks) per location/distance**, then move (new location / coverage angle / variety197 insert). Rotate locations; never park the character back at the opening wide.19823. **Voice and subtitles are DELEGATED to installed skills; reference199 instructions are bundled into this skill. All executable work runs in200 `sandbox_exec`.** Phase 5 invokes `narrator`; Phase 7 invokes `subtitles`.201 Before Phase 0 resolve the directory containing this `SKILL.md` as202 `FACELESS_SKILL_DIR`, then set `FACELESS_FLOW_DIR`,203 `FACELESS_STYLES_DIR`, and `FACELESS_MODES_DIR` to that same directory.204 Their documents are all under `${FACELESS_SKILL_DIR}/references/`.205 Executable scripts always206 come from `${HF_WORKFLOWS}/faceless-video/scripts/` inside the207 Higgsfield sandbox. For ordinary motion-video runs use208 `finish_video.sh` (internally `assemble_final.sh`); Picture Story uses its209 `--stills` route (internally `assemble_slides.sh`). These FFmpeg scripts are210 the canonical assembly paths, not fallbacks. Never call `explainer_video` merely to211 stitch completed clips and narration. Never hand-roll another FFmpeg path around212 the scripts; if an assembler errors, fix the inputs and rerun it.21324. **Generation widgets are stage summaries, never progress indicators.** Batch214 submission and waiting stay headless. Persist every `{index, job_id}` immediately215 and trust `jobs_wait`, not widget chrome. After the complete media stage is216 terminal, display its exact final ledger with `show_generation_by_ids`; never217 browse history with `show_generations`.21825. **Narration target is 7.8–9.5s of speech per full 10s block.** The narrator219 measures speech and rate rather than padded file length, requires `rate=ok`,220 rewrites out-of-window or rushed lines,221 and allows at most three attempts per line, with changed text before a third.222 Accept 7.2–7.8s only after one retry; hard reject outside 7.2–9.5s. Stop with223 `AUDIO_GEN_FAILED` and the exact slot/metrics when a take still fails; never224 ship the closest failed take or time-stretch it.225226---227228## Types & format229230Output = **ONE video file**: a motion-clip montage for Explainer / History / Kids, or231narrated STILLS for the Picture Story direction (`${FACELESS_MODES_DIR}/references/picture-flow.md`).232Kids additionally has **Talking Characters** — alternating narrated and cast-dialogue233blocks (`references/kids-talking-characters.md`) — and **SONG MODE**, a music video built on a real sung children's234song (`${FACELESS_MODES_DIR}/references/kids-song.md`: song generated FIRST via `seed_audio` prompt-only,235blocks choreographed to it, assembly via the assembler's `--song` mode; no narrator,236no bed, no subtitles). These two Kids sound modes are mutually exclusive. Standalone image deliverables (slide decks, image sets)237remain REMOVED — every direction ships a single video.238239| Channel type | Default style | Pacing | VO tone |240|---|---|---|---|241| **Kids** | **Baked-in Kids set** (`${FACELESS_STYLES_DIR}/references/kids-styles.md`, Studio 3D recommended; Fluffy Toy via preset widget) | FAST — 4 cuts per block (WIDE → CU character → ECU detail → MEDIUM), varied every block | warm teacher, direct address, catchphrases; **the QUESTION-FIRST skeleton and picture-storytelling in `kids-styles.md` are MANDATORY**, as is narrator↔character↔viewer interplay |242| **History** | **Editorial Motion Graphics** (house style — `${FACELESS_STYLES_DIR}/references/style-editorial-collage.md`); named alternates: **Paper Diorama** (`${FACELESS_STYLES_DIR}/references/style-paper-diorama.md`), **Mannequin** (`${FACELESS_STYLES_DIR}/references/style-mannequin.md`); LONG-FORM direction: **Documentary 10+ min, Watercolor Chronicle** (`${FACELESS_MODES_DIR}/references/history-longform.md`) | slower, chronological (long-form: cold open → rewind → chapters) | witty, sarcastic, anachronistic storyteller (Mannequin: dry British; long-form: measured documentary narrator) |243| **Explainer** | TWO main directions, offer both: **Editorial Motion Graphics** (first, recommended) / **Stickman Cartoon** (generic webcomic formula) | fast, rapid cuts | casual 2nd-person, deadpan, hook + promise |244| **Picture Story** | Narrated STILLS (`${FACELESS_MODES_DIR}/references/picture-flow.md`): **Flat 2D Papercraft (recommended)** / Stickman / Hand-drawn Ink — one continuous narration drives a dense Whisper-timed microframe sequence | set by the audio timeline | free (kids-warm, history-witty, deadpan slice-of-life — tone follows the topic) |245| **Fairy Tale & Myth** | **Cinematic Storybook** (`${FACELESS_STYLES_DIR}/references/style-cinematic-storybook.md`): lush hand-painted 2D-animation fairytale look, ANIMATED ON TWOS (`--stepped 12`); optional book-spread inserts | slower, atmospheric; 2–3 min default (12–18 blocks); 5 ~2s cuts per block | enchanting storyteller — hushed, warm, mysterious, unhurried, mythic (no jokes); MANDATORY mysterious-calm music bed |246247**Editorial Motion Graphics is the flagship house style** — the default for BOTH248History and Explainer, pinned in `${FACELESS_STYLES_DIR}/references/style-editorial-collage.md` (STYLE249FORMULA, palette lock, {MOTION} mapping, asset guidance) — no preset id, no250picker needed. Alternates stay one chip away: **Paper Diorama** (History's named251alternate — geopolitics/money/power or a "cinematic" ask;252`${FACELESS_STYLES_DIR}/references/style-paper-diorama.md`), **3D Papercraft** (History) via the preset253widget, and on Explainer the second MAIN direction **Stickman Cartoon** —254described GENERICALLY in every prompt ("crude paint-program webcomic: thin wobbly255black outlines, flat solid fills, egg-head dot-eye stick figures, plain256flat-color backgrounds") and **never naming a real comic/brand/IP**.257258---259260## PIPELINE (Phases 0→7, in order)261262Resolve `FACELESS_SKILL_DIR` and the three reference aliases from rule 23 before263reading bundled Markdown. Every executable command uses the sandbox-provided264`$HF_WORKFLOWS`; never resolve a local scripts directory.265266> **PICTURE STORY runs use this same pipeline with the deltas in267> `${FACELESS_MODES_DIR}/references/picture-flow.md`:** voice is one continuous narration generated268> BEFORE the final frames; Whisper word timestamps create a dense ~0.7–1.2s269> microframe timeline, and Phase 6 uses `${HF_WORKFLOWS}/faceless-video/scripts/assemble_slides.sh` inside `sandbox_exec` (never270> assemble_final.sh, never minimax_h3 — nothing is animated). Rules 2/21/22271> (10s blocks, cuts, freeze probes) do not apply there; every other GOLDEN RULE does.272> Its review order is necessarily AUDIO → IMAGES and it has no video checkpoint.273274### OpenAI batch generation + stage review contract275276Use this contract for workflow stages. A direct, single user-facing generation uses277the ordinary `generate_image`, `generate_video`, or `generate_audio` tool so its widget278can render immediately. Batch tools are for two or more independent jobs, or for one279internal/headless dependency (such as a style key) that must stay hidden until its280stage gallery. Multiple variants of the SAME prompt use the ordinary tool's `count`281instead of a batch. Batch tools never improve quality or cost by themselves.2822831. Submit independent workflow work with `generate_image_batch`,284 `generate_video_batch`, or `generate_audio_batch`. Every request is285 `{index, params}`, every `index` is a stable non-negative script/asset number,286 and every `params.count` is `1`. Indices are unique across the ENTIRE media287 stage and never reset when a new submission group starts. A call carries 1–6288 requests.2892. **BATCH-WAVE LAW:** for more than six ready items, precompute the complete logical290 wave, split it into the minimum number of groups of at most six, and submit every291 group before the first wait. Then wait each accepted group. If a later group hits292 the workspace concurrency limit, finish accepted jobs and retry only its rejected293 indices at the reported smaller size. A real dependency starts a new wave; array294 length alone does not.2953. Persist successful `{index, job_id}` pairs immediately. Never pass a296 `submission_failed` item without a `job_id` to `jobs_wait`. If submission297 fails with a concurrent-job/rate-limit error, finish the active group and retry298 only the rejected indices in a smaller later group. Honor a reported299 `concurrent_jobs_limit` as the next group size.3004. Call `jobs_wait` with the current group's pairs and301 `timeout_seconds:15`. If `all_terminal:false`, wait302 `poll_after_seconds`, then call it again only for active jobs and retryable303 `lookup_failed` jobs. Freeze completed indices. The 15 seconds are a per-call304 long-poll budget, not the total wait; repeat until terminal. If a group shows305 no status change for 20 minutes, stop and surface its pending indices/job ids306 instead of looping silently. A permanent lookup failure is terminal for that307 attempt and enters the normal retry/failure ladder.3085. Do not call `show_generation_by_ids`, `show_generations`, `job_display`, or309 `job_status` while the stage is running. The batch tools and `jobs_wait` are310 intentionally headless. Never use history-based `show_generations` for a311 batch stage.3126. After the ENTIRE media stage and its bounded retries are complete, build the313 final ledger with exactly one `completed` `{index, job_id}` per stage item.314 A successful retry replaces the failed job id at that same index. Sort the315 ledger by `index`, then interactive runs call `show_generation_by_ids` with316 those exact pairs. For 1–24 items call it once; the widget paginates locally317 in groups of 12. Only stages larger than 24 use consecutive display groups318 of at most 24. Never pass history arguments such as `type`, `size`, or319 `cursor`.3207. In interactive mode, immediately render one `ask_user_input` review question321 after that list and END THE TURN:322 - images: “The images are ready. Continue to video?”323 - videos: “The videos are ready. Continue to voiceover?” (SONG MODE:324 “The videos are ready. Assemble the final video?”)325 - audios: “The voiceover is ready. Assemble the final video?”326 Use two options: `Continue (recommended)` and `Stop here`. Localize the text327 to the user's language and use the same callable/raw GenUI fallback mechanism328 defined in Phase 0. Never start the next media stage in the turn that displays329 this question.3308. Explicit hands-off/auto runs skip both331 `show_generation_by_ids` and the review question, then continue automatically332 after the stage is terminal. They use headless batches throughout.333334The standard animated route therefore reviews **IMAGES → VIDEOS → AUDIOS**.335Dependencies override presentation order only in documented special modes:336Picture Story reviews AUDIO → IMAGES; SONG MODE reviews the song/audio before337the videos choreographed to it and has no narrator stage.338339### Phase 0 — Intake and platform dispatch340341Read `${FACELESS_FLOW_DIR}/references/intake-and-dispatch.md` completely before starting Phase 0 and follow it exactly. Return here at Phase 1 after its gate passes.342343### Phase 1 — Style anchor344Get ONE look anchor, by the path chosen in Phase 0:345- **Authoritative reference images (headless CMS preset or upload)** → import every346 `style_reference_url`, then make ONE `seedream_v5_pro` style SAMPLE with347 `resolution:"1k"` using all imported348 images and the verbatim style-only prefix from `${FACELESS_STYLES_DIR}/references/prompts.md §1`. Write the349 80–100-word locked formula from the donors' visible line/surface work, shading,350 palette, background treatment and motion implication only; paste it byte-identical in351 every later prompt. Ignore any accompanying preset id and do not open a house-style352 file. Keep the new style-key `job_id` as the sole Phase-2 look anchor. The imported353 donor `medias` are IMMUTABLE across the complete retry ladder: every retry carries354 the same donor media ids. If all donor-bound retries fail, report355 `STYLE_ANCHOR_FAILED`; generating a prompt-only key or silently dropping the donors is356 forbidden.357- **House style (Editorial Motion Graphics — default for History & Explainer; Paper358 Diorama when picked; Stickman via the generic §0 formula)** →359 open the style's reference file, take its STYLE FORMULA verbatim (**Editorial and360 Paper Diorama: first LOCK the one {ACCENT} color per the style file and write it into361 the formula + PALETTE LOCK; Mannequin: import its canonical ref URLs for the key and362 generate the LOCKED CAST with the identity chain per the style file**), and generate the363 look anchor with `seedream_v5_pro` (`aspect_ratio` = chosen aspect,364 `resolution:"1k"`) as a pretty, readable style SAMPLE (§1 template with the365 formula), attaching the card's resolved `media_id` and every canonical donor from366 its style file as `medias` with role `image`. Keep its `job_id` — that is the367 anchor for every Phase-2 asset. A pinned house style needs no STYLE-LOCK approval368 round (record the key without a separate widget and move on). If the render visibly369 missed the formula (wrong palette / photoreal drift), use the bounded retry ladder;370 do not open a separate approval gate.371- **Named preset without reference URLs (interactive flow only)** → map the name to its372 style file and pinned canonical refs from Phase 0. A card with NO style file (legacy373 explainer cards) → `resolve_faceless_channel_preset` → use the returned `media_id` as the look374 anchor and derive the locked formula from its visible traits.375- **Custom (uploaded images / free description)** → generate ONE **pretty, readable style376 SAMPLE** with `seedream_v5_pro` (`aspect_ratio` = chosen aspect,377 `resolution:"1k"`): a small representative378 vignette — one simple recognizable subject rendered so the line weight, shading and379 colours read at a glance — NOT formless blobs. **Never draw a palette strip, colour380 chips, swatch bar, labels or a reference-sheet layout:** the style key is attached to381 every later asset and block, so anything drawn into it can propagate into the video.382 Add all of those elements to this call's negative prompt. Keep its `job_id`. For uploads use the verbatim style-only prefix in383 `${FACELESS_STYLES_DIR}/references/prompts.md §1`. Record it (**STYLE LOCK** notification only; do not384 render a separate widget — it appears in the final image-stage list) and tell the385 user plainly: *"this style sample can386 look a little odd — that's normal, it's only a look reference, not a final frame."*387For every newly generated style key, use a one-request `generate_image_batch`388call with stable `index:0`, then `jobs_wait`; it stays headless because the key389is an internal dependency, not a separate review. Keep it in the later image-stage390display ledger; reserve asset indices `1..N` so the final ledger stays unique.391**GATE 1:** a look anchor exists (preset media_id OR approved custom `style_key_job_id`).392393### Phase 2 — Asset roster (MANDATORY — characters, locations, props)394Tool: image (`seedream_v5_pro`, always `resolution:"1k"`). Pass the **look anchor** (preset style-reference395media_id OR custom `style_key_job_id`) as `medias` (role `image`). Embed the ONE style396formula BYTE-IDENTICAL in every asset prompt (this is the entire consistency mechanism).397Generate one image per asset through the grouped batch requests below:398- **Characters** — `aspect_ratio` 2:3: full body, plain flat backdrop, distinctive readable design.399 **Long-form History: one variant PER ERA the character appears in** (identity400 invariants verbatim in every variant prompt + the era's aging/costume changes;401 `henry_young` / `henry_old`). **Later era variants ALWAYS attach the character's402 FIRST incarnation as an image reference** ("the SAME person as in the reference,403 now {aged/changed}") — never from the style ref alone; see the IDENTITY CHAIN in404 `${FACELESS_MODES_DIR}/references/history-longform.md`.405- **Locations — MULTIPLE, not one** (`aspect_ratio` = chosen aspect): a real DRESSED406 environment with one named anchor object, NO people. Generate **enough distinct407 locations that no single one carries more than ~2 CONSECUTIVE blocks** (a location may408 return later in the video; a 2-min / 12-block video wants ~4–6 locations). For each location also generate 1–2 **coverage angles**409 (reverse / lateral / detail crop) so blocks in the same place aren't the identical plate.410- **Props** — `aspect_ratio` 1:1: single isolated object, no hands/scene.411- **Variety inserts (optional, esp. Kids):** a subject on a clean solid color card, a412 pop-up diagram, an anthropomorphized object with a face — for cutaway shots.413Generate the roster through `generate_image_batch` in sequential groups of at414most six. Keep one stable asset index through retries; wait each group with415`jobs_wait` and save `(index, job_id)` per asset + coverage view. After every416image is completed, interactive mode displays the exact final image ledger with417`show_generation_by_ids`, renders the IMAGE review question, and ends the turn; continue418to Phase 3 only after `Continue`. **Picture Story exception:** its Phase-2419assets are internal dependencies, so defer the single IMAGE list/review until420all final timeline frames are complete. In auto/headless mode post the full421roster (**ASSET LOCK**) and continue without the list.422**GATE 2:** every character + location + prop the script needs has a `completed`,423approved asset. Do NOT enter Phase 4 with a missing asset (that beat would drift).424Prompt templates → `${FACELESS_STYLES_DIR}/references/prompts.md §2`.425426### Phase 3 — Script + block plan427**Read `${FACELESS_STYLES_DIR}/references/prompts.md` § Scriptwriter first — it is not optional:** pick the428**through-line** (one physical object that appears in every block, escalates429monotonically, resolves in the payoff — and gets its own Phase-2 prop asset so it430never morphs), research factual topics to its target list (hook stat · 3–5 concretes ·431the counterintuitive turn; Sources line kept), and run its rewrite pass before showing432anything.433**Long-form History runs FIRST do OUTLINE LOCK** (`${FACELESS_MODES_DIR}/references/history-longform.md`) as434a notification that posts and proceeds:435chapter outline + ERA MAP (characters×eras asset math, shown with the roster count) +436through-line + vignettes — finalized BEFORE any asset generation; then the standard flow437below per chapter (assets may be generated era-by-era alongside chapters).438Write the story as **N blocks**. **Each block = 10s = FIVE hard-cut shots, ~2s each439(Kids: FOUR — the kids-styles.md interplay pattern, order varied every block).** Kids scripts are built on the440MANDATORY interplay: the narrator addresses characters and the viewer by name, the441shots stage the visible reactions (wave/nod/look-to-camera), questions sit at the END442of a line so the block boundary is the answer beat and the next block opens with the443payoff. Build an arc444(hook → build → turn → payoff): cold-open hook stated flat and SHORT — block 1 opens445on a ≤8-word punchy line, then fills to normal density (History/Explainer — no446greetings, no throat-clearing; Kids keeps its warm host manner), ONE idea per block447(the shots are angles on it), build blocks **escalating** (if they can be448reordered without loss, rewrite), a turn that surprises rather than summarizes, a449payoff whose kicker reframes the hook. Humor = deadpan setup → absurd450punch, Barnum lines, confirmation-bias gags.451**Shot-variety rules (enforce per block — this is what stops the "samey" problem):**452- EVERY shot in a block differs in SIZE and ANGLE from its neighbours (e.g. MEDIUM →453 CU → OTS → low WIDE → ECU). Only the FIRST block of a new location may open on a454 full establishing WIDE — later blocks in the same location must NOT re-establish; open455 on a fresh close/medium/coverage angle.456- OTS requires a named visible character whose shoulder/head is intentionally in the457 foreground. If the shot's subject list has no character (object, diagram, empty458 location), OTS is invalid and must be replaced before Phase 4.459- **≤2 consecutive blocks per location.** Then change: next location, a coverage angle,460 or a variety insert. Plan the location rotation up front so no place repeats back-to-back461 for long. Kids especially: rotate locations + drop in object-with-face / diagram inserts.462- Vary the character's distance and screen position; don't reset to the opening framing.463For each block write: the shots (size+angle each) + which assets/location/coverage appear464(**≤7 refs per block** — plan the roster so no block needs more; rule of Phase 4)465+ one VO line. Save the canonical machine-readable version to466`script_manifest.json` using this exact shape:467`{topic,genre,animation_mode:"fully_animated",channel_type,style,through_line:{name,asset,progression,resolution},468arc:{hook,build:[...],turn,payoff},blocks:[{n,arc_role,vo_line,location,469through_line_state,shots,assets_used}],sources:[absolute research URLs]}`.470Map `genre` deterministically: Explainer → `education`, History → `history`, Kids471→ `kids`, Fairy Tale & Myth → `storytelling`. Do not put the display label into472the validator field.473Every `assets_used` array includes `through_line.asset`; source labels without URLs are474invalid. `vo_line` contains ONLY the authored words spoken by the narrator — never put475delivery brackets or `[00:00-00:09]` timecodes in the manifest. Construct that wrapper476only when making the corresponding Phase-5 TTS call. Lock `NARRATION_LANGUAGE` here as477the two-letter language code inferred from the actual authored `vo_line` / `phrase` text478(`en`, `ru`, `es`, …), never from the topic or a hard-coded default. Pass that same479literal to take verification, assembly and captions; update it before any new audio call480if the authored language changes. For videos ≥60s run481**SCRIPT LOCK** as a notification: post the FULL482script IN CHAT (every block: VO line + shots + location; plus the through-line named in483one sentence and each block's arc role) and PROCEED in the same turn — no484approve/tweak question in any mode; the user replies only if they want changes. Never485claim a script was approved that the user hasn't been shown.486**Picture Story runs the FRAME-BY-FRAME model — `${FACELESS_MODES_DIR}/references/picture-flow.md` is the487source of truth** (ONE continuous narration → Whisper timeline → frames; NOT per-beat488takes). Write the frame plan to `script_manifest.json` before any audio, then run the489SCRIPT gate:490```491sandbox_exec({492 command:"python3 ${HF_WORKFLOWS}/faceless-video/scripts/validate_picture_story.py --script script_manifest.json --duration-seconds {requested_seconds}"493})494```495Exit code 1 BLOCKS Phase 5. Every frame entry declares `image_mode:"new"|"variation"`;496The top-level manifest uses `genre` and `animation_mode:"scene_based"`.497Variations also declare `variation_of` = the immediately previous frame and one concise498`change_only` detail. **~2 of every 3 frames must be `variation` — and a `variation`499is a literal EDIT of the previous rendered frame (that frame's job_id as the ONLY500image reference, NO asset sheets/location/props on the call), not a fresh render from501assets. Sending assets on a variation rebuilds the scene and produces a different502picture — the #1 picture-story bug. Full KIND-A/KIND-B recipe in503`${FACELESS_MODES_DIR}/references/picture-flow.md` Phase 4.** Rewrite only the `invalid_beats` reported,504rerun until `valid:true`. Final delivery may enrich this already-validated manifest with505durable frame URLs, but never rewrites its phrases or ordering.506**Motion-video hard gate:** for Explainer, History and Kids, run:507```508sandbox_exec({509 command:"python3 ${HF_WORKFLOWS}/faceless-video/scripts/validate_motion_script.py --script script_manifest.json --duration-seconds {requested_seconds}"510})511```512Exit code 1 BLOCKS every later generation phase. Rewrite only the fields listed in513`invalid_blocks`/`errors`, then rerun until `valid:true`. This deterministically enforces514the exact block count, the per-full-10s-line word budget (proportional for a short last515block), structured through-line/arc, per-block through-line state, shot/ref limits,516absolute source URLs and ≤2 consecutive blocks per location. It also writes517`script.lock`; assembly verifies that lock so edited narration cannot silently reach518the cut. Never generate clips or voice from a script that has not passed this command.519Initial validation enforces **20–23 words** per full 10s line and **17–21 for Kids**.520After measured overlong speech, `--duration-retry-blocks` permits 17–19 words only521for those full blocks (proportional for a short final block); it never relaxes522unmeasured blocks. The validator also enforces at most two sentences, digit-free narration, and these523non-negotiable gates: no verbatim phrase of five or more words shared by two blocks;524framing size on every shot with adjacent sizes different; no re-establishing a visited525location; OTS only over a named visible shoulder; no repeated eight-word shot526description; no two blocks with the same location plus same ordered assets; and for527Explainer/History a cold open of at most eight words before its first full stop.528For a Kids Talking Characters run, read529`${FACELESS_MODES_DIR}/references/kids-talking-characters.md` before writing. Add530top-level `talking_characters:true`; alternate `block_kind:"narration"|"dialogue"`531starting with narration. Narration blocks keep `vo_line` at 17–21 words. Dialogue532blocks carry 16–22 words total across at most two named speakers and use the generated533clip audio rather than a narrator take. SONG MODE never sets this flag.534**GATE 3:** N blocks, each with 5 varied shots (Kids: 4) + assets + a VO line; through-line present535in every block and resolved in the payoff; rewrite pass done; location rotation536respects ≤2 blocks/place; no block after the first in a place re-opens on the establishing WIDE.537538### Phases 4–8b — Generate, narrate, assemble, subtitle, cover, and deliver539540After Gate 3 passes, read `${FACELESS_FLOW_DIR}/references/generation-and-delivery.md` completely and follow Phases 4–8b exactly before using the retry ladder and final QC below.541542## RETRY LADDER (use on every `nsfw`/`failed` image or clip)5431. **Resubmit the SAME prompt** — attempt 2, then attempt 3. Change `seed` only544 if the live model schema declares it; never invent a seed field for H3.5452. Still failing → **reword**: remove risky tokens (`child`/`kid`/`childlike`, tight546 animal-face close-ups, aggressive/intimate poses); resubmit up to 2 more times.5473. Still failing → **change that beat's framing** (different shot size / staging).5484. NEVER drop the block, NEVER leave a gap, NEVER substitute a neighbouring block.5495. **Budget cap:** if ONE block is still failing after ~8 total attempts, STOP and surface550 it to the user (which beat, what was tried) instead of burning credits in a loop.5516. **References are immutable.** Every retry keeps the exact same ordered `medias` as552 the failed call. Reword prompt text or framing only. Never turn a reference-bound553 style key, asset, frame, or clip into text-to-image/text-to-video to get around554 moderation. For a donor-bound style key, exhaustion is `STYLE_ANCHOR_FAILED`.555(A preset recommendation is not a failure — resubmit with `declined_preset_id` per rule 5.)556557## FINAL QC CHECKLIST (before delivering)558- [ ] `final.mp4` CAME OUT OF `assemble_final.sh` (Picture Story:559 `assemble_slides.sh`) and passed its built-in asserts560 (fixed duration, audio present, full decode) — a hand-assembled file fails QC by definition.561- [ ] Deliverable is EXACTLY ONE video file (`final.mp4`) — not part562563…(truncated)