timg：终端图片视频查看器

项目简介

timg 是一个用户友好的终端图片查看器。它会优先使用终端的图形能力（sixel、Kitty Graphics Protocol 或 iTerm2 Graphics Protocol）以完整分辨率显示图片；如果终端不支持这些协议，则回退到 24 位色与 Unicode 块字符的半块/四分之一块显示方式。

它的用途是在不离开 shell、不启动笨重图形查看器的情况下快速看一眼图片，尤其是在通过 ssh 远程连接时。图标通常能像素级还原，较大的图片会被缩小以适配终端。

项目主页：https://timg.sh/

主要功能

• 多种像素化模式：-p 可选 h（半块）、q（四分之一块）、k（Kitty graphics）、i（iTerm2 graphics）、s（sixel graphics）。默认自动探测图形协议，否则使用 quarter。半块颜色准确，四分之一块空间分辨率更高但颜色精度略低。
• 网格显示：--grid=<cols>[x<rows>] 把多张图片排成「联系表」，便于快速浏览大量图片。
• 标题显示：--title[=<fmt_str>] 在每张图上方打印标题，支持 %f 完整文件名、%b 基名、%w 宽度、%h 高度、%D 解码器等格式参数。
• 多格式内容：显示普通图片、播放动图 gif、滚动静态图，以及播放视频；也能查看 PDF、SVG 等（取决于编译时的依赖）。
• 管道输入：文件名 - 表示从 stdin 读取，可以直接接 qrencode、gnuplot 等命令的输出。
• 图像处理选项：--auto-crop 自动裁掉同色边框、--rotate=<exif|off> 按 exif 旋转、-C 水平居中、-W 适应宽度、-U 允许放大、-b 指定 alpha 背景色、-B 指定棋盘格颜色。
• 动画与视频控制：--loops、--frames、--frame-offset、-t 控制循环次数、帧数与播放时长；--scroll 支持横向滚动。
• 其他：--threads 并行解码、-o 输出到文件、--compress 压缩 Kitty/iTerm2 图形数据、--color8 8 位色模式。

安装与使用

命令基本形式：

usage: timg [options] <image/video> [<image/video>...]

常用示例：

# 显示一张静态图片
timg some-image.jpg

# 限制在 50x50 字符的框内显示
timg -g50x50 some-image.jpg

# 多张图片：带标题、排成网格
timg --title *.jpg
timg --title="%b (%wx%h)" *.jpg
timg --grid=3x2 *.jpg
timg --grid=3 -t5 *.gif          # 网格中逐个播放 gif，每个 5 秒

# 做成别名，当成图片版 ls
alias ils='timg --grid=2x1 --upscale=i --center --title --frames=1 '
ils *.jpg *.gif

# 从文件列表读取要显示的图片
locate "*.jpg" > /tmp/allimg.txt ; timg -f /tmp/allimg.txt

# 显示 PDF：占满终端宽度并裁掉空白边框
timg -W --auto-crop some-document.pdf

# 从管道读取（文件名 - 表示 stdin）
qrencode -s1 -m2 "http://timg.sh/" -o- | timg -
echo "set terminal png; plot sin(x);" | gnuplot | timg -

# 从 URL 打开图片（由视频子系统处理，被视为单帧）
timg --center https://i.kym-cdn.com/photos/images/newsfeed/000/406/282/2b8.jpg

# 播放视频、摄像头
timg some-video.mp4
timg /dev/video0

# 从管道读视频时必须用 -V 跳过图像解码
youtube-dl -q -o- -f'[height<480]' 'https://youtu.be/dQw4w9WgXcQ' | timg -V -

安装方面，项目 release 页面提供的 app-image 是一个只含少量依赖的精简版本；若要使用视频、PDF、SVG 等完整功能，需要自行编译，或通过你所使用的操作系统发行版获取。

注意事项

• 完整分辨率显示依赖终端支持 sixel、Kitty Graphics Protocol 或 iTerm2 Graphics Protocol；不支持时会退回块字符显示，分辨率和颜色表现会有所下降。
• 从管道读取视频时必须加 -V 直接使用视频子系统，否则会先尝试图像解码而消耗掉管道字节。
• 通过 URL 打开图片时走的是视频子系统，因此裁剪、滚动等部分图像专属功能不可用；需要自动裁剪时可先用 wget 取回内容再通过 stdin 处理。
• 手动裁剪可由 --auto-crop=<pre-crop> 先去掉不均匀边框，再进行自动裁剪。
• 许可证：GPL-2.0。

---

本作品整理自 GitHub 开源项目 hzeller/timg，原作者 @hzeller，许可证 GPL-2.0。中文介绍由 AI 根据项目 README 整理，以原仓库为准。