cerul-ai/cerul

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

这些数字如何统计

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

166 星标 9 forks

实测星标增长

24小时: 0
7天: 0
15天: +1
1个月: 更新延迟

各周期内的星标净变化，周期相互重叠，并非每日新增。缺失的测量保持空白。星标代表关注度，不代表软件质量。

README.zh-CN.md

原文

让 AI 理解、记住并调用视频。

开源视频处理核心与 CLI。使用你自己的模型服务，无需 Cerul 账号。

官网 · 快速上手 · 让 agent 安装 · 配置 · X / Twitter · Discord

English · 简体中文 · 繁體中文

用一句话搜索你的视频

Cerul 将本地视频变成可搜索的资料库。描述一个画面，查找视频中说过或出现过的文字，再把匹配片段导出。支持普通视频文件夹，使用你自己的模型 API key。

按含义或图片搜索：输入一句描述，或提供参考图片。
查找语音和屏幕文字：语音转录配合内置的本地 OCR。
保存有用的结果：导出片段，生成结构化语义标注。
中断后继续：重复运行会复用已完成的工作。

快速开始

Cerul 是一个搜索视频、导出片段的命令行工具。安装包已包含所需的媒体工具和 OCR 模型。

支持 macOS Apple Silicon 和 Linux x86_64（Ubuntu 24.04 或更新）。

1. 安装

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

之后用 cerul upgrade 升级到最新版本，工作区、密钥和标注文件都不受影响。

2. 添加视频

cerul index ./demo.mp4

第一次使用时，按提示输入 Gemini API key，也可以提前用 cerul auth set 保存，之后无需重复输入。

[!IMPORTANT] 模型处理会把你的视频数据发送给 Gemini，并可能产生 API 费用。任何命令都可以先加 --dry-run，看清楚会发送什么再执行。

随时直接运行 cerul，可以看到已索引的视频和下一步命令。

3. 搜索并保存片段

cerul search "有人把杯子放到桌上"
cerul search "有人把杯子放到桌上" --save ./clips

每条结果是一张卡片，显示匹配度、时间区间和链接。在 iTerm2、Ghostty、Kitty 或 WezTerm 中还会显示该瞬间的画面截图，用 --no-preview 可以关闭。装了 IINA 时，链接会直接跳到匹配的时间点，而不是从头播放。

结果都有编号，cerul open 2 会用播放器直接从第二个片段开始播，不用离开终端。

清理数据

cerul remove ./demo.mp4      # 删除索引与旁车数据，保留原视频
cerul remove --cache         # 释放可再生的磁盘占用

shell 补全的配置见安装指南。

更多使用示例 →

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.

让 agent 帮你安装

把下面这段话发给能操作终端的 agent：

按 https://github.com/cerul-ai/cerul/blob/main/docs/agent-setup.md 帮我安装 Cerul，安全配置 Gemini API key，搜索一个本地视频并保存匹配片段，然后教我怎么使用。

支持 skill 的 agent 可以直接从 Cerul 学会整套命令行：

cerul skill --install claude    # 也支持 codex、pi，或 --dir ./skills

Agent 安装指南 → · Agent 接口约定 →

常用命令

目标	命令	什么时候用
处理整个文件夹	`cerul index ./videos`	会递归子目录，已完成的部分自动跳过
预览要做的事	`cerul --dry-run index ./videos`	花钱调模型之前，先看清处理计划
查看进度和结果	`cerul status`	中断之后继续，或查找 sidecar 位置
限定一个视频搜索	`cerul search "打开门" --in ./demo.mp4`	跳过资料库里的其他视频
回看某条结果	`cerul open 2`	用播放器打开编号对应的片段
按意图剪短片	`cerul clip ./talk.mp4`	先按各个角度列出带原话引用的候选片段，再用 `--export 1,3` 渲染带字幕的短片

转录、标注和向量保存在视频旁的 sidecar 文件中，可不调用模型重建搜索索引。

配置模型服务

Cerul 调用的是你自己的模型服务，供应商由你选择，费用也记在你自己账上。运行 cerul config 可以修改下面任意一项。

环节	默认	可选
多模态搜索	Gemini Embedding 2，3072 维	任意已配置的服务
语音转录	有可用 key 时默认用 Gemini	Groq、OpenAI、OpenAI 兼容服务，或关闭
屏幕文字（OCR）	本地运行，不调用 API	—

索引只构建视频和文字的搜索数据，不会生成场景描述、章节或摘要。需要场景和总览请用 cerul analyze ./video.mp4。--no-audio 可以单独跳过语音环节。

模型服务与凭据 → · 查看已保存的分析结果 →

工作原理

索引会把画面、屏幕文字和可选的语音编码到同一个多模态空间。另有一条独立的视觉生成流程，为动作、交互和状态变化生成带时间戳的标注，同样适用于具身与第一人称录像。

Cerul 架构：多模态索引与搜索，以及独立的第一人称标注流程

架构图中的画面由 AI 生成，仅作示意。默认搜索会把视频、语音、屏幕文字和描述四路独立候选，与受控的全文匹配结果，用 max fusion 和受限的一致性加权合并。原始证据和时间戳始终可以回溯查看。已实现的行为详见 DESIGN.md。

了解更多

社区

欢迎提问、报 bug，也欢迎分享你搜出来的得意片段。

Discord · Issues · X / Twitter

许可证

Cerul 的 Rust 代码采用 Apache-2.0。发行包中的媒体工具和 OCR 模型各自遵循其许可证，详见第三方声明。Cerul 名称与标识用于识别项目，不代表对第三方产品的背书。