Kelly Drama

---
name: kelly-drama
description: Short-drama and product-video development skill for planning drama projects through a bundled Busabase App-in-Skill UI, with each project linked to a specified HyperFrame project and each episode linked to a HyperFrame composition for final motion/video tuning. Use when the user asks to create, edit, organize, or review short-drama scripts, product explainer episodes, character consistency cards, series bibles, episode beat sheets, storyboard shots, HyperFrame project/composition links, production checklists, or a drama planning workbench.
metadata:
  category: production
  tags:
    - risk:local-write
    - surface:busabase
    - surface:moonrouter
    - surface:byteplus-ark
  busabase:
    template: true
    folderSlug: kelly-drama
    resources:
      - project
      - settings
      - characters
      - relationships
      - episodes
      - shots
      - tasks
    risk: local-write

---

# Kelly Drama

## App UI Screenshots

<table>
  <tr>
    <td width="50%"><img src="assets/screenshots/overview.webp" alt="Kelly Drama overview"></td>
    <td width="50%"><img src="assets/screenshots/episodes.webp" alt="Kelly Drama episode table"></td>
  </tr>
  <tr>
    <td><strong>Overview</strong><br>Series workbench with health dashboard, execution timeline, stats, and settings for series parameters.</td>
    <td><strong>Episode table</strong><br>Episode list with script and storyboard status, shot readiness indicators, and per-episode detail pane.</td>
  </tr>
  <tr>
    <td width="50%"><img src="assets/screenshots/characters.webp" alt="Kelly Drama character library"></td>
    <td width="50%"><img src="assets/screenshots/relationships.webp" alt="Kelly Drama relationship map"></td>
  </tr>
  <tr>
    <td><strong>Character library</strong><br>Character list with three-view image status, actor settings, wardrobe, and voice preview controls.</td>
    <td><strong>Relationship map</strong><br>Character relationship view with power dynamics, evidence links, and relationship detail pane.</td>
  </tr>
</table>

## Core Idea

Use this skill as a short-drama and product-video planning workspace. Keep the app as the human editing surface and planning system of record: the skill reasons, drafts, validates, exports, and fulfills the AI-generation requests the app can only queue. The app reads and writes a Busabase workspace — one Folder, seven Bases (project/settings/characters/relationships/episodes/shots/tasks) — plus Busabase Drive Assets for every generated character reference card, reference voice, storyboard image, and shot video.

Kelly Drama is **not** the final motion editor. For final video tuning, each Kelly Drama project should point to a concrete HyperFrame project path, and each episode should point to a concrete HyperFrame composition. Kelly Drama manages the creative plan, canonical beats, storyboard metadata, review state, and asset index; HyperFrame owns the final composition, animation, captions, audio timing, render, and publish pass.

Default to the AirApp for ongoing creative work — give the user the clickable AirApp URL, or run `pnpm --dir content/kelly-drama-app dev` for a local preview. Use chat-only mode only when the user explicitly asks for "chat only", "no UI", "纯聊天", or similar.

## Default Flow

