Update to Frameo.AI

SKILL.md text changes

− removed · + added

--- before
+++ after
@@ -1,31 +1,38 @@
 ---
 name: faceless-story-video
-description: "A narrated explainer or story with no on-screen speaker: one image per scene, gentle motion, a narrator voice, music, captions burned in."
+description: "A narrated explainer or story with no on-screen speaker: a locked look, reusable characters and places, multi-shot clips, a narrator voice, music and captions. Use for history and science shorts, kids' stories and songs, fairy tales, listicles and 'did you know' channels."
 ---
 
-Needs: a script or a topic outline; the narrator's language
-Credits: about 800–1,300 for 60–90 seconds, about 200–250 per 15 seconds (images ~18 each, clips ~65 per 5 s, speech ~1 per 50 characters)
-Time: 15–30 minutes
-
 ## When
 
-Use for explainers, history and science shorts, kids' stories, listicles, "did you know"
-channels — anything told by a narrator over scenes. Not for characters speaking on
+Use for explainers, history and science shorts, kids' stories, fairy tales and myths, listicles,
+"did you know" channels — anything told by a narrator over scenes. Not for characters speaking on
 screen (`script-to-video`) or a presenter (`talking-presenter`).
 
 ## Ask first
 
-1. **Frame and length** — 9:16 or 16:9; target seconds.
-2. **Look** — photoreal, illustrated, paper-cut, 3D; one reference image if they have one.
-3. **Narrator** — 3 candidates from `search_voices` in the script's language; they pick.
+1. **Channel type** — explainer (the default, and for listicles and "did you know"), history,
+   kids, or fairy tale and myth. It sets the default look, the pacing and the narrator's tone:
+   `get_skill_file(skill_id="faceless-story-video", path="references/channel-types.md")`. For
+   kids, ask whether it is narrated or a sung song (a sing-along or nursery song); a song follows
+   `get_skill_file(skill_id="faceless-story-video", path="references/kids-song.md")`, and background music alone is not a song.
+2. **Frame and length** — 16:9 for a channel, 9:16 for Shorts; target seconds.
+3. **Look** — the channel type's default, or theirs (photoreal, illustrated, paper-cut, 3D); one
+   reference image if they have one.
+4. **Motion** — moving clips (the default) or still pictures (lower cost: the cut pans over
+   stills instead of animating them).
+5. **Narrator** — 3 candidates from `search_voices` in the script's language; they pick. A
+   kids song has no narrator: the song is the voice.
 
-Say the rough cost from the scene count in the same turn as the questions; the user's yes comes with the plan (Steps, **The plan first.**).
+Say the rough cost from the block count in the same turn as the questions; the user's yes comes
+with the plan (Steps, **The plan first.**).
 
 ## Steps
 
 **Before any paid step.** The project: `list_projects` (or `create_project`) gives the `project_id`
 and, when the project has several modules, the `module_id`; every call below that takes a project —
-`estimate_cost` included — gets that same pair; without it those tools answer `project_needed`. The
+`estimate_cost` included — gets that same pair; without the project those tools answer `project_needed`, and without the
+module of a project that has several, `module_needed`, which lists its modules. The
 quote: one `estimate_cost(items=[…])` prices a stage in one call, with the same project, model,
 size and number of `image_urls` or `reference_image_urls` (`reference_count`) as each generate call, and returns a `quote_id` per item plus the total. Each generate call
 then passes its own item's `quote_id` and `confirmed_by_user=true`. A quote is single-use and lasts
@@ -33,7 +40,7 @@
 comes to more than the user approved is asked about again first. Generate calls return
 `generation_ids`; `wait_task` returns the links, and `show_generations` shows each stage's running
 and finished work in one card where the chat app displays Frameo cards: all the stage's ids at
