The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Bezelbub MCP listing page.
Bezelbub wraps your screenshots and screen recordings in realistic Apple device bezels — iPhone, iPad, Mac, and Apple TV — producing pixel-perfect device mockups as framed images and videos. It ships three ways:
bezelbub CLI (brew install cwooddgr/tap/bezelbub): frame a screenshot in an iPhone bezel from the command line, add a device frame to a screen recording, or export a transparent HEVC-with-alpha video (plus a VP9/WebM copy for Chrome/Firefox) — designed for scripts, CI, and AI agents. Jump to the CLI docs.BezelbubKit, for embedding the framing engine in your own tools.Download the latest macOS release (DMG)
.mov), for compositing device-framed video over any web page or presentationbezelbub)bezelbub is a command-line tool that composites Apple device bezels onto screenshots and screen recordings — no GUI, no interactive prompts — so shell scripts, CI pipelines, and AI agents can generate device mockups. Every input is a flag with a sensible default, output is available as JSON, and errors go to stderr with distinct nonzero exit codes and concrete suggestions (valid ids, matching devices, nearest screen sizes), so a failed call tells the caller how to fix the next one.
Install via Homebrew:
frame is the default subcommand, so bezelbub --input shot.png works too.
Omit --device and the CLI detects the device from the input's pixel dimensions. iPhones and iPads match by exact screen resolution (±1px); display devices (Macs, iMac, Apple TV) match by aspect ratio, so screenshots taken at any scaled resolution still work and are rescaled to the bezel's screen. Detection succeeds when exactly one device matches; if several share the resolution, the error lists the candidates so you can re-run with --device <id>, and if none match, the nearest devices by aspect ratio are suggested. bezelbub devices --input <path> (or --dimensions WxH) answers "which devices fit this input" without framing anything.
--background transparent on a video input exports HEVC with an alpha channel in a QuickTime .mov instead of MP4 — a device-framed screen recording with a fully transparent background, ready to composite over anything. HEVC-with-alpha plays in Safari and Apple frameworks (AVFoundation, AppKit/UIKit) only; Chrome and Firefox don't decode it.
For those browsers, add --webm to also write a VP9/WebM copy that keeps the alpha channel. The CLI renders a temporary ProRes 4444 master and feeds that to ffmpeg (which must be on your PATH) — deliberately not the HEVC .mov, because ffmpeg builds older than 8.0 cannot decode HEVC's alpha layer and silently produce an opaque WebM. (ffmpeg 8+ decodes HEVC alpha correctly, but the ProRes bridge works on any build.) Serve both files, with the .mov listed first:
The order matters: Safari can play VP9/WebM but drops its alpha channel, so a WebM-first listing renders the transparency as an opaque black background in Safari. Listed .mov-first, Safari takes the HEVC-alpha .mov, while Chrome and Firefox skip video/quicktime (which they can't play) and fall through to the WebM.
An explicit --output for a transparent export must end in .mov; the WebM lands beside it with a .webm extension.
frame options:
| Flag | Meaning |
|---|---|
--input, -i | Input screenshot (PNG/JPEG/HEIC) or video (.mov/.mp4/.m4v, routed by extension). Required. |
--device, -d | Device id (see bezelbub devices). Omit to auto-detect from pixel size. |
--color, -c | Color name or id, case-insensitive. Defaults to the device's default color. |
--orientation | portrait | landscape | auto (default: infer from the input's aspect). |
--background | Hex color (#RRGGBB / #RRGGBBAA) or transparent. Default: transparent for images, black for video. transparent on video switches to HEVC-with-alpha .mov. |
--output-size | Scale preserving the bezel's aspect: a width (1920), exact WxH (must match the aspect), or a percentage (50%). Limits: 16–16,384 px images, 16–7,680 px video. |
--output, -o | Output path. Default: <input>-framed.png / .mp4 / .mov beside the input. |
--webm | Also write a VP9/WebM copy with alpha (video + --background transparent only; needs ffmpeg on PATH). |
--json | Machine-readable JSON result on stdout instead of a text summary. |
devices lists the full catalog (ids, display names, colors, orientations, screen sizes), or filters to the devices matching an --input file or bare --dimensions. Filtering always exits 0 — an empty matches array is the signal, with nearest (by aspect ratio) filled in when nothing matches.
frame --json emits one object:
kind is "image" or "video"; video results add "transparent": true|false and, when --webm ran, the "webm" output path. devices --json emits an array of {id, displayName, defaultColor, colors, landscapeOnly, hasPortraitBezel, screenWidth, screenHeight}; with --input/--dimensions it emits {width, height, matches, nearest} using the same device objects (nearest is filled only when matches is empty).
Stable and distinct, so scripts can branch on failure type instead of parsing stderr:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Invalid flag value (e.g. malformed --background or --output-size) |
| 2 | Unknown, ambiguous, or undetectable device (stderr lists candidates) |
| 3 | Unknown color (stderr lists the device's valid colors) |
| 4 | Input image or video unreadable |
| 5 | Compositing or video export failed |
| 6 | Output could not be written |
| 7 | --webm conversion failed (ffmpeg missing from PATH or errored) |
| 64 | Malformed arguments (standard EX_USAGE) |
The CLI is designed for non-interactive, programmatic use — by LLM agents (Claude Code, MCP-style tool wrappers, CI bots) as much as by humans:
--json on both subcommands gives machine-readable results (shapes above).bezelbub devices --input shot.png --json to check the match, then bezelbub frame --input shot.png --json and read output from the result.This repo also ships a ready-made Claude Code skill at skills/bezelbub-cli/ that teaches an agent the full workflow. To install it for all your projects, copy it into your user skills directory:
The device-framing engine lives in BezelbubKit, a UI-free Swift package (BezelbubKit/). It does the pure transformation — screenshot + device id + orientation → framed image — with no SwiftUI, app state, or GUI session, so it runs fully offscreen. Video framing lives in a sibling product, BezelbubVideoKit (AVFoundation-based), so still-image consumers like the Share Extension don't pull in the video pipeline. The macOS app, the iOS app, the Share Extension, and the bezelbub CLI are all thin clients of these packages; bezel/mask assets ship inside BezelbubKit and resolve via Bundle.module.
The apps are generated with XcodeGen:
Schemes:
The engine and CLI build with SwiftPM:
Copyright 2026 DGR Labs, LLC. All rights reserved.