Release 1.3

Changelog for 1.3

Frames 1.3 is the video release: the CLI can now frame screen recordings with Apple Frames assets, inspect video/device matches before rendering, merge multiple framed videos, and export transparent ProRes MOVs for compositing.

New Video Commands

• Added frames video for .mp4, .mov, and .m4v inputs.
• Added frames video-info to probe dimensions, duration, FPS, codec, audio state, matched device, selected color, frame size, mask state, and resize metadata without rendering.
• Video support uses external ffmpeg and ffprobe 5.1+ while keeping Python responsible for Apple Frames asset/device resolution.

Video Framing and Merging

• Frame single videos with the same device detection, color selection, masks, and resize metadata used for screenshots.
• Merge framed videos side by side with frames video -m.
• Added --playback-offset for left-to-right sequential merged playback.
• Merged videos keep the existing physical-height scaling model and bottom alignment, with --no-scale available for native framed sizes.
• Single-video outputs preserve audio by default; --strip-audio removes audio. Sequential playback-offset merges concatenate audio and synthesize silence where needed; simultaneous merges omit mixed audio.

Transparent Video Output

• Added transparent ProRes MOV output for merged videos with frames video -m --alpha ....
• --background transparent now also produces transparent ProRes MOV output for single and merged videos.
• --alpha defaults the canvas to transparency unless an explicit background is provided.
• Transparent outputs preserve alpha with ProRes 4444 and alpha-capable pixel formats for use in Final Cut Pro, Keynote, and other compositors.
• Explicit transparent output files must use a .mov extension; MP4/H.264 and MP4/HEVC do not support alpha.

Export Presets and Reporting

• Added --preset compact, --preset balanced, and --preset best for video exports.
• best is the default preset.
• Presets tune H.264/HEVC hardware bitrates and software CRF values; ProRes/alpha output keeps ProRes settings.
• Kept --quality as an expert software-encoder CRF override.
• Video exports now report output size, source size, savings/delta, and savings percentage in human output and JSON.

Setup, Docs, and Agent Support

• frames setup and frames doctor now check video tool readiness and report missing or outdated ffmpeg/ffprobe cleanly.
• Added live terminal progress for interactive video renders while keeping JSON/non-TTY runs script-friendly.
• Updated README, CLI help, and agent skill documentation for the new video commands, presets, alpha output, JSON fields, and workflow guidance.

Validation

• Tested single-video and merged-video rendering paths, including transparent merged ProRes output, random and specific frame colors, playback-offset merges, output filename validation, JSON output shape, and normal non-alpha MP4 output.

Release 1.2.8

Update the default Apple Frames asset bundle URL to https://cdn.macstories.net/AppleFrames401.zip.

This picks up the corrected asset bundle for issue #2, where iPhone 17 Portrait_mask.png under-clipped the screen corners and let screenshot content bleed past the bezel. The updated bundle makes the iPhone 17 and iPhone 17 Pro portrait masks match.

Verification performed locally:

• python3 -m py_compile frames
• python3 -m unittest discover -s tests -v
• ./frames --version -> frames v1.2.8
• Real download/extract of AppleFrames401.zip
• ./frames --assets <downloaded bundle> --json doctor
• Forced iPhone 17 Portrait framing against a real 1206x2622 screenshot

Release 1.2.7

frames setup now falls back to system curl when Python's SSL stack rejects the CDN certificate chain.

This keeps the standard Python download path in place, but fixes the certificate verification failure that blocked some macOS setups from downloading assets from https://cdn.macstories.net/AppleFrames40.zip.

No other user-facing changes in this release.

Release 1.2.6

Update the asset bundle CDN URL to AppleFrames40.zip (the canonical name on cdn.macstories.net). frames setup and the auto-download path now fetch from the correct location.

No other functional changes — everything from 1.2.5 carries over.

Release 1.2.5

Full Changelog: 1.2.4...1.2.5

Release 1.2.4

Full Changelog: 1.2.3...1.2.4

Release 1.2.3

Full Changelog: 1.2.2...1.2.3

Release 1.2.1

frames-cli 1.2.1

• fixes top-level help so merge and --no-scale are discoverable
• adds a small doctor command for diagnosing asset/config problems
• updates the installed CLI on this Mac because /Users/viticci/bin/frames is symlinked to the repo script

Release 1.2.0

frames-cli 1.2.0

• MIT licensed
• simplified installation docs
• security and reliability hardening in the CLI
• no tests included in the repository