Framecap
Coming soon!
HomeDocs

Documentation
(pre-release version!)

Getting Started

Basic Commands

CommandDescription
framecap sourcesList all available recording sources
framecap -t "screen:0" -o ~/VideosRecord primary screen
framecap -t "camera:builtin" -o ~/VideosRecord webcam
framecap --helpShow all options

First Recording

framecap -t "screen:0,audio:system" -o ~/Desktop

Press Enter to stop recording.

Recording Sources

Screens

SourceDescriptionExample
screen:0Primary displayframecap -t "screen:0"
screen:1External displayframecap -t "screen:1"

Cameras

SourceDescriptionExample
camera:builtinBuilt-in webcamframecap -t "camera:builtin"
camera:cam-link-4kExternal cameraframecap -t "camera:cam-link-4k"

Run framecap sources to find your device IDs.

Audio Recording

Audio Options

TypeDescriptionUse With
audio:systemApp & system soundsScreens only
audio:builtinBuilt-in microphoneAny video source
audio:noneNo audioAny video source
audio:appSingle app's audioWith app: filter

Examples

framecap -t "screen:0,audio:system"

framecap -t "camera:builtin,audio:builtin"

framecap -t "screen:0,app:com.spotify.client,audio:app"

Multi-Track Recording

Record multiple sources simultaneously with frame-perfect sync.

Screen + Webcam

framecap \
  -t "screen:0,audio:system,filename:presentation" \
  -t "camera:builtin,flip:h,audio:builtin,filename:presenter" \
  -o ~/Videos/webinar

Multiple Screens

framecap \
  -t "screen:0,filename:main_display" \
  -t "screen:1,filename:external_display" \
  -o ~/Videos/dual_screen

Video Filters

Crop Filter

Remove unwanted areas from your recording.

framecap -t "screen:0,filters:crop(x=0,y=39,w=1920,h=1041)"
ParameterDescriptionExample
xStart X positionx=100 or x=10%
yStart Y positiony=50 or y=5%
wWidthw=1280 or w=80%
hHeighth=720 or h=90%

Mask Filter

Focus on a specific area with background.

framecap -t "screen:0,filters:mask(x=560,y=140,w=800,h=800,r=24),codec:prores4444"
ParameterDescriptionExample
x,y,w,hArea to showSame as crop
rCorner radiusr=24
bgBackground colorbg=#000000

Note: Use codec:prores4444 for transparency, otherwise black background.

Filter Chaining

framecap -t "screen:0,filters:'mask(x=100,y=100,w=800,h=800,r=32),crop(x=50,y=50,w=700,h=700)'"

(more filters coming soon!)

Application Recording

Record specific application windows.

Single App

framecap -t "screen:0,app:com.figma.Desktop,audio:app" -o ~/Videos/design

With Transparency

framecap -t "screen:0,app:com.google.Chrome,codec:prores4444" -o ~/Videos

Find App Bundle IDs

framecap sources --windows

Video Transformations

Flip Options

TransformDescriptionExample
flip:hMirror horizontallycamera:builtin,flip:h
flip:vFlip verticallyscreen:0,flip:v
flip:hvRotate 180°camera:overhead,flip:hv

Example: Mirrored Webcam

framecap -t "camera:builtin,flip:h,audio:builtin" -o ~/Videos/vlogs

Output Configuration

File Organization

OptionDescriptionExample
-oGlobal output directory-o ~/Videos
out:Track-specific directoryscreen:0,out:~/Videos/screens
filename:Custom filenamecamera:builtin,filename:facecam

Multi-Directory Example

framecap \
  -t "screen:0,out:~/Videos/screens,filename:tutorial" \
  -t "camera:builtin,out:~/Videos/cameras,filename:instructor" \
  -t "screen:0,app:com.apple.dt.Xcode,out:~/Videos/code,filename:xcode"

Codec Selection

Available Codecs

CodecQualityFile SizeUse Case
h264GoodSmallestWeb sharing
proresltExcellentMediumDefault, editing
prores422ExcellentLargeProfessional
prores4444Excellent + AlphaLargestTransparency

Setting Codec

framecap -t "screen:0" -c h264 -o ~/Videos

framecap -t "screen:0,app:com.sketch.sketchapp,codec:prores4444"

Frame Rate Control

Common Frame Rates

FPSUse CaseExample
24Cinematic-r 24
30Standard (default)-r 30
60Smooth motion-r 60
framecap -t "screen:0" -r 60 -o ~/Videos/gameplay

Shortcuts Reference

Command Options

ShortLongDescription
-t--trackAdd recording track
-o--outputOutput directory
-r--framerateFrame rate (1-120)
-c--codecVideo codec
-d--durationRecording duration
-w--overwriteReplace existing files
-q--quietMinimal output
-h--helpShow help

Quick Recording

framecap --screen

framecap --camera

framecap --screen --camera

Permissions

Required Permissions

PermissionWhen NeededGrant In
Screen RecordingRecording screensSystem Settings > Privacy
CameraRecording webcamSystem Settings > Privacy
MicrophoneRecording audioSystem Settings > Privacy

First Run

framecap sources

Grant permissions when prompted.

Troubleshooting

Common Issues

IssueSolution
"Permission denied"Grant Screen Recording permission in System Settings
"Camera not found"Check device ID with framecap sources
"No audio"Verify audio device ID matches exactly
"High CPU usage"Use H.264 codec or reduce framerate
"Another instance running"Only one screen recording at a time allowed

Debug Commands

framecap sources --debug

framecap sources --devices

framecap sources --windows

System Requirements

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

File Formats

All recordings saved as .mov files with:

  • Container: QuickTime
  • Video: ProRes or H.264
  • Audio: Linear PCM, 48kHz, 16-bit
  • Frame Rate: Constant (CFR)

Tips & Best Practices

  1. Test First: Record 5 seconds to verify setup
  2. Check Space: ProRes uses ~1 GB/minute at 4K
  3. Use Shortcuts: -t instead of --track
  4. Copy IDs: Use exact IDs from framecap sources
  5. Stop Method: Press Enter to stop recording

Limitations

  • One screen recording instance at a time
  • No HEVC/H.265 support
  • macOS only
  • No live preview
  • No audio mixing (separate tracks only)