1. Open the AirApp (or `pnpm --dir content/kelly-drama-app dev` for local preview, which asks you to connect Busabase and select a Space — never an API key).
2. On first run the workspace is empty; provision it from the app's setup screen, then seed the bundled starter with `node scripts/create_sample_project.mjs --apply` (a short-drama adaptation of 《三国演义》, one episode per original chapter), or start from scratch.
3. Use the app to maintain:
   - Series bible: logline, genre, platform, target audience, episode format, hook rules, world rules.
   - HyperFrame project link: `series.hyperframe_project_path` is the absolute path to the matching HyperFrame project. Do not guess it when the user has provided a path; store the explicit path.
   - Episode HyperFrame links: each episode can carry `hyperframe_composition` (for example `index.html` or `compositions/ep-002.html`) and `hyperframe_video_asset` (the rendered/reference output indexed back into Kelly Drama).
   - Visual bible: aspect ratio, screen orientation, realism target, cinematography, color palette, period detail, background reference images, and generated style anchors.
   - Character library: stable role id, actor profile, character card, three-view visual notes, wardrobe, voice, secrets, forbidden drift.
   - Character reference cards: generate character card images before storyboard/video work when consistency matters.
   - Character voice: keep a `voice_profile` (timbre/type, pace, accent, signature delivery, casting reference, sample audition line) and a `voice_reference` asset slot for a generated reference voice. Clicking "Generate reference voice" in the app only writes a **request** onto the character record (`voice_reference_status = "requested"`) — the browser cannot spawn the local Qwen3-TTS process. After the user asks, fulfill pending requests with `node scripts/execute_generation_requests.mjs --apply`, which spawns `scripts/gen_voice.py` with the `voice_profile` as the VoiceDesign `instruct` and `sample_script` as the line and uploads the result as a Busabase Asset; samples are non-destructive candidates (`voice_candidates`), pick the active one. Keep shot `audio.dialogue[].tone` and `srt` speakers aligned with each character's voice profile. `gen_voice.py` needs a local Python with `mlx_audio` installed (Apple Silicon); point `KELLY_DRAMA_TTS_PYTHON` at it. First run downloads `mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-8bit`.
   - Relationship map: relationship type, power direction, emotional temperature, conflict, evidence episodes.
   - Episode ladder: episodes, acts, beats, turning points, cliffhangers, emotional payload.
   - Storyboard bench: shots, image prompts, negative prompts, continuity anchors, production status.
4. After major edits, run `node scripts/validate_shot_readiness.mjs` before generating a shot's image or video (checks the video-ready Definition of Done below and flags overdense dialogue and characters missing reference cards).
5. Export a readable bible with `node scripts/export_story_bible.mjs` when the user wants a handoff, pitch note, or production brief.

## Kelly Drama ↔ HyperFrame Contract

Default architecture:

- One Kelly Drama project = one HyperFrame project.
- One Kelly Drama episode = one HyperFrame composition inside that project.
- Kelly Drama is for planning and management; HyperFrame is for final visual/motion/audio polish.

Use these fields consistently:

- `series.hyperframe_project_path`: absolute path to the HyperFrame project, e.g. `/Users/you/projects/my-app/videos/my-series`.
- `episode.hyperframe_composition`: composition filename/path relative to the HyperFrame project, e.g. `index.html` or `compositions/ep-001-introducing.html`.
- `episode.hyperframe_video_asset`: a reference to the rendered/reference video for this episode (a path or URL on the HyperFrame side, or a note pointing to it) indexed back into Kelly Drama.

The paired HyperFrame project lives on the operator's machine, never inside the Kelly Drama AirApp, so the app itself can never read it directly (the browser cannot access an arbitrary local filesystem path, and an AirApp process cannot either). Status is read by a trusted skill-root script instead: `node scripts/read_hyperframe_status.mjs --apply` scans the configured path for `hyperframes.json`, `design.md`, HTML compositions, scene ids, embedded audio tracks, rendered video files, thumbnails, and changelog notes, then caches the result on the project record (`hyperframe_status_json`) for the app's HyperFrame panel to display. This is for planning visibility and sync checks only; it must not mutate the HyperFrame project. Re-run the script after the HyperFrame project changes to refresh the cached status.

When importing an existing HyperFrame episode into Kelly Drama:

1. Read the HyperFrame project path the user supplied; run `node scripts/read_hyperframe_status.mjs --apply` to cache its current status.
2. Inspect the composition HTML, project `design.md`, relevant changelog notes, rendered video, and thumbnails/frames when available.
3. Create/update the Kelly Drama episode beats and storyboard shots to mirror the composition scenes.
4. Store the original source path and time ranges on the episode/shots so future syncs are traceable.
5. Run `node scripts/validate_shot_readiness.mjs`.

When planning a new episode first in Kelly Drama:

1. Draft the episode promise, beats, and storyboard shots in Kelly Drama.
2. Assign/confirm `series.hyperframe_project_path`.
3. Choose a stable `episode.hyperframe_composition` path before final production.
4. Treat the HyperFrame composition as the canonical final-cut surface once it exists; if the composition changes, re-import the new scene structure or update the Kelly Drama shots to match.

## Creative Operating Rules

- Preserve continuity first: every new scene should point to character ids, relationship ids, and prior facts instead of rewriting canon.
- Treat actors and characters separately. An actor can play a character, but the character card is the story source of truth.
- Write short-drama beats as production units: each beat needs a hook, conflict turn, emotional value, and either a reveal, reversal, choice, or cliffhanger.
- Treat episode runtime as flexible: a short-drama episode is usually 2-4 minutes, adjusted by story density rather than forced to a fixed length.
- Respect AI video model shot limits: one generated shot should be planned as 4, 5, 6, 8, 10, or 12 seconds, and never exceed 12 seconds in a single generation unit. Float the duration to the shot's information density — quick reactions/close-ups run short (4-6s), establishing/ceremony/group/action runs longer (8-12s). Do not pin every shot at 12s.
- Keep dialogue deliverable: Chinese dialogue should stay at or below ~8 characters per second of shot duration (ideal 5-7). Overdense lines cannot be performed in the shot length and waste video generations — trim the line, split the shot, or extend the duration.
- Keep image prompts grounded in stable anchors: character id, face/hair/body notes, wardrobe, camera, setting, mood, continuity constraints, and negative prompts.
- Storyboard images can be generated through an OpenAI-compatible Images API. Default model is `gpt-image-2`; default `BASE_URL` is `https://moonrouter.dev/v1` (base URL/model/size live on the `settings` Busabase record; the API key itself is the `KELLY_DRAMA_IMAGE_API_KEY` env var read only by `scripts/execute_generation_requests.mjs`, never stored or sent to the browser).
- Use real image-to-image conditioning for character consistency: storyboard generation feeds the existing character reference-card images (and the visual background reference) to the `/images/edits` endpoint as actual input images, not just as text. Text mentions of a reference path do nothing — the model must receive the pixels. If a character lacks a generated reference card, that shot falls back to text-to-image and consistency will drift, so generate the card first.
- Generate in dependency order: visual bible/background reference images first, then character reference-card images, then episode storyboard images, then video generation units. If character or background references are missing, create those before generating storyboard/video assets to avoid consistency drift and wasted generations.
- Finish the text before spending on pixels: a shot must reach the video-ready Definition of Done (below) and pass `scripts/validate_shot_readiness.mjs` before you generate its image or video. Thin shot data (missing motion, audio, transitions, timed dialogue) produces wasted image and video generations.
- For realism-oriented dramas, prompts should explicitly request live-action cinema stills, natural lensing, physical costumes, period-accurate sets, and "almost impossible to tell it is AI generated"; also forbid UI overlays, captions, watermarks, readable fake text, modern items, fantasy glow, and plastic-looking skin.
- Use "forbidden drift" on character cards for details the image or script generator must not change.
- Make relationship changes explicit. If two characters reconcile, betray, divorce, reveal kinship, or shift power, update the relationship map and evidence episode.
- Prefer concrete scene work over abstract summaries. A useful outline says what the audience sees, what the character chooses, and why the next episode is clicked.

## Storyboard Shot Definition of Done (video-ready)

A storyboard shot is "image-ready" once it describes a still frame, but final shot-video production needs more. Before generating a shot's image or video, the shot should carry a complete production sheet:

