// Frame screenshots and screen recordings with the `frames` CLI. Use this skill when the user asks to add Apple device bezels, frame screenshots or videos, create device mockups, inspect screenshot/device matches, or batch-process screenshot/video folders with the command line.
| name | frames-cli |
| description | Frame screenshots and screen recordings with the `frames` CLI. Use this skill when the user asks to add Apple device bezels, frame screenshots or videos, create device mockups, inspect screenshot/device matches, or batch-process screenshot/video folders with the command line. |
frames 1.3.0 is a single-file Python CLI that applies Apple device bezels to screenshots and videos, auto-detects devices from input dimensions, applies masks when needed, and can merge multiple framed results. Video support uses external ffmpeg 5.1+ and ffprobe 5.1+ with no extra Python media stack.
frames is the default command. frames screenshot.png and frames frame screenshot.png are equivalent.frames --json ... for automation. Put global flags such as --json, --assets, and --verbose before subcommands for the broadest compatibility.frames list and frames list-colors as the source of truth when exact names matter.frames video ... for .mp4, .mov, and .m4v; the default frames ... path is for images.frames video-info ... to probe videos and resolve the matching frame metadata without rendering.ffmpeg 5.1+ and ffprobe 5.1+. frames setup checks this and can offer a Homebrew install on macOS; frames doctor reports video tool readiness.frames video preserves single-video audio by default. Pass --strip-audio when the user asks for silent output, privacy-safe delivery, or validation clips where audio does not matter.frames video --preset compact|balanced|best controls MP4 export size/quality; best is the default. Video exports report output file size and source-vs-output savings in human and JSON output.# Frame one screenshot
frames screenshot.png
# Frame every top-level image in a folder
frames ~/Screenshots/
# Pick a specific color or randomize colors
frames -c "Cosmic Orange" screenshot.png
frames -c random *.png
frames --colors "Silver,Space Black,random" one.png two.png three.png
# Frame videos
frames video-info recording.mp4
frames --json video-info recording.mp4
frames video recording.mp4
frames video --preset compact recording.mp4
frames video --preset balanced recording.mp4
frames video --preset best recording.mp4
frames --json video --strip-audio recording.mp4
frames video --strip-audio recording.mp4
frames video --background "#f5f5f5" --codec hevc recording.mp4
frames video -m --playback-offset 1.mp4 2.mp4
frames video -m --colors "Silver,random" 1.mp4 2.mp4
# Force an exact frame instead of auto-resolving the newest variant
frames -d "iPhone 15 Pro Portrait" screenshot.png
# Merge framed outputs side by side
frames -m shot1.png shot2.png
# Merge without proportional physical scaling
frames -m --no-scale shot1.png shot2.png
# Batch merge sequential groups
frames -b 3 *.png
# Save to a separate output directory
frames -o ~/Framed *.png
# Save to a subfolder next to originals
frames -f *.png
frames --subfolder mockups *.png
# Inspect matches without framing
frames info screenshot.png
frames --json info ~/Screenshots/
# Discover supported devices and colors
frames list
frames list-colors "17 Pro"
# Manage default colors
frames colors
# Diagnose asset/config problems
frames doctor
# Download or re-point assets
frames setup
frames setup /path/to/Frames
--device to skip variant resolution.default, or random.--colors for per-input colors on images and videos; it maps comma-separated values to expanded inputs by order..mp4, .mov, and .m4v files through frames video; single-video audio is preserved unless --strip-audio is passed.--preset compact, --preset balanced, or --preset best to tune MP4 export size/quality. best is the default.--json agent output.frames video-info.frames video -m, or sequentially left-to-right with frames video -m --playback-offset.--no-scale to disable proportional scaling and keep native framed sizes when merging.--batch N to merge sequential groups. --batch implies merge and N must be at least 2.--output, or into a validated single-name subfolder via -f or --subfolder.--copy.info.doctor.colors.--json for machine-readable output--no-color to disable ANSI color--assets PATH to override asset discovery-v / --verbose for variant, resize, and mask detailsframes video --help and frames video-info --help for the human-facing video examples and option summaries.frames colors is interactive in a real terminal. If stdin is not a TTY, or curses is unavailable, it falls back to a plain printed color list.frames list-colors does partial device-name matching. frames list-colors "17 Pro" is valid..png, .jpg, .jpeg, .heic, .tiff, and .webp..mp4, .mov, and .m4v.20,000px on either side trigger a warning. Images larger than 50,000px are rejected.--subfolder only accepts a single directory name, not a path like ../out or foo/bar.frames video-info FILE reports dimensions, duration, fps, codec, audio state, matched device, selected color, frame size, mask state, and resize metadata without creating an output video.frames video FILE writes FILE_framed.mp4 by default, or .mov when --alpha, --codec prores, or --background transparent is used.--output may be an explicit output file path or a directory. For multiple individual videos, use an output directory.--merge creates one horizontal video. Without --playback-offset, videos play simultaneously and duration is the longest input.--playback-offset requires --merge; videos play left to right, inactive future videos hold their first frame, and completed videos hold their final frame.physicalHeight and bottom-aligned by default. Use --no-scale only when native framed pixel sizes matter more than physical proportion.--strip-audio is passed. Sequential --playback-offset merges concatenate audio and generate silence for inputs without audio. Simultaneous merges omit mixed audio in this version.--background accepts only white, black, transparent, or #RRGGBB. transparent implies alpha/ProRes MOV output.--codec h264 is the default. --codec hevc is smaller but may be slower or less compatible. Use --codec prores or --alpha for transparent .mov.--preset compact|balanced|best controls H.264/HEVC hardware bitrate and software CRF. best is the default; balanced and compact trade quality for smaller files. ProRes/alpha output keeps ProRes settings.--quality N is an expert software CRF override; lower is higher quality.--color random randomizes independently per input. --colors "A,B,random" maps values to expanded inputs by order and the count must match after directory expansion.video-info accepts --device, --color, and --colors; it uses the same resolution rules as frames video.frames; render first, verify the output, then use the delivery workflow the user requested.frames --json screenshot.png returns one framed-image object with fields such as source, device, color, dimensions, frame_size, resized, masked, physicalHeight, and output.frames --json *.png returns { "frames": [...] } for multiple individual outputs.frames --json -m ... returns a merged result with merged, count, and frames.frames --json -b N ... returns batches, batch_size, total, and frames.scale_factor values are included in the JSON output.frames --json info ... returns either one object or a list of objects, including device, primary_match, colors, color_count, has_mask, resize_width, variants, and is_variant.frames --json video-info ... returns one video metadata object, or a list for multiple videos, including dimensions, duration, fps, codec, audio, device, primary_match, color, frame_size, resize_width, and mask_missing.frames --json doctor returns asset path/source/version, PNG count, config presence, issues, notes, and suggested next steps.frames --json video ... returns one video object, or { "videos": [...] } for multiple individual outputs, including preset, output_size_bytes, output_size, source_size_bytes, source_size, savings_bytes, savings, and savings_percent.frames --json video -m ... returns merged, duration, dimensions, playback_offset, audio state, top-level output size/savings fields, and per-input frames.Config file:
~/.config/frames/config.json
Config keys:
assets_path: explicit asset folder pathdefault_colors: saved default frame colors by base device nameuse_subfolder: true for framed, or a custom folder name stringAsset resolution order:
--assetsFRAMES_ASSETSassets_path from config~/Library/Mobile Documents/iCloud~is~workflow~my~workflows/Documents/Frames~/Library/Application Support/frames/assetsSetup behavior:
frames setup downloads the current asset archive from https://cdn.macstories.net/AppleFrames401.zip.frames setup /path/to/Frames points the CLI at an existing asset folder instead of downloading.NewFrames.json, version.txt, and the frame/mask PNGs.ffmpeg/ffprobe for video framing and can install ffmpeg through Homebrew on macOS when run interactively.frames setup --subfolder and frames setup --no-subfolder update the default save behavior in config.frames doctor is the first command to run when assets were moved, edited, corrupted, or when video dependencies need verification.The current v4 asset bundle used by frames 1.3.0 includes these primary families:
Current default variant resolution favors the newest matching frame for shared screenshot sizes:
iPhone 17 Portrait resolves to iPhone 17 Pro PortraitiPhone 17 Landscape resolves to iPhone 17 Pro LandscapeiPhone 17 Pro Max shares sizes with iPhone 16 Pro MaxiPhone 16 shares sizes with iPhone 15 ProiPhone 16 Plus shares sizes with iPhone 15 Pro MaxMacBook Pro M5 shares sizes with MacBook Pro 2021MacBook Air M5 13 shares sizes with MacBook Air 2022Studio Display shares sizes with Studio Display XDRWatch Series 11 shares sizes with Watch Series 10If an exact older variant is required, pass --device with the exact frame name instead of relying on auto-detection.
frames --json info ... first when you do not control the screenshot source. For videos, run frames --json video-info ... when you need dimensions, duration, audio state, or the matched frame before rendering.frames list or frames list-colors.frames doctor before changing config or re-downloading assets.--device only when the user wants an exact frame, older variant, or a non-default shared-size match.--no-scale only when the user explicitly wants native framed sizes instead of physically proportionate merges.frames video -m for simultaneous playback and frames video -m --playback-offset for left-to-right sequential playback.--strip-audio for generated test artifacts unless the user specifically wants audio preserved.ffprobe when final output audio state, duration, codec, or stream count matters.