scenecast 0.1.0

Add your logo and your clips. Get a finished, on-brand video. Everything else is automatic.

Scenecast

Add your logo and your clips. Get a finished, on-brand video. Everything else is automatic.

Scenecast reads your brand straight from your logo, reads the scenes in your own footage, writes your colours and your text onto the video, and encodes the finished file. It all happens on your own machine, and nothing is uploaded.

Status: early development. Phase 1 is the first working release. See the roadmap below.

---

Why it is different

• Two inputs, and that is all. A logo and a folder of clips. No timeline to build, no code to write, no spec to hand-author.
• Your brand, read from your logo. Scenecast pulls your colours out of the logo and applies them across the video, with text contrast checked so it always stays readable.
• It watches your footage. Scene detection finds every cut, and your text cards land on those cuts on their own.
• Yours, and private. It runs locally. Your media never leaves your machine, and the tool is built to stand up to hostile files.
• Looks right by default. Card timing and spacing follow a house style tuned for reading, so the result looks considered with no fiddling.

How it compares. Remotion turns React code into video: you write components. editly assembles a video from a JSON spec: you write the spec. Scenecast takes a logo and a folder of clips: you write nothing.

---

Quick start

scenecast auto ./logo.png ./clips

One command. Scenecast reads your brand from the logo, watches your footage (up to five minutes per clip), keeps the best moments and drops the dull ones, writes the on-screen story itself from what it sees, cuts with clean dissolves and a gentle push-in, places every line where the frame is calm, and renders a polished vertical film in your colours. Video-only, ready to post; sound is added in the TikTok or Reels editor.

Every choice is recorded beside the output in a story file: which moments were kept, which were dropped and why, and every written line. Run again with --seed 2 for a fresh take on the story, --length 40 for a longer film, or --dry-run to read the plan before rendering anything.

Prefer your own words? Write them in a config and use the crafted modes:

# 1. read your brand from your logo (writes theme.json)
scenecast brand ./logo.png

# 2. build the video from your config (writes output.mp4)
scenecast build ./scenecast.yaml

Two commands, a finished branded video, nothing uploaded anywhere.

Prefer to be walked through it? Run scenecast init for a short set of questions (orientation, audience, resolution, length), and it writes the config for you.

Cinematic film mode

Give it video clips and get a polished, vertical, video-only story film for TikTok, Reels, or Shorts. It cuts and grades your footage, reads the scenes, and lays elegant text and effects on top:

scenecast film ./scenecast.yaml       # writes a cinematic MP4, no audio track

It reads a short hook, a few beats (each mapped to a scene, with an optional small label), and a one-line ending from your config, holds each line long enough to read, cross-dissolves between clips, and ends cleanly on your logo. The regal serif ships inside the tool, so the look is the same everywhere. Sound is added later in the social editor.

The commands

scenecast auto LOGO CLIPS      # everything automatic: analyse, write, cut, render
scenecast init                 # answer a few questions, write a config
scenecast brand LOGO           # read the palette from a logo, write theme.json
scenecast probe MEDIA_DIR      # list what is in a media folder
scenecast build [CONFIG]       # build a branded slideshow video
scenecast film  [CONFIG]       # cinematic film from your own copy
scenecast preview [CONFIG]     # render a keyframe contact sheet to check first

Where a command takes a config and you do not give one, it looks for --config, then for ./scenecast.yaml. Add --dry-run to plan without rendering.

---

How it works

1. Brand. Your logo goes in. Scenecast extracts a colour palette, picks readable text colours that pass a contrast check, and writes a theme.json you can hand-edit.
2. Media. Your photos and clips are validated, cleaned up, and fitted to your chosen shape (landscape, portrait, or square).
3. Scenes. Scenecast samples each clip at an interval matched to its length, finds the cuts, and refines each one to the exact frame.
4. Cards. Your text lines are placed on the scene changes, timed for comfortable reading, and never overlapping.
5. Render. The whole thing is composed as an HTML timeline, captured frame by frame in a headless browser, and encoded to MP4 with ffmpeg. The render is reproducible and resumable.

---

Install

Requires Python 3.11 or newer, and ffmpeg (which includes ffprobe) on your machine. ffmpeg is the free video engine Scenecast uses to read your clips and write the finished MP4, so install it first: on macOS brew install ffmpeg, on Debian or Ubuntu sudo apt install ffmpeg.

Phase 1 runs from a source checkout while packaging is prepared:

git clone https://github.com/roomcareos/scenecast
cd scenecast
python -m venv .venv && source .venv/bin/activate
pip install -e .
python -m playwright install chromium   # one-off, downloads the browser

That gives you the scenecast command. A published pip install scenecast and a container image with the browser and ffmpeg pinned are to follow.

See CONTRIBUTING.md for a development setup.

---

Configuration

The minimum is a logo and a folder of clips. Everything else has a sensible default. A commented example lives in scenecast.example.yaml, and the full shape is defined in config.schema.json.

output:
  orientation: "9:16"      # 16:9 | 9:16 | 1:1 | 4:5
  resolution: "1080p"      # 720p | 1080p | 1440p | 2160p
  fps: 30

brand:
  logo: "./assets/logo.png"

media:
  items:
    - "./clips/opening.mov"
    - "./photos/site-01.jpg"
    - "./clips/flyover.mp4"

cards:
  lines:
    - { scene: 1, text: "First light over the site" }
    - { scene: 3, text: "Six acres, cleared and ready" }

---

Security and privacy

Scenecast runs locally and sends nothing off your machine. It processes untrusted media and renders HTML, so it is built with a full threat model and a hardened default posture: safe command execution, a restricted headless browser with no network egress, strict media validation, path confinement, resource limits, and metadata stripping. The details are in SECURITY.md. To report a security issue, see the disclosure section there.

---

Roadmap

• Phase 1 (MVP): brand extraction with contrast gate, config wizard, media validation, scene detection with refinement, deterministic ordering with quality gates, scene-mapped text cards, the render pipeline, resumable rendering, silent-by-default output, and a preview contact sheet.
• Phase 2: heuristic "best bits" selection, optional supplied audio, more platform presets.
• Phase 3: learned aesthetic selection, optional auto-drafted card text (always human-reviewed), transcription and subtitles.
• Phase 4: an optional MCP server, shipped with its full security posture.

Full detail in PRD.md.

---

Licence

MIT. See LICENSE.

Built by RoomCare.