终端里的迷你影院：Sakura 入门完全指南

把 JPG、GIF、MP4 直接播放在命令行窗口，只需 1000 行 C++ 代码。

目录

  1. Sakura 是什么？
  2. 它能做什么
  3. 一分钟速览安装步骤
  4. 上手：第一次运行
  5. 进阶：四种渲染模式怎么选
  6. 常见问题 FAQ
  7. 性能优化 5 个小技巧
  8. 开发者视角：如何把 Sakura 嵌入自己项目
  9. 常见报错与修复
  10. 下一步还能做什么

Sakura 是什么？

一句话：Sakura 是一个“极轻量级”的多媒体播放器，1000 行左右 C++ 代码，把终端变成小影院。
它用 SIXEL 图形协议把像素直接画在命令行窗口，同时调用 ffplay 同步播放声音。

关键词 通俗解释
SIXEL 终端里的“位图”指令，支持真彩色
libsixel 把 RGB 图片翻译成 SIXEL 指令的库
OpenCV 负责解码 JPG、PNG、MP4 等常见格式
ffplay FFmpeg 自带的小播放器，只播声音不显示画面

它能做什么

  • 图片：JPG、PNG、BMP
  • 动图：GIF（保持帧率）
  • 视频：MP4、AVI、MOV、MKV（自动缩放 + 声音同步）
  • 在线资源：直接贴 URL 即可播放
  • 自适应：窗口多大，画面就缩放到多大，长宽比不变

一分钟速览安装步骤

系统 一键指令
Ubuntu / Debian sudo apt install libopencv-dev libsixel-dev ffmpeg cmake build-essential
Arch Linux sudo pacman -S opencv sixel ffmpeg cmake base-devel
macOS brew install opencv libsixel ffmpeg cmake

注意：Ubuntu/Debian 没有现成的 cpr 包，需要手动编译。
把下面三行粘进终端即可：

git clone https://github.com/libcpr/cpr.git && cd cpr
mkdir build && cd build && cmake .. && make && sudo make install

编译 Sakura

git clone https://github.com/Sarthak2143/sakura.git
cd sakura && mkdir build && cd build
cmake .. && make -j$(nproc)

完成后会得到一个 ./sakura 可执行文件，直接运行即可。

上手：第一次运行

  1. 终端执行 ./sakura
  2. 出现菜单：

    Sakura Video Player with SIXEL
1. Image
2. GIF
3. Video (URL)
4. Video (File)
Choose option (1-4):
  3. 按需输入序号 + 路径或网址即可。

快速体验（无需本地文件）

# 在线随机图片
echo -e "1\nhttps://picsum.photos/800/600" | ./sakura

# 在线 GIF
echo -e "2\nhttps://media.giphy.com/media/3o7qE1YN7aBOFPRw8E/giphy.gif" | ./sakura

进阶：四种渲染模式怎么选

模式 优点 缺点 适用场景
SIXEL（默认） 真彩色、最清晰 需要终端支持 现代终端（xterm、wezterm、foot）
ASCII Color 兼容所有终端 只有色块 远程 SSH、老机器
ASCII Grayscale 纯字符，极省带宽 无彩色 纯调试或怀旧
Exact Mode 用 Unicode 块拼像素 字体必须等宽 想尝鲜时试试

如何强制切换？在代码里把 RenderMode 枚举改掉即可，后面“开发者视角”会给出示例。

常见问题 FAQ

Q1：我的终端一片黑，什么也没显示？
A：先确认终端本身支持 SIXEL。
最简单测试：

echo -e '\ePq"1;1;100;100#0;2;0;0;0#1;2;100;100;0#1~~@@vv@@~~@@~~$#0~~@@~~@@~~@@vv$#1!14~\e\\'

如果看到彩色方块，说明支持；否则换 xterm、wezterm 或 foot。

