# caixukun-go

**Repository Path**: spitman/caixukun-go

## Basic Information

- **Project Name**: caixukun-go
- **Description**: ikun纯享, 命令行字符动画
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-08-06
- **Last Updated**: 2026-04-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ASCII Player · 视频转字符动画

一个本地工具：选一个视频，用 ffmpeg 拆帧 + 抽音轨，再把每帧转成 ASCII 字符画，最后在浏览器里以音画同步的形式播放字符动画。

形态参考 Jupyter Notebook —— 启动一个 Go 写的本地 Web 服务器，自动打开浏览器、真正操作文件系统的是后端、UI 只是个壳。

---

## 前置要求

- 系统装好 [**ffmpeg**](https://ffmpeg.org/download.html) 并放到 `PATH`（`ffprobe` 同目录，一起装就有）。启动时程序会探测一次，没装会在 UI 顶部挂红条并在控制台警告。
- 一个现代浏览器（Chrome / Edge / Firefox / Safari）。
- 用户目录可写（放 `~/.ascii-player/db.sqlite` 做历史索引）。

## 下载 & 运行

发布产物见 `dist/`，按平台取用：

| 平台 | 文件 |
|---|---|
| Windows x64 | `ascii-player-windows-amd64.exe` |
| macOS Intel | `ascii-player-darwin-amd64` |
| macOS Apple Silicon | `ascii-player-darwin-arm64` |
| Linux x64 | `ascii-player-linux-amd64` |

### Windows

双击 `ascii-player-windows-amd64.exe`。浏览器会自动打开；如果没开，复制控制台里的 `http://127.0.0.1:xxxx/` 手动访问。Windows Defender 或杀软可能拦截（二进制未签名），放行即可。

### macOS

```bash
chmod +x ascii-player-darwin-arm64
xattr -d com.apple.quarantine ascii-player-darwin-arm64   # 若从浏览器下载
./ascii-player-darwin-arm64
```

或 Finder 里右键 → 打开 → 同意一次。

### Linux

```bash
chmod +x ascii-player-linux-amd64
./ascii-player-linux-amd64
```

---

## 使用流程

UI 顶栏有两个 tab：**转换** 和 **播放**。右上角是 **退出** 按钮（干净地关掉后端进程）。

### 转换 tab

1. 点**浏览…**选视频文件（或直接粘贴绝对路径）
2. 调整**宽度 / 高度 / 帧率 / 字符集 / 对比度**（都有合理默认）
3. 点**开始转换**。程序在视频同级目录建工作目录 `<视频名>.ascii/`：
   ```
   demo.ascii/
   ├── meta.json      转换参数 + has_audio 等统计
   ├── frames/        ffmpeg 拆出来的 jpg
   ├── ascii/         每一帧对应的 .txt 字符画
   └── audio.m4a      若源视频有音轨（AAC 128kbps），无则不存在
   ```
4. 进度页实时显示两段进度条（拆帧 → 字符转换）和 ffmpeg 日志，可随时**取消**（取消会清掉工作目录）
5. 完成后 1.5 秒自动跳到播放 tab；也可以点 ▶ 播放 立即跳

**冲突处理**：用同一个视频再提交时，后端返回 `409`，UI 弹确认框询问"是否覆盖"。

### 播放 tab

- 顶部列出**最近使用**（从 SQLite 读），每行点 **▶ 播放** 即加载；点**移除**把行从列表里删（不动磁盘）
- 工作目录已经不存在的条目灰显 + 标注
- 右上角**打开新文件…** 启文件浏览弹窗：
  - 选视频文件：若同级 `.ascii/` 已存在则直接加载；否则提示"前往转换 tab"
  - 列表里以 `.ascii` 结尾的目录，行尾有独立的 **播放** 按钮，点即加载

### 播放器

- 字符帧**自动适配窗口**（默认）：窗口变大字号自动放大、字符铺满容器；按 **−/+** 切到手动档，点 **自动** 切回
- **⛶ 全屏**按钮调用 Fullscreen API，字符帧吃满整屏
- 有音轨时隐藏 `<audio>` 作为时钟源，rAF 按 `currentTime × fps` 取帧，**音画严格同步**；无音轨退回 `performance.now()` 本地时钟
- 倍速（0.5× / 1× / 1.5× / 2×）和循环开关会同步作用到音频
- 配色三档：黑底白字 / 绿色终端 / 白底黑字；偏好写 `localStorage`

#### 快捷键

| 键 | 功能 |
|---|---|
| `Space` | 播放 / 暂停 |
| `←` / `→` | 上一帧 / 下一帧 |
| `L` | 切换循环 |
| `F` | 切换全屏 |

---

## 持久化

- 每次创建或打开一个任务都会 upsert 一行到 `~/.ascii-player/db.sqlite`（Windows 下是 `%USERPROFILE%\.ascii-player\db.sqlite`），用于播放 tab 的"最近"列表
- 拿不到 home 目录或 DB 打不开：后端降级为"无持久化"，控制台打 warn，功能不受影响
- 任务 ID 由工作目录的绝对路径派生（`sha256(abs-path)[:16]`），**重复打开同一工作目录会得到同一 ID**，方便复用

---

## 从源码构建

需要 Go 1.21+。除了 SQLite 驱动外无外部依赖，前端资源通过 `go:embed` 进二进制。

```bash
# 本平台
go build -o ascii-player ./cmd/ascii-player

# 一次出全平台（Windows / macOS Intel + Apple Silicon / Linux）
./scripts/build-all.sh           # Linux / macOS / git-bash
pwsh ./scripts/build-all.ps1     # Windows PowerShell
```

产物都落在 `dist/`。SQLite 驱动用纯 Go 版（`modernc.org/sqlite`），**无 CGO**，任意平台都能一键交叉编译。

开发循环：

```bash
go run ./cmd/ascii-player
```

监听 `127.0.0.1:0`（随机端口）并自动开浏览器。

---

## 项目结构

```
ascii-player/
├── cmd/ascii-player/
│   ├── main.go             入口：HTTP 服务 + 打开浏览器 + 接入 manager / store
│   └── history.go          adapter: task.HistorySink ↔ store.Store
├── internal/
│   ├── server/             HTTP 路由 + SSE
│   │   ├── server.go
│   │   ├── tasks.go        /api/tasks, /events, /cancel, /frames, /audio
│   │   ├── history.go      /api/tasks/open, /api/tasks/history[/{id}]
│   │   ├── fs.go           /api/fs/roots, /api/fs/list
│   │   ├── health.go       /api/health (ffmpeg 状态)
│   │   └── shutdown.go     /api/shutdown
│   ├── task/               任务状态机 + 事件总线 + 派生 ID + Open
│   ├── video/              ffmpeg 封装（Extract + HasAudioStream）
│   ├── ascii/              图像 → 字符画 (OOP 版)
│   ├── store/              SQLite 持久化 (modernc.org/sqlite)
│   ├── fsys/               跨平台目录浏览 (roots_*.go)
│   └── platform/           跨平台浏览器打开 (browser_*.go)
├── web/                    前端静态资源 (embed)
│   ├── embed.go
│   ├── index.html
│   └── static/{app.css,app.js}
├── legacy/                 v0.x 旧实现归档（独立 go.mod 子模块，不参与主构建）
├── scripts/build-all.*     交叉编译脚本
├── docs/
│   ├── PRD.md
│   └── DESIGN-v2.md
└── dist/                   构建产物（gitignored）
```

## API 速览

| 路径 | 方法 | 说明 |
|---|---|---|
| `GET /api/health` | GET | ffmpeg 状态（available / version / error） |
| `GET /api/fs/roots` | GET | 平台相关的入口位置列表（盘符 / `/` / `~` / 挂载点） |
| `GET /api/fs/list?path=...` | GET | 列出目录下的子目录 + 视频文件 |
| `POST /api/tasks` | POST | 新建转换任务；活动任务未终止时返 409 |
| `POST /api/tasks/open` | POST | 加载已有任务：入参 `{path}`，视频文件或 `.ascii/` 目录都可以 |
| `GET /api/tasks/{id}` | GET | 任务快照（meta + progress + logs + error） |
| `GET /api/tasks/{id}/events` | GET (SSE) | 订阅进度 / 日志 / 状态 / 结束事件 |
| `POST /api/tasks/{id}/cancel` | POST | 取消任务（清理工作目录） |
| `GET /api/tasks/{id}/frames` | GET | 全部 ASCII 帧（仅 `status=done` 时可用） |
| `GET /api/tasks/{id}/audio` | GET/HEAD | 原样返回 `audio.m4a`，支持 `Range`；无音轨时 404 |
| `GET /api/tasks/history` | GET | SQLite 里的已知任务列表，含 `work_dir_exists` |
| `DELETE /api/tasks/history/{id}` | DELETE | 从列表里移除一条；不动磁盘 |
| `POST /api/shutdown` | POST | UI 触发后端进程优雅退出 |

## Legacy

`legacy/` 是 v0.x 的命令行 / Windows GUI 实现，独立 `go.mod`，主模块构建不会进去。想重跑旧版：

```bash
cd legacy
go run ./app/all          # 一键三步
```

---

## 许可

见 `LICENSE`。