Framecap - A CLI Screen Recorder for macOS

Quick Start

# Install
curl -fsSL https://framecap.app/install | bash

# Record your screen
framecap -t "screen:0,audio:system"

# Press Enter to stop recording

Usage

framecap -t <track> [options]    # Track-based recording
framecap sources                 # List devices & apps
framecap --help                  # Show help

Options

Option	Description	Default
`-t, --track <spec>`	Recording track specification	Required
`-o, --output <dir>`	Output directory	Current directory
`-r, --framerate <fps>`	Frame rate (1-120)	30
`-c, --codec <type>`	h264, proreslt, prores422, prores4444	proreslt
`-d, --duration <sec>`	Recording duration (0.1-86400)	Manual stop
`-w, --overwrite`	Overwrite existing files	false
`-q, --quiet`	Minimal output	false

Track Format

Tracks follow this pattern:

source:id[,option:value...]

Sources

Source	Description
`screen:0`	Primary display
`screen:1`	External display
`camera:builtin`	Built-in camera
`camera:<id>`	Camera by device ID
`audio:system`	System audio (screen recording only)
`audio:<id>`	Microphone by device ID

Track Options

Option	Description	Example
`app`	Filter to specific app(s)	`app:com.figma.Desktop`
`hide`	Hide specific apps	`hide:[com.apple.dock,com.apple.menubar]`
`filters`	Apply video filters	`filters:[crop(...),flip(h)]`
`codec`	Override codec for this track	`codec:h264`
`out`	Track-specific output directory	`out:~/Videos`
`filename`	Custom filename prefix	`filename:presentation`

Filters

Crop

Remove unwanted regions from your recording.

crop(x=0,y=40,w=1920,h=1040)

Mask

Create rounded corners with optional background.

mask(x=100,y=100,w=800,h=800,r=24,bg=#000000)

Flip

Mirror or rotate your recording.

flip(h)   # Horizontal mirror
flip(v)   # Vertical flip
flip(hv)  # 180° rotation

Examples

Basic Recording

# Screen with system audio
framecap -t "screen:0,audio:system"

# Camera with microphone
framecap -t "camera:builtin,audio:builtin"

# Screen only, no audio
framecap -t "screen:0"

Advanced Recording

# Multiple filters
framecap -t "screen:0,filters:[crop(x=0,y=40,w=1920,h=1040),flip(h)]"

# Hide dock and menu bar
framecap -t "screen:0,hide:[com.apple.dock,com.apple.notificationcenterui]"

# Record specific app with transparency
framecap -t "screen:0,app:com.figma.Desktop,codec:prores4444"

# Multiple apps
framecap -t "screen:0,app:[com.spotify.client,com.google.Chrome]"

Multi-track Recording

# Screen + camera
framecap \
  -t "screen:0,audio:system,filename:presentation" \
  -t "camera:builtin,audio:builtin,filename:presenter" \
  -o ~/Videos

# Multiple screens
framecap \
  -t "screen:0,filename:main" \
  -t "screen:1,filename:external" \
  -o ~/Desktop/recordings

Codecs

Codec	Quality	File Size	Use Case
`h264`	Good	Smallest	Sharing, streaming
`proreslt`	Excellent	Medium	General use (default)
`prores422`	Excellent	Large	Professional editing
`prores4444`	Excellent + Alpha	Largest	Transparency support

Device Discovery

# List all available sources
framecap sources

# List with details
framecap sources --verbose

# List windows only
framecap sources --windows

# List audio devices
framecap sources --audio

Permissions

macOS requires explicit permissions for recording:

Screen Recording → System Settings → Privacy & Security
Camera → System Settings → Privacy & Security
Microphone → System Settings → Privacy & Security

Grant permissions when prompted or run framecap sources to trigger permission requests.

Troubleshooting

Common Issues

Issue	Solution
Permission denied	Grant Screen Recording permission in System Settings
Camera not found	Run `framecap sources` to find correct device ID
No audio in recording	Use `audio:system` for screen or verify microphone ID
High CPU usage	Use `h264` codec or reduce framerate with `-r 24`
Another instance running	Only one screen recording allowed at a time

System Requirements

macOS 13.0 (Ventura) or later
Storage ~500 MB/min for ProRes LT at 1080p
Memory 4 GB RAM minimum
Processor Apple Silicon or Intel

Documentation