Q2：视频播放卡顿？
A：三步排查

  1. 按 Ctrl+C 退出后看最后一行提示 Drop Rate: x%，>10% 才需处理。
  2. 用 ffmpeg -i input.mp4 -vf scale=640:480 -r 15 smaller.mp4 先压缩。
  3. 在代码里把 scale_factor 改小，例如 0.5。

Q3：没有声音？
A：确保 ffplay 已安装且音量没静音：

which ffplay
ffplay -nodisp -autoexit test.mp4

Q4：能播 YouTube 链接吗？
A：不能直接播。先用 yt-dlp 或 youtube-dl 把视频拉下来，再用 Sakura 播放本地文件。

Q5：如何退出？
A：按 q 或 Ctrl+C 均可。

性能优化 5 个小技巧

  1. 提前缩放
    用 FFmpeg 把 4K 视频压到 720p：ffmpeg -i in.mp4 -vf scale=1280:720 out.mp4
  2. 降低帧率
    30 fps 足够流畅：ffmpeg -i in.mp4 -r 30 out.mp4
  3. 减少颜色
    在 RenderOptions 里把 paletteSize 改成 128 或 64。
  4. 硬件加速
    FFmpeg 支持 --hwaccel auto 时，Sakura 会直接受益。
  5. 关闭桌面特效
    在老旧笔记本上，把桌面合成器关掉，CPU 占用立刻下降。

开发者视角：如何把 Sakura 嵌入自己项目

最小可运行示例

#include "sakura.hpp"

int main() {
    Sakura player;
    RenderOptions opt;
    opt.mode = SIXEL;
    opt.paletteSize = 256;

    // 1. 播放在线图片
    player.renderFromUrl("https://example.com/pic.jpg", opt);

    // 2. 播放本地视频
    player.renderVideoFromFile("clip.mp4", opt);

    return 0;
}

关键类速查

类 / 结构 说明
Sakura 主渲染器，提供 renderFromUrl、renderVideoFromFile 等函数
RenderOptions 配置宽高、颜色数量、渲染模式、亮度对比度等
RenderMode 枚举 SIXEL / ASCII_COLOR / ASCII_GRAY / EXACT

自己写循环批量处理

std::vector<std::string> urls = { "a.jpg", "b.jpg", "c.jpg" };
for (const auto& u : urls) {
    player.renderFromUrl(u, opt);
    std::this_thread::sleep_for(std::chrono::seconds(2)); // 间隔 2 秒
}

常见报错与修复

报错信息 原因 修复
Failed to open video 文件不存在或权限不足 ls -l 确认路径，chmod +r
Sixel output not visible 终端协议不支持 换用 xterm -ti vt340
ffplay not found FFmpeg 未安装 sudo apt install ffmpeg
Audio but black screen 视频分辨率太高 先转码降低分辨率
Drop Rate: 50% 以上 CPU 吃紧 关特效、降分辨率、降帧率

NixOS 用户专属

如果你用 NixOS，可直接用 Flakes：

# configuration.nix
{
  inputs.sakura.url = "github:sarthak2143/sakura";
  inputs.sakura.inputs.nixpkgs.follows = "nixpkgs";

  outputs = { self, nixpkgs, sakura }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ./configuration.nix
        sakura.nixosModules.sakura
      ];
    };
  };
}
# 启用
programs.sakura.enable = true;

临时体验一行搞定：

nix run github:sarthak2143/sakura

下一步还能做什么

  • 把 TODO 列表做完：

    • 把掉帧率降到 5 % 以下
    • 增加异常类，让报错更友好
  • 写一个脚本，把监控摄像头的 RTSP 流实时转码后丢给 Sakura
  • 在树莓派上跑，当作“终端数字相框”

写在最后

Sakura 的核心价值不是炫技，而是“够用且极简”。
1000 行代码就能让终端播放高清视频，这对教育、嵌入式、远程调试都有实际意义。
如果你把它用在有趣的项目里，欢迎回到 GitHub 提 Issue 或 Pull Request，一起把终端影院做得更好。