name: "cli-anything-openscreen"
description: >-
Command-line interface for Openscreen — a screen recording editor.
A stateful CLI for editing screen recordings with zoom, speed ramps,
trim, crop, annotations, and polished exports. Built on the Openscreen
JSON project format with ffmpeg as the rendering backend. Designed for
AI agents and power users who need programmatic video editing.
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#
pip install cli-anything-openscreenPrerequisites:
- Python 3.10+
- ffmpeg must be installed on your system
Usage#
Basic Commands#
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 infoREPL 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
heroframe for quick inspection summary.jsonwith 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:
cli-hub previews inspect /path/to/bundle
cli-hub previews html /path/to/bundle -o page.html
cli-hub previews open /path/to/bundlesession#
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
.openscreenfiles - 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#
- Always use
--jsonfor parseable output - Check return codes — 0 = success, non-zero = error
- Parse stderr for error messages in non-JSON mode
- Use absolute file paths
- After
export render, verify the output exists and probe it - Times are in milliseconds for all region commands
- Coordinates (focus, crop, position) are normalized 0-1
- Use
preview capture --jsonto validate zoom, trim, annotation, and timing visually - Read returned bundle artifact paths from the JSON payload; images and clips live on disk
- Use
cli-hub previews ...only to inspect/open existing bundles
Version#
1.0.0