-once, before its first `wait_task`, and the finished result with `final: true`.
+once, before its first `wait_task`; the card updates itself as the work finishes, so the same ids are not shown again.
 
 **The plan first.** Before the first paid call, the plan goes to the user in the chat as plain
 text: what will be made, in order, one line per generation (for a script, the shot list; for a
@@ -43,62 +50,92 @@
 generated until the user says yes. The user can drop or change lines; a changed line is priced
 again.
 
-**Canvas rows.** Pass `shot_number` on every `generate_image` and `generate_video` of a shot (1, 2, 3… in story order; the same number for a retake and for that shot's video), so each shot gets its own row on the Frameo canvas. Cast, prop and location references take `placement_kind` (`character`, `prop` or `location`) and the subject's name as `placement_group` instead: they sit on their own board, and the shots built from them do not pile into their row.
+**Shot order.** Pass `shot_number` on every `generate_image` and `generate_video` of a shot (1, 2, 3… in story order; the same number for a retake and for that shot's video), so the project keeps each shot apart, in order. Cast, prop and location references take `placement_kind` (`character`, `prop` or `location`) and the subject's name as `placement_group` instead: they are kept with the project's references, apart from the shots built from them.
 
-**Review (on by default).** Every scene image and clip is checked before it is built on,
-following `review-shots` (its steps come from `get_skill("review-shots")`, loaded before the
-first scene image), and a failed scene is retaken once. The checks are free here — no
-scene has speech on screen, so no clip needs the paid media analysis — but a retake is paid like the
-scene it replaces, from the retake allowance the plan carries for the user to approve. With no
-cast, "who" is checked against the reference image or the scene's visual line. The user can
-turn the review off.
-
-**0. Scenes.** Split the script into scenes of one idea each, 5–8 s of narration per scene.
-Write a one-line visual for every scene. Keep the list.
-
-**1. Narration (~1 per 50 characters).** `generate_speech` per scene (one file each keeps
-the cut simple); `wait_task` for the links. Each result's `duration_seconds` is
-the scene's measured spoken length; a result without one is estimated at 2.8 words per second
-(2.5 for Hindi) plus one second of headroom, and that timing is approximate. The scene's estimate
-is that length rounded up to whole seconds and kept inside the video model's range
-(`list_models(kind="video")`; 4–30 s on the default).
-
-**2. Images (~18 each).** `generate_image` per scene, each with its own quote, from its
-visual line in the chosen look, `aspect_ratio` from Ask first, the reference image as `image_urls` when given. A subject that
-recurs across scenes (a character, a mascot, a place) gets its own image first
-(`placement_kind` and its name as `placement_group`), passed in `image_urls` on every scene that
-shows it, so it stays the same from scene to scene.
-`wait_task`; show the first two before the rest. Review every image (`review-shots` steps 0,
-1 and 4) before it is animated.
-
-**3. Motion (~65 per 5 s).** `generate_video` from each image (`first_frame_url`) with a
-slow camera move in the prompt ("slow push in", "gentle drift") and the scene otherwise
-unchanged: no new objects or people, ending on the same scene (the same subjects and setting), `duration` = the scene's
-whole-second estimate. Silent (`generate_audio=false`) — the narrator carries the sound.
-`wait_task` each, then review the clips (`review-shots` steps 2 and 4). Skip this step for a
-lower-cost cut and let ffmpeg pan over the stills instead.
-
-**4. Music (~1 per 50 characters of prompt).** `generate_music` for one bed matching the tone, `duration` =
-the total, at most 120 s (the tool's cap); for a longer story make one 120 s bed and loop
-it at the join (`-stream_loop -1` on the bed input, `-shortest`).
+**Review (on by default).** Every image and clip is checked before it is built on, following
+`review-shots` (its steps come from `get_skill("review-shots")`, loaded before the first image),
+and a failed one is retaken once. The checks are free here — no clip has speech on screen, so no
+clip needs the paid media analysis — but a retake is paid like the image or clip it replaces,
+from the retake allowance the plan carries for the user to approve. With no cast, "who" is
+checked against the assets. The user can turn the review off.
+
+**A kids song** replaces steps 0, 2, 4 and 5 with the song-first order in
+`get_skill_file(skill_id="faceless-story-video", path="references/kids-song.md")`; steps 1 and 3 and the review hold.
+
+**0. Blocks.** Split the script into blocks of one beat each, about 10 s of narration per block
+(8–12 s is fine). A block's narration has to fit its clip: about 2.8 words per second (2.5 for
+Hindi) with one second spare, so about 25 words for a 10 s block (22 in Hindi). For every block
+write its narration line, its shots in the channel type's cut pattern (shot size, subject,
+action — 4 or 5 shots of about 2 s) and the assets it shows. That list is the plan.
+
+**1. Look and assets.** First a style key: one `generate_image` that fixes the look
+(medium, palette, line, light), shown to the user before any other image (in the kids-song mode the song comes first), since a
+change of look is cheap now and costly later. The style key takes `placement_kind="location"` and
+`placement_group="style key"`, so it sits on the reference board rather than in a shot row; it
+is not passed to the clips, since the assets carry the look. Then each recurring location, character and prop gets its own
+image made from the style key (`image_urls=[style key]`, `placement_kind` and its name as
+`placement_group`), as a full staged scene or a clear character design, never on a blank
+background. Review the assets (`review-shots` steps 0, 1 and 4).
+
+**2. Narration.** `generate_speech` per block; `wait_task` for the links.
+Each result's `duration_seconds` is the block's measured spoken length. A line whose `duration_seconds`
+leaves less than one second of its block's planned length is rewritten shorter and made again
+(voices run from about 2.5 to 3 words per second, so the word count is only a first guess); audio is never sped up, slowed or time-stretched in
+the cut. A shorter line is padded with silence.
+
+**3. Clips.** One `generate_video` per block, written as several hard-cut shots
+in one prompt, as set out in `get_skill_file(skill_id="faceless-story-video", path="references/multi-shot-prompt.md")`: the
+default model (Seedance 2.5, 4–30 s), `duration` = the block's narration `duration_seconds` plus about 1 s, rounded up to whole seconds (the narration is made first so
+the clip fits it, and the shot count follows the length, about one shot per 2 s), `reference_image_urls` =
+the block's assets in the order location, characters, props, `aspect_ratio` passed every time,
+`generate_audio=false` (the narrator carries the sound), `shot_number` = the block number.
+Characters gesture and react; they never talk. `wait_task`, then review the clips
+(`review-shots` steps 2 and 4) and count the cuts as that file describes; a block that merged
+its shots is retaken once with each shot's timing spelled out.
+
+When a look keeps merging shots, or on a still-picture run, use one shot per block instead:
+an image per block staged from the assets (`generate_image`, `image_urls=[style key, assets…]`,
+`shot_number`), then either `generate_video` from it (`first_frame_url`) with one camera move
+from the camera-movement presets (`list_presets(category="camera-movements")`, then
+`get_presets` for the move, such as `get_presets(["push-in"])`) and the scene otherwise
+unchanged, or, for still pictures, no video at all: the cut pans over the stills. Quote that
+clip with `first_frame=true` and `reference_count=0`. The camera-movement presets are written for
+products: put the shot's subject in place of "the product" in the preset's prompt (for example
+"slow steady push in toward the kid on the hill, everything else still").
+
+**4. Music.** `generate_music` for one bed matching the channel
+type's tone, `duration` = the total, at most 120 s (the tool's cap); for a longer story make one
+120 s bed and loop it at the join (`-stream_loop -1` on the bed input, `-shortest`).
 
 **5. Cut (free).** `run_ffmpeg` takes at most 10 inputs and 4 outputs, so the cut is passes, `wait_task`
-after each (its outputs are the next pass's inputs): per scene, mix its narration over its clip (or pan over its
-still) into `sceneN.mp4` at exactly the clip's `duration` (`tpad`/`apad` over-pad,
-`-t <duration>` sets the length), up to four scenes per call (one output each) and fewer when their files would pass ten inputs
-(a clip plus its narration is two inputs and four such scenes fill a call); then concatenate the scenes in order in groups of at
-most 10; then one last call joins the groups, mixes the music under at low volume and
-burns captions from an `.ass` sidecar (one cue per scene, timed from those clip
-durations). Output `final.mp4`, review the finished cut (`review-shots` step 5), and return the
+after each (its outputs are the next pass's inputs): per block, mix its narration over its clip (or pan over its
+still) into `blockN.mp4`, the narration starting 0.2 s into the block (`adelay=200:all=1`, then
+`apad`), at exactly the clip's `duration` (`tpad`/`apad` over-pad,
+`-t <duration>` sets the length), up to four blocks per call (one output each) and fewer when their files would pass ten inputs
+(a clip plus its narration is two inputs and four such blocks fill a call); then concatenate the blocks in order in groups of at
+most 10; then one last call joins the groups, scales the cut to the frame's full size
+(1080×1920 for 9:16, 1920×1080 for 16:9; clips come smaller), mixes the music under at
+`volume=0.15` with `amix=inputs=2:duration=first:normalize=0` (`apad` on the bed) and burns
+captions from an `.ass` sidecar. With four blocks or fewer, the concatenation, music and captions
+go in that one call after the block pass (two `run_ffmpeg` calls in all). Captions: one cue per
+phrase of at most 8 words (split long sentences at a comma), at most two lines, each block's
+cues timed by splitting its narration's `duration_seconds` across its phrases by character
+count, from the narration's start. `PlayResX`/`PlayResY` match the scaled size, and one style:
+`Noto Sans`, Bold -1, Fontsize 62, PrimaryColour &H00FFFFFF, OutlineColour &H00000000,
+BorderStyle 1, Outline 5, Shadow 2, Alignment 2, MarginL and MarginR 80, MarginV 420 (above a
+phone's on-screen controls; 120 for 16:9). Captions are on by default for this format, off when
+the user asks. Output `final.mp4`, review the finished cut (`review-shots` step 5), and return the
 link and `open_in_frameo`.
 
 ## Done
 
-The video and the review note per scene (passed, retaken and why, or kept with a known
-flaw) and for the finished cut, plus every scene image and clip in the Frameo project.
-`open_in_frameo` on the result opens the project in the Frameo app, where every take sits on
-the canvas, ready for retakes and edits.
+The video and the review note per block (passed, retaken and why, or kept with a known flaw,
+including a block that kept fewer cuts than planned) and for the finished cut, plus the style
+key, every asset and clip in the Frameo project.
+`open_in_frameo` on the result opens the project in the Frameo app, where every take is ready for retakes and edits.
 
 ## Files
 
-None.
+- `references/channel-types.md` — the default look, pacing, cut pattern, narrator tone and music per channel type, read in Ask first and at step 0.
+- `references/multi-shot-prompt.md` — how to write a block as timed hard-cut shots, how to count the cuts, and when to fall back to one shot per block, read at step 3.
+- `references/kids-song.md` — a kids music video: the song written and made first, blocks staged to it, read when a kids run is a song.