- Identity & timing: `id`, `episode_id`, `beat_id`, `title`, `characters` (valid ids), `duration_seconds` (in {4,5,6,8,10,12}), `duration_preset`, `aspect_ratio`, `emotion`.
- Camera spec (structured, not only free text): `shot_size`, `camera_angle`, `camera_movement`, `lens`, plus freeform `camera`, `composition`, `setting`, `lighting`.
- Motion: `action` — what actually moves over the shot's seconds (subject action, blocking changes, eyelines, prop and environment motion), distinct from the still composition.
- Generation prompts: `prompt` (structured still/keyframe prompt with character anchors and forbidden drift), `negative_prompt`, and `video_prompt` (a model-agnostic image-to-video motion prompt: camera move + subject action + environment motion).
- Audio/sound design: `audio` = `{ dialogue:[{speaker,line,tone}], narration, sfx:[], ambient, music }`.
- Timed dialogue: `srt` = `[{time, text, speaker?}]` with cumulative episode timecodes matching the durations, and dialogue density ≤ ~8 chars/second. Segment into multiple short cues (~1.5-4s, ≤18 chars each), not one block per shot.
- Pure-visual shots are allowed and encouraged for rhythm: a montage/atmosphere/action beat can be intentionally silent (set `silent: true`, no dialogue, empty `srt`). A silent shot still needs a sound bed (`audio.ambient`/`sfx`/`music`). Do not force a subtitle into every shot — let some breathe.
- Editorial: `transition_in`, `transition_out`.
- Continuity: `continuity` = `{ wardrobe, props:[], carries_from_prev, anchors:[] }` (anchors are forbidden-drift traits that must stay consistent).

The app's shot detail panel renders this whole sheet and shows a per-shot readiness chip; `scripts/validate_shot_readiness.mjs` enforces it (and flags overdense dialogue and characters missing reference cards). Treat any shot below this bar as not ready to generate.

## Video, Audio & Episode Assembly

Turning storyboards into an actual short drama (continuous episode with characters speaking) has its own pipeline and hard-won constraints:

- Visual style is a strategic choice tied to both audience and the video model's content filter. For an overseas (Western / Japan-Korea) audience, a non-photoreal **cinematic painterly ("Arcane-style") look** was chosen: it reads premium and international, and it avoids photoreal pitfalls. Drive the whole look from `series.visual_bible.style_medium`; every shot/character prompt inherits it. Switching style = update the visual bible + rewrite each prompt's `Style/medium` line + set `negative_prompt` to forbid `photorealistic, real person, live-action`, then regenerate character cards → storyboards (image-to-image keeps consistency).
- Storyboard video uses **Seedance 2.0 via BytePlus/Volcengine Ark** (`POST /contents/generations/tasks` → poll `GET …/{id}` → download). Constraints learned the hard way:
  - **Real-person filter**: rejects photoreal human keyframes for image-to-video; even stylized **close-up faces** can be flagged ("input image may contain real person"), while wide / group / medium shots pass. Do NOT silently fall back to text-to-video — surface the error. Mitigations: push faces more illustrated/cel-shaded (less photoreal), use 3/4 or non-front framing for close-ups, or add a second provider.
  - **Native audio**: `generate_audio` is on by default (synced ambient/foley); that auto-audio can trip an audio-safety filter, so retry the same shot with `generate_audio:false` (we dub our own dialogue anyway).
- **Non-destructive generation + candidates**: every image/video/voice generation appends a candidate (`image_candidates` / `video_candidates` / `voice_candidates`); the user picks the active one in the app (a Busabase record write, not a file rename). Different models/providers just add more candidates. Never overwrite.
- **Character voices**: local Qwen3-TTS (mlx-audio, Apple Silicon), VoiceDesign `instruct` built from each character's `voice_profile`. It tends to speak slowly — fit each line into its shot window with ffmpeg `atempo` during assembly.
- **Episode assembly** (the step that makes clips into a drama): per-shot visual sized to exactly the shot's duration (Seedance clip where available, else a Ken Burns `zoompan` move on the storyboard still) → `concat` into one silent episode video → synthesize each dialogue line (right voice), place it at its cumulative SRT time (`adelay`), atempo-fit to its shot window, and `amix` all lines → mux audio onto the video. Burned-in subtitles need an ffmpeg built with **libass** (the default Homebrew build here lacked the `subtitles` filter) — otherwise ship a `.srt` sidecar. **Lip-sync** is a later polish (cut to the speaker's close-up + a dedicated lip-sync model); ship voiceover-over-picture first.
- Local video generation on Mac (LTX-Video on MPS) proved impractical (tens of GB across multiple models, slow/thermal MPS, stalling downloads) — use cloud (Seedance/Ark) for video.

