Glyphloop

Glyphloop

一款浏览器工作室和无头工具包，可用于创建循环完美衔接的生成式 ASCII 动画：流场、波干涉、变形噪声团、矩阵雨、旋转 3D 形状、自定义数学表达式和参数曲面。 可在图像、视频或文本上叠加效果，继承其颜色，并导出为 PNG、GIF、MP4、自包含网页嵌入内容或终端播放器。

也可通过包的 CLI 或 MCP 服务供 AI Agent 以无头方式使用——Agent 甚至可以通过表达式字符串定义自己的动画和 3D 形状。请参阅 AGENTS.md。

Glyphloop = 字形 + 无缝循环。

试用托管工作室，无需账户；或查看实时示例。

本地工作室

npm ci
npm run dev        # opens on http://localhost:5199

需要 Node.js 20 或更高版本。推荐使用 Chrome，因为 MP4 导出需要 WebCodecs；其他工作流可在现代浏览器中运行。

CLI 和 MCP

此包提供一个 glyphloop 可执行文件，包含两个命令：

npx glyphloop@beta render --preset flowfield-hero --out hero
npx glyphloop@beta mcp

在源代码检出目录中，可使用以下等效开发命令：

npm run render -- --preset flowfield-hero --out hero
npm run mcp

render 接受内置预设名称、预设 JSON 文件或内联 JSON。 运行 node bin/glyphloop.js --help 查看完整命令摘要。

使用

1. 选择一种效果源并实时调整其参数——也可以将任意图像/视频拖放到编辑器中，将自己的设计转换为 ASCII，同时保留其颜色。
2. 设置样式：字符渐变（或输入自定义内容）、伽马、反转、单色或双色渐变。
3. 设置网格列数、单元格大小、宽高比、时长和 FPS。导入的媒体会以其原生宽高比开始显示，栅格导出也可匹配其精确像素尺寸。
4. 导出：
   • PNG - 当前帧，缩放比例为 1–3×。
   • GIF / MP4 - 完整播放一遍动画，逐帧确定性渲染（绝不丢帧）。生成的动态效果可无缝循环。
   • 网页嵌入内容（zip） - frames.json（RLE 压缩的字符帧）+ player.js（轻量、无依赖的播放器，遵循 prefers-reduced-motion）+ 演示用的 index.html。将这两个文件放到任意网站，并添加 <div data-ascii-player></div>。
   • 终端（zip） - frames.ans + play.sh；运行 bash play.sh，即可在终端中循环播放动画。

编辑器包含六个入门预设。也可将预设保存到 localStorage，或通过顶部栏以 JSON 格式下载/加载。可通过 /studio/?preset=flowfield-hero 打开共享预设。

导入的媒体会保留在浏览器中；Glyphloop 不会上传这些内容。为保证稳定的 Beta 体验，图像限制为 25 MiB 和 40 百万解码像素，视频限制为 100 MiB 和前 20 秒，预设文件限制为 10 MiB。过大的渲染任务会被拒绝，并提示降低缩放比例、列数、FPS 或时长。

托管网站和工作室会向 Cloudflare 第一方端点发送一小部分经过允许列表筛选的匿名产品事件。绝不会包含创作输入和输出。源代码检出目录、CLI 和 MCP 服务不会发送分析数据。请参阅托管网站的隐私声明。

源颜色与图像调色板

导入媒体的着色方式有两种，彼此不同：

• 颜色模式：源颜色会在每个网格单元格采样图像或视频，因此每个字形都会保留其下方区域的局部颜色。它能保留多色图稿，并逐帧跟随视频颜色变化。
• 从图像设置墨色和纸色会提取一个小型代表性调色板，并填充“墨色”、“墨色 2”和“纸色”控件。选择单色或渐变，即可使用这些精心挑选的颜色进行渲染，而不是保留所有源颜色。

简而言之：源颜色模式会保留图像的色彩图；调色板操作则以图像为灵感，生成可控的 Glyphloop 配色方案。工作室的撤销图像调色板操作会恢复提取调色板之前设置的确切墨色和纸色。

为什么生成的循环能无缝衔接

Glyphloop 内置的源和周期表达式都是时间的纯函数，不包含逐帧状态。所有噪声都沿着额外两个噪声维度中的圆进行采样 （src/core/noise.ts:loopCoords），所有正弦相位都以循环中 2π 的整数倍递增，因此第 N 帧会精确回到第 0 帧。导出时会从 t=0 开始渲染 round(fps × duration) 帧，且不会渲染 t=duration（第 0 帧就是循环衔接点）。

导入的视频不会自动变成完美循环。Glyphloop 会在动画时长内采样一遍视频片段，然后从头重复播放。只有当源视频本身已设计为循环播放（例如 Claude 水母示例），或导入的底图是静态图像时，合成结果才会无缝衔接。

开发

npm test           # vitest unit tests (noise periodicity, mapper, RLE, ZIP, ANSI, sources)
npm run build      # typecheck + production build
npm run build:site # typecheck + production website and Studio build

架构：Source → FieldFrame (brightness grid) → AsciiMapper → CanvasRenderer → exporters。

许可、输出与品牌

Glyphloop 的软件（包括编辑器、渲染器、CLI、MCP 服务、导出器、预设和生成的嵌入式播放器）依据 MIT 许可提供。

Glyphloop 不主张拥有你导入的内容或导出的动画。你可以将导出的动画用于商业用途，无需注明出处，但须遵守适用于源素材的任何权利规定。

Glyphloop 的名称和视觉标识不在 MIT 许可范围内。演示和营销媒体均单独标注。请参阅 TRADEMARKS.md 和 LICENSES/ASSETS.md。

欢迎在 Beta 阶段提交问题和有针对性的反馈。请参阅 CONTRIBUTING.md 和 SECURITY.md。