零依赖 · 跨平台 · CLI 与 Python 库双形态 · 12 种内置特效 · 一键导出动画 SVG / HTML / JSON
GlyphFx 是一个纯 Python 标准库实现的终端文字时序动画引擎。一行命令，就能让普通文字在终端里打字、流光、故障、解码、燃起 ASCII 火焰；同时它也是一个可以直接 import 的动画库，每一帧都由整数随机种子确定性生成，可复现、可测试、可离线渲染成文件。
- 😮💨 终端动画只能在自己屏幕上看：录屏模糊、截图是死的，没法贴进 PR、博客、群聊。GlyphFx 可把同一份动画无头导出为自包含的动画 SVG（SMIL）、带播放器的独立 HTML 与结构化 JSON。
- 🧩 现有工具要么是静态二进制、要么依赖链沉重：GlyphFx 零三方运行时依赖，Python 3.8+ 即可运行，Windows / macOS / Linux 行为一致。
- 🔗 特效之间无法编排：GlyphFx 原生支持特效管线串联（
--chain typewriter,rainbow）。 - 🧪 动画难以自测：GlyphFx 的“特效 = 进度值 → 字符网格”的纯函数模型，让每一帧都能被断言，CI 里也能稳定跑。
项目灵感来自近期终端动效赛道的高热度探索（终端文字特效、ASCII 火焰清屏等方向）。GlyphFx 没有复制任何现有项目的一行代码，全部架构与 12 种特效均为从零独立实现，并在“可分享导出、确定性帧引擎、管线编排、跨平台降级、无障碍支持”五个方向做出了差异化设计。
- 🎬 12 种自研内置特效
typewriter（打字机）·fade（逐字淡入）·beam（扫描光束）·rainbow（流动彩虹）·wave（正弦波浪）·bounce（抛物线弹跳）·scroll（跑马灯）·scramble（密码解码）·sparkle（星点闪烁）·glitch（故障毛刺）·matrix（数字雨解码）·flame（ASCII 火焰） - 🧰 双形态交付：同一个引擎既是
glyphfx命令行工具，也是import glyphfx的 Python 库 - 📤 三种无头导出：动画 SVG（纯 SMIL，无 JS）、独立 HTML（内嵌播放器，可暂停/调速）、JSON 帧数据（便于二次开发与快照测试）
- 🔗 特效管线串联：多个特效首尾相接，一条命令编排完整开场动画
- 🎲 确定性渲染：所有随机效果由
--seed控制，同一种子逐帧一致，天然适合 CI 与演示 - 🖥️ 真正跨平台：自动启用 Windows 10+ 虚拟终端序列；真彩 → 16 色 → 无色三级降级；遵循
NO_COLOR；非 TTY 管道自动只输出静态终帧，绝不刷屏 - 🪶 零运行时依赖：仅用 Python 标准库，安装无网络依赖陷阱
- ✅ 28 个测试全程护航：覆盖缓动、颜色、画布、全部特效、三种导出器与子进程级 CLI
| 打字机 | 流动彩虹 | 数字雨 | 故障毛刺 |
|---|---|---|---|
 |
 |
 |
 |
| 逐字淡入 | 正弦波浪 | 密码解码 | ASCII 火焰 |
 |
 |
 |
 |
