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-openscreen

Prerequisites:

• 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 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:

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