ASCII 影片製作管線
使用時機
當使用者要求：ASCII 影片、文字藝術影片、終端機風格影片、字元藝術動畫、復古文字視覺化、ASCII 音訊視覺化器、將影片轉換為 ASCII 藝術、矩陣風格效果，或任何動畫 ASCII 輸出時使用。
內容說明
ASCII 藝術影片的生產管線 — 任何格式皆可。將影片/音訊/圖片/生成式輸入轉換為帶有色彩的 ASCII 字元影片輸出（MP4、GIF、影像序列）。涵蓋：影片轉 ASCII 轉換、音訊反應式音樂視覺化、生成式 ASCII 藝術動畫、混合影片+音訊反應、文字/歌詞疊加、即時終端機渲染。
創作標準
這是視覺藝術。ASCII 字元是媒介；電影是標準。
在撰寫任何程式碼之前，先闡明創作概念。氛圍是什麼？它訴說了什麼視覺故事？是什麼讓這個項目與其他所有 ASCII 影片不同？使用者的提示是起點 — 以創意野心來詮釋，而非字面翻譯。
首次渲染即達到卓越，這是不容妥協的。 輸出必須在視覺上引人注目，無需修訂輪次。如果某些東西看起來平淡無奇、缺乏深度，或像「AI 生成的 ASCII 藝術」，那就是錯的 — 在交付前重新思考創作概念。
超越參考詞彙。 參考資料中的效果目錄、著色器預設與調色盤庫只是起點詞彙。對於每個項目，都要組合、修改並發明新模式。目錄是油漆的調色盤 — 你來繪製畫作。
主動發揮創意。 當項目需要時，擴展技能的詞彙量。如果參考資料沒有你願景所需的東西，就自行建立。至少要包含一個使用者未要求但會欣賞的視覺時刻 — 一個轉場、一個效果、一個能提升整體作品的色彩選擇。
連貫美學優於技術正確性。 影片中的所有場景必須透過統一的視覺語言相互連結 — 共享的色溫、相關的字元調色盤、一致的動詞詞彙。一個技術上正確但每個場景都使用隨機不同效果的影片，是美學上的失敗。
密集、分層、深思熟慮。 每一幀都應值得觀看。絕不使用純黑背景。始終採用多網格構圖。始終為每個場景變化。始終使用有意圖的色彩。
模式
| 模式 | 輸入 | 輸出 | 參考資料 |
|---|---|---|---|
| 影片轉 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 個 worker |
| TTS | ElevenLabs API（可選） | 生成旁白片段 |
| 可選 | OpenCV | 影片幀取樣、邊緣檢測 |
管線架構
所有模式都遵循相同的 6 階段管線：
輸入 → 分析 → 場景函式 → 色調映射 → 著色 → 編碼
- 輸入 — 載入/解碼原始素材（影片幀、音訊樣本、圖片或無）
- 分析 — 提取每幀特徵（音訊頻帶、影片亮度/邊緣、運動向量）
- 場景函式 — 場景函式渲染到像素畫布 (
uint8 H,W,3)。透過_render_vf()+ 像素混合模式組合多個字元網格。請參閱references/composition.md - 色調映射 — 基於百分位數的自適應亮度標準化。請參閱
references/composition.md§ 自適應色調映射 - 著色 — 透過
ShaderChain+FeedbackBuffer進行後處理。請參閱references/shaders.md - 編碼 — 將原始 RGB 幀透過管道傳送給 ffmpeg 進行 H.264/GIF 編碼
創作方向
美學維度
| 維度 | 選項 | 參考資料 |
|---|---|---|
| 字元調色盤 | 密度漸層、區塊元素、符號、文字（片假名、希臘文、符文、盲文）、項目特定 | architecture.md § 調色盤 |
| 色彩策略 | HSV、OKLAB/OKLCH、離散 RGB 調色盤、自動生成和諧色、單色、色溫 | architecture.md § 色彩系統 |
| 背景紋理 | 正弦場、fBM 雜訊、域扭曲、Voronoi、反應擴散、細胞自動機、影片 | effects.md |
| 主要效果 | 環、螺旋、隧道、渦旋、波、干涉、極光、火焰、SDF、奇異吸引子 | effects.md |
| 粒子 | 火花、雪、雨、氣泡、符文、軌道、群聚模擬、流場跟隨者、拖尾 | effects.md § 粒子 |
| 著色器風格 | 復古 CRT、簡潔現代、故障藝術、電影感、夢幻、工業風、迷幻 | shaders.md |
| 網格密度 | xs(8px) 到 xxl(40px)，每層混合 | architecture.md § 網格系統 |
| 座標空間 | 笛卡爾、極座標、平鋪、旋轉、魚眼、Möbius、域扭曲 | 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 檔案。元件（附參考資料）：
- 硬體檢測 + 品質設定檔 —
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 - 色調映射 — 自適應亮度標準化；
references/composition.md - 著色器管線 —
ShaderChain+FeedbackBuffer；references/shaders.md - 場景表 + 調度器 — 時間 → 場景函式 + 設定；
references/scenes.md - 平行編碼器 — 使用 ffmpeg 管道進行 N 個 worker 的片段渲染
- 主程式 — 編排完整管線
步驟 4：品質驗證
- 先測試幀：在完整渲染前，於關鍵時間戳記渲染單一幀
- 亮度檢查：所有 ASCII 內容的
canvas.mean() > 8。如果太暗，降低 gamma - 視覺連貫性：所有場景是否感覺屬於同一部影片？
- 創作願景檢查：輸出是否與步驟 1 的概念相符？如果看起來很普通，請返回
關鍵實作注意事項
亮度 — 使用 tonemap()，而非線性乘數
這是 #1 的視覺問題。黑色背景上的 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，過曝 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 字元都能在所有字型中渲染。請在初始化時驗證調色盤 — 渲染每個字元，檢查是否為空白輸出。請參閱 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 廣播陷阱、混合模式陷阱、多處理/pickling、亮度診斷、ffmpeg 問題、字型問題、常見錯誤 |
創作發散（僅在使用者要求實驗/創作/獨特輸出時使用）
如果使用者要求創作性、實驗性、驚喜或非傳統的輸出，請選擇最適合的策略，並在生成程式碼之前推導其步驟。
- 強制連結 — 當使用者想要跨領域靈感時（「讓它看起來有機」、「工業美學」）
- 概念混合 — 當使用者提到兩個事物要結合時（「海洋遇見音樂」、「太空 + 書法」）
- 迂迴策略 — 當使用者極度開放時（「給我驚喜」、「一些我從未見過的東西」）
強制連結
- 選擇一個與視覺目標無關的領域（天氣系統、微生物學、建築、流體動力學、紡織編織）
- 列出其核心視覺/結構元素（侵蝕 → 逐漸揭示；有絲分裂 → 分裂複製；編織 → 交錯圖案）
- 將這些元素映射到 ASCII 字元和動畫模式
- 綜合 — 「侵蝕」或「結晶」在字元網格中看起來像什麼？
概念混合
- 命名兩個不同的視覺/結構概念（「海洋」與「電路」；「書法」與「粒子物理」）
- 列出每個概念的核心屬性（海洋：波浪、深度、流動、漸變；電路：節點、路徑、焊點、開關）
- 找到交集（如何用電路元件表現波浪？節點路徑如何像洋流？）
- 合成混合視覺語言（電路追蹤洋流模式；焊點作為波浪泡沫）
迂迴策略
從清單中選擇一個提示（或在精神上擲骰子），並將其作為專案的限制條件：
- 「用你非慣用手畫出」 — 使用不完美的渲染、低解析度、受限調色盤
- 「像侵犯邊界一樣使用它」 — 字元溢出網格、破壞框架、色調衝突
- 「移除核心元件」 — 沒有背景效果、沒有色彩、沒有動畫。純靜態文字
- 「將錯誤轉化為特徵」 — 將單色調色盤錯誤、網格錯位、渲染瑕疵作為核心美學
- 「更改比例」 — 極小的網格（2px 字元）與極大的網格（80px），或兩者混合
- 「在不相關的事物之間建立一個系統」 — 將雜訊的 FFT 頻率映射到字元類別
- 「反轉」 — 反轉強度（黑字白底）、反轉速度（慢動作）、反轉邏輯（空字元代表最密集）
- 「像回音一樣重複自己」 — 延遲、反饋回路、重複序列、回文式動畫
對於所有發散策略：最終輸出必須仍然感覺經過設計且令人愉悅，而非隨機。其目標是擴展而非打破技能的美學。
最後更新：技能版本 2.0