📁 全部 12 个特效的 SVG 见
docs/assets/effects/，连续播放版见docs/assets/showcase.html（下载后用浏览器打开）。
| 项目 | 要求 |
|---|---|
| Python | 3.8 / 3.9 / 3.10 / 3.11 / 3.12+ |
| 操作系统 | Windows 10+、macOS、Linux（任意支持 ANSI 的终端） |
| 第三方依赖 | 无 |
# 推荐：pipx 全局隔离安装
pipx install glyphfx
# 或使用 pip
python3 -m pip install glyphfx
# 从源码安装（可编辑模式，便于二次开发）
git clone https://github.com/gitstq/glyphfx.git
cd glyphfx
python3 -m pip install -e .# 1) 终端里直接播放彩虹流动
glyphfx "Hello, GlyphFx!" -e rainbow
# 2) 打字机 + 解码 + 彩虹 三段串联
glyphfx "Deploy Success" --chain typewriter,scramble,rainbow
# 3) 导出一份自包含动画 SVG（可直接嵌进 README / 博客）
glyphfx "Shipped!" -e matrix --frames 36 --export svg -o shipped.svg
# 4) 管道输入
echo "build passed" | glyphfx -e beam
# 5) 查看全部特效
glyphfx --list作为 Python 库使用：
import glyphfx
# 在当前终端播放
glyphfx.animate("Hello", effect="typewriter", fps=24)
# 无头取帧（不触碰终端）
frames = glyphfx.frames("Hello", effect="glitch", frames=20, seed=3)
svg_text = glyphfx.to_svg("Hello", effect="glitch", frames=20, seed=3)
open("hello.svg", "w", encoding="utf-8").write(svg_text)| 参数 | 说明 | 默认值 |
|---|---|---|
TEXT |
要动画化的文本；省略时从标准输入读取 | — |
-e, --effect |
特效名（glyphfx --list 查看全部） |
rainbow |
--chain a,b,c |
特效管线，按顺序串联播放 | 关闭 |
--fps N |
每秒帧数 | 24 |
--frames N |
覆盖特效默认总帧数 | 各特效内置 |
--seed N |
随机种子，保证逐帧可复现 | 0 |
--width N |
固定画布列宽（便于对齐） | 自适应 |
--easing NAME |
缓动曲线：linear/out-quad/in-out-cubic/out-back/elastic 等 10 种 |
linear |
--loop |
循环播放直到 Ctrl+C |
关闭 |
--color |
auto / truecolor / ansi16 / none |
auto |
--opt KEY=VALUE |
特效专属参数，可重复，如 --opt amplitude=3 |
— |
--export |
无头导出：svg / html / json |
关闭 |
-o, --output |
导出文件路径（JSON 省略时输出到 stdout） | 自动命名 |
--list |
列出全部特效后退出 | — |
--preview |
依次播放每一个特效 | — |
--version |
输出版本号 | — |
| 特效 | 参数 | 含义 |
|---|---|---|
wave |
amplitude=2 |
波浪振幅（行数） |
wave |
loops=1.5 |
文本宽度内的正弦周期数 |
bounce |
travel=10 |
水平弹跳移动距离（列） |
rainbow |
saturation=0.75 / value=1.0 |
HSV 饱和度与明度 |
glyphfx "WAVE" -e wave --opt amplitude=3 --opt loops=2.0# 动画 SVG：纯 SMIL 实现，无 JavaScript，可直接 <img> 引用或拖进浏览器
glyphfx "CI GREEN" -e beam --export svg -o ci.svg
# 独立 HTML：内嵌全部帧与迷你播放器（暂停 / 重播 / 0.25x–3x 调速），双击即开
glyphfx "CI GREEN" -e beam --export html -o ci.html
# JSON：结构化帧数据，stdout 输出便于 jq / 前端二次渲染
glyphfx "CI GREEN" -e beam --frames 8 --export json | python3 -m json.tool | headJSON 结构示例：
{"glyphfx": 1, "width": 10, "height": 1, "fps": 24,
"frames": [[[{"c": "C", "f": "#e2e8f0", "k": null, "b": true}]]]}import glyphfx
from glyphfx.effects import build_effect
from glyphfx.exporters import export_svg, export_html, export_json
# 1) 直接播放（自动检测终端能力，非 TTY 只打印终帧）
glyphfx.animate("OK", effect="sparkle", loop=False)
# 2) 串联管线
canvases = glyphfx.chain_frames(["typewriter", "rainbow"], "OK", frames=24)
# 3) 逐帧处理：Canvas 是 width×height 的字符网格
effect = build_effect("matrix", "WAKE UP", frames=48, seed=42)
for i, canvas in enumerate(effect):
print(i, canvas.render("truecolor"))
# 4) 查看全部特效元信息
for info in glyphfx.effect_info():
print(info["name"], "-", info["description"])- 设置环境变量
NO_COLOR=1即输出纯文本；--color ansi16可降级到经典 16 色。 - 输出被重定向到管道/文件（非 TTY）时，实时模式只输出静态终帧，避免 ANSI 转义污染日志。
Ctrl+C中断循环时会自动恢复光标与颜色，终端不会残留花屏状态。
python3 -m unittest discover -s tests -vsrc/glyphfx/
├── easing.py # 10 种纯函数缓动曲线
├── colors.py # 真彩/16色/无色三级 SGR 抽象 + Windows VT 启用
├── canvas.py # 字符网格 Cell/Canvas：特效绘制的唯一画布
├── effects/ # 12 个特效，每个都是 p∈[0,1] → Canvas 的确定性映射
│ ├── base.py # Effect 基类：帧迭代、缓动、每帧独立 RNG
│ └── *.py
├── engine.py # 实时播放器（清屏/光标/帧率/Ctrl+C 安全还原）
├── exporters.py # SVG(SMIL) / HTML / JSON 三种无头导出
└── cli.py # argparse 命令行入口
核心设计取舍：
- 特效即纯函数。给定
(文本, 帧序号, 种子)必然得到同一张画布，因此测试、导出、回放共用同一条代码路径，不存在“终端里好看、导出就翻车”的两套实现。 - 只依赖标准库。终端工具的最大失败模式是安装即报错；GlyphFx 在任何能跑 Python 3.8 的机器上开箱即用。
- 导出优先。动画的价值在于传播，SVG/HTML 导出与终端渲染同源，保证“所见即所导出”。
- v1.1：新增
neon（霓虹脉冲）、slide-up（逐行升起）、gradient-shift三种特效 - v1.1：支持从
.txt/ stdin 批量生成每行动画 - v1.2：导出 GIF（可选 Pillow 扩展，保持核心零依赖）
- v1.2：自定义配色主题（
--themeJSON / 内置主题） - v1.3：ANSI 录制回放（
.cast格式兼容 asciinema） - 🌟 欢迎在 Issues 提名新特效与导出格式
新特效、新缓动曲线、新导出器、终端兼容性报告、多语言文档校对都非常欢迎——请先阅读 CONTRIBUTING.md。
GlyphFx 属于工具库 / CLI 组件类项目，纯 Python 实现、无需编译任何二进制产物。
python3 -m pip install build
python3 -m build # 在 dist/ 下生成 .whl 与 .tar.gz把 wheel 拷贝到目标机器后：
python3 -m pip install glyphfx-1.0.0-py3-none-any.whl
glyphfx --version# pyproject.toml
dependencies = ["glyphfx"]from glyphfx.frames import frames # 或：from glyphfx import framesFROM python:3.12-slim
RUN pip install --no-cache-dir glyphfx
ENTRYPOINT ["glyphfx"]💡 容器/CI 中通常没有 TTY，GlyphFx 会自动退化为静态终帧输出；需要产物时请使用
--export。
- 提交信息遵循 Conventional Commits：
feat:/fix:/docs:/refactor:/test:/chore: - 新特效请注册到
src/glyphfx/effects/__init__.py，通用测试会自动覆盖帧数、确定性与字形保留 - 提交前请确保
python3 -m unittest discover -s tests全绿 - 完整流程（开发环境、PR 清单、发版步骤）见
CONTRIBUTING.md
本项目基于 MIT License 开源，允许自由使用、修改、分发与商用，保留版权声明即可。
如果你喜欢 GlyphFx，欢迎 ⭐ Star 支持，也欢迎把导出的动画分享给我们！