iframesco

---

What it makes

	Short	Long-form
Canvas	1080×1920	1920×1080
Length	30-60 s	6-15 min, 5-8 chapters
Captions	burned-in karaoke	.srt for YouTube CC
Packaging	9:16 cover, title, description, tags	1280×720 thumbnail, chapter timestamps, title options

Every render ships with video.mp4, thumbnail(s), .youtube.json (title / description / tags / chapters), .srt, the script, and a credits file for Creative Commons media.

Built for retention, not just "a video"

The writer follows the structure that keeps viewers past the first 30 seconds (research notes):

1. Cold open on the most dramatic true moment. No greeting, no logo sting.
2. Promise: one specific line about what the viewer will understand.
3. Stakes: why it mattered.
4. Chapters that end on open loops: a question that pulls into the next chapter.
5. Payoff that answers the cold open.

Plus the packaging that earns the click: thumbnail hook and title written as one unit (never repeating each other), three title options, and chapters YouTube recognises.

Features

• Local writer: Ollama (qwen3:8b by default, auto-falls back to any installed model), outline → cold open → chapters.
• Grounded: research from the full Wikipedia article; a fact-check pass drops sentences whose numbers or years aren't in the source.
• Soothing narration, offline: Kokoro-82M voices, or Microsoft Edge neural voices with no install. Presets: soothing, storyteller, documentary, warm, british, energetic.
• Pronunciation control: respell hard names for the voice; captions keep the real spelling.
• Relevance-ranked footage: Pexels + Pixabay stock video (free keys) and Wikimedia Commons stills, re-ranked with CLIP against each narration line; near-duplicate shots rejected.
• Cinematic render: Ken Burns motion, crossfades, film grade, chapter lower-thirds, music ducked under the voice, -14 LUFS loudness, NVENC when your GPU supports it.
• Mood music: a local licensed library tagged by mood; generated ambient pad as fallback.
• Brand templates: accent colour, fonts, kicker/tagline, default voice and format per channel.
• Job queue that survives restarts (SQLite), extra worker processes, optional S3 mirror.
• YouTube connector: an MCP server + CLI for your channel: edit, schedule, thumbnails, playlists, captions, retention analytics, uploads, and "make me a video" from Claude.

Quick start

git clone https://github.com/MicoleKurt/iframesco && cd iframesco
pip install -e ".[all]"          # or: pip install -r requirements.txt
ollama pull qwen3:8b             # https://ollama.com (any model works; see FALLBACKS)
iframesco serve                # http://localhost:8000

Needs Python 3.10+ and ffmpeg on PATH.

iframesco make "How the Apollo 13 crew made it home" --format long --minutes 10
iframesco make "The history of coffee" --format short --voice storyteller
iframesco make "Apollo 13" --script examples/apollo-13-long.json --brand noir
iframesco voices                       # one sample per voice preset into samples/
iframesco safezone photo.jpg            # check caption/title placement against the Shorts UI

Optional free keys for real stock video: PEXELS_API_KEY, PIXABAY_API_KEY.

Publish from Claude (MCP)

iframesco youtube auth                                  # one-time Google consent
claude mcp add youtube -- python -m iframesco.mcp_server

Then ask: "Make a 10-minute video on the Apollo 13 rescue, upload it, add it to my History playlist and schedule it for Sunday 11 AM Eastern." Setup and limits: docs/YOUTUBE_CONNECTOR.md.

How it works

flowchart LR
  T[Topic or script] --> R[Wikipedia research]
  R --> O[Outline: cold open, chapters, open loops]
  O --> W[Chapter prose] --> F[Fact check]
  F --> V[Voice: Kokoro / Edge + word timings]
  F --> Q[Image queries]
  Q --> M[Pexels · Pixabay · Commons] --> C[CLIP re-rank + dedupe]
  V --> X[Render: Ken Burns, crossfades, grade, chapter cards]
  C --> X --> P[Package: mp4, thumbnail, srt, chapters, metadata]
  P --> Y[YouTube connector / MCP]

Configuration

Variable	Default
OLLAMA_MODEL	qwen3:8b	writer model
OLLAMA_NUM_GPU	0 (CPU)	-1 lets Ollama use the GPU (needs a recent NVIDIA driver)
FS_VOICE	soothing	default voice preset
FS_CLIP	1	0 disables CLIP ranking
FS_ENCODER	auto	force libx264 / h264_nvenc
PEXELS_API_KEY, PIXABAY_API_KEY	–	stock video
FS_S3_BUCKET, FS_S3_ENDPOINT	–	mirror outputs to S3 / R2 / MinIO
FS_MUSIC_DIR	music/	mood library (music/README.md)
FS_SAFE_TOP, FS_SAFE_BOTTOM, FS_SAFE_RIGHT	250 / 580 / 150	px of a Short that YouTube's own UI covers; captions and title cards stay clear of it

Script format

Write your own script and keep everything else automated:

{
  "title": "Apollo 13", "subject": "Apollo 13", "format": "long", "mood": "tense",
  "pronounce": {"Haise": "Haze"},
  "scenes": [
    {"narration": "Two hundred thousand miles from home, a bang shook the spacecraft ...", "keywords": ["Apollo 13 mission control"]},
    {"narration": "...", "keywords": ["Apollo 13 lunar module Aquarius"], "anchor": false, "pause": 0.8, "chapter": "The lifeboat"}
  ],
  "thumbnail": {"label": "Apollo 13", "hook": "Houston, we've\nhad a problem", "scene": 0},
  "youtube": {"title": "...", "description": "...", "tags": ["..."]}
}

anchor: false uses keywords as-is; chapter starts a chapter (long-form); rate / pause tune pacing per scene.

Accurate images. A keyword can point at Wikipedia instead of a free-text search:

• "wiki:Apollo 13" uses the photos editors placed in that Wikipedia article (logos, flags and icons skipped), ranked against the line.
• "file:Apollo 13 Mission Control.jpg" uses that exact Wikimedia Commons file. When every keyword of a scene is a file:, the photos are used in the order given.

Archive results are filtered: files whose titles name offensive or explicit material are dropped, CLIP rejects images that look like them, and maps, plans and casual snapshots rank lower unless the line asks for them.

Frame-1 hook (Shorts). "hook_text": "Two words that stop the scroll" shows a large line for the first two seconds, low in the frame so faces stay clear, and the first scene cuts to a new picture sooner.

Licensing of what you publish

iframesco's code is MIT. Media keeps its own licence: Commons files are credited automatically in the description and .credits.txt; Pexels/Pixabay don't require credit; YouTube clips are restricted to Creative Commons (CC BY) and credited. Kokoro is Apache-2.0. Check your music's licence.

Roadmap

• TikTok / Instagram publishing once their APIs allow it without app review
• On-screen maps and timeline graphics for long-form
• A/B thumbnail variants from the title options