cerul-ai/cerul

cerul-ai/cerul has 166 GitHub stars and 9 forks. GitHot measured 0 in 7 days and +1 in 15 days. Last checked 2026-11-11 03:23 UTC. Last push 2026-10-22.

How these counts are measured

Open-source video processing core and CLI. Search and annotate local videos with your own model endpoints.

166 stars 9 forks

Measured star growth

in 24h: Update delayed
in 7 days: 0
in 15 days: +1
in 1 month: Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

README.md

Original

Help AI understand, remember, and access video.

Open-source video processing core and CLI. Use your own model endpoints, without a Cerul account.

Website · Quickstart · Install with an agent · Configuration · X / Twitter · Discord

English · 简体中文 · 繁體中文

Search your videos with words

Cerul turns local videos into a searchable library. Describe a moment, find text spoken or shown on screen, and save matching clips. It works with ordinary video folders, using your own model API key.

Search by meaning or example. Use a sentence or a reference image.
Find speech and screen text. Transcription plus local, embedded OCR.
Keep useful results. Export clips and structured semantic annotations.
Resume where you left off. Completed work is cached; rerun after interruption.

Getting started

Cerul is a command-line tool for searching videos and saving clips. The download includes the media tools and OCR models it needs.

Supports macOS Apple Silicon and Linux x86_64 (Ubuntu 24.04 or newer).

1. Install

curl -fsSL https://cerul.ai/install.sh | sh

Later, cerul upgrade installs the newest release over this one and leaves your workspace, key, and annotations alone.

2. Add a video

cerul index ./demo.mp4

On first use, follow the prompt to enter your Gemini API key, or save one ahead of time with cerul auth set. Cerul keeps it on your computer for future runs.

[!IMPORTANT] Model processing sends your video data to Gemini and may incur API charges. Run any command with --dry-run first to see exactly what will be sent.

Run cerul on its own at any time to see what is indexed and what to do next.

3. Search and save clips

cerul search "A person puts a cup on the table"
cerul search "A person puts a cup on the table" --save ./clips

Each result is a card with the match percentage, the time range, and a link. In iTerm2, Ghostty, Kitty, or WezTerm it also shows a still frame of the moment; add --no-preview to turn that off. With IINA installed the link opens the video at the matched moment instead of the beginning.

Results are numbered, so cerul open 2 plays the second moment in your video player without leaving the terminal.

Cleaning up

cerul remove ./demo.mp4      # remove its index and sidecars; keep the video
cerul remove --cache         # free regenerable disk space

Shell completions live in the installation guide.

More examples →

Robotics workflows

Robot demonstration labels, human-hand tracking, LeRobot datasets and annotated review videos are maintained in Cerul Robotics. See the migration guide for commands and existing data.

Let your agent do the setup

Copy this prompt into an agent that can use a terminal:

Install Cerul by following https://github.com/cerul-ai/cerul/blob/main/docs/agent-setup.md. Help me set up my Gemini API key securely, search a local video, and save a matching clip. Teach me the commands in my language.

Agents that read skills can learn the whole command line from Cerul itself:

cerul skill --install claude    # also: codex, pi, or --dir ./skills

Agent setup guide → · Agent contract →

Common commands

Goal	Command	When to reach for it
Index a folder	`cerul index ./videos`	Walks subfolders and skips work already done
Preview the work	`cerul --dry-run index ./videos`	See the plan, and what will call a model, before paying for it
Check progress	`cerul status`	After an interruption, or to find where sidecars live
Search one video	`cerul search "opening a door" --in ./demo.mp4`	Skip the rest of the library
Replay a result	`cerul open 2`	Open a numbered match in your video player
Cut clips by intent	`cerul clip ./talk.mp4`	Propose quoted moments across every angle, then `--export 1,3` renders them with captions

Sidecar files preserve transcripts, annotations, and vectors alongside your media. Search indexes can be rebuilt from them without model calls. LeRobot subtask writeback is available as an explicit opt-in.

Configure models

Cerul calls your own model endpoints, so you pick the providers and pay for your own usage. Run cerul config to change any of it.

Stage	Default	Alternatives
Multimodal search	Gemini Embedding 2, at 3072 dimensions	Any configured endpoint
Speech transcription	Gemini, whenever a key is available	Groq, OpenAI, an OpenAI-compatible service, or disabled
Screen text (OCR)	Runs locally, no API calls	—

Indexing builds video and text search data without generating scene descriptions, chapters, or summaries. Use cerul analyze ./video.mp4 for scenes and an overview, with Robotics for embodied semantic labels. --no-audio skips speech independently of everything else.

Model endpoints and credentials → · Inspect saved output →

How it works

Indexing encodes video, screen text, and optional speech into a shared multimodal space. Independent visual generation produces timed annotations for actions, interactions, and state changes, including embodied and egocentric recordings.

Proposed Cerul architecture: multimodal indexing and search, with an independent egocentric annotation pipeline

Architecture with AI-generated illustrative frames. Default search combines independent video, speech, screen-text, and description candidates with gated full-text matches using max fusion and capped agreement. Original evidence and timestamps remain inspectable. Robotics owns dataset writeback. See DESIGN.md for implemented behavior.

Learn more

Community

Questions, bug reports, and clips you are proud of are all welcome.

Discord · Issues · X / Twitter

License

Cerul's Rust code is Apache-2.0. Bundles also contain separately licensed media tools and OCR weights; see third-party notices. The Cerul name and logo identify the project and do not imply endorsement of third-party products.