## Busabase Resources

One Folder (`kelly-drama`), seven Bases, declared in `content/kelly-drama-app/app/js/config.js` and the generated template sidecars under `content/`:

- `project`: single-row series bible + visual bible + the paired HyperFrame project path and its cached status (`hyperframe_status_json`, refreshed by `scripts/read_hyperframe_status.mjs`).
- `settings`: one row (`record-id: "config"`) with the image/video/TTS generation backend settings (base URL/model/size, LTX draft params, Seedance/Ark prod params, TTS model — API keys themselves are env vars for the trusted scripts, never stored).
- `characters`: character library — card (identity/motivation/wound/secret/arc/voice), three-view visual notes, wardrobe, anchors/forbidden-drift (JSON arrays), voice profile, and the reference-card + reference-voice status/prompt/asset id.
- `relationships`: directional relationships — type, public status, hidden truth, power dynamic, emotional temperature, conflict, evidence (JSON array).
- `episodes`: episode ladder — number, title, promise, A/B-plot, cliffhanger, beats (JSON array), and the paired HyperFrame composition/video-asset fields.
- `shots`: storyboard shots (`position` field carries order within an episode) — the full video-ready production sheet (camera spec, action, prompts, audio/srt/continuity as JSON), plus image/video asset id + status + JSON-encoded candidate list.
- `tasks`: freeform human/agent review tasks (`@ai` notes, missing-field follow-ups) — a distinct collection from generation requests, which live as status fields directly on the owning character/shot record.

Binary media (character reference-card images, reference-voice samples, shot
storyboard images/videos) are **Busabase Drive Assets**, not Base fields —
uploaded by the trusted generation scripts via `busabase-sdk`'s real `assets`
client (`createUploadUrl` → PUT bytes → `confirm`), with only the returned
asset id stored on the owning record. See `references/ui-schema.md` for the
full field <-> asset mapping.

Clicking a "Generate" button in the app only writes a **request** onto the
character/shot record (`reference_card_status` / `voice_reference_status` /
`image_status` / `video_status` = `requested`) — the browser cannot hold the
image-API key or spawn the local Qwen3-TTS/LTX-Video processes. After the
user asks, fulfill pending requests with `node scripts/execute_generation_requests.mjs --apply`
(dry run without `--apply`).

Resources provision lazily through an idempotent Busabase ChangeRequest the
first time the app runs in a Space. A soft-delete `deleted` text field
(`"true"`/`"false"`) backs the app's Delete buttons — there is no destructive
record delete in the write surface.

## When To Read References

- Read `references/drama-workflow.md` when designing or improving a short-drama project, character library, relationship map, episode ladder, or image prompt workflow.
- Read `references/ui-schema.md` when editing the app, generating/validating project data, or working with the Busabase field shapes or Drive Assets.

## Useful Commands

```bash
pnpm --dir skills/kelly-drama/content/kelly-drama-app dev
node skills/kelly-drama/scripts/create_sample_project.mjs --apply
node skills/kelly-drama/scripts/read_hyperframe_status.mjs --apply
node skills/kelly-drama/scripts/validate_shot_readiness.mjs --episode ep-001
node skills/kelly-drama/scripts/export_story_bible.mjs
node skills/kelly-drama/scripts/execute_generation_requests.mjs --apply
```

Run `validate_shot_readiness.mjs` (optionally `--strict` to fail on warnings) before any image/video generation pass to confirm shots meet the video-ready Definition of Done. Every trusted script here connects with its own credentials (`BUSABASE_BASE_URL` / `BUSABASE_API_KEY` / `BUSABASE_SPACE_ID`), never the AirApp's ambient session, and defaults to a dry run wherever it writes or generates.

Use paths relative to the skills repository root, or run the scripts from inside `skills/kelly-drama`.