bezelbub-mcp

Bezelbub

Bezelbub 可将屏幕截图和录屏放入逼真的 Apple 设备边框中，为 iPhone、iPad、Mac 和 Apple TV 生成像素精准的设备样机图片和视频。你可以通过三种方式使用它：

• 作为 macOS 和 iOS 应用。导入屏幕截图或视频，Bezelbub 会选择匹配的设备并为其添加边框。
• 作为 无头命令行工具，bezelbub（brew install cwooddgr/tap/bezelbub）。通过脚本为屏幕截图添加设备边框、为录屏添加设备边框，或导出带透明度的 HEVC 视频，并同时生成 VP9/WebM 副本，供 Chrome 和 Firefox 使用。我们专为 Shell 脚本、CI 和 AI Agent 打造了它。跳转到 CLI 文档。
• 作为无界面的 Swift 包 BezelbubKit，如果你想将边框处理引擎集成到自己的工具中。

在 App Store 获取 Bezelbub，适用于 Mac、iPhone 和 iPad。

你可以用它做什么

• 让它识别设备。 导入屏幕截图或视频，即可获得合适的边框。我们会根据精确分辨率识别 iPhone 和 iPad。对于 Mac、iMac、Studio Display 和 Apple TV，我们能识别 macOS 各种显示缩放设置下的捕获尺寸，从“更大文字”到“更多空间”皆可，因此你可以在任意缩放级别下捕获画面。如果我们没有记录某个尺寸，就会根据宽高比进行匹配。当多个型号共用同一块屏幕时，你可以从中选择。再导入同一设备的屏幕截图时，你之前选择的设备和颜色会保留。
• 在 Mac 上拖放。将屏幕截图或录屏拖到窗口或 Dock 图标上。
• 在 Mac 上粘贴。复制屏幕截图并按 ⌘V，或使用“编辑 ▸ 粘贴”。
• 在 iPhone 和 iPad 上使用照片和共享菜单。从“照片”导入，或通过任意应用的共享菜单将图片发送到 Bezelbub。
• 为视频添加边框。 导出带有边框且保留音频的 MOV 和 MP4 录屏。
• 导出透明视频。 将带边框、背景完全透明的录屏保存为 QuickTime .mov 格式的 HEVC-with-alpha 视频，可直接叠加到任意网页或演示文稿上。
• 修正旋转方向。 旋转方向不对的视频。按住 Option 并点击可反向旋转。
• 选择颜色。 提供 Apple 为每款设备推出的所有颜色。
• 设置导出尺寸。 保存前可更改宽度、高度或缩放比例。图片最高支持 16,384 px，视频最高支持 7,680 px。
• 复制或保存。 将带边框的图片复制到剪贴板、保存为 PNG，或将带边框的视频导出为 MOV 或 MP4。
• iPhone 和 iPad 支持纵向或横向。

设备

• iPhone： 14、14 Plus、14 Pro、14 Pro Max、15、15 Plus、15 Pro、15 Pro Max、16、16 Plus、16 Pro、16 Pro Max、17、17 Pro、17 Pro Max、Air、18 Pro、18 Pro Max
• iPhone Duo： 提供三种视图，每种视图对应一款设备。可为手机展开时的内屏添加边框（iphoneduo）、为手机合上时的外屏添加边框（iphoneduoouter），或为手机展开且从背面看到的外屏添加边框（iphoneduoouteropen），支持纵向或横向
• iPad： iPad、iPad (A16)、iPad Air 11"/13" M2、iPad Air 11"/13" M4、iPad mini、iPad mini (A17 Pro)、iPad Pro 11"/13" M4、iPad Pro 11"/13" M5
• Mac： MacBook Air 13"、MacBook Air 13"/15" M5、MacBook Pro 14"、MacBook Pro 16"、MacBook Pro 14"/16" M5、MacBook Neo、iMac 24"、iMac 24" M4、Studio Display (2026)。支持任意显示缩放设置。Studio Display 边框也适用于 XDR，因为 Apple 为两者提供了相同的图像
• Apple TV： Apple TV 4K，支持 1080p 或 4K 屏幕截图

bezelbub 命令行工具

使用 bezelbub，你可以通过 Shell 脚本、CI 流水线或 AI Agent 为屏幕截图和录屏添加设备边框。它没有 GUI，也不会弹出任何提示。所有输入都通过标志指定，并且有合理的默认值；你可以请求 JSON 输出。出现问题时，工具会返回不同的非零退出码，并在 stderr 中给出具体建议（有效 ID、匹配的设备、最接近的屏幕尺寸），因此每次失败都会告诉你如何修正下一次调用。

通过 Homebrew 安装：

brew install cwooddgr/tap/bezelbub

快速开始

# Frame a screenshot. We detect the device from its pixel size.
bezelbub frame --input shot.png                 # writes shot-framed.png

# Frame a screen recording (.mov/.mp4/.m4v). Audio is kept; you get an MP4.
bezelbub frame --input demo.mp4                 # writes demo-framed.mp4

# Transparent video: HEVC-with-alpha in a QuickTime .mov
# (plays in Safari and Apple frameworks; the background is fully transparent)
bezelbub frame --input demo.mp4 --background transparent   # writes demo-framed.mov

# Add a VP9/WebM copy with alpha for Chrome and Firefox (needs ffmpeg on PATH)
bezelbub frame --input demo.mp4 --background transparent --webm
#   writes demo-framed.mov and demo-framed.webm

# List device ids, colors, and screen sizes
bezelbub devices [--json]

# Which devices fit this screenshot or recording?
bezelbub devices --input shot.png               # or demo.mp4, or --dimensions 1206x2622

# Or spell everything out
bezelbub frame --input shot.png --device iphone17pro \
               --color "Cosmic Orange" \
               --orientation landscape \
               --background "#1D1D1F" \
               --output-size 50% \
               --output framed.png --json

frame 是默认子命令，因此也可以使用 bezelbub --input shot.png。

设备检测的工作方式

省略 --device 时，我们会根据输入的像素尺寸推断设备。对于 iPhone 和 iPad，这意味着屏幕分辨率必须精确匹配，误差不超过 1 个像素。对于 Mac、iMac、Studio Display 和 Apple TV，这意味着采集尺寸必须精确匹配：每种 macOS 显示缩放设置都会针对每个型号以已知像素尺寸进行采集，因此，3420×2214 的屏幕截图只能来自 15 英寸 MacBook Air，无论截图时使用了哪种缩放设置。对于文件中没有记录的尺寸（例如外接显示器或缩小尺寸的录屏），则会改为按宽高比匹配。为显示器采集的画面添加边框时，我们会缩放画面，使其适配边框内的屏幕。

恰好有一台设备匹配时，检测才会成功。如果多个型号的尺寸相同，错误信息会列出这些型号，方便你再次运行时指定 --device <id>。如果没有匹配项，我们会按宽高比列出最接近的设备。若要在添加边框前进行检查，请运行 bezelbub devices --input <path> 或 bezelbub devices --dimensions WxH。

透明视频和 WebM

视频输入使用 --background transparent 时，输出将是带 Alpha 通道的 HEVC 视频，封装在 QuickTime .mov 中，而不是 MP4：这是一段带设备边框、背景完全透明的录屏，可直接叠加到任何内容上。Safari 和 Apple 的框架（AVFoundation、AppKit、UIKit）都能播放带 Alpha 通道的 HEVC。Chrome 和 Firefox 无法解码它。

对于这些浏览器，请添加 --webm，工具还会生成一个保留 Alpha 通道的 VP9/WebM 副本。为此，工具会渲染一个临时的 ProRes 4444 母版，并将其交给 ffmpeg，因此 ffmpeg 必须位于 PATH 中。我们不会直接把 HEVC .mov 交给 ffmpeg：低于 8.0 的 ffmpeg 版本无法解码 HEVC 的 Alpha 图层，还会悄无声息地生成不透明的 WebM。8 及更高版本可以正常解码，但 ProRes 方案适用于任何版本。提供这两个文件时，请将 .mov 放在前面：

<video autoplay loop muted playsinline>
  <source src="demo-framed.mov" type="video/quicktime" />
  <source src="demo-framed.webm" type="video/webm" />
</video>

顺序很重要。Safari 可以播放 VP9/WebM，但会丢弃其 Alpha 通道；因此，如果把 WebM 放在前面，Safari 会将透明区域显示为纯黑色。将 .mov 放在前面后，Safari 会使用带 Alpha 通道的 HEVC 文件，而 Chrome 和 Firefox 会跳过 video/quicktime，改用 WebM。

为透明视频导出指定 --output 时，路径必须以 .mov 结尾。WebM 文件会以 .webm 扩展名保存在同一目录中。

标志

bezelbub frame --input <path> [options]
bezelbub devices [--input <path> | --dimensions WxH] [--json]

frame 的选项：

标志	作用
--input, -i	截图（PNG、JPEG、HEIC）或视频（.mov、.mp4、.m4v，根据扩展名选择）。必填。
--device, -d	来自 bezelbub devices 的设备 ID。省略时，根据像素尺寸检测。
--color, -c	颜色名称或 ID，不区分大小写。默认为设备的默认颜色。
--orientation	portrait、landscape 或 auto（默认值，根据输入的形状确定）。
--background	十六进制颜色（#RRGGBB 或 #RRGGBBAA）或 transparent。图像默认为透明，视频默认为黑色。视频使用 transparent 时，输出格式会切换为带 Alpha 通道的 HEVC .mov。
--output-size	缩放结果，同时保持设备边框的宽高比：指定宽度（1920）、与宽高比相符的精确 WxH，或百分比（50%）。图像尺寸范围为 16 至 16,384 px，视频为 16 至 7,680 px。
--output, -o	结果的写入位置。默认为输入文件所在目录下的 <input>-framed.png、.mp4 或 .mov。
--webm	另外生成带 Alpha 通道的 VP9/WebM 副本。仅适用于使用 --background transparent 的视频；需要 PATH 中存在 ffmpeg。
--json	在标准输出中打印 JSON 结果，而不是文本摘要。

devices 会列出完整目录（ID、显示名称、颜色、方向、屏幕尺寸，以及每台显示设备已知的捕获尺寸），也可以筛选出适合 --input 文件或单独的 --dimensions 值的设备。筛选操作始终以 0 退出。空的 matches 数组表示没有符合条件的设备；如果出现这种情况，则会填入 nearest（按宽高比匹配）。

JSON 输出

frame --json 会打印一个对象：

{
  "color" : "Cosmic Orange",
  "device" : "iphone17pro",
  "height" : 2760,
  "kind" : "image",
  "orientation" : "portrait",
  "output" : "/path/shot-framed.png",
  "width" : 1350
}

kind 的值为 "image" 或 "video"。视频还会包含 "transparent": true|false；如果运行了 --webm，还会包含 "webm" 输出路径。devices --json 会打印 {id, displayName, defaultColor, colors, landscapeOnly, hasPortraitBezel, screenWidth, screenHeight, captureSizes} 数组。使用 --input 或 --dimensions 时，会打印 {width, height, matches, nearest}；仅当 matches 为空时，才会填入 nearest。

退出代码

每种失败类型都有各自的代码，因此脚本无需解析 stderr 即可分支处理：

代码	含义
0	成功
1	无法解析的标志值，例如格式错误的 --background 或 --output-size
2	未知、有歧义或无法检测的设备。stderr 会列出候选项。
3	未知颜色。stderr 会列出设备支持的颜色。
4	无法读取输入图像或视频
5	合成或视频导出失败
6	无法写入输出
7	--webm 转换失败，因为 PATH 中缺少 ffmpeg 或 ffmpeg 返回了错误
64	参数格式错误（标准 EX_USAGE）

面向 AI Agent

我们构建 CLI 时，既考虑了人类用户，也同样考虑了 LLM Agent（Claude Code、MCP 工具封装、CI 机器人）的非交互式编程使用：

• 不会出现提示。 每个输入都是带默认值的标志，因此调用要么立即完成，要么立即失败。
• 两个子命令都支持 --json，并返回上文所示的数据结构。
• 错误会告诉你如何修复。 stderr 会提供设备和颜色 ID 的相似选项、符合输入像素尺寸的设备，以及最接近的尺寸，让 Agent 无需人工协助即可修正下一次调用。
• 退出代码 2 到 7 对应不同的失败类型（见上表），让 Agent 无需读取文本即可分支处理。
• 管道输出保持干净。 只有在 TTY 中，我们才会将视频导出进度打印到 stderr，因此捕获的输出仍可解析。
• Agent 的典型工作流：运行 bezelbub devices --input shot.png --json 检查匹配结果，然后运行 bezelbub frame --input shot.png --json，并从结果中读取 output。

本仓库还包含一个开箱即用的 Claude Code 技能，位于 skills/bezelbub-cli/，可教会 Agent 完整的工作流。要为所有项目安装它，请将其复制到用户技能目录：

cp -R skills/bezelbub-cli ~/.claude/skills/

此外还有一个 MCP 服务 @dgr_labs/bezelbub-mcp，可将 CLI 封装为 frame_image、frame_video 和 list_devices 工具。

要求

• macOS 14 或更高版本，iOS 17 或更高版本
• Xcode 16 或更高版本
• XcodeGen

项目组成

取景引擎位于 BezelbubKit，这是一个没有 UI 的 Swift 包（BezelbubKit/）。它只执行一种转换：根据屏幕截图、设备 ID 和方向生成带边框的图像；仅使用 Core Graphics，因此可完全在后台运行，无需 SwiftUI、应用状态或 GUI 会话。视频取景功能位于同级产品 BezelbubVideoKit 中，基于 AVFoundation 构建，因此 Share Extension 等静态图像使用方不会引入视频处理流水线。macOS 应用、iOS 应用、Share Extension 和 bezelbub CLI 都是这些包的轻量客户端。边框和遮罩资源包含在 BezelbubKit 中，并通过 Bundle.module 解析。

构建

我们使用 XcodeGen 生成应用：

xcodegen generate
open Bezelbub.xcodeproj

方案：

• Bezelbub 构建 macOS 应用
• Bezelbub-iOS 构建 iOS 应用和 Share Extension

引擎和 CLI 使用 SwiftPM 构建：

cd BezelbubKit
swift build            # BezelbubKit library and the bezelbub CLI
swift test             # engine round-trip tests

许可证

版权所有 2026 DGR Labs, LLC。保留所有权利。