ASCII 视频工坊使用指南
工坊与 Embed 播放器

ASCII 视频工坊是什么？

ASCII 视频工坊是一套纯前端、单文件的 ASCII 字符画工具，包含两个版本： 完整版（ASCIIplayer.html，负责"生产"）与 Embed 版（ASCIIplayer-embed.html，负责"消费"）。 视频 / 图片 / 摄像头画面会被实时转换为字符画帧序列，保存为自定义的 .ascii-video 文件；Embed 版读取该文件并在任意网页中播放。

本指南先简要介绍完整版的使用，然后重点讲解 Embed 版的三种外部控制方式： URL 参数（加载即生效）、postMessage（iframe 嵌入实时调参）、 全局 API（同页脚本直接调用）。

功能特性

完整版（ASCIIplayer.html）

• 多来源输入：上传视频 / 图片 / GIF，或直接使用摄像头录制
• 实时字符画渲染：WebGPU 着色器按当前参数实时重算字符，调参即时生效
• 时间线编辑：分割 / 排序 / 删除 / 合并片段，拖动边缘变速（0.1×–10×），双击分割
• 块独立画面设置：每个片段可单独覆盖显示模式、字形、伽马、翻转等参数
• 多格式导出：.ascii-video（v6/v7 含音频）、GIF、普通视频（MP4/WebM）、图片
• 画中画：角落同步显示原视频，方便对比

Embed 版（ASCIIplayer-embed.html）

• 单文件零构建：约 67 KB，无任何参数面板，适合 iframe 嵌入第三方页面
• 多种加载方式：本地拖拽 / 「打开文件」按钮 / ?src= 远程 URL
• 16+ URL 参数：模式、字形、伽马、亮度、对比度、反色、翻转、颜色、画面比例、音频、界面级别等
• 外部实时控制：postMessage 消息与 window.AsciiEmbed 全局 API
• GPU/CPU 双后端：默认 WebGPU 离屏加速，异常时自动切换 CPU 计算（画面不中断）
• v6/v7 播放：支持内嵌音轨（Opus/WebM），按帧时间戳严格对齐源视频时长

完整版快速上手

1. 生成字符画视频

打开 ASCII 视频工坊（ASCIIplayer.html）：

• 点击「上传视频或图片」，或直接把文件拖入预览区；也可点击「录制」调用摄像头实时录制。
• 在右侧「画面」面板调整显示模式、字形大小、伽马、反色、翻转、画面比例等参数，预览即时更新。
• 点击「保存」导出 .ascii-video 文件（默认 v6 无音频；在「处理与导出 → 音频」中开启「嵌入音频」后保存为 v7 含声音）。

2. 时间线编辑（可选）

选中已加载的条目后点击「编辑」进入编辑模式：双击片段分割、拖动排序与修剪、 拖动边缘变速、选中多个片段可合并/删除，每个片段还能单独设置画面参数（右上角琥珀色圆点标记）。 编辑完成后用时间轴工具栏的导出按钮输出 .ascii-video 或普通视频。

提示：Embed 版仅支持 v6 / v7 格式。旧版本（v1–v5）文件请用工坊重新导出。

Embed 版使用教程

1. 快速开始

直接打开 Embed 播放器（ASCIIplayer-embed.html），会显示拖拽提示：

/ToolBase/ASCII/ASCIIplayer-embed.html

通过 ?src= 指定远程 .ascii-video 文件，打开即自动加载播放：

/ToolBase/ASCII/ASCIIplayer-embed.html?src=/ToolBase/ASCII/video/demo.ascii-video

也可在页面内拖入 .ascii-video 文件，或点击「打开文件」按钮选择本地文件。

2. URL 参数（加载时即生效）

示例：

# 灰度 + 大字形
/ToolBase/ASCII/ASCIIplayer-embed.html?src=/ToolBase/ASCII/video/demo.ascii-video&mode=grayscale&glyph=24

# 白色字符 + 青色前景 + 高对比
/ToolBase/ASCII/ASCIIplayer-embed.html?src=/ToolBase/ASCII/video/demo.ascii-video&mode=white&fg=%2322d3ee&contrast=1.6

# 纯画布嵌入（点击画布播放/暂停，无任何控件）
/ToolBase/ASCII/ASCIIplayer-embed.html?src=/ToolBase/ASCII/video/demo.ascii-video&ui=none

# 等比铺满（放大裁剪无空白，不变形）
/ToolBase/ASCII/ASCIIplayer-embed.html?src=/ToolBase/ASCII/video/demo.ascii-video&aspect=cover

3. iframe 嵌入

Embed 版没有参数面板，ui=full 保留播放控制条，ui=none 为纯画布（点击画布切换播放/暂停，键盘空格/Esc/左右方向键同样有效）。

<iframe
  src="/ToolBase/ASCII/ASCIIplayer-embed.html?src=/ToolBase/ASCII/video/demo.ascii-video&ui=full"
  width="960" height="540"
  allow="autoplay"
  style="border:0;border-radius:8px"
  title="ASCII 视频播放器"
></iframe>

注意：如需自动播放内嵌音频，iframe 必须带 allow="autoplay"，否则浏览器可能拦截。

