nite
790c775eac
- Set bundled FunASR transcription project to Python 3.12 - Restrict requires-python to >=3.12,<3.13 and refresh uv.lock - Document Windows editdistance wheel issue on Python 3.13 - Update README/SKILL prerequisites to recommend Python 3.12 - Add Windows FunASR uv setup troubleshooting reference
101 lines
4.7 KiB
Markdown
101 lines
4.7 KiB
Markdown
# Video Edit Planner
|
|
|
|
An agent skill that helps plan video edits through iterative dialogue — transcribe audio, extract key frames on demand, analyze visuals, and produce a structured edit plan.
|
|
|
|
**Repository**: https://git.nite07.com/nite/video-edit-planner-skill
|
|
|
|
## Features
|
|
|
|
- **Audio transcription** — bundled [funasr-script](https://github.com/modelscope/FunASR) with Fun-ASR-Nano (default, high quality, Chinese-optimized) and SenseVoice (fast preview) models
|
|
- **On-demand frame extraction** — ffmpeg-based clip cutting (`-c copy`) + scene-change detection + uniform sampling, with hardware acceleration (CUDA/NVDEC preferred)
|
|
- **Artifact indexing** — JSON file tracks all transcriptions, clips, and frames with relative paths to avoid duplicate processing across sessions
|
|
- **Vision analysis guidance** — binary-search-style frame sampling strategy; works with any vision-capable model the agent's runtime provides
|
|
- **Iterative edit plans** — Markdown-table output (timecodes, segment descriptions, actions, transitions, notes) refined through follow-up questions
|
|
- **Agent-agnostic** — no platform-specific tool names; works with any agent framework (Hermes, Claude Code, Codex, etc.)
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
| Dependency | Install |
|
|
|---|---|
|
|
| `ffmpeg` + `ffprobe` | Linux: `pacman -S ffmpeg` / `apt install ffmpeg`; macOS: `brew install ffmpeg`; Windows: `winget install Gyan.FFmpeg` |
|
|
| `uv` | Linux: `pacman -S uv`; macOS: `brew install uv`; Windows: `winget install astral-sh.uv`; fallback: `pip install uv` |
|
|
| `python3` / Python 3.12 | Linux: `pacman -S python`; macOS: `brew install python@3.12`; Windows: `winget install Python.Python.3.12` |
|
|
|
|
### Install the skill
|
|
|
|
**Option 1: `npx skills add` (recommended)**
|
|
|
|
This skill is compatible with the [open agent skills ecosystem](https://www.npmjs.com/package/skills). You can install it directly:
|
|
|
|
```bash
|
|
# Install globally (available across all projects)
|
|
npx skills add https://git.nite07.com/nite/video-edit-planner-skill.git -g -y
|
|
|
|
# Install to specific agents
|
|
npx skills add https://git.nite07.com/nite/video-edit-planner-skill.git -g -a claude-code -y
|
|
|
|
# List available skills without installing
|
|
npx skills add https://git.nite07.com/nite/video-edit-planner-skill.git --list
|
|
```
|
|
|
|
Supports 73+ agent frameworks including Claude Code, Codex, Cursor, OpenCode, and more.
|
|
|
|
**Option 2: `git clone` (manual)**
|
|
|
|
```bash
|
|
git clone https://git.nite07.com/nite/video-edit-planner-skill.git ~/.hermes/skills/media/video-edit-planner
|
|
```
|
|
|
|
For Hermes Agent specifically, clone into `~/.hermes/skills/media/`. For other agents, follow their respective skills directory conventions.
|
|
|
|
## Workflow
|
|
|
|
```
|
|
1. Check dependencies (ffmpeg, uv, python3)
|
|
2. Gather inputs (video path + audio track index)
|
|
3. Ask editing requirements
|
|
4. Transcribe audio (skip if cached in index)
|
|
5. Extract clips & frames on demand (agent decides when transcript is insufficient)
|
|
6. Analyze frames with vision model (binary-search-style sampling)
|
|
7. Produce Markdown-table edit plan + overall recommendation
|
|
8. Iterate — user asks follow-ups, plan is refined
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
video-edit-planner/
|
|
├── SKILL.md # Skill definition (workflow, guidance, pitfalls)
|
|
├── README.md # This file (English)
|
|
├── README.zh.md # 中文说明
|
|
├── scripts/
|
|
│ ├── transcription/ # Bundled funasr-script (self-contained uv project)
|
|
│ │ ├── pyproject.toml
|
|
│ │ ├── uv.lock
|
|
│ │ ├── funasr_common.py # Shared: ffprobe, audio extraction, model runner
|
|
│ │ ├── funasr_nano.py # Fun-ASR-Nano entry point (default, high quality)
|
|
│ │ ├── funasr_fast.py # SenseVoice entry point (fast preview)
|
|
│ │ └── funasr_regular.py # Paraformer entry point (comparison)
|
|
│ ├── frames/
|
|
│ │ └── extract_frames.py # Clip extraction + frame sampling (ffmpeg wrapper)
|
|
│ └── index/
|
|
│ └── manage_index.py # JSON index management (8 subcommands)
|
|
└── references/
|
|
└── frame-extraction-guide.md # Vision model token costs, resolution/batch guidance
|
|
```
|
|
|
|
## Index File
|
|
|
|
All processing artifacts are tracked in a JSON file (`<video_stem>.vedit.json`) stored next to the video file:
|
|
|
|
- **transcriptions** — JSON path, track index, duration
|
|
- **clips** — start/end time, file path, extraction reason
|
|
- **frames** — timestamp, file path, scene score, extraction method
|
|
|
|
All paths are stored as **relative paths** (relative to the video directory), so moving the entire directory does not break references. The JSON file is human-readable and editable with any text editor.
|
|
|
|
## License
|
|
|
|
MIT |