# ========================================================================== # RAP-AVATAR-MV PACK — TEMPLATE. Copy to .pack and fill in. # One pack = one subject (a real person whose portrait performs the rap). # Superset of _template.pack: same format, same loader, extra rap fields. # Engine: skills/rap-avatar-mv/ · run: make-rap-mv.sh # THIS FILE IS THE APPROVED RECIPE (New Era, 2026-08-31: sung-length windows, vocal-swap # audio, own-take cuts, fit+join). The copy in the repo is canonical; ~/videoclaw/packs/ # links to it. A pack without AUDIO_MODE is refused by preflight. # ========================================================================== PACK_NAME="" # e.g. dav (matches the filename, minus .pack) DISPLAY_NAME="" # e.g. Dav PERFORMER_NAMES="" # e.g. Dav — the name the sheet and prompts use PERFORMER_PRONOUNS="" # he|she|they — STATED (a bio, the person), never inferred LYRIC_LANGUAGE="English" # --- CONSENT (required — the runner refuses without it) ------------------ # This lane animates a real human face and puts words in its mouth. Set to # "yes" only when the portrait is your own, or its subject has agreed. PORTRAIT_CONSENT="no" # --- IDENTITY (who) ------------------------------------------------------ PORTRAIT="" # ABSOLUTE path to the source portrait. One clear, # front-facing photo; the face is the whole product. PORTRAIT_ORIGINAL="" # the frame the portrait was cropped/edited from (provenance) CHAR_IDS="" # the GB character id registered FROM that portrait CHAR_NAMES="" # e.g. "Dav" GB_CHARACTER="" # convenience alias: ":" IDENTITY_NOTES="" # how the keyframes should describe this person # BEYOND the photo — build, hair, skin, age range, # facial hair. The keyframe gate prints this, and a # bare "the man" will not hold identity across shots. # --- SONG (what they rap) ------------------------------------------------ SONG_STYLE="modern trap, hard 808 sub, crisp hi-hat rolls, confident male rap vocal, short-form hook, starts on the hook, no intro, dry vocal minimal reverb" # "starts on the hook" is the single highest-value # phrase here: a song with a long ambient intro # burns a generation and trips the climax gate. # State the voice explicitly (male/female). SONG_MODEL="V5" # A FILM THAT COPIES A REAL RECORDING: set SOURCE_URL and nothing is bought. ingest_source.py # downloads it once into references/source.{mp4,wav,-silent.mp4,json} and writes its audio # as the song; SHOT_REFS_VIDEO then defaults to references/source.mp4. The recording's # rights are the operator's to hold (PORTRAIT_CONSENT covers the face; this covers the # music). SOURCE_COOKIES=chrome opts into yt-dlp's browser cookies (Keychain prompt). # SOURCE_URL="" # SOURCE_COOKIES="" TITLE_ROMAN="" # the song's title as it appears on screen and in the upload SONG_VOICE="male" # documentation only — state the voice inline in SONG_STYLE too SONG_LANGUAGE="en" LANGUAGE="en" WHISPER_MODEL="medium" # small placed a chant 1.4 s late and garbled a number (New Era); medium is the floor # WHISPER_ENGINE=cpp # whisper.cpp via the in-tree shim (Metal; a 4:33 song in ~41 s, not 75 min). # Default openai. ONE ear per film: recorded at the map stage, a change refuses. VOCAL_BRIEF_MIN_RATIO="0.45" # how close whisper must hear a sheet line to place it; lower per film when a sung line reads "not heard" (film #3: 0.41) VOCAL_BRIEF_MAX_INTRA_GAP_S="2.0" # longest silence one sheet line may span; raise for a song that breathes mid-line (a slow devotional holds 2+ s inside a line) # --- FILM SHAPE ---------------------------------------------------------- HOOK_FULL_TRACK="1" # the whole song is the film (a 90 s song ≈ 9 sung windows on the free lane) # HOOK_SECONDS="8" # only with HOOK_FULL_TRACK unset: an 8 s hook film to prove the gates STYLE_COUNT="6" # worlds the film walks through, one per SECTIONS block BROLL_PER_STYLE="1" BROLL_EVERY_STYLE="1" # one cutaway per world; the instrumental gaps draw from them # SONG_BREAKDOWN="1" # optional: Gemini listens to the stem and proposes section / who sings / # a cue per line (build/song-breakdown.html) — ADVISORY; the sheet and # singers.html decide. Cues → song-cues-proposed.json for SHOT_MOVES. SECTIONS="" # optional: /build/sections.json — which world sings which block SECTION_WORLDS="" # optional: "Hook=jasmine-garden-morning,Verse 1=banyan-swing" — worlds per sheet section for the PROPOSED sections file (unset SECTIONS to take the proposal) STYLES_FILE="" # optional: a per-film styles register (default: the lane's styles.json) STYLE_ALLOW="" # optional: restrict the draw, e.g. # "gold-rooftop,red-room,desert-highway,violet-haze" # (ids in skills/rap-avatar-mv/references/styles.json) # --- RENDER -------------------------------------------------------------- ROUTE="seedance-direct" # the free lane (vendored Higgsfield engine). # 2026-08-11: was veo-useapi. Runway is SUSPENDED, and Flow # (veo-useapi) is not drivable by the rap explore # supervisor. ONE FILM, ONE ROUTE — mixing lanes seams. ASPECT="9:16" # 9:16 for Shorts/Reels/TikTok, 16:9 for YouTube RESOLUTION="720x1280" # the free lane's ceiling; DELIVER upscales to 1080x1920 SCENE_SECONDS="12" # the cap on a phrase window's SUNG span; the render is sized by the singing RAP_BAR="keep" RAP_PROOF="once" SLACK_HEAD="0" EXACT_ONSETS="1" # windows open on the real word onsets from the map MV_FPS="24" # What the model HEARS as the voice reference: "mix" cuts every slice from hook.wav # (the whole track); "stem" cuts it from the Demucs vocal stem the `stem` stage writes # — one clock, no bed under it. The w11 A/B (2026-08-29) measured NO difference between # stem and mix on the sung rate; "mix" stays the default (no venv dependency). "stem" # makes a missing stem a hard stop (the venv at $VCLAW_WORKSPACE/tools/singer-diarize), and # so is a stem that FAILS stem_check.py (silent, truncated, wrong song, the mix under the # stem's name) — build/stems/stem-check.json carries the six measurements. VOICE_SOURCE="mix" # THE PAID DOOR. The free lane renders every window; a window it cannot land (moderation # refuses it draw after draw, the slot is starved) can be bought ONE take at a time on the # Higgsfield API pool through the official CLI: PAID_WINDOWS="w05,w11". Each named window # goes through paid_take.py inside render-all — `generate cost` quotes it (the references # are uploaded to quote), the SAME approved submit contract binds it (plus the donor's # sha), the same judge keeps or parks the clip, and the lane log records it like any draw. # Needs `higgsfield` on PATH and `higgsfield auth login`; ~12.5 credits per 5 s at 480p. # Never on the standing word: UNATTENDED=1 with PAID_WINDOWS set is refused. PAID_WINDOWS="" # Where each sung WORD ENDS. Whisper hears onsets to ~100 ms (the lane's clock) but its word # END tiles to the next word's onset on 88 % of words (measured on a real stem, 2026-09-05) — # "until the next word", not "until the note stops" — so a held vowel and a word before a # 3 s silence look the same. `stem` MEASURES the end from the vocal stem's RMS (local, free, # both directions). `gemini` hears the audio and answers per word: on the same stem its ends # ran ~0.9 s LATE on every word before a silence and tiled elsewhere — selectable, not the # default. `whisper` keeps whisper's own ends. A pack WITHOUT this line behaves as `whisper` # (older films keep their plan.hash). gemini with no key is a hard stop. WORD_ENDS="stem" # The lip-sync direction in every sung prompt: 0 = quote the lines in order and name # no seconds (the audio reference is the only clock); 1 = the timestamped script # ("0.1–5.8s the lead voice sings …"), which the Seedance guidance calls a second clock. PROMPT_TIMESTAMPS="0" # Lyric lines per sung window. Unset = phrase packing (2-3 lines per clip, fewer renders). # The 2026-08-29 A/B that favoured one line per window was explained the next day: the # padded arms stretched, the tight one did not — it was the render length, not the line # count (see SLACK_TAIL). Leave unset; set 1 only when a take proves a long window wanders. # WINDOW_LINES="1" # THE RENDER IS AS LONG AS THE SINGING. A clip longer than its sung span comes back sung # slower by that ratio (New Era, 2026-08-30: 7 s renders of 5 s lines, every window 1.35x # slow). make_plan sizes each window as sung + 0.3 s of silence each side, whole seconds, # and plan_coherence #12 refuses more than 1 s of padding. Tail slack is that padding — 0. SLACK_TAIL="0" # One take before the rest: the runner renders FIRST_TAKE_WINDOW alone (default: the first # sung window), shows its filmstrip beside the portrait and the primed speed measure, and # waits for `touch build/first-take-approved`. Pick the best-lit, clearest window. FIRST_TAKE_WINDOW="" # leave EMPTY: the runner picks the first SUNG window. Pinning "w00" # aimed the proof at an instrumental window on the first duet film — # it measured nothing (rate None) and proved no lip-sync (2026-08-31). # --- AUDIO (the approved recipe, 2026-08-31) ------------------------------------- # A lip-sync model's mouth matches its OWN voice. vocal-swap = the record's instrumental # stem + each take's own voice over its window + the record's vocal elsewhere; the slide # stage fits every take to the record's tempo and lets it finish its last word before the # cut; captions are timed from the takes' words. "record" is the old mode (the take is bent # to the record; needs the sync gates) — set it on purpose only. AUDIO_MODE="vocal-swap" VOCAL_SWAP_FADE="0.15" CUT_OWN_TAKES="1" # every window takes its own take; the cut is authored, not asked for SLICE_CHECK="0" # the per-slice whisper proof; slices.html + the first take stand in CAPTIONS="1" # burned captions from the takes' own words # PAUSE_COVER="0.5" # seconds, off by default (unset/0): cutaway an in-window # silence too short for --min-cover's own section (see # COVER_PINS/COVER_SPANS above cover_mouthing.py in the runner) # --- BRAND / CHANNEL ----------------------------------------------------- CHANNEL="" KICKER="" PALETTE="" SUBSCRIBE_LINE="Subscribe for more" THANKS_LINE="" # --- UPLOAD / METADATA --------------------------------------------------- # Consumed by rap_metadata.py / rap_thumbnail.py / rap-publish.sh. The upload itself # NEVER runs on a re-run: it requires PUBLISH_GO=1 in the environment, explicitly. YT_CATEGORY="Music" YT_HASHTAGS="" YT_TAGS="" # comma-separated YT_BLURB="" # first paragraph of the description; lyrics follow it YT_PRIVACY="unlisted" # public|unlisted|private — what rap-publish uploads AS MADE_FOR_KIDS="no" # yes|no — a rap MV of an adult is almost always "no" THUMB_FRAME_SEC="10.0" # which film second the thumbnail is composed from # --- BOOKENDS (optional; omit any line and that element is simply left out) ----- # Cards ALWAYS built: ident, title, outro. The foreword and the partner board are # built ONLY when their vars below are set, so a pack that wants neither says nothing. # # NOTHING WITH A BRAND MARK ON IT IS EVER GENERATED. CLUB_CREST and the partner strip # are composited from real artwork; unset CLUB_CREST and the badge is omitted and the # layout reflows — it is never replaced with a drawn mark. # # PALETTE above is prose for prompts and cannot drive these — colours are hex. BOOKEND_TITLE="" # the film's on-screen title; falls back to the slug BOOKEND_TITLE_KICKER="" # small eyebrow over the title; defaults to KICKER BOOKEND_FACTS="" # "|"-separated lines on the end card BOOKEND_VALUES_LINE="" # a final muted line under the URL BOOKEND_INK="#0b1426" # ground BOOKEND_PAPER="#f7f9fc" # primary type BOOKEND_ACCENT="#f2a96c" # rules, kickers, the URL BOOKEND_MUTED="#96a3b8" # secondary type # Display face for names/titles, UI face for tracked caps, BODY for anything you must # READ. Keep BODY different from DISPLAY: a didone's horizontals are hairlines, and at # body size reversed on dark its em-dashes disappear entirely. FONT_DISPLAY="/System/Library/Fonts/Supplemental/Didot.ttc" FONT_UI="/System/Library/Fonts/Avenir Next Condensed.ttc:2" FONT_BODY="/System/Library/Fonts/HelveticaNeue.ttc" BOOKEND_PLATE_INTRO="" # background art; a gradient is synthesized if unset BOOKEND_PLATE_OUTRO="" BOOKEND_PLATE_PARTNERS="" BOOKEND_PLATE_FOREWORD="" # A foreword from a named person. It auto-splits across beats so ~90 words are read, # not flashed. These are a REAL person's words — get them approved before publishing. BOOKEND_FOREWORD_FILE="" BOOKEND_FOREWORD_TEXT="" BOOKEND_FOREWORD_NAME="" BOOKEND_FOREWORD_ROLE="" BOOKEND_FOREWORD_KICKER="A MESSAGE" BOOKEND_FOREWORD_PORTRAIT="" # The performer credit on the end card. BOOKEND_CREDIT_PORTRAIT="" # defaults to PORTRAIT BOOKEND_CREDIT_NAME="" BOOKEND_CREDIT_KICKER="WRITTEN & PERFORMED BY" # Partner board. The strip is composited WHOLE on a white bar — these marks are drawn # for light backgrounds, and keying them out cuts through the wordmarks. BOOKEND_PARTNERS_STRIP="" BOOKEND_PARTNERS_CAPTION="PRINCIPAL PARTNERS" BOOKEND_PARTNERS_KICKER="PROUDLY SUPPORTED BY" BOOKEND_PARTNERS_FOOTER="" # --- SECOND PERFORMER (optional; leave unset for a solo film) ------------- # A second real face needs its OWN consent line — the runner refuses without it. # PORTRAIT_2="" # ABSOLUTE path to the second performer's portrait # PORTRAIT_CONSENT_2="no" # "yes" only when that person has agreed # IDENTITY_NOTES_2="" # their visual descriptor (required with PORTRAIT_2) # PERFORMER_NAMES="" # "Dav|Amisha" — storyboard labels only # PERFORMER_PRONOUNS="" # "he|she" — one per performer (he|she|they), NEVER inferred # LYRIC_LANGUAGE="" # default English; e.g. Hinglish # Style blocks then say "performer": "a" | "b" | "both" (+ optional "wardrobe2"). LIBRARY_SOURCES="" # other projects' clips this film may reuse: space-separated paths/globs, ":origin" optional, # e.g. "$VCLAW_WORKSPACE/projects/my-film-p1/build/queue/explore/clips:part1" — the inventory # stage indexes them against every window BEFORE anything renders (a part 2 reuses part 1)