Open source · v1.2.0 · MIT

A little foresight.
A better final cut.

Four senses for your media. Inspect the render, surface concrete evidence, and give your agent a verdict small enough to use.

Standalone Python toolkit + one Hermes Agent tool.

01 / Perception

Four ways to look closer.

Local analysis by default. A vision provider only when you configure one.

01 — HEAR

Know what was said.

Word-timed transcription, script differences and labelled mix estimates. Beat detection adds tempo, onsets and estimated bars, downbeats and sections.

02 — SEE

Find the right shot.

Scene detection finds shots, fades and cached thumbnails. CLIP searches 1–3 frames per shot by phrase or reference image. Export shot lists and edit markers.

03 — READ

Catch visible details.

Full-size OCR, spelling hints and persistent safe-zone evidence. Lone characters stay uncertain.

04 — JUDGE

Ask for evidence.

One bounded visual critique. Your brief and rules, concrete findings, validated JSON and OCR cross-checks.

02 / The loop

From render to evidence.

Reuse the work. Frames, transcripts and embeddings live in a shared artifact cache.

Render

Make your video with the tools you already use. Hermes hooks can notice new and modified outputs.

Check

Measure signals, beats and cut pacing; read text and review cut frames. Flash safety estimates flag rapid luminance or red flashing: estimate, not a certified Harding test.

Compact verdict

Get small JSON with the important findings and a path to the full Markdown or HTML report.

Fix & re-check

Mechanical level fixes write a new .cbfix file. The original remains, and the output is checked again.

03 / Clear evidence

Small verdict.
Full paper trail.

Keep long transcripts, images and repeated findings out of the model's context. Follow artifact paths when you need the detail.

The standalone CLI and Hermes tool share the same engine. Tool results normally fit in 1,500 UTF-8 bytes and never embed images.

Check passed ≠ approved.
Static samples cannot hear, establish continuous motion or judge lip-sync. Two critique rounds, then human direction.
SYNTHETIC EXAMPLE · EXTRACTreport.html
WARN Generated test pattern · youtube
Full decodePASS
Black framesPASS
Subtitles · noneWARN
Audio ASR · example engine unavailableSKIP
Vision · quick signal gateSKIP
Full evidence → cache/results/…/report.md
04 / Start local

A toolkit you can own.

Python 3.11+, ffmpeg and Tesseract. User-installed models. No bundled footage or weights.

Standalone

TERMINALLinux / macOS
python3 -m venv .venv
.venv/bin/python -m pip install .
.venv/bin/crystal-ball setup
cp crystal-ball.example.toml crystal-ball.toml
# Set your engine and model paths.
.venv/bin/crystal-ball doctor
.venv/bin/crystal-ball check render.mp4 --json

Run from a downloaded or cloned checkout. Setup prints the pinned install and model download steps; ordinary actions stay offline.

Hermes Agent

ONE TOOLcrystal_ball
{
  "action": "check",
  "file": "/media/render.mp4",
  "mode": "quick",
  "platform": "youtube"
}

Run python3 scripts/install_hermes.py --hermes-home DIR to copy the plugin, its private package and skill into your chosen profile without pip. Configure engines, then run hermes plugins enable crystal-ball. See the repository README for all commands.

Debounced background checks · two concurrent jobs · once-per-file reminders · three reminders per session · fail-open hooks.

05 / No guessing

Know what is available.

crystal-ball doctor checks binaries, engine versions, local model checksums, CPU/GPU availability and configured fallbacks.

It never downloads. Availability diagnostics are separate from a successful live inference test. Missing components stay visible as WARN or FAIL.

Illustrative table; run doctor for your actual machine. Run opt-in live tests with CRYSTAL_BALL_LIVE=1.

DOCTORillustrative availability
Example statuses, not this machine's results
StatusEngineEvidence
PASSffmpegVersion detected
PASShearModel hash · GPU / CPU
PASSreadTraineddata SHA256
WARNdemucsOptional; use labelled estimate
WARNjudgeBackend off
Open by design

MIT licensed. Yours to inspect.

Models and external binaries have separate licences.
See LICENSE and THIRD_PARTY_NOTICES.md in the repository.