Metadata-Version: 2.4
Name: scenecast
Version: 0.1.0
Summary: Add your logo and your clips. Get a finished, on-brand video. Everything else is automatic.
Project-URL: Homepage, https://github.com/roomcareos/scenecast
Project-URL: Documentation, https://github.com/roomcareos/scenecast#readme
Project-URL: Source, https://github.com/roomcareos/scenecast
Author: RoomCare Ltd
License: MIT License
        
        Copyright (c) 2026 RoomCare Ltd
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: branding,ffmpeg,local,render,video
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.11
Requires-Dist: defusedxml==0.7.1
Requires-Dist: jinja2==3.1.5
Requires-Dist: jsonschema==4.23.0
Requires-Dist: numpy==2.2.1
Requires-Dist: pillow==11.1.0
Requires-Dist: playwright==1.49.1
Requires-Dist: pyyaml==6.0.2
Provides-Extra: dev
Requires-Dist: pytest==8.3.4; extra == 'dev'
Requires-Dist: ruff==0.9.2; extra == 'dev'
Description-Content-Type: text/markdown

# Scenecast

![tests](https://github.com/roomcareos/scenecast/actions/workflows/ci.yml/badge.svg)

**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

```bash
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:

```bash
# 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:

```bash
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

```bash
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:

```bash
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`.

```yaml
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.
