Wrap Apple device screen recordings and screenshots in a device frame for presentation-ready output.
| Before | After |
|---|---|
 |
 |
pip install -r requirements.txtDownload device frames from Apple Design Resources:
- Download the device bezels you need, such as "Apple Watch" or "iPhone 16"
- Extract and copy the
PNG/folder to this project's root directory
python3 watchframe.py -s examples/recording.mov -f "PNG/Milanese Loop/AW Ultra 3 - Black + Milanese Loop.png"python3 watchframe.py -s examples/screenshot.png -f "PNG/Milanese Loop/AW Ultra 3 - Black + Milanese Loop.png"By default, mismatched screenshot/frame sizes use --fit cover, which fills the
device screen opening without gutters and crops from the center if the aspect
ratios differ. For a pixel-perfect result, use a bezel that matches the source
screenshot's device model and screen resolution.
python3 watchframe.py -s screenshot.png -f frame.png --fit cover
python3 watchframe.py -s screenshot.png -f frame.png --fit contain
python3 watchframe.py -s screenshot.png -f frame.png --fit stretchpython3 watchframe.py -s input.mov -f frame.png -o output.mp4If auto-detection doesn't find the correct screen area:
python3 watchframe.py -s recording.mov -f frame.png --screen-x 95 --screen-y 219 --screen-width 410 --screen-height 502- Loads the device frame PNG (must have transparent screen area)
- Detects the screen region via connected component analysis on the alpha channel
- Renders the source media into a screen-sized layer using the selected fit mode
- Masks that layer to the frame's transparent screen opening
- Alpha-composites the Apple frame on top so rounded corners and glass edges win
- Outputs MP4 (video) or PNG (image)
- PNG format with alpha channel (RGBA)
- Screen area must be transparent (alpha < 10)
- Frame should have the watch body/bezel as opaque pixels
Images: .png, .jpg, .jpeg, .bmp, .tiff, .webp
Videos: .mov, .mp4, .avi, .mkv, .webm, .m4v
MIT