@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/videocut/SKILL.md

@@ -1,159 +0,0 @@
----
-name: videocut
-description: "口播视频转录和口误识别。生成审查稿和删除任务清单。触发词：剪口播、处理视频、识别口误 Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "cocolayuan/videoclip-AI-skill"
----
-
-# 剪口播
-
-## Running it in AICUT
-
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-
-Where the words below name another program's part, it becomes this:
-
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-
-
-> 转录 + 口误/静音识别 → 生成审查稿
-
-## 快速使用
-
-```
-用户: 帮我剪这个口播视频
-用户: 处理一下这个视频
-```
-
-## 流程
-
-```
-1. FunASR 30s 分段转录（字符级时间戳）
-    ↓
-2. 识别口误（逐句检查）
-    ↓
-3. 识别微口误（VAD 检测短片段）
-    ↓
-4. 识别语气词（嗯/哎/诶 等）
-    ↓
-5. 识别静音（≥1s）
-    ↓
-6. 生成审查稿（时间戳驱动）
-    ↓
-7. 输出删除任务 TodoList
-    ↓
-【等待用户确认】→ 用户确认后，执行 /videocut:剪辑
-```
-
-### ⚠️ 为什么用 30s 分段
-
-FunASR 长视频有时间戳漂移，30s 分段可避免。
-
-## 进度 TodoList
-
-启动时创建：
-
-```
-- [ ] 读取「转录最佳实践」→ 转录视频
-- [ ] 读取「口误识别方法论」→ 识别口误
-- [ ] VAD 检测微口误（短片段 < 0.5s）
-- [ ] 扫描语气词（嗯/哎/诶 等）
-- [ ] 识别静音（≥1s）
-- [ ] 生成审查稿
-- [ ] 输出删除任务清单
-```
-
-### ⚠️ 必须先读方法论再执行
-
-| 阶段 | 先读 | 再执行 |
-|------|------|--------|
-| 转录 | `tips/转录最佳实践.md` | 调用ASR |
-| 识别口误 | `tips/口误识别方法论.md` | 逐句分析 |
-
----
-
-## 核心：时间戳驱动
-
-### 删除任务格式
-
-每项**必须标注精确时间戳** `(start-end)`：
-
-```
-口误（N处）：
-- [ ] 1. `(start-end)` 删"错误文本" → 保留"正确文本"
-
-语气词（N处）：
-- [ ] 1. `(前字end-后字start)` 删"嗯" 上下文: XX【嗯】YY
-
-静音（N处）：
-- [ ] 1. `(start-end)` 静音Xs
-```
-
-### 口误类型
-
-| 类型 | 示例 | 删除策略 |
-|------|------|----------|
-| 重复型 | `拉满新拉满` | 只删差异（"新"） |
-| 替换型 | `AI就是AI就会` | 删第一个完整版本（"AI就是"） |
-| 卡顿型 | `听会会` | 删第一个重复字 |
-
-### ⚠️ 关键规则
-
-1. **时间戳驱动**：审查稿直接标注时间戳，剪辑不再搜索文本
-2. **逐token分析**：对于"删前面保后面"的口误，必须逐token查时间戳
-3. **检查时间跨度**：如果口误时间跨度 > 2秒，必有静音，需拆分
-
----
-
-## 输出文件
-
-```
-01-xxx-v1_transcript.json  # 转录结果（含时间戳）
-01-xxx-v1_审查稿.md        # 口误审查稿
-```
-
-### 展示要求
-
-生成审查稿后，**必须展示给用户**：
-1. 写入文件 `01-xxx-v1_审查稿.md`
-2. 读取并展示内容
-3. 等待用户确认要删除哪些项目
-
----
-
-## 方法论
-
-详见 `tips/口误识别方法论.md`：
-- 口误识别方法（逐句检查）
-- "删前面保后面"的精确处理
-- FunASR 时间戳对齐规则
-
-## Source
-
-Rewritten for AICUT from [`cocolayuan/videoclip-AI-skill`](https://github.com/cocolayuan/videoclip-AI-skill)
-(MIT), 剪口播/SKILL.md. The method is that skill's own; the way it runs is AICUT's.
-
-The repository holds 6 skills; this is the one its entry stands for.

package/skills/videodb/SKILL.md

@@ -1,497 +0,0 @@
----
-name: videodb
-description: "See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- run analyzers over speech, scenes, objects, OCR, brands and activity; build searchable indexes; then search moments, ask questions about a video, filter and aggregate results with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "video-db/skills"
----
-
-# VideoDB Skill
-
-## Running it in AICUT
-
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-
-Where the words below name another program's part, it becomes this:
-
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-
-
-**Perception + memory + actions for video, live streams, and desktop sessions.**
-
-Use this skill when you need to:
-
-## 1) Desktop Perception
-- Start/stop a **desktop session** capturing **screen, mic, and system audio**
-- Stream **live context** and store **episodic session memory**
-- Run **real-time alerts/triggers** on what’s spoken and what's happening on screen
-- Produce **session summaries**, a searchable timeline, and **playable evidence links**
-
-## 2) Video ingest + stream
-- Ingest a **file or URL** and return a **playable web stream link**
-- Transcode/normalize: **codec, bitrate, fps, resolution, aspect ratio**
-
-## 3) Understand + index + retrieve (timestamps + evidence)
-- **Understand**: run analyzers over speech, scenes, objects, OCR, brands, activity
-- **Index**: turn analyzer artifacts into semantic, filterable, and aggregatable indexes
-- **Retrieve**: search moments, ask questions, filter exactly, count and group — with **timestamps** and **playable evidence**
-- Auto-create **clips** from results
-
-## 4) Timeline editing + generation
-- Subtitles: **generate**, **translate**, **burn-in**
-- Overlays: **text/image/branding**, motion captions
-- Audio: **background music**, **voiceover**, **dubbing**
-- Programmatic composition and exports via **timeline operations**
-
-## 5) Live streams (RTSP) + monitoring
-- Connect **RTSP/live feeds**
-- Run **real-time visual and spoken understanding** and emit **events/alerts** for monitoring workflows
-
----
-
-## Common inputs
-- Local **file path**, public **URL**, or **RTSP URL**
-- Desktop capture request: **start / stop / summarize session**
-- Desired operations: get context for understanding, transcode spec, index spec, search query, clip ranges, timeline edits, alert rules
-
-## Common outputs
-- **Stream URL** — make it playable: `https://console.videodb.io/player?url={STREAM_URL}`
-- Search results with **timestamps** and **evidence links**
-- Generated assets: subtitles, audio, images, clips
-- **Event/alert payloads** for live streams
-- Desktop **session summaries** and memory entries
-
----
-
-## Canonical prompts (examples)
-- “Start desktop capture and alert when a password field appears.”
-- “Record my session and produce an actionable summary when it ends.”
-- “Ingest this file and return a playable stream link.”
-- “Index this folder and find every scene with people, return timestamps.”
-- “Generate subtitles, burn them in, and add light background music.”
-- “Connect this RTSP URL and alert when a person enters the zone.”
-
-## Running Python code
-
-**CRITICAL:** Always `cd` to the user's project directory before running Python code. This ensures `load_dotenv(".env")` finds the correct `.env` file.
-
-```python
-from dotenv import load_dotenv
-load_dotenv(".env")
-
-import videodb
-conn = videodb.connect()
-```
-This reads `VIDEO_DB_API_KEY` from:
-1. Environment (if already exported)
-2. Project's `.env` file in current directory
-
-If the key is missing, `videodb.connect()` raises `AuthenticationError` automatically.
-
-Do NOT write a script file when a short inline command works.
-
-When writing inline Python (`python -c "..."`), always use properly formatted code — use semicolons to separate statements and keep it readable. For anything longer than ~3 statements, use a heredoc instead:
-```
-```bash
-python << 'EOF'
-from dotenv import load_dotenv
-load_dotenv(".env")
-
-import videodb
-conn = videodb.connect()
-coll = conn.get_collection()
-print(f"Videos: {len(coll.get_videos())}")
-EOF
-```
-
-## Setup
-
-When the user asks to "setup videodb" or similar:
-
-### 1. Install SDK
-
-```
-If `videodb[capture]` fails on Linux, install without the capture extra:
-```
-```
-The `>=0.5.0` pin matters — the understand/index/ask/aggregate APIs do not exist in earlier versions.
-```
-
-### 2. Configure API key
-
-The user must set `VIDEO_DB_API_KEY` using **either** method:
-
-- **Export in terminal (recommended)**: `export VIDEO_DB_API_KEY=your-key`
-- **Project `.env` file**: Save `VIDEO_DB_API_KEY=your-key` in the project's `.env` file
-
-Get a free API key at https://console.videodb.io ($20 free credits, no credit card required).
-
-**Do NOT** read, write, or handle the API key yourself. Always let the user set it.
-
-### 3. Authorize the hosted MCP server (Claude Code plugin only)
-
-The plugin bundles the hosted MCP server at `https://mcp.videodb.io/mcp`, which is
-authorized separately from the SDK key above. Tell the user to run `/mcp`, select
-**videodb**, and complete browser authorization with their VideoDB account. Verify with
-"list my VideoDB collections".
-
-The MCP tools need no local Python install and no API key. Skip this step when the skill
-was installed with `npx skills add` or is running outside Claude Code — there is no MCP
-server in that case, and the SDK path above is the only one available.
-
-## Quick Reference
-
-### Upload media
-
-```python
-
-# URL
-video = coll.upload(url="https://example.com/video.mp4")
-
-# YouTube
-video = coll.upload(url="https://www.youtube.com/watch?v=VIDEO_ID")
-
-# Local file
-video = coll.upload(file_path="/path/to/video.mp4")
-
-### Understand → index → retrieve (default path)
-
-Three stages. Run analyzers to produce **artifacts**, index each artifact, then retrieve.
-
-```python
-import time
-
-# 1. Understand. Naming each analyzer keeps `analyzer.name` meaningful downstream.
-understanding = video.understand(
-    analyzers=[
-        {"type": "spoken_words", "name": "transcript"},
-        {"type": "vlm", "name": "scene",
-         "config": {"prompt": "Describe the scene and any on-screen text."}},
-    ],
-    segmentation={"type": "shot", "threshold": 30},
-)
-
-# A run with a failed or skipped analyzer ends `partial`, which the SDK does not
-
-# treat as terminal — wait_until_complete() would poll to TimeoutError. Poll the
-
-# analyzers instead. The `analyzers and` guard is load-bearing: a refresh can
-
-# transiently return an empty list, and all([]) is True, which would exit the
-
-# loop while the run is still going.
-deadline = time.time() + 3600
-while time.time() < deadline:
-    analyzers = understanding.refresh().list_analyzers()
-    if analyzers and all(a.is_complete for a in analyzers):
-        break
-    time.sleep(15)
-
-# 2. Index each artifact that succeeded.
-for analyzer in understanding.list_analyzers():
-    if analyzer.is_successful:
-        video.index(source=analyzer, name=analyzer.name).wait_until_complete()
-
-# 3. Retrieve.
-response = video.search("discussion about pricing")
-for shot in response.shots:
-    print(f"[{shot.start:.1f}s - {shot.end:.1f}s] {shot.text}")
-if response.response_type in ("shots", "deepsearch") and len(response):
-    stream_url = response.compile()   # raises SearchError otherwise
-```
-Analyzer types: `spoken_words` (→ artifact `transcript`), `vlm` (→ `scene`), `object_detection` (→ `objects`), `ocr`, `brand_detection` (→ `brands`), `activity_recognition` (→ `activity`), `location_detection` (→ `location`), `faces`, `audio_event_detection`. They are plain strings — there is no SDK enum.
-
-See [reference/indexing.md](reference/indexing.md) for segmentation, sampling, field configuration, and cost tuning.
-```
-
-### Retrieval
-
-`search(query)` is the default — it plans the retrieval and picks the indexes itself. Reach past it when you need something specific:
-
-```python
-
-# Target a specific index, with a relevance floor
-video.semantic_search("a customer holding the product", index_names=["scene"], score_threshold=0.7)
-
-# Exact filtering, no natural-language interpretation
-video.query(index_name="objects",
-            filter=[{"field": "frames.detections.label", "op": "contains", "value": "car"}])
-
-# Counts and facets — returns the raw server payload, not a SearchResult
-video.aggregate(index_name="objects", group_by="frames.detections.label", metric="count")
-
-# A written answer plus the moments it came from
-answer = video.ask("What did they say about pricing?", include_sources=True)
-```
-All five exist on `Collection` too, fanning out across every indexed video. See [reference/search.md`search.md`.
-
-**`search()` now returns `SearchResponse`, not `SearchResult`.** `get_shots()`, `compile()`, `play()`, and iteration all work, but there is no `.stream_url` on it — use `.compile()`.
-```
-
-### Transcript + subtitle
-
-```python
-
-# force=True skips the error if the video is already indexed
-video.index_spoken_words(force=True)
-text = video.get_transcript_text()
-stream_url = video.add_subtitle()
-```
-`index_spoken_words()` is the correct call here even on 0.5.0 — `add_subtitle()` and `CaptionAsset(src="auto")` read the v1 spoken-word index. A v2 `spoken_words` artifact does not substitute for it. This is the one place v1 indexing is still the right answer.
-```
-
-### Legacy indexing (existing codebases)
-
-```python
-
-# v1 API — still supported in 0.5.0, not deprecated. New code should use the v2 path above.
-from videodb import IndexType
-
-video.index_spoken_words(force=True)
-scene_index_id = video.index_scenes(prompt="Describe the visual content.")
-results = video.legacy_search(
-    "person writing on a whiteboard",
-    index_type=IndexType.scene,
-    scene_index_id=scene_index_id,
-)
-```
-Recognise this pattern in existing repos and leave it alone unless asked to migrate — it still works. See [reference/migration.md](reference/migration.md) to port it, or [reference/legacy/search.md](reference/legacy/search.md) to maintain it.
-```
-
-### Timeline editing
-
-Use the Editor API to compose videos, images, audio, and text. See [reference/editor.md](reference/editor.md) for full workflow.
-
-```python
-from videodb.editor import Timeline, Track, Clip, VideoAsset, ImageAsset, AudioAsset, Fit
-
-timeline = Timeline(conn)
-timeline.resolution = "1280x720"
-
-video_track = Track()
-video_track.add_clip(0, Clip(asset=VideoAsset(id=video.id, start=10), duration=20))
-
-audio_track = Track()
-audio_track.add_clip(0, Clip(asset=AudioAsset(id=music.id, volume=0.2), duration=20))
-
-timeline.add_track(video_track)
-timeline.add_track(audio_track)
-stream_url = timeline.generate_stream()
-
-### Transcode video (resolution / quality change)
-
-```python
-from videodb import TranscodeMode, VideoConfig, AudioConfig
-
-# Change resolution, quality, or aspect ratio server-side
-job_id = conn.transcode(
-    source="https://example.com/video.mp4",
-    callback_url="https://example.com/webhook",
-    mode=TranscodeMode.economy,
-    video_config=VideoConfig(resolution=720, quality=23, aspect_ratio="16:9"),
-    audio_config=AudioConfig(mute=False),
-)
-
-### Reframe aspect ratio (for social platforms)
-
-**Warning:** `reframe()` is a slow server-side operation. For long videos it can take
-several minutes and may time out. Best practices:
-- Always limit to a short segment using `start`/`end` when possible
-- For full-length videos, use `callback_url` for async processing
-- Trim the video on a `Timeline` first, then reframe the shorter result
-
-```python
-from videodb import ReframeMode
-
-# Always prefer reframing a short segment:
-reframed = video.reframe(start=0, end=60, target="vertical", mode=ReframeMode.smart)
-
-# Async reframe for full-length videos (returns None, result via webhook):
-video.reframe(target="vertical", callback_url="https://example.com/webhook")
-
-# Presets: "vertical" (9:16), "square" (1:1), "landscape" (16:9)
-reframed = video.reframe(start=0, end=60, target="square")
-
-# Custom dimensions
-reframed = video.reframe(start=0, end=60, target={"width": 1280, "height": 720})
-
-### Generative media
-
-```python
-image = coll.generate_image(
-    prompt="a sunset over mountains",
-    aspect_ratio="16:9",
-)
-
-### Sandbox Compute (self-hosted / open-weight models)
-
-Run open-weight models (Gemma, Qwen, Whisper, OmniVoice, FLUX, RT-DETR) by creating a sandbox and passing `sandbox_id` to a supported job. Requires `videodb>=0.5.1`.
-
-```python
-from videodb import SandboxTier, SandboxModel
-
-# 1. Create a sandbox sized for the largest model, then wait until active.
-sandbox = conn.create_sandbox(
-    tier=SandboxTier.medium,
-    models=[SandboxModel.GEMMA_4_31B.value],   # exact ID, NO -FP8 suffix
-)
-sandbox.wait_for_ready(timeout=300, interval=5)
-
-# 2. Understanding: set config.model + config.sandbox_id on the analyzer.
-understanding = video.understand(analyzers=[{
-    "type": "vlm", "name": "scene",
-    "config": {"model": "google/gemma-4-31B-it", "sandbox_id": sandbox.id,
-               "prompt": "Describe the scene."},
-}])
-
-# 2b. Generation: pass model_name + sandbox_id (jobs return GenerationJob → .wait()).
-response = coll.generate_text(prompt="Summarize this.", model_name="Qwen/Qwen3.5-9B",
-                             sandbox_id=sandbox.id, max_tokens=300)
-job = coll.generate_image(prompt="a city at sunset", model_name="black-forest-labs/FLUX.1-dev",
-                          sandbox_id=sandbox.id)
-image = job.wait(timeout=900, interval=5)
-
-# 3. Stop when done — provisioning/active/alert all count toward the tier limit.
-sandbox.stop(); sandbox.wait_for_stop()
-```
-Model IDs must match the catalog exactly (**no `-FP8` suffix**) or `create_sandbox` raises `Unsupported sandbox model`. See [reference/sandbox.md`sandbox.md` for the full model catalog, tiers, categories, pricing, and pitfalls.
-```
-
-## Error handling
-
-```python
-from videodb.exceptions import AuthenticationError, InvalidRequestError
-
-try:
-    conn = videodb.connect()
-except AuthenticationError:
-    print("Check your VIDEO_DB_API_KEY")
-
-try:
-    video = coll.upload(url="https://example.com/video.mp4")
-except InvalidRequestError as e:
-    print(f"Upload failed: {e}")
-
-### Common pitfalls
-
-| Scenario | Error message | Solution |
-|----------|--------------|----------|
-| Search result has no stream URL | `AttributeError: 'SearchResponse' object has no attribute 'stream_url'` | `search()` returns `SearchResponse` in 0.5.0. Use `results.compile()` |
-| `search(score_threshold=)` searches the wrong indexes | no error, unexpected results | `score_threshold` does not route to legacy. Use `semantic_search(score_threshold=)`, or `legacy_search()` for v1 indexes |
-| Semantic index on object detection | `use_for includes semantic but no scene has embeddable text` | Object artifacts have no top-level text. Omit `use_for` (it degrades automatically) or pass `["query", "aggregate"]` |
-| Indexing a field that does not exist | `fields.filter names not present in any scene's data` | The error lists the available field names — read it. Or check `index.field_schema` |
-| Search finds no matches | v2 returns an empty `SearchResponse`; only `legacy_search()` raises `InvalidRequestError: No results found` | Check `len(response)`. Wrap only legacy calls in try/except |
-| Indexing an already-indexed video (v1) | `Spoken word index for video already exists` | Use `video.index_spoken_words(force=True)` to skip if already indexed |
-| Reframe times out | Blocks indefinitely on long videos | Use `start`/`end` to limit segment, or pass `callback_url` for async |
-| Negative timestamps on Timeline | Silently produces broken stream | Always validate `start >= 0` before creating `VideoAsset` |
-| `generate_video()` / `create_collection()` fails | `Operation not allowed` or `maximum limit` | Plan-gated features — inform the user about plan limits |
-
-## Additional docs
-
-Reference documentation is in `${CLAUDE_SKILL_DIR}/reference/`. Read files there with that prefix; the links below are relative to this SKILL.md.
-
-- [reference/api-reference.md](reference/api-reference.md) - Complete VideoDB Python SDK API reference
-- [reference/indexing.md](reference/indexing.md) - Understand → index pipeline: analyzers, artifacts, segmentation, field configuration
-- [reference/indexing-reference.md](reference/indexing-reference.md) - Analyzer catalog and Understanding/Index class reference
-- [reference/search.md`search.md` - Retrieval guide: search, ask, semantic_search, query, aggregate
-- [reference/search-reference.md`search-reference.md` - Retrieval signatures, filter syntax, response objects
-- [reference/migration.md](reference/migration.md) - v1 → v2 mapping and SDK 0.5.0 breaking changes. Read when you find v1 code
-- [reference/editor.md](reference/editor.md) - Timeline editing workflow guide (4-layer model, use cases, examples)
-- [reference/editor-reference.md](reference/editor-reference.md) - Editor code reference (constructors, parameters, enums)
-- [reference/streaming.md`streaming.md` - HLS streaming and instant playback
-- [reference/generative.md](reference/generative.md) - AI-powered media generation (images, video, audio)
-- [reference/sandbox.md`sandbox.md` - Sandbox Compute workflow (run open-weight models: Gemma, Qwen, Whisper, OmniVoice, FLUX, RT-DETR)
-- [reference/sandbox-reference.md`sandbox-reference.md` - Sandbox code reference (create/get/list/stop, tiers, model catalog, sandbox-aware generation)
-- [reference/rtstream.md`rtstream.md` - Live stream ingestion workflow (RTSP/RTMP)
-- [reference/rtstream-reference.md`rtstream-reference.md` - RTStream SDK methods and AI pipelines
-- [reference/capture.md](reference/capture.md) - Desktop capture workflow
-- [reference/capture-reference.md](reference/capture-reference.md) - Capture SDK and WebSocket events
-- [reference/use-cases.md`use-cases.md` - Common video processing patterns and examples
-
-Legacy v1 indexing and search. These APIs still work and are not deprecated, but read these only when maintaining existing v1 code:
-
-- [reference/legacy/index.md](reference/legacy/index.md) - v1 scene indexing and frame extraction workflow
-- [reference/legacy/index-reference.md](reference/legacy/index-reference.md) - v1 scene index code reference (SceneCollection/Scene/Frame)
-- [reference/legacy/search.md](reference/legacy/search.md) - v1 spoken-word and scene search
-
-## Screen Recording (Desktop Capture)
-
-Use `ws_listener.py` to capture WebSocket events during recording sessions. Desktop capture supports **macOS** only.
-
-`${CLAUDE_SKILL_DIR}` is this skill's install directory, set by Claude Code. On agents that do not set it, substitute the directory holding this SKILL.md.
-
-### Quick Start
-
-1. **Start listener**: `python "${CLAUDE_SKILL_DIR}/scripts/ws_listener.py" --cwd=<PROJECT_ROOT> &`
-2. **Get WebSocket ID**: `cat /tmp/videodb_ws_id`
-3. **Run capture code** (see reference/capture.md for full workflow)
-4. **Events written to**: `/tmp/videodb_events.jsonl`
-
-### Query Events
-
-```python
-import json
-events = [json.loads(l) for l in open("/tmp/videodb_events.jsonl")]
-
-# Get all transcripts
-transcripts = [e["data"]["text"] for e in events if e.get("channel") == "transcript"]
-
-# Get visual descriptions from last 5 minutes
-import time
-cutoff = time.time() - 300
-recent_visual = [e for e in events 
-                 if e.get("channel") == "visual_index" and e["unix_ts"] > cutoff]
-
-### Utility Scripts
-
-- `${CLAUDE_SKILL_DIR}/scripts/ws_listener.py` - WebSocket event listener (dumps to JSONL)
-
-For complete capture workflow, see [reference/capture.md](reference/capture.md).
-
-
-**Do not use ffmpeg, moviepy, or local encoding tools** when VideoDB supports the operation. The following are all handled server-side by VideoDB — trimming, combining clips, overlaying audio or music, adding subtitles, text/image overlays, transcoding, resolution changes, aspect-ratio conversion, resizing for platform requirements, transcription, volume control, fade transitions, and media generation. Only fall back to local tools for operations listed under Limitations in reference/editor.md (speed changes, crop/zoom, colour grading, keyframe animation).
-
-### When to use what
-
-| Problem | VideoDB solution |
-|---------|-----------------|
-| Make a video searchable | `video.understand(analyzers=[...])` then `video.index(source=analyzer)` |
-| Find moments by what was said or shown | `video.search(query)`, or `semantic_search(index_names=[...])` to target an index |
-| Answer a question about a video | `video.ask(question, include_sources=True)` |
-| Count or group what appears in a video | `video.aggregate(index_name=..., group_by=..., metric="count")` |
-| Filter moments on exact field values | `video.query(index_name=..., filter={...})` |
-| Platform rejects video aspect ratio or resolution | `video.reframe()` or `conn.transcode()` with `VideoConfig` |
-| Need to resize video for Twitter/Instagram/TikTok | `video.reframe(target="vertical")` or `target="square"` |
-| Need to change resolution (e.g. 1080p → 720p) | `conn.transcode()` with `VideoConfig(resolution=720)` |
-| Need to overlay audio/music on video | `AudioAsset` on an Editor `Timeline` with volume control |
-| Need to add subtitles | `video.add_subtitle()` or `CaptionAsset` on Editor `Timeline` |
-| Need to combine/trim clips | `VideoAsset` on an Editor `Timeline` |
-| Need to compose images with voiceover | `ImageAsset` + `AudioAsset` on separate Editor tracks |
-| Need to generate voiceover, music, or SFX | `coll.generate_voice()`, `generate_music()`, `generate_sound_effect()` |
-
-## Source
-
-Rewritten for AICUT from [`video-db/skills`](https://github.com/video-db/skills)
-(MIT), python/SKILL.md. The method is that skill's own; the way it runs is AICUT's.