cli-anything-openscreen

What this skill does

# cli-anything-openscreen

A stateful command-line interface for editing screen recordings. Transform raw
captures into polished demo videos with zoom effects, speed adjustments,
trimming, annotations, and beautiful backgrounds.

## Installation

```bash
pip install cli-anything-openscreen
```

**Prerequisites:**
- Python 3.10+
- ffmpeg must be installed on your system

## Usage

### Basic Commands

```bash
cli-anything-openscreen --help
cli-anything-openscreen                     # REPL mode
cli-anything-openscreen project new -v recording.mp4 -o project.openscreen
cli-anything-openscreen --json project info
```

### REPL Mode

Run `cli-anything-openscreen` without arguments to enter interactive mode.
Type `help` for available commands, `quit` to exit.

## Command Groups

### project

Create, open, save, and configure projects.

| Command | Description |
|---------|-------------|
| `project new [-v VIDEO] [-o PATH]` | Create new project with optional video |
| `project open <path>` | Open existing .openscreen project |
| `project save [-o PATH]` | Save project to file |
| `project info` | Show project metadata and region counts |
| `project set-video <path>` | Set source video file |
| `project set <key> <value>` | Set editor setting (padding, wallpaper, etc.) |

### zoom

Manage zoom regions — smooth zoom effects on specific timeline areas.

| Command | Description |
|---------|-------------|
| `zoom list` | List all zoom regions |
| `zoom add --start MS --end MS [--depth 1-6] [--focus-x 0-1] [--focus-y 0-1]` | Add zoom |
| `zoom remove <id>` | Remove zoom region |

Zoom depths: 1=1.25x, 2=1.5x, 3=1.8x, 4=2.2x, 5=3.5x, 6=5.0x

### speed

Manage speed regions — speed up idle time, slow down important moments.

| Command | Description |
|---------|-------------|
| `speed list` | List all speed regions |
| `speed add --start MS --end MS [--speed 0.25-2.0]` | Add speed change |
| `speed remove <id>` | Remove speed region |

Valid speeds: 0.25, 0.5, 0.75, 1.25, 1.5, 1.75, 2.0

### trim

Manage trim regions — cut out sections of the recording.

| Command | Description |
|---------|-------------|
| `trim list` | List all trim regions |
| `trim add --start MS --end MS` | Cut out a section |
| `trim remove <id>` | Remove trim region |

### crop

Set the visible area of the recording.

| Command | Description |
|---------|-------------|
| `crop get` | Show current crop region |
| `crop set --x 0-1 --y 0-1 --width 0-1 --height 0-1` | Set crop (normalized) |

### annotation

Add text overlays to the recording.

| Command | Description |
|---------|-------------|
| `annotation list` | List all annotations |
| `annotation add-text --start MS --end MS --text "..." [--x 0-1] [--y 0-1]` | Add text |
| `annotation remove <id>` | Remove annotation |

### media

Inspect and validate media files.

| Command | Description |
|---------|-------------|
| `media probe <path>` | Show video metadata (resolution, duration, codec) |
| `media check <path>` | Validate a video file |
| `media thumbnail <input> <output> [-t TIME]` | Extract a frame |

### export

Render the final polished video.

| Command | Description |
|---------|-------------|
| `export presets` | List available export presets |
| `export render <output_path>` | Render project to video file |

### preview

Capture truthful review bundles from the current Openscreen project.

| Command | Description |
|---------|-------------|
| `preview recipes` | List available preview recipes |
| `preview capture --recipe quick` | Render a low-res preview bundle |
| `preview latest [--recipe quick]` | Return the latest existing bundle |

Current preview support is static rather than live. A `quick` bundle typically
contains:

- a low-res preview clip
- sampled frames
- a `hero` frame for quick inspection
- `summary.json` with trim/zoom/speed facts

Bundle capture also writes or updates a stable recipe-level `trajectory.json`
beside the preview root so agents can reconstruct preview history over time.

Viewer commands:

```bash
cli-hub previews inspect /path/to/bundle
cli-hub previews html /path/to/bundle -o page.html
cli-hub previews open /path/to/bundle
```

### session

Manage session state with undo/redo.

| Command | Description |
|---------|-------------|
| `session status` | Show session info |
| `session undo` | Undo last operation |
| `session redo` | Redo last undone operation |
| `session save` | Save session state to disk |
| `session list` | List all saved sessions |

## State Management

- **Undo/Redo**: Up to 50 levels of undo history
- **Project persistence**: JSON `.openscreen` files
- **Session tracking**: auto-tracks modifications

## Output Formats

- Human-readable (default): Formatted key-value pairs
- Machine-readable (`--json`): Structured JSON output

## Editor Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `aspectRatio` | string | "16:9" | 16:9, 9:16, 1:1, 4:3, 4:5 |
| `wallpaper` | string | "gradient_dark" | Background preset |
| `padding` | int | 50 | 0-100, padding around video |
| `borderRadius` | int | 12 | Corner radius in pixels |
| `shadowIntensity` | float | 0 | 0-1, drop shadow strength |
| `motionBlurAmount` | float | 0 | 0-1, motion blur during zoom |
| `exportQuality` | string | "good" | medium, good, source |
| `exportFormat` | string | "mp4" | mp4, gif |

## For AI Agents

1. Always use `--json` for parseable output
2. Check return codes — 0 = success, non-zero = error
3. Parse stderr for error messages in non-JSON mode
4. Use absolute file paths
5. After `export render`, verify the output exists and probe it
6. Times are in **milliseconds** for all region commands
7. Coordinates (focus, crop, position) are **normalized 0-1**
8. Use `preview capture --json` to validate zoom, trim, annotation, and timing visually
9. Read returned bundle artifact paths from the JSON payload; images and clips live on disk
10. Use `cli-hub previews ...` only to inspect/open existing bundles

## Version

1.0.0