4. postMessage 实时控制

父页面通过 iframe.contentWindow.postMessage() 控制播放器，无需刷新页面：

const player = document.querySelector('iframe#player');

// 实时改参：灰度 + 字形 24
player.contentWindow.postMessage({
  type: 'ascii:params',
  params: { mode: 'grayscale', glyph: 24 },
}, '*');

// 传输本地文件（transferable 零拷贝）
file.arrayBuffer().then((buf) => {
  player.contentWindow.postMessage(
    { type: 'ascii:loadBuffer', buffer: buf, name: file.name },
    '*', [buf]
  );
});

5. 全局 API（同页脚本）

在播放器自身页面内（或 devtools 控制台）可直接调用 window.AsciiEmbed：

window.AsciiEmbed.setParams({ mode: 'white', invert: true });
window.AsciiEmbed.load('/ToolBase/ASCII/video/demo.ascii-video');
window.AsciiEmbed.loadFile(file);   // File 对象
window.AsciiEmbed.play();
window.AsciiEmbed.pause();
window.AsciiEmbed.stop();
window.AsciiEmbed.seekTo(0.5);
window.AsciiEmbed.getState();
// → { frames, cols, rows, fps, playIndex, isPlaying, hasAudio, renderMode }

6. 实时演示

下面是一个实际运行的嵌入示例（播放器 /ToolBase/ASCII/ASCIIplayer-embed.html，示例数据 /ToolBase/ASCII/video/demo.ascii-video）：

注意：示例 .ascii-video 文件位于 /ToolBase/ASCII/video/demo.ascii-video；也可把 ?src= 换成你自己的文件路径。

完整版与 Embed 版对比

.ascii-video 文件格式

二进制容器：头部 48 字节 + 数据区。头部包含 magic "ASCI"、版本号、flags（扩展字符集 / 颜色位数 / 含音频）、列数、行数、fps、帧数。

• v6：每帧 u32 真实时间戳（源媒体时间，播放严格死比对源时长）+ 帧间残差（量化后比较，微变自动忽略）+ 整体 gzip。播放按时间戳驱动，时长恒等于源视频时长。
• v7：v6 + 尾部音频段（u32 视频数据长度 + gzip 视频 + u32 音频长度 + Opus/WebM 音频），播放器自动同步内嵌音频（audio=0 可关闭）。

内存帧为每格 7B（字符占位 + RGB 8bit），渲染时由 GPU 着色器按当前参数从 RGB 实时重算字符——因此导入后修改字形大小 / 伽马 / 反色等参数会实时生效。

浏览器要求

• WebGPU：Chrome 113+ / Edge 113+（GPU 计算渲染）；Firefox 需手动开启 dom.webgpu.enabled。
• DecompressionStream('gzip')：Chrome 80+ / Edge 80+ / Safari 16.4+（v6/v7 文件解压必需）。
• 自愈降级：默认 GPU 计算（离屏渲染 → 2D 显示）；GPU 不可用、读回挂起、画面连续无变化时自动切换 CPU 计算，画面不中断。任何浏览器都能播放。
• 诊断：render=cpu 可强制 CPU 计算；右上角徽标常驻显示当前后端；控制栏「调试」开关显示实时渲染状态；getState() 返回 renderMode / renderErrorCount / gpuStaticCount 便于定位问题。

常见问题

1. 如何生成 .ascii-video 文件？

使用完整版 ASCII 视频工坊：上传视频/图片 → 调整画面参数 → 点击「保存」。默认导出 v6；在「处理与导出 → 音频」开启「嵌入音频」后保存为 v7 含声音。

2. Embed 版播放旧文件提示"仅支持 v6/v7"？

v1–v5 旧格式已放弃兼容（使解码路径最短、最可靠）。请用完整版重新导入并另存为新版本。

3. 不支持 WebGPU 的浏览器能播放吗？

能。播放器会自动切换到 CPU 计算模式（画面不中断），右上角徽标会显示 CPU；也可用 render=cpu 或控制栏按钮强制。

4. 嵌入页面后音频没有声音？

检查两点：文件必须是 v7（含音频）；iframe 需要加 allow="autoplay" 属性，否则浏览器会拦截自动播放。

5. 画面比例如何控制？

aspect=original 原比例不变形（默认）；aspect=cover 等比放大铺满（裁剪溢出，无空白）；aspect=stretch 拉伸填满；aspect=custom&aw=…&ah=… 自定义；fill=1 等效 stretch。

6. 参数不生效？

URL 参数在加载时生效，postMessage 随时覆盖，二者可混用、后到者胜；extended 若文件内嵌标记已启用，仅当 URL 未显式指定时才沿用文件标记。修改 ui= / render= 这类启动级参数需要刷新页面。

🤝 相关资源

• 完整版工坊：/ToolBase/ASCII/ASCIIplayer.html
• Embed 播放器：/ToolBase/ASCII/ASCIIplayer-embed.html
• 技术文档：docs/ASCIIplayer-embed-doc.md（仓库内，含全部参数与 API 细节）
• 在线演示：ASCII 播放器 Embed 演示（交互式调参与代码生成）

Happy Hacking! 🎉