Story Telling

Story Telling Video Skill

Environment

• Node 20+, npm. No bun and no ffmpeg anywhere in the pipeline
• Remotion 4.0.512, every @remotion/* on one version, mediabunny 1.50.8
• Narration: Sarvam AI bulbul:v3, returns WAV, played directly with no conversion
• Images: FLUX 2 on fal.ai, fal-ai/flux-2-pro for text to image and

fal-ai/flux-2-pro/edit to restyle a reference photo the user owns

• Drafting: OpenAI, optional, one call, only used by npm run draft
• Durations: @remotion/media-parser with nodeReader, never ffprobe
• Keys and every model id come from .env, loaded by cli/env.ts from the

project root and from the parent folder. SARVAM_KEY aliases SARVAM_API_KEY

• Fonts: @remotion/google-fonts, loaded at module level with explicit weights
• Output: 1920x1080 landscape or 1080x1920 vertical, 30fps, H.264
• Stories live in public//, renders in out/
• Never use icons or emoji in code, prompts, logs, narration or commit messages

Critical Rules

1. story.json is the single source of truth. Script, image prompts, voice,

fonts, colours, stat cards and measured durations all live in public//story.json. The composition reads it through calculateMetadata. Never hardcode a duration, size or asset path in a component.

1. Audio drives length. npm run generate measures every voice file and

writes durationInFrames back. durationInFrames and audioDurationInSeconds are outputs, never hand edited. To lengthen a video, change the words or raise outro.durationInFrames, never stretch a scene.

1. Show the narration before generating. Voices and images cost money and

take minutes. A wrong figure caught in review is free.

1. Facts come only from the given context. Nothing inferred, rounded or

assumed. When the source contradicts itself, prefer body text over headline and tell the user which reading was used.

1. Spell numbers as words in narration, digits only on stat cards. "thirty

four thousand crore" is spoken, Rs 34,387 cr is shown.

1. Never name a real person in an image prompt. Use a reference photo the

user owns through the edit model, or describe the person generically. In an edit prompt the likeness clause comes first, scene direction second.

1. One art style for the whole story. style.artPrompt is prepended to

every image prompt. That single string is what makes the frames feel like one film rather than a stock photo set.

1. Animate with useCurrentFrame() and interpolate(), inline in the

style prop, always clamped. CSS transitions, CSS animations and Tailwind animation classes render as still frames.

1. Use scale, translate, rotate CSS properties, not transform

strings, with output: "perceptual-scale" on scale animations.

1. Respect the video safe area. 80px from the sides, 100px from top and

bottom at 1080 wide, scaled by composition width. Headlines at least 84px, supporting text at least 44px on the same scale. Take sizes from getLayout(), never typed pixel constants.

1. Image ids are global across the story, not per scene. A reused id

silently overwrites a frame, and zod will not catch it.

1. Skip work that already exists. The generator skips any voice or image

already on disk. Delete exactly what should change and rerun; --force should be rare.

1. Never commit .env, a key, or generated media. story.json regenerates

everything else, and keys must never reach a settings file or a skill file.

Modular Rule Files

| Rule File | Topic | |---|---| | [story-json](rules/story-json.md) | The schema field by field, full example, cheap edit recipes | | [narration](rules/narration.md) | Script shape, word budget per duration, TTS-safe phrasing, stat cards | | [voices](rules/voices.md) | Complete bulbul voice catalog, 11 languages, pace and temperature, font pairing | | [images](rules/images.md) | FLUX 2 models, prompt recipe, reference photos, likeness, real failure modes | | [models](rules/models.md) | Every model id, where it is configured, how to choose, cheap iteration loop | | [story-formats](rules/story-formats.md) | Format catalog with scene skeletons and stat placement | | [composition](rules/composition.md) | Remotion best practices the components follow | | [workflow](rules/workflow.md) | Commands, key verification, cost and timing, troubleshooting | | [pitfalls](rules/pitfalls.md) | The fourteen common mistakes, plus both checklists |

Story Templates (in rules/assets/)

Schema-validated starting points. Copy to public//story.json, change slug and compositionId, rewrite the narration and prompts, then generate.

| Format | Path | Length | Scenes | Images | |---|---|---|---|---| | Biography | assets/biography/story.json | 60s | 6 | 12, uses a reference photo | | Concept explainer | assets/explainer/story.json | 60s | 6 | 9, metaphor led | | Vertical short | assets/reel/story.json | 30s | 3 | 3, 1080x1920 | | Numbered list | assets/listicle/story.json | 60s | 6 | 7, numbered stat cards | | News or event | assets/news/story.json | 45s | 5 | 7, dated claims | | Myth versus fact | assets/myth-buster/story.json | 45s | 5 | 5, alternating |

Companion Skills

| Skill | Use for | |---|---| | story-setup | First run: Node check, install, .env, key verification, version alignment | | story-new | Context to finished video, with a script review step | | story-render | Change one line, one image, the voice or the orientation, then re-render |

Pipeline

context (article, notes, a paragraph, a page already read)
   |
   |  npm run draft            OpenAI, optional. Or write story.json yourself.
   v
public//story.json       script, image prompts, voice, style, stats
   |
   |  npm run generate         Sarvam voices, FLUX 2 images, measured durations
   v
public//                 voice-0.wav ... image-1.jpg ... story.json updated
   |
   |  calculateMetadata        reads story.json, sets size, fps, durationInFrames
   v
npx remotion render  out/.mp4 --codec h264

Instructions

1. Check the pipeline exists before anything else. These skills drive a

Remotion project. If the skills were installed on their own, cli/ and src/ are not present yet and must be fetched once:

``bash test -f cli/generate.ts && test -f src/Root.tsx && echo present || echo missing ``

If missing, run the story-setup skill, which fetches the project with npx --yes degit marketcalls/story-telling story-telling, installs dependencies, creates .env and verifies the keys. Everything below runs from the project root.

1. Read the rules you need from the table above. story-formats first if the

shape is not decided, narration and images before writing anything.

1. Confirm the environment: .env with SARVAM_API_KEY and FAL_KEY,

npm install done. If unsure, run the story-setup skill.

1. Settle three things with the user if not already clear: orientation, length

in seconds, and whether reference photos are involved.

1. Write public//story.json from a template, or draft it with

npm run draft and then fix the facts by hand.

1. Show the narration and wait for approval.
2. npm run generate -- --slug .
3. Preview with npm run studio, then render.
4. Run the shipping checklist in rules/pitfalls.md.
5. Report measured numbers: scene count, duration, image count, output path and

size, plus any assumption made about an ambiguous fact.

Commands

npm install                                          # once
npm run story    -- --slug big-bull --context ./article.md --seconds 60 [--render]
npm run draft    -- --slug big-bull --context ./article.md --orientation vertical
npm run generate -- --slug big-bull [--only voice|images] [--force] [--logs]
npm run studio
npm run typecheck
npx remotion render BigBull out/big-bull.mp4 --codec h264

--context accepts a file path or the text itself. Any folder under public/ containing a story.json becomes a composition automatically, named after the slug in PascalCase, so nothing is registered by hand.

Project Layout

.env                       keys and every model id
cli/
  env.ts                   loads .env from here and from the parent folder
  service.ts               Sarvam, FLUX 2 text to image, FLUX 2 edit, OpenAI
  draft.ts                 context  ->  story.json
  generate.ts              story.json  ->  assets  ->  measured durations
  story.ts                 draft, generate and optionally render in one go
src/
  Root.tsx                 story discovery, calculateMetadata
  StoryVideo.tsx           scene timeline, audio, outro
  components/              ImageLayer, Subtitle, StatCard, TitleCard, OutroCard
  lib/schema.ts            zod schema shared by the CLI and the composition
  lib/layout.ts            safe areas and type scale, both orientations
  lib/fonts.ts             module level font loading
public//             story.json, voice-N.wav, image-N.jpg
out/                       rendered mp4

Worked Example

public/jhunjhunwala/story.json is a complete 6 scene, 58.7 second landscape story: cartoon art, two reference photos restyled through flux-2-pro/edit, stat cards on four scenes, and a silent outro. Read it before writing a new one. Its media files are gitignored, so regenerate them with npm run generate -- --slug jhunjhunwala.

Example Usage

/story-telling turn this article into a sixty second explainer /story-new big-bull ./article.md 60 landscape /story-render big-bull images

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: marketcalls
• Source: marketcalls/story-telling
• License: MIT

Install and usage instructions live in the source repository linked above.