OSC 1337 — iTerm2 内联图片与文件传输

字节形式

涵盖所有常见的字符串字面量写法，方便正反查找。

说明

iTerm2 私有的 OSC 1337 通过一个 OSC 代码复用一整族带外特性，靠体内首个 token 区分。最常用形式是 **`File=...:<base64>`** 用于内联图片与文件传输 —— 同一词汇，不同 `inline=` 标志。键（key=value，`;` 分隔，置于 `:` 之前）： - `name=<文件名 base64>` —— 显示名 / Cmd-S 保存目标。 - `size=<字节>` —— 进度条用。 - `inline=1` —— 在光标处渲染为图片（默认 0 表示「下载到 ~/Downloads」）。 - `width=<n>` / `height=<n>` —— 尺寸，单位为单元、像素（`px` 后缀）、百分比（`%` 后缀）或 `auto`。 - `preserveAspectRatio=0|1` —— 默认 1。 - `type=<mime>` —— `image/png`、`image/jpeg`、`image/gif`（动画）、`application/pdf` 等。 键之后跟单个 `:` 分隔符，再是 **base64 编码的载荷**。GIF 的动画帧自动播放。iTerm2 还为 OSC 1337 定义了非 File 子码：`RemoteHost=<user>@<host>`、`CurrentDir=<path>`（如今多被 OSC 7 取代）、`SetUserVar=<name>=<base64>`（自定义状态栏变量）、`SetMark`（跳转点，与 OSC 133 不同）、`ReportCellSize`（回复单元像素大小 —— tmux 用它做像素精确的 Sixel 缩放）。**现代采用**：iTerm2（始作俑者）；WezTerm + Konsole 22.04+ 实现 `File=` 子集；Kitty / Ghostty 各自宣传自家协议（kitty graphics / WezTerm imgcat-compat），但都接受 OSC 1337 `File=` 以兼容 iTerm2 发行的 `imgcat` shell 脚本。今日用途：把图片送入终端面板而不依赖 Sixel；`imgcat` 脚本是标准入口。

规范出处: iTerm2 Proprietary Escape Codes (OSC 1337)

参数

示例

# imgcat-style: render PNG at cursor.\nB64=$(base64 -w 0 ./logo.png)\nprintf '\033]1337;File=name=%s;inline=1:%s\007' "$(printf 'logo.png' | base64 -w 0)" "$B64"

import base64, sys\ndata = open('logo.png','rb').read()\nname = base64.b64encode(b'logo.png').decode()\npayload = base64.b64encode(data).decode()\nsys.stdout.write(f'\x1b]1337;File=name={name};inline=1:{payload}\x07')

// Advertise CWD via iTerm2's older mechanism (most apps prefer OSC 7 now):\nfmt.Print("\x1b]1337;CurrentDir=/Users/me/code\x07")

// Set a custom iTerm2 user var that a status-bar component can read:\nconst b64 = Buffer.from('on-call').toString('base64')\nprocess.stdout.write(`\x1b]1337;SetUserVar=role=${b64}\x07`)

/* Probe iTerm2/wezterm cell-pixel size — used by Sixel renderers: */\nfputs("\x1b]1337;ReportCellSize\x07", stdout);\n/* Reply lands on stdin as another OSC 1337. */

终端支持

xterm

不支持

Linux console (fbcon)

不支持

macOS Terminal.app

不支持

iTerm2

支持

Windows Terminal

不支持

cmd.exe / ConPTY

不支持

kitty

部分

alacritty

不支持

WezTerm

支持

Ghostty

部分

GNOME Terminal

不支持

Konsole

支持

tmux

不支持

GNU screen

不支持

相关序列

• DCS Sixel — 内联栅格图像（ESC P q … ESC \）
• Kitty 图形协议 —— 内联像素图像（ESC _ G … ESC \）
• OSC 7 — 当前工作目录提示
• OSC 8 — 内联超链接

在家族食谱中

↗OSC 食谱 · 6. 内联图片与进度 —— `OSC 1337` 与 `OSC 9 ; 4`