ascii-video

ASCII 视频制作流水线

使用场景

当用户请求以下内容时使用：ASCII 视频、文本艺术视频、终端风格视频、字符艺术动画、复古文本可视化、ASCII 音频可视化器、将视频转换为 ASCII 艺术、矩阵风格效果，或任何动画 ASCII 输出。

内容

适用于任意格式的 ASCII 艺术视频制作流水线。将视频、音频、图像或生成式输入转换为彩色 ASCII 字符视频输出（MP4、GIF、图像序列）。涵盖：视频转 ASCII、音频响应式音乐可视化器、生成式 ASCII 艺术动画、视频与音频响应式混合效果、文本／歌词叠加、实时终端渲染。

创作标准

这是视觉艺术。ASCII 字符是媒介；电影是标准。

在编写任何代码之前，先阐明创作概念。氛围是什么？它讲述了怎样的视觉故事？这个项目与其他所有 ASCII 视频有何不同？用户的提示只是起点——应以创作野心来诠释，而非照字面转录。

首轮渲染就要出色，这是不可妥协的。 输出必须在无需反复修改的情况下就足够惊艳。如果效果看起来平庸、单调，或像“AI 生成的 ASCII 艺术”，那就是错的——交付前重新构思创作概念。

超越参考词汇。 参考资料中的效果目录、着色器预设和调色板库只是基础词汇。每个项目都应组合、修改并创造新的模式。目录是颜料盘——画作由你来创作。

主动发挥创意。 项目有需要时，应扩展此技能的表现手法。如果参考资料无法满足创意构想，就亲自实现。至少加入一个用户没有要求、但会欣赏的视觉瞬间——例如转场、效果，或能提升整部作品的配色选择。

美学统一性优先于技术正确性。 视频中的所有场景都必须通过统一的视觉语言联系起来——共享的色温、相关的字符调色板、一致的运动表现。一部技术上正确、但每个场景都使用随机不同效果的视频，在美学上是失败的。

丰富、分层、精心设计。 每一帧都应值得细看。绝不使用单调的黑色背景。始终采用多网格构图。始终让各场景有所变化。始终有意识地运用色彩。

模式

模式	输入	输出	参考
视频转 ASCII	视频文件	将源片段重现为 ASCII	references/inputs.md § Video Sampling
音频响应式	音频文件	由音频特征驱动的生成式视觉效果	references/inputs.md § Audio Analysis
生成式	无（或种子参数）	程序化 ASCII 动画	references/effects.md
混合式	视频 + 音频	带有音频响应式叠加效果的 ASCII 视频	两种输入参考
歌词／文本	音频 + 文本／SRT	带视觉效果的定时文本	references/inputs.md § Text/Lyrics
TTS 旁白	文本引言 + TTS API	配有打字文本的旁白见证／引言视频	references/inputs.md § TTS Integration

技术栈

每个项目使用一个自包含的 Python 脚本。无需 GPU。

层	工具	用途
核心	Python 3.10+、NumPy	数学运算、数组操作、矢量化效果
信号	SciPy	FFT、峰值检测（音频模式）
成像	Pillow (PIL)	字体栅格化、帧解码、图像输入／输出
视频输入／输出	ffmpeg (CLI)	解码输入、编码输出、混流音频
并行	concurrent.futures	批处理／片段渲染的 N 个工作线程
TTS	ElevenLabs API（可选）	生成旁白片段
可选	OpenCV	视频帧采样、边缘检测

管线架构

每种模式都遵循相同的 6 阶段管线：

INPUT → ANALYZE → SCENE_FN → TONEMAP → SHADE → ENCODE

1. INPUT — 加载/解码源素材（视频帧、音频采样、图像或无内容）
2. ANALYZE — 提取逐帧特征（音频频段、视频亮度/边缘、运动矢量）
3. SCENE_FN — 场景函数渲染到像素画布（uint8 H,W,3）。通过 _render_vf() 和像素混合模式组合多个字符网格。参见 references/composition.md
4. TONEMAP — 基于百分位数的自适应亮度归一化。参见 references/composition.md § 自适应色调映射
5. SHADE — 通过 ShaderChain 和 FeedbackBuffer 进行后期处理。参见 references/shaders.md
6. ENCODE — 将原始 RGB 帧传入 ffmpeg，编码为 H.264/GIF

创作方向

美学维度

维度	选项	参考
字符调色板	密度渐变、块状元素、符号、文字系统（日文片假名、希腊字母、卢恩符文、盲文）、项目专属	architecture.md § 调色板
色彩策略	HSV、OKLAB/OKLCH、离散 RGB 调色板、自动生成的和谐配色、单色、色温	architecture.md § 色彩系统
背景纹理	正弦场、fBM 噪声、域扭曲、沃罗诺伊图、反应扩散、元胞自动机、视频	effects.md
主要效果	光环、螺旋、隧道、漩涡、波浪、干涉、极光、火焰、SDF、奇异吸引子	effects.md
粒子	火花、雪、雨、气泡、符文、轨道、群集 boid、流场跟随者、轨迹	effects.md § 粒子
着色器氛围	复古 CRT、简洁现代、故障艺术、电影感、梦幻、工业、迷幻	shaders.md
网格密度	从 xs（8px）到 xxl（40px），可按图层混用	architecture.md § 网格系统
坐标空间	笛卡尔、极坐标、平铺、旋转、鱼眼、莫比乌斯、域扭曲	effects.md § 变换
反馈	缩放隧道、彩虹轨迹、幽灵回声、旋转曼荼罗、色彩演变	composition.md § 反馈
遮罩	圆形、环形、渐变、文字模板、动画光圈/擦除/溶解	composition.md § 遮罩
转场	交叉淡化、擦除、溶解、故障切换、光圈、基于遮罩的显现	shaders.md § 转场

按章节变化

切勿在整段视频中使用相同配置。对每个章节/场景：

• 使用不同的背景效果（或组合 2-3 种）
• 使用不同的字符调色板（与氛围匹配）
• 使用不同的色彩策略（或至少更换色相）
• 调整着色器强度（高潮部分增强辉光，安静部分增加颗粒感）
• 如果启用了粒子，使用不同的粒子类型

项目专属创意

每个项目至少创作以下一项：

• 与主题相符的自定义字符调色板
• 自定义背景效果（组合/修改现有构件）
• 自定义色彩调色板（符合品牌/氛围的离散 RGB 集合）
• 自定义粒子字符集
• 新颖的场景转场或视觉时刻

不要只从目录中挑选。目录是词汇——你要写出诗篇。

工作流

步骤 1：创意构想

编写任何代码之前，先阐明创意概念：

• 氛围/气场：希望观众有何感受？充满活力、沉静、混乱、优雅、阴森？
• 视觉故事：整个过程中会发生什么？逐步营造紧张感？发生转变？逐渐消散？
• 色彩世界：暖色/冷色？单色？霓虹？大地色调？主色相是什么？
• 字符质感：密集的数据？稀疏的星点？有机的圆点？几何块状？
• 有何独特之处：让这个项目与众不同的关键是什么？
• 情绪弧线：场景如何推进？以活力开场，逐渐推向高潮，再收尾？

将用户的提示词映射为美学选择。“轻松的 lo-fi 可视化器”和“故障风赛博朋克数据流”在各方面都截然不同。

步骤 2：技术设计

• 模式 — 上述 6 种模式之一
• 分辨率 — 横屏 1920x1080（默认）、竖屏 1080x1920、正方形 1080x1080，@ 24fps
• 硬件检测 — 自动检测核心数/RAM，设置质量配置文件。参见 references/optimization.md
• 分段 — 将时间戳映射到场景功能，每个场景都有自己的效果/调色板/颜色/着色器配置
• 输出格式 — MP4（默认）、GIF（640x360 @ 15fps）、PNG 序列

步骤 3：构建脚本

单个 Python 文件。组件（附参考资料）：

1. 硬件检测 + 质量配置文件 — references/optimization.md
2. 输入加载器 — 依赖模式；references/inputs.md
3. 特征分析器 — 音频 FFT、视频亮度或合成数据
4. 网格 + 渲染器 — 带位图缓存的多密度网格；references/architecture.md
5. 字符调色板 — 每个项目可有多个调色板；references/architecture.md § Palettes
6. 颜色系统 — HSV + 离散 RGB + 和谐色生成；references/architecture.md § Color
7. 场景函数 — 每个函数都返回 canvas (uint8 H,W,3)；references/scenes.md
8. 色调映射 — 自适应亮度归一化；references/composition.md
9. 着色器管线 — ShaderChain + FeedbackBuffer；references/shaders.md
10. 场景表 + 分发器 — 时间 → 场景函数 + 配置；references/scenes.md
11. 并行编码器 — 使用 ffmpeg 管道进行 N 工作者片段渲染
12. 主程序 — 编排完整管线

步骤 4：质量验证

• 先测试帧：完整渲染前，在关键时间戳渲染单帧
• 亮度检查：所有 ASCII 内容的 canvas.mean() > 8。如果画面太暗，请降低 gamma
• 视觉连贯性：所有场景看起来都像属于同一段视频吗？
• 创意愿景检查：输出是否符合步骤 1 中的概念？如果看起来很普通，请返回上一步

关键实现说明

亮度 — 使用 tonemap()，而非线性乘数

这是首要的视觉问题。黑底上的 ASCII 天生较暗。切勿使用 canvas * N 乘数——这会导致高光裁切。请使用自适应色调映射：

def tonemap(canvas, gamma=0.75):
    f = canvas.astype(np.float32)
    lo, hi = np.percentile(f[::4, ::4], [1, 99.5])
    if hi - lo < 10: hi = lo + 10
    f = np.clip((f - lo) / (hi - lo), 0, 1) ** gamma
    return (f * 255).astype(np.uint8)

管线：scene_fn() → tonemap() → FeedbackBuffer → ShaderChain → ffmpeg

每个场景的 gamma：默认 0.75，solarize 为 0.55，posterize 为 0.50，明亮场景为 0.85。暗色图层使用 screen 混合（不要使用 overlay）。

字体单元格高度

macOS Pillow：textbbox() 返回的高度不正确。请使用 font.getmetrics()：cell_height = ascent + descent。参见 references/troubleshooting.md。

ffmpeg 管道死锁

长时间运行的 ffmpeg 进程绝不能使用 stderr=subprocess.PIPE——缓冲区会在达到 64KB 时填满并导致死锁。请重定向到文件。参见 references/troubleshooting.md。

字体兼容性

并非所有字体都能渲染所有 Unicode 字符。请在初始化时验证调色板——渲染每个字符，并检查输出是否为空。参见 references/troubleshooting.md。

片段级架构

对于分段视频（引言、场景、章节），将每个部分渲染为单独的片段文件，以便并行渲染和选择性重新渲染。参见 references/scenes.md。

性能目标

组件	预算
特征提取	1-5ms
效果函数	2-15ms
字符渲染	80-150ms（瓶颈）
着色器管线	5-25ms
总计	~100-200ms/帧

参考资料

文件	内容
references/architecture.md	网格系统、分辨率预设、字体选择、字符调色板（20+）、色彩系统（HSV + OKLAB + 离散 RGB + 色彩协调生成）、_render_vf() 辅助函数、GridLayer 类
references/composition.md	像素混合模式（20 种）、blend_canvas()、多网格合成、自适应 tonemap()、FeedbackBuffer、PixelBlendStack、遮罩／模板系统
references/effects.md	效果构建模块：值场生成器、色相场、噪声／fBM／域扭曲、Voronoi、反应扩散、元胞自动机、SDF、奇异吸引子、粒子系统、坐标变换、时间连贯性
references/shaders.md	ShaderChain、_apply_shader_step() 分派、38 种着色器目录、音频响应缩放、转场、色调预设、输出格式编码、终端渲染
references/scenes.md	场景协议、Renderer 类、SCENES 表、render_clip()、节拍同步剪辑、并行渲染、设计模式（图层层级、定向弧线、视觉隐喻、构图技巧）、各复杂度级别的完整场景示例、场景设计检查清单
references/inputs.md	音频分析（FFT、频段、节拍）、视频采样、图像转换、文本／歌词、TTS 集成（ElevenLabs、语音分配、音频混合）
references/optimization.md	硬件检测、质量配置、向量化图案、并行渲染、内存管理、性能预算
references/troubleshooting.md	NumPy 广播陷阱、混合模式问题、多进程／序列化问题、亮度诊断、ffmpeg 问题、字体问题、常见错误

---

创意发散（仅在用户要求实验性／创意／独特输出时使用）

如果用户要求创意、实验性、出人意料或非传统的输出，请选择最合适的策略，并在生成代码前逐步推演。

• 强制联想 — 用户希望获得跨领域灵感时（“让它看起来有机”“工业美学”）
• 概念融合 — 用户提出要结合两种事物时（“海洋遇上音乐”“太空 + 书法”）
• 迂回策略 — 用户完全开放时（“给我惊喜”“来点我从未见过的”）

强制联想

1. 选择一个与视觉目标无关的领域（天气系统、微生物学、建筑、流体动力学、纺织编织）
2. 列出其核心视觉／结构元素（侵蚀 → 逐渐显现；有丝分裂 → 分裂复制；编织 → 交错图案）
3. 将这些元素映射到 ASCII 字符和动画模式
4. 综合思考 — “侵蚀”或“结晶”在字符网格中会呈现什么样子？

概念融合

1. 指定两个不同的视觉／概念空间（例如，海浪 + 乐谱）
2. 建立对应关系（波峰 = 高音，波谷 = 休止符，泡沫 = 断奏）
3. 有选择地融合 — 保留最有趣的对应关系，舍弃牵强的部分
4. 发展只存在于融合之中的涌现特性

迂回策略

1. 选一条：“尊重你的错误，把它视为隐藏的意图” / “采用一个旧点子” / “你最亲近的朋友会怎么做？” / “强调缺陷” / “把它倒过来” / “只看一部分，不看整体” / “反转”
2. 将指令结合当前 ASCII 动画挑战进行解读
3. 写代码前，将这一横向思路应用于视觉设计