device-framer

Device Framer

Wraps screen recordings and screenshots in photorealistic iPhone device frames with drop shadow, rounded corners, and a configurable background. Supports 12 devices with 44 color variants.

Quick Start

SKILL_DIR="/path/to/this/skill"
cp -r "$SKILL_DIR/scripts" /home/claude/device-framer-scripts
cp -r "$SKILL_DIR/frames" /home/claude/device-framer-frames
pip install Pillow --break-system-packages 2>/dev/null || true

python3 /home/claude/device-framer-scripts/frame_video.py INPUT_FILE \
  -o /mnt/user-data/outputs/framed_output.mp4 \
  -d iphone-16-pro --color black-titanium --bg '#0a0a0a' \
  --padding 100 --scale 0.5

Auto-detects video vs image from extension. Video → MP4, Image → PNG.

Available Devices

Device	Colors
iphone-17-pro-max	cosmic-orange, deep-blue, silver
iphone-17-pro	cosmic-orange, deep-blue, silver
iphone-16-pro-max	black-titanium, natural-titanium, white-titanium, desert-titanium
iphone-16-pro (default)	black-titanium, natural-titanium, white-titanium, desert-titanium
iphone-16-plus	black, pink, teal, ultramarine, white
iphone-16	black, pink, teal, ultramarine, white
iphone-15-pro-max	black-titanium, natural-titanium, white-titanium, blue-titanium
iphone-14-pro-max	deep-purple, gold, silver, space-black
iphone-13-mini	black, blue, pink, red, starlight
iphone-air	cloud-white, light-gold, sky-blue, space-black
iphone-xs-max	space-gray
iphone-xs	space-gray, silver

Options

Flag	Default	Description
-d, --device	iphone-16-pro	Device model
--color	first color	Device color variant
--bg	#0a0a0a	Background color (hex)
--no-shadow	(shadow on)	Disable drop shadow
--shadow-blur	50	Shadow blur radius
--shadow-opacity	80	Shadow opacity (0-255)
--padding	100	Padding around device (px)
--scale	(native)	Scale factor (e.g. 0.5)
-q, --quality	high	Video: high/medium/low
--no-audio	(keep)	Strip audio (video only)
--list-devices	—	Show all devices and colors

Recommended Settings

Scale: 0.5 for most uses. Omit for native resolution.

Good combos:

• --device iphone-17-pro --color cosmic-orange --bg '#1a1a2e'
• --device iphone-16-pro --color natural-titanium --bg '#0f172a'
• --device iphone-16 --color ultramarine --bg '#0a0a0a'
• --device iphone-air --color sky-blue --bg '#f0f4f8'
• --device iphone-14-pro-max --color deep-purple --bg '#0a0a0a'

How It Works

Frame PNGs have transparent screen areas. The script extracts a pixel-perfect screen mask from each frame's alpha channel (flood-fill to separate interior screen from exterior transparency), then composites: background → shadow → content (masked) → frame overlay.

Images: Pillow compositing (instant). Videos: ffmpeg filter_complex single-pass.

Interaction Guide

1. Auto-detect input type from extension
2. If user doesn't specify a device, ask or default to iPhone 16 Pro
3. If user doesn't specify color, use the default (first listed)
4. Recommend --scale 0.5 and dark background
5. Run the script, present the output

Credits

• Modern frames from jamesjingyi/mockup-device-frames (Apple Developer Resources)
• Classic XS/XS Max frames from t9mike/iphone_overlay (Apache 2.0)