ASCII 视频制作流程
Harness-agent 工具
本技能从 Octop 移植。使用以下 harness/deepagents 工具:
| 概念 | 工具 |
|---|---|
| Shell | execute |
| 读/写/编辑文件 | read_file, write_file, edit_file |
| 查找文件/搜索内容 | glob, grep |
| 获取 URL | web_fetch |
| 浏览器自动化 | browser_use |
| 子代理工作 | task |
| 记忆 | memory_store, memory_recall, memory_search |
内置技能文件位于 /_builtin_skills/<name>/。用户安装的技能位于 /skills/<name>/。
何时使用
当用户请求:ASCII 视频、文本艺术视频、终端风格视频、字符艺术动画、复古文本可视化、音频可视化(ASCII)、将视频转换为 ASCII 艺术、矩阵风格效果或任何动画 ASCII 输出时使用。
内容概览
ASCII 艺术视频制作流程——支持任何格式。将视频/音频/图像/生成式输入转换为彩色 ASCII 字符视频输出(MP4、GIF、图像序列)。涵盖:视频转 ASCII 转换、音频反应式音乐可视化、生成式 ASCII 艺术动画、混合视频+音频反应式、文本/歌词叠加、实时终端渲染。
创意标准
这是视觉艺术。ASCII 字符是媒介;电影是标准。
在编写一行代码之前,阐明创意概念。情绪是什么?这个视频讲述了什么视觉故事?是什么让这个项目不同于其他所有 ASCII 视频?用户的提示是一个起点——要用创意野心去诠释它,而不是字面转录。
首次渲染 excellence 是不可协商的。 输出必须在不需要修改轮次的情况下在视觉上引人注目。如果某些东西看起来普通、平淡或像"AI 生成的 ASCII 艺术",那就是错误的——在交付之前重新思考创意概念。
超越参考词汇表。 参考中的效果目录、着色器预设和调色板库是一个起始词汇表。对于每个项目,组合、修改并发明新模式。目录是颜料调色板——你来绘制画作。
主动具有创意。 当项目需要时,扩展技能的词汇表。如果参考中没有视觉需求,就构建它。至少包含一个用户没有要求但会欣赏的视觉时刻——过渡、效果、提升整个作品的色彩选择。
** cohesive 美学优于技术正确性。** 视频中的所有场景必须通过统一的视觉语言连接起来——共享色温、相关字符调色板、一致的运动词汇。一个技术正确但每个场景使用随机不同效果的视频是美学失败。
密集、分层、经过深思熟虑。 每一帧都应该值得观看。绝不要平淡的黑色背景。始终多网格构图。始终每个场景都有变化。始终有意的色彩。
模式
| 模式 | 输入 | 输出 | 参考 |
|---|---|---|---|
| 视频转 ASCII | 视频文件 | ASCII 重现源素材 | references/inputs.md § 视频采样 |
| 音频反应式 | 音频文件 | 由音频特征驱动的生成式视觉 | references/inputs.md § 音频分析 |
| 生成式 | 无(或种子参数) | 程序化 ASCII 动画 | references/effects.md |
| 混合式 | 视频 + 音频 | 带音频反应式叠加的 ASCII 视频 | 两个输入参考 |
| 歌词/文本 | 音频 + 文本/SRT | 带视觉效果的定时文本 | references/inputs.md § 文本/歌词 |
| TTS 旁白 | 文本引用 + TTS API | 带打字文本的旁白证言/引用视频 | references/inputs.md § TTS 集成 |
技术栈
每个项目一个独立的 Python 脚本。无需 GPU。
| 层 | 工具 | 用途 |
|---|---|---|
| 核心 | Python 3.10+, NumPy | 数学、数组操作、向量化效果 |
| 信号 | SciPy | FFT、峰值检测(音频模式) |
| 成像 | Pillow (PIL) | 字体光栅化、帧解码、图像 I/O |
| 视频 I/O | ffmpeg (CLI) | 解码输入、编码输出、混合音频 |
| 并行 | concurrent.futures | N 个工作线程用于批处理/剪辑渲染 |
| TTS | ElevenLabs API(可选) | 生成旁白剪辑 |
| 可选 | OpenCV | 视频帧采样、边缘检测 |
流程架构
每个模式都遵循相同的 6 阶段流程:
INPUT → ANALYZE → SCENE_FN → TONEMAP → SHADER → ENCODE
- INPUT — 加载/解码源素材(视频帧、音频采样、图像或无)
- ANALYZE — 提取每帧特征(音频频带、视频亮度/边缘、运动向量)
- SCENE_FN — 场景函数渲染到像素画布 (
uint8 H,W,3)。通过_render_vf()+ 像素混合模式组合多个字符网格。参见references/composition.md - TONEMAP — 基于百分位的自适应亮度归一化。参见
references/composition.md§ 自适应 Tonemap - SHADER — 通过后处理
ShaderChain+FeedbackBuffer。参见references/shaders.md - 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 个)
- 不同的字符调色板(匹配情绪)
- 不同的色彩策略(或至少是不同的色调)
- 变化着色器强度(高峰期更多 bloom,安静期更多颗粒)
- 不同的粒子类型(如果粒子处于活动状态)
项目特定发明
对于每个项目,至少发明以下之一:
- 匹配主题的自定义字符调色板
- 自定义背景效果(组合/修改现有构建块)
- 自定义色彩调色板(匹配品牌/情绪的离散 RGB 集合)
- 自定义粒子字符集
- 新颖的场景过渡或视觉时刻
不要只是从目录中挑选。目录是词汇表——你来写诗。
工作流
步骤 1:创意愿景
在编写任何代码之前,阐明创意概念:
- 情绪/氛围:观众应该感受到什么?充满活力、冥想、混乱、优雅、不祥?
- 视觉故事:持续时间内发生了什么?建立张力?转变?溶解?
- 色彩世界:温暖/凉爽?单色?霓虹?大地色调?主导色调是什么?
- 字符纹理:密集数据?稀疏星星?有机点?几何块?
- 是什么让这个不同:使这个项目独一无二的一件事是什么?
- 情感弧:场景如何进展?以能量开始,建立到高潮,解决?
将用户的提示映射到美学选择。"寒冷的低传真可视化"需要与"故障赛博朋克数据流"完全不同的所有东西。
步骤 2:技术设计
- 模式 — 上述 6 种模式中的哪一种
- 分辨率 — 横向 1920x1080(默认)、纵向 1080x1920、方形 1080x1080 @ 24fps
- 硬件检测 — 自动检测核心/RAM,设置质量配置文件。参见
references/optimization.md - 段落 — 将时间戳映射到场景函数,每个都有自己的效果/调色板/色彩/着色器配置
- 输出格式 — MP4(默认)、GIF(640x360 @ 15fps)、PNG 序列
步骤 3:构建脚本
单个 Python 文件。组件(带参考):
- 硬件检测 + 质量配置文件 —
references/optimization.md - 输入加载器 — 模式相关;
references/inputs.md - 特征分析器 — 音频 FFT、视频亮度或合成
- 网格 + 渲染器 — 带位图缓存的多密度网格;
references/architecture.md - 字符调色板 — 每个项目多个;
references/architecture.md§ 调色板 - 色彩系统 — HSV + 离散 RGB + 和谐生成;
references/architecture.md§ 色彩 - 场景函数 — 每个返回
canvas (uint8 H,W,3);references/scenes.md - Tonemap — 自适应亮度归一化;
references/composition.md - 着色器管道 —
ShaderChain+FeedbackBuffer;references/shaders.md - 场景表 + 调度器 — 时间 → 场景函数 + 配置;
references/scenes.md - 并行编码器 — 带 ffmpeg 管道的 N 工作线程剪辑渲染
- 主函数 — 编排完整流程
步骤 4:质量验证
- 首先测试帧:在完整渲染之前在关键时间戳渲染单个帧
- 亮度检查:所有 ASCII 内容的
canvas.mean() > 8。如果暗,降低 gamma - 视觉一致性:所有场景是否感觉属于同一个视频?
- 创意愿景检查:输出是否匹配步骤 1 中的概念?如果看起来普通,返回
关键实现注意事项
亮度 — 使用 tonemap(),而不是线性乘数
这是 #1 视觉问题。黑色背景上的 ASCII 本质上是暗的。绝不要使用 canvas * N 乘数——它们会剪切高光。使用自适应 tonemap:
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,曝光过度 0.55,海报化 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 字符在所有字体中都能渲染。在 init 时验证调色板——渲染每个字符,检查空白输出。参见 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/域扭曲、沃罗诺伊图、反应扩散、元胞自动机、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 问题、字体问题、常见错误 |
创意分歧(仅当用户请求实验性/创意/独特输出时使用)
如果用户要求创意、实验性、令人惊讶或非传统的输出,请选择最适合的策略,并在生成代码之前通过其步骤进行推理。
- 强制连接 — 当用户想要跨域灵感时("让它看起来有机"、"工业美学")
- 概念混合 — 当用户命名两个要组合的事物时("海洋遇见音乐"、"太空 + 书法")
- 斜向策略 — 当用户最大开放时("给我一个惊喜"、"我从未见过的东西")
强制连接
- 选择一个与视觉目标无关的域(天气系统、微生物学、建筑学、流体动力学、纺织编织)
- 列出其核心视觉/结构元素(侵蚀 → 渐进式揭示;有丝分裂 → 分裂复制;编织 → 互锁图案)
- 将这些元素映射到 ASCII 字符和动画模式
- 综合——"侵蚀"或"结晶"在字符网格中看起来像什么?
概念混合
- 命名两个不同的视觉/感知空间(例如,海浪 + 乐谱)
- 映射对应关系(波峰 = 高音,波谷 = 休止,泡沫 = 断奏)
- 选择性混合——保留最有趣的映射,丢弃强制的映射
- 开发仅存在于混合中的新兴属性
斜向策略
- 抽取一个:"尊重你的错误作为隐藏意图" / "使用旧想法" / "你最接近的朋友会做什么?" / "强调缺陷" / "把它颠倒过来" / "只要一部分,而不是整体" / "反转"
- 针对当前的 ASCII 动画挑战解释指令
- 在编写代码之前,将横向见解应用到视觉设计中