bezelbub-mcp

Bezelbub

Bezelbubを使うと、スクリーンショットや画面収録をリアルなApple製デバイスのベゼルにはめ込み、iPhone、iPad、Mac、Apple TVのピクセル単位で正確なデバイスモックアップを、フレーム付きの画像や動画として作成できます。次の3通りの方法で使えます。

• macOSおよびiOSアプリとして。スクリーンショットや動画を読み込むと、Bezelbubが対応するデバイスを選んでフレームを付けます。
• ヘッドレスのコマンドラインツール、bezelbub（brew install cwooddgr/tap/bezelbub）として。スクリプトからスクリーンショットにフレームを付けたり、画面収録にデバイスフレームを追加したり、アルファチャンネル付きHEVCの透過動画と、ChromeおよびFirefox向けのVP9/WebM版を書き出したりできます。シェルスクリプト、CI、AI エージェント向けに開発しました。CLIのドキュメントを見る。
• UIのないSwiftパッケージ、**BezelbubKit**として。フレーム処理エンジンをご自身のツールに組み込みたい場合に使えます。

Mac、iPhone、iPad向けのBezelbubをApp Storeで入手。

できること

• デバイスを自動で判別します。 スクリーンショットや動画を読み込むと、適切なベゼルが選ばれます。iPhoneとiPadは正確な解像度で判別します。Mac、iMac、Studio Display、Apple TVでは、「文字を拡大」から「スペースを拡大」まで、macOSの各ディスプレイズーム設定でのキャプチャサイズを判別するため、どのズームレベルでキャプチャしても使えます。サイズが登録されていない場合は、アスペクト比で判別します。同じパネルを使うモデルが複数ある場合は、その中から選択できます。同じデバイスの別のスクリーンショットを読み込んでも、デバイスと色の選択はそのまま維持されます。
• Macでドラッグ＆ドロップできます。ウインドウまたはDockアイコンにスクリーンショットや画面収録をドロップします。
• Macでペーストできます。スクリーンショットをコピーして⌘Vを押すか、「編集」▸「ペースト」を使います。
• iPhoneとiPadで写真アプリや共有シートを使えます。写真アプリから読み込むか、任意のアプリの共有シートから画像をBezelbubに送信します。
• 動画にフレームを付けます。 音声をそのまま残し、ベゼルを重ねたMOVおよびMP4の画面収録を書き出せます。
• 透過動画を書き出します。 背景が完全に透過したフレーム付き動画を、QuickTime .movのアルファチャンネル付きHEVCとして保存できます。Webページやプレゼンテーションに重ねてすぐ使えます。
• 回転を修正します。 横向きになっている動画を回転できます。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： 3つのビューがあり、それぞれ別のデバイスとして扱われます。縦向きまたは横向きで、開いた状態の内側ディスプレイ（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)。どのディスプレイズーム設定でも使えます。Appleが両方に同じ画像を提供しているため、Studio DisplayのベゼルはXDRにも対応します
• Apple TV： 1080pまたは4Kのスクリーンショットに対応するApple TV 4K

bezelbub コマンドラインツール

bezelbub を使うと、シェルスクリプト、CI パイプライン、AI エージェントからスクリーンショットや画面収録にフレームを付けられます。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 で撮影されたものに限られます。外部モニターや縮小された録画など、登録されていないサイズの場合は、アスペクト比による照合に切り替わります。ディスプレイのキャプチャにフレームを付ける場合は、ベゼルの画面に収まるように拡大縮小します。

一致するデバイスが 1 つだけの場合、検出は成功します。同じサイズのモデルが複数ある場合は、エラーに候補が表示されるので、--device <id> を指定して再実行できます。一致するものがない場合は、アスペクト比が最も近いデバイスを提案します。フレームを付ける前に確認するには、bezelbub devices --input <path> または bezelbub devices --dimensions WxH を実行します。

透明な動画と WebM

動画入力に --background transparent を指定すると、MP4 の代わりに、アルファチャンネル付きの HEVC を QuickTime .mov で出力します。デバイスフレーム付きの録画は背景が完全に透明になり、ほかのコンテンツに重ねて使えます。Safari と Apple のフレームワーク（AVFoundation、AppKit、UIKit）は、アルファ付き HEVC を再生できます。Chrome と Firefox ではデコードできません。

これらのブラウザー向けには、--webm を追加すると、アルファチャンネルを保持した VP9/WebM 版も出力されます。これを作成するには、一時的な ProRes 4444 マスターをレンダリングして ffmpeg に渡します。ffmpeg は PATH 上にある必要があります。HEVC のアルファレイヤーをデコードできず、気づかないまま不透明な WebM を出力するため、HEVC の .mov を ffmpeg に直接渡すことは意図的にしていません。バージョン 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 を再生できますが、アルファチャンネルを破棄するため、WebM を先に指定すると、Safari では透明部分が黒一色で表示されます。.mov を先に指定すると、Safari はアルファ付き 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	16 進数の色（#RRGGBB または #RRGGBBAA）、または transparent です。デフォルトは画像の場合は透明、動画の場合は黒です。動画で transparent を指定すると、出力はアルファチャンネル付き HEVC の .mov に切り替わります。
--output-size	ベゼルの縦横比を維持して結果を拡大縮小します。幅（1920）、縦横比に一致する正確な WxH、またはパーセンテージ（50%）を指定します。画像は 16～16,384 px、動画は 16～7,680 px です。
--output, -o	結果の書き込み先です。デフォルトでは入力ファイルと同じ場所に <input>-framed.png、.mp4、または .mov として保存します。
--webm	アルファチャンネル付きの VP9/WebM 版も書き出します。動画で --background transparent を指定した場合のみ使用でき、PATH 上に ffmpeg が必要です。
--json	テキストの概要ではなく、JSON の結果を標準出力に表示します。

devices はカタログ全体（ID、表示名、色、向き、画面サイズ、および各ディスプレイデバイスで既知のキャプチャサイズ）を一覧表示します。または、--input ファイルや単独の --dimensions 値に適合するデバイスに絞り込めます。絞り込みでは常に終了コード 0 が返されます。matches 配列が空の場合は適合するデバイスがないことを示し、その場合は nearest に縦横比が最も近いデバイスが設定されます。

JSON 出力

frame --json は 1 つのオブジェクトを出力します。

{
  "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} が出力されます。nearest が設定されるのは matches が空の場合のみです。

終了コード

失敗の種類ごとに異なるコードが割り当てられているため、スクリプトで標準エラー出力を解析せずに分岐できます。

コード	意味
0	成功
1	解析できないフラグ値。形式が不正な --background や --output-size など
2	不明、曖昧、または検出できないデバイス。標準エラー出力に候補が表示されます。
3	不明な色。標準エラー出力にデバイスで有効な色が表示されます。
4	入力画像または動画を読み込めませんでした
5	合成または動画の書き出しに失敗しました
6	出力を書き込めませんでした
7	PATH 上に ffmpeg がない、またはエラーが返されたため、--webm の変換に失敗しました
64	引数の形式が不正です（標準の EX_USAGE）

AI エージェント向け

この CLI は、人だけでなく LLM エージェント（Claude Code、MCP ツールのラッパー、CI ボット）による、非対話型のプログラムからの利用を想定して構築されています。

• プロンプトは表示されません。 すべての入力はデフォルト値を持つフラグなので、呼び出しはすぐに完了するか、失敗します。
• どちらのサブコマンドも --json を受け付け、 上記の形式で結果を返します。
• エラーには修正方法が示されます。 stderr には「もしかして」と候補となるデバイス ID とカラー ID、入力のピクセルサイズに合うデバイス、最も近いサイズが出力されるため、エージェントは人の手を借りずに次の呼び出しで修正できます。
• 終了コード 2〜7 で失敗の種類がわかります（上の表を参照）。エージェントはテキストを読み取らずに処理を分岐できます。
• パイプの出力は汚れません。 動画のエクスポートの進行状況は、標準エラー出力が TTY の場合にのみ出力するため、キャプチャした出力を解析可能な状態に保てます。
• エージェントの一般的な手順は、bezelbub devices --input shot.png --json を実行して一致を確認し、次に bezelbub frame --input shot.png --json を実行して、結果から output を読み取ることです。

このリポジトリには、エージェントにワークフロー全体を教える、すぐに使える Claude Code スキル skills/bezelbub-cli/ も含まれています。すべてのプロジェクトで使えるようにするには、ユーザーのスキルディレクトリにコピーしてください。

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

また、CLI を frame_image、frame_video、list_devices ツールとしてラップする MCP サーバー @dgr_labs/bezelbub-mcp もあります。

要件

• macOS 14 以降、iOS 17 以降
• Xcode 16 以降
• XcodeGen

構成

フレーミングエンジンは UI のない Swift パッケージ BezelbubKit（BezelbubKit/）に含まれています。スクリーンショット、デバイス ID、向きからフレーム付き画像への変換を 1 つだけ行います。Core Graphics のみを使用するため、SwiftUI、アプリの状態、GUI セッションがなくても完全にオフスクリーンで動作します。動画のフレーミングは、AVFoundation を基盤とする兄弟プロダクト BezelbubVideoKit に含まれているため、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

ライセンス

Copyright 2026 DGR Labs, LLC. All rights reserved.