storybook-intro

name	storybook-intro
author	Noustiny
license	MIT
version	1.0.0
description	Decide cinematic intro parameters for the Noustiny storybook tool. Given a story title, snapshot path beats and an image count, choose the right pace, tone, transition and duration so the opening montage matches the story's energy. Use this skill whenever the noustiny_storybook tool is being invoked in audiobook mode and any of intro_pace, intro_tone, intro_transition, intro_duration_secs are left for the agent to decide.
metadata	{"hermes":{"tags":["video","intro","storybook","marvel","noustiny","cinematic","montage"],"homepage":"https://github.com/noustiny/noustiny-skills","related_skills":[]}}

Storybook Intro Director

You are deciding how the opening cinematic of a Noustiny storybook plays. The tool you'll dispatch to is noustiny_storybook. Your output is the parameter set, not the video — the tool's render service does the actual ffmpeg / Playwright work.

This is a directing decision: pace, colour palette, transition style and total length. A wrong call here makes a story about a dystopian detective feel like a children's birthday slideshow, or compresses an epic fantasy into a 3-second blink.

When to invoke

Trigger this skill whenever:

1. The web app message contains mode=audiobook (intros only run in audiobook mode — mode=intro is itself a standalone teaser, no separate intro is rendered).
2. The user message says "intro_style=auto" or omits the cinematic parameters (intro_pace, intro_tone, intro_transition, intro_duration_secs). Auto mode is the contract that says "AI, you choose."

If the user message explicitly sets intro_pace=fast intro_tone=marvel-red ..., respect those — they overrode you. Only fill what's missing.

Inputs you have

The web app composes a user message like:

Render a Noustiny storybook. snapshot_id=<id>, endpoint_id=<id>, mode=audiobook,
audio=true, language=tr, intro_style=marvel, intro_duration_secs=auto.
Story tone hint: dark psychological thriller. Image count: 7.

Extract:

• story_title — the title field if present, otherwise infer from endpoint_id slug
• tone_hint — explicit phrase like "dark psychological thriller" or "epic heroic fantasy"
• image_count — number of images that will feed the montage (typically the path length, capped at 12)
• user_duration — slider value if the user picked one (e.g. intro_duration_secs=10); auto means you choose
• language — tr | en | es | fr | de (doesn't change pace/tone but adjusts how you label the title beat)

Decision rules

1. intro_tone — colour palette

Map tone hint to one palette key:

Story tone hint	Pick
epic, heroic, superhero, action, blockbuster	marvel-red
triumphant, mythic, royalty, fantasy hero, coming-of-age	hero-gold
sci-fi, tech, mystery, cyberpunk, neon noir	cinematic-cyan
dark, detective, dystopian, thriller, war	noir-gray
magical, arcane, dream, fairytale, witch, sorcery	magical-purple
horror, gore, slasher, blood, demonic	horror-blood

If the hint is empty or ambiguous, fall back to cinematic-cyan — it's the cleanest default and reads as "premium movie trailer" without committing to a sub-genre.

2. intro_pace — per-image visible time

pace controls cuts-per-second. Higher cut density = more energy regardless of tone; the chosen tone palette colours the visuals, not the cadence. Use these HARD rules in order:

1. image_count >= 5 → ALWAYS fast. Many images at slow pace reads as a slideshow no matter the tone. The renderer auto-loops the stack to fill duration; the cycle cap (3×) keeps it sane.
2. image_count == 4 → medium by default; bump to fast if tone is marvel-red/horror-blood/hero-gold; bump to slow if tone is noir-gray/magical-purple.
3. image_count <= 3 → slow (each beat earns the screen). Bump to medium only if tone is marvel-red/horror-blood.

Implementation seconds (reference only, not your decision): fast=0.30s/img, medium=0.70s, slow=1.30s. Don't recompute pace from duration / image_count — that math fights the loop logic.

3. image_loop — repeat the stack

Default is image_loop=true whenever pace=fast. At fast pace each image gets ~0.45s on screen, which means the stack burns through quickly and the rest of the timeline would go black if we don't cycle. Marvel's opening montage works precisely because the imagery keeps flooding — a held-still tail kills the energy.

Concrete rules:

• pace=fast → image_loop=true, full stop. The viewer should feel the same images cycling on top of each other to drive momentum.
• pace=medium → image_loop=true only when image_count <= 4 AND duration >= 7s (otherwise the stack covers the timeline naturally).
• pace=slow → image_loop=false always. Slow pace + loop reads as cheap padding.

4. intro_transition — keyframe profile

Pace × tone	Pick
fast + any tone	cut (Marvel rapid cuts)
medium + marvel-red/horror-blood	whip (motion energy)
medium + any other	fade (cinematic crossfade)
slow + any tone	fade (let images breathe)

Edge case: if image_count >= 8, force cut — too many slow fades blur the montage into mush.

5. intro_outro — exit overlay to the audiobook body

The intro's settle frame holds at scale 1.0, then the audiobook's first narrated page lands. Without an outro the cut feels brutal. Pick the overlay that bridges the energy:

Tone × pace	Pick
marvel-red or horror-blood (any pace)	fade-black (theatrical curtain)
hero-gold or magical-purple (any pace)	page-close (book-closing storybook feel)
cinematic-cyan (any pace)	split-vertical (sci-fi vault close)
noir-gray (any pace)	split-vertical (detective-room reveal)
pace=slow (any tone)	prefer hold — the stillness IS the moment

If the user explicitly chose intro_outro=<value>, respect it.

Default if unclear: fade-black for fast pace, hold for slow pace, page-close for medium pace.

6. beat_transition — how audiobook beats connect

After the intro outro lands, the audiobook body plays each path beat in sequence. This param decides how those beats join:

• hardcut — no fade, beat hard-cuts to next beat. Fits urgent / fast pace and tones with built-in adrenaline (marvel-red, horror-blood).
• fade-chapter — each beat fades in from black + out to black. Reads as a chapter break and matches storybook narration cadence.

Rules:

• pace=fast AND tone in (marvel-red, horror-blood) → hardcut
• pace=slow (any tone) → fade-chapter
• otherwise → fade-chapter (default — most stories want chapter feel)
• if path length ≥ 12 → still fade-chapter but the renderer auto-shortens the per-beat fade; you don't need to bump anything

7. voice_gender — TTS narrator gender

Picks a male or female neural voice within the chosen language locale. Drive from tone:

Story tone	Pick
horror, war, dark detective, dystopian, gore	male (gravelly storyteller)
magical, fairytale, coming-of-age, fantasy, sci-fi	female (warm narrator)
epic hero, heroic fantasy, action	male (heroic narrator)
triumphant / royal / mythic	female (regal voice)

If the user explicitly chose voice_gender=<x>, respect it.

Default if unclear: female.

8. voice_style — TTS prosody profile

Drives rate + pitch on the neural voice for narrative texture.

Story tone	Pick
horror, war, dystopian, gore	dramatic (slow + deeper)
thriller, detective, noir	whisper (hushed intimate)
fairytale, coming-of-age, magical	bright (lively + brighter)
epic hero, triumphant, sci-fi, default	narrator (warm storyteller)

9. subtitle_source — caption text origin

Decides which node field becomes the on-screen caption.

• audiobook mode (default) → body-snippet so subtitles match the spoken language, since both come from the same field.
• intro mode → title (cinematic identity, short label is enough).
• User explicitly wants no captions → none.

10. chapter_markers — seek-bar bookmarks

Embed FFMETADATA chapter list?

• audiobook → true (long content benefits from MPC/VLC navigation).
• intro → false (too short to matter).

11. narration_translate — translate body to audio locale before TTS

When the snapshot's narrative bodies are likely in a different language than the requested language, the renderer can translate each body via Hermes before TTS — keeping spoken line and subtitle in the same locale.

Rules:

• The user message tells you language=<x>.
• Inspect the Story tone hint + Ending beat snippets the route forwards. If those phrases look like the audio language, body is probably already in that language → narration_translate=false.
• If the tone hint contains characters from a different alphabet than the requested locale (Turkish letters ı, ş, ğ, ç while language=en; or Latin while language=tr and the hint mentions Turkish words) → narration_translate=true.
• When in doubt and language != tr → set narration_translate=true. Snapshot bodies are most often Turkish in this Noustiny instance.

Default: false for language=tr renders, true otherwise.

12. intro_sfx — synthetic SFX track on the intro mp4

The renderer mirrors the JS plan composer in Python and places one audio "hit" at every visual cut, so SFX cadence locks to image cadence — no manual timing math. A final settle hit lands at the outro start. Pick by tone:

Story tone	Pick
marvel-red, horror-blood, action	marvel-jet (whip whoosh per cut + final jet pass)
hero-gold, magical-purple, fairytale	page-turn (paper crinkle per cut)
cinematic-cyan, sci-fi	whoosh (soft low pass + deep settle)
noir-gray, dystopian, dread	cinematic-rumble (sustained low rumble, no per-cut hits)
user explicitly wants silent intro	none

Default if unclear: marvel-jet (most generic energetic option).

13. intro_duration_secs — total seconds

If the user picked a slider value (e.g. intro_duration_secs=10), respect it.

If auto, the rule is static, not math-derived: the NOUSTINY logo needs a fixed window to read its zoom-out smoothly regardless of how many images are stacked behind it. The renderer auto-loops the image stack inside that window at 50ms-per-image cuts (fast pace), so adding more images doesn't lengthen the intro — it just packs more cycles into the same 10 seconds.

if image_loop:
    duration = 10.0     # static — many-image case, loops within window
else:
    # No-loop mode: per-image pace × image_count + 1s tail, but still
    # clamped to a minimum so the logo animation doesn't strobe.
    duration = clamp(round(pace_seconds * image_count + 1.0), 6, 10)

Concrete picks:

image_count	image_loop	duration
40, fast	true	10s (5 cycles of 40×50ms)
15, fast	true	10s (~13 cycles of 15×50ms)
6, fast	true	10s (~33 cycles — pleasant flicker, but logo reads)
6, slow	false	clamp(round(0.7×6+1), 6, 10) = 6s
3, slow	false	clamp(round(0.7×3+1), 6, 10) = 6s (clamp floor)

Output contract

You don't write prose for this skill. You produce a single tool call to noustiny_storybook with all parameters filled. Pass through the snapshot_id / endpoint_id / mode / audio / language exactly as the user message stated. Decide the cinematic params per the rules above.

Example — user said intro_style=auto, tone hint "epic Avatar-style hero quest", 6 images:

{
  "snapshot_id": "abc123...",
  "endpoint_id": "n_xyz",
  "mode": "audiobook",
  "audio": true,
  "language": "tr",
  "intro_style": "marvel",
  "intro_pace": "fast",
  "intro_tone": "hero-gold",
  "intro_transition": "cut",
  "intro_outro": "page-close",
  "intro_duration_secs": 5.5,
  "image_loop": false
}

Reasoning trace (don't include in the tool call, but think it):

6 images, "epic hero quest" → hero-gold for triumph, fast pace because we have enough images to cut through, cut transition (Marvel rapid montage). Duration 6×0.45 + 1.5 = 4.2 → clamped up to 5.5s. No loop needed.

Anti-patterns

• Picking slow + 8 images + 12 seconds — produces a sluggish slideshow.
• marvel-red for a kids' fairytale — pick hero-gold or magical-purple.
• image_loop=true with pace=slow — the loop becomes obvious and cheap.
• Forgetting intro_style=marvel when filling intro_pace/tone/transition — those atomic params only apply when the high-level style is marvel. If the user wants detroit or cinematic, leave atomic params at defaults.
• Returning prose advice instead of dispatching the tool. The web app is waiting on a video URL, not your essay.