# video-script

Intelligent short-form & long-form video scripting microservice: turn a topic into scroll-stopping hooks, a full beat-structured script for a target duration, a retention-beat map...


Intelligent video-scripting microservice. Turns a **topic** into everything you need to shoot a
short- or long-form video: scroll-stopping **hooks**, a **beat-structured script** sized to a target
duration, a **retention-beat** timeline, **timed captions** (SRT), a **scene/B-roll list**, and
**call-to-action** variants.

Every tool has a deterministic heuristic/template core that runs **fully offline** with no model. The
generative tools (`hook`, `script`, `cta`) also try an optional LLM (via `../_shared/llm.js`) and
**silently fall back** to the template when no model is reachable. Results carry `mode: 'heuristic' | 'llm'`.

## Tools

| Tool | Args | Returns |
|---|---|---|
| `hook` | `{ topic, count?, tone?, audience?, platform? }` | ranked hook variants (formula-driven; optional LLM rewrite) |
| `script` | `{ topic, duration?, wpm?, tone?, platform?, audience? }` | beat framework (hook→context→value beats→payoff→CTA) with per-beat word/time budgets + full `scriptText` |
| `retentionBeats` | `{ topic, duration? }` | pattern-interrupt / open-loop / re-hook timeline + predicted retention curve |
| `captions` | `{ script, wpm?, options.maxCharsPerCaption? }` | timed subtitle cues + a ready `.srt` string |
| `sceneList` | `{ topic?, script?, duration?, wpm? }` | shot-by-shot scene plan (shot type, narration, text overlay, B-roll) |
| `cta` | `{ goal?, platform?, count?, audience?, options.product?, options.link? }` | ranked call-to-action variants |

`duration` accepts `60`, `'60s'`, `'2m'`, `'1m30s'`. `platform` ∈ `tiktok|reels|shorts|youtube|ad|explainer`.

## Example

```js
import pack from './index.js';

const s = await pack.adapters.script({ topic: 'cold email that gets replies', duration: '60s', platform: 'shorts' });
console.log(s.beats.map(b => `${b.label} (${b.durationSec}s): ${b.line}`));

const caps = pack.adapters.captions({ script: s.scriptText, wpm: 150 });
console.log(caps.srt);
```

## DRY boundaries

- Not **seo** (that generates page meta tags / sitemaps / JSON-LD, not spoken video narrative).
- Not **a-text** (generic string transforms) or **chatbots** (conversational agents).
- Caption timing here is spoken-word cue timing, distinct from **datetime** clock math.
- Self-contained: no cross-pack imports except `../_shared/llm.js`.


---
Source: shared/engines/adapters/domain/video-script/README.md
Canonical: https://docs.leumas.tech/p/adapters/domain/video-script