render-hand-swipe-flavor-listicle

Render the hand-swipe-flavor-listicle format from a config: a short vertical (1080×1920, 30fps, ~7.5s) "N flavors of <Brand>" listicle. Each flavor is a card — a flat, saturated color field + a persistent title + the brand's REAL product cutout with a soft contact shadow. Cards change by sliding right-to-left (a phone-feed scroll), while a real-looking hand sweeps at the bottom of the frame. Music-only, no VO.

This capability is the FREE, deterministic assembly (no paid calls, no keys). It never generates or edits the product — the cutouts are composited as-is, so labels stay crisp. It needs four kinds of input, gathered first (see Getting the inputs): product cutouts, a title TTF, a green-screen hand clip, and (optionally) a music bed.

Run

S=/tmp/gooseworks-scripts/render-hand-swipe-flavor-listicle/scripts   # after `gooseworks fetch render-hand-swipe-flavor-listicle`
python3 $S/build_hand_swipe_listicle.py config.json                 # writes config "output"
python3 $S/build_hand_swipe_listicle.py config.json --out final.mp4 # override the output
python3 $S/build_hand_swipe_listicle.py config.json --stills cards/ # one PNG per card, no video
python3 $S/build_hand_swipe_listicle.py config.json --work work/    # keep the intermediates in work/

Relative paths in config.json resolve against the config file's own folder. Render --stills first: it is instant and shows the title, colors and cutouts before the full render.

Prereqs: python3 with Pillow, and ffmpeg + ffprobe on PATH. Nothing else.

Getting the inputs

Input	Free route	Paid route (paid step; runs only on an approved order)
Product cutouts	The brand's transparent PNGs (PDP/press kit).	A brand-site photo is usually NOT a cutout. Remove its background with create-image-fal, model fal-ai/birefnet/v2 (see below).
Title TTF	Download a TTF matching choices.title_style (table below).	—
Hand clip	The bundled clip (one woman's hand): curl -fL -o hand-swipe-greenscreen.mp4 https://d2m0qbg34x1ii2.cloudfront.net/ads/samples/455dc125-e41c-46dc-9fa6-9ae125e9b6bf/media-hand-swipe-greenscreen.mp4 (also in the recipe's config.hand.bundled_clip_url).	A new clip via create-video-fal (see Making the hand clip).
Music bed	None ("music": null, a silent cut).	create-music-elevenlabs (see Making the music bed).

Cutouts. The renderer warns when an image has no transparent pixels: it would render as a white box with a rectangular shadow. Fix it before rendering, never by AI-regenerating the product. The cutout route is create-image-fal with model fal-ai/birefnet/v2 (paid, gated), payload {"image_url": "<public url of the product photo>"}, the same route render-vignette uses. Known gap: birefnet returns image, not images[], and create-image-fal's gen_image.py currently reads only images[], so check that capability's notes before relying on it. If no cutout route works, ask the user for transparent PNGs.

Title font. Always pass title_font. Without it the renderer falls back to whatever the machine has (Brush Script on macOS, DejaVu Sans Bold on Linux), so the same config renders a different title style on different machines. Free TTFs from Google Fonts, one per title_style:

choices.title_style	Download
cursive / script	curl -fL -o fonts/title.ttf https://github.com/google/fonts/raw/main/ofl/pacifico/Pacifico-Regular.ttf
bold condensed sans	curl -fL -o fonts/title.ttf https://github.com/google/fonts/raw/main/ofl/anton/Anton-Regular.ttf
elegant serif	curl -fL -o fonts/title.ttf https://github.com/google/fonts/raw/main/ofl/dmserifdisplay/DMSerifDisplay-Regular.ttf
hand-drawn marker	curl -fL -o fonts/title.ttf https://github.com/google/fonts/raw/main/apache/permanentmarker/PermanentMarker-Regular.ttf
the brand's own display font	The brand's TTF/OTF file if you have it; otherwise the closest row above.

The title is auto-shrunk (with a warning) until it fits 88% of the frame width, and the underline follows the drawn text, so long brand names never clip on the edges.

Config

scripts/config.example.json is the worked example (the fictional Fortuna Energy "5 Flavors of Fortuna"). Copy its structure, never its creative values.

Field	What it is
title	The persistent header line (required).
title_font	A TTF in the style from choices.title_style (see Title font). Missing → a warned, machine-dependent fallback.
title_size, title_y, title_color, title_underline	Title layout (defaults 118, 200, white, true). title_size is a maximum: a too-wide title is shrunk to fit.
flavors[]	{ "bg": "#hex", "can": "cutout.png" } per flavor, in play order (required, ≥2). image is accepted as an alias for can. Cutouts must be transparent PNGs.
can_height, can_center_y	Product size + vertical center (defaults 950, 940).
slide.frames	Frames per slide (default 12). slide.direction is fixed: always right-to-left (any other value is ignored with a warning).
hand_clip	The green-screen hand swipe mp4 (required to render).
hand	trim_start, trim_end (the clean finger-up window, default 0–1s, must lie inside the clip), speed, scale (default 0.45), green_margin (default 1.12).
end_card, end_card_hold_frames	Optional PNG at the frame size (1080×1920) that slides in after the last flavor; hold (default 60 frames). Another aspect ratio is stretched, with a warning.
music	{ "path", "trim_intro_sec", "volume" } or a plain path string, or null for a silent cut. path is the create-music-elevenlabs output file. volume is a gain after loudness normalization (1.0 = the demo level, -18 LUFS).
output	Output mp4 (default hand-swipe-listicle.mp4 next to the config).

Hard errors (exit 1): an unfilled <input:…> / <brand:…> placeholder in a required field; a missing file; a music object whose path is empty or a placeholder (set "music": null if the cut is meant to be silent); a hand.trim_start at or past the clip's end.

Timing. Each flavor lasts one hand-loop (the trimmed clip length). With 5 flavors, a 1s trim, a 12-frame end-card slide and a 60-frame end-card hold, the cut is ~7.4s.

Music length. The bed must cover trim_intro_sec + the cut. If it is too short, the renderer trims less of the intro (with a warning) so the music still runs to the end and fades out there. If the file is shorter than the whole cut, the tail is silent (warned).

Choices

The recipe asks the user these before any paid step; the renderer only draws what the config says.

• flavor_lineup — which SKUs and in what order → flavors[]. The demo used 5 energy-drink flavors, strongest last.
• title_style — the header style → title_font (download per the table), title_size. The demo used a cursive script.
• hand — whose hand → hand_clip: the bundled clip (free) or a new create-video-fal clip (paid). The demo used a woman's hand.
• music — the bed's feel → the create-music-elevenlabs prompt, then music.path. The demo used an upbeat, punchy energy underscore.

Making the hand clip (paid, gated — not this capability)

Only when choices.hand asks for a different hand than the bundled clip, or no bundled-clip URL is available. Fill {hand} from choices.hand (e.g. "a man's hand with a silver watch"). Write the payload to a file so apostrophes in the description don't break the shell:

cat > hand-payload.json <<'JSON'
{
  "prompt": "Close-up of {hand}, the BACK of the hand facing the camera, index finger extended pointing up. The hand swipes smoothly from RIGHT to LEFT across the frame like scrolling to the next photo on a phone. One clean horizontal swipe, the index finger stays extended (do not curl it). Solid flat bright green screen background, even flat lighting, fixed camera, no zoom, no camera shake.",
  "negative_prompt": "curled finger, closed fist, vertical motion, static, frozen, morphing, deformed fingers, extra fingers, text, watermark, changing background",
  "duration": "5",
  "aspect_ratio": "9:16",
  "generate_audio": false
}
JSON
python3 /tmp/gooseworks-scripts/create-video-fal/scripts/gen_video.py \
  --model fal-ai/kling-video/v3/standard/text-to-video \
  --payload @hand-payload.json --out hand-swipe-greenscreen.mp4

Then look at the first ~1s (e.g. --stills-style frame grabs with ffmpeg, or watch) and set hand.trim_start / hand.trim_end to the clean finger-up window. Set hand_clip to the file.

Making the music bed (paid, gated — not this capability)

Generate it long enough to cover the intro trim plus the cut, plus 1s of slack: at least (trim_intro_sec + target_duration_sec + 1) seconds, i.e. about 11s for the default 2.5s trim and a 7.5s cut. Keep --trim-intro 0 there; this renderer does the trim.

python3 /tmp/gooseworks-scripts/create-music-elevenlabs/scripts/gen_music.py \
  --prompt '<from choices.music; instrumental only, no vocals, no artist names>' \
  --length-ms 11000 --duration 11 --out music-bed.m4a

Then set music.path to music-bed.m4a.

Craft rules (baked into the renderer)

• Never AI-regenerate the product. Image-to-video hallucinates the can and garbles the label. Only the hand is generative; the products are real cutouts.
• Green-dominance key, not colorkey/chromakey. Alpha is 0 only where g > green_margin × max(r, b). It is brightness-invariant, so it survives a muddy, uneven AI green. Kept pixels are despilled (green clamped to max(r, b)), so green spill on skin turns neutral instead of see-through. Raise green_margin if skin goes see-through; lower it if green fringe remains.
• Back of hand toward camera, finger UP. A nails-forward hand reads as the wrong hand.
• Trim to the finger-UP window. These clips curl the finger periodically.
• Scale the hand down and anchor it at the bottom so the fingertip reaches ~35% up (the can base) and never covers the product.
• Flavors change by sliding RIGHT-TO-LEFT, never a vertical flick or a top-drop.
• The hand is scaled to the frame width with its aspect kept, so a non-9:16 clip is not stretched.

Output

A WxH (default 1080×1920) H.264 mp4, with AAC audio when music is set (fade in/out + loudnorm, padded to the full length). The last line names the length and music/silent; read the WARNING lines above it. Then review the FULL mp4 with watch: the hand is opaque in every frame with no green fringe, the finger stays up, the title fits the frame, labels are crisp and readable, the slide is right-to-left, and the music runs to the end.