ASCIIビデオプロダクションパイプライン
使用するタイミング
ユーザーが以下のリクエストをする場合に使用します：ASCIIビデオ、テキストアートビデオ、ターミナルスタイルビデオ、キャラクターアートアニメーション、レトロテキストビジュアライゼーション、ASCIIのオーディオビジュアライザー、動画のASCIIアート変換、マトリックス風エフェクト、またはアニメーションASCII出力全般。
中身
ASCIIアートビデオのプロダクションパイプライン — あらゆるフォーマットに対応。動画/音声/画像/生成入力をカラーASCIIキャラクタービデオ出力（MP4、GIF、画像シーケンス）に変換します。以下をカバー：ビデオ→ASCII変換、音声反応型ミュージックビジュアライザー、生成ASCIIアートアニメーション、ハイブリッドビデオ+音声反応、テキスト/歌詞オーバーレイ、リアルタイム端末レンダリング。
クリエイティブスタンダード
これは視覚芸術です。ASCII文字が媒体であり、映画が基準です。
コードを一行書く前に、創造的なコンセプトを明確にしてください。ムードは？どんな視覚的なストーリーを語るのか？このプロジェクトを他のASCIIビデオと違うものにするのは何か？ユーザーのプロンプトは出発点です — 文字通りの転写ではなく、創造的な野心で解釈してください。
初回レンダリングでの優れた品質は絶対条件です。 出力は修正ラウンドを必要とせず、視覚的に印象的でなければなりません。何かが汎用的で、平面的で、「AIが生成したASCIIアート」のように見えるなら、それは間違いです — 出荷前に創造的コンセプトを再考してください。
参照語彙を超えてください。 参照のエフェクトカタログ、シェーダープリセット、パレットライブラリは出発点の語彙です。プロジェクトごとに、新しいパターンを組み合わせ、修正し、発明してください。カタログは絵の具のパレットです — あなたが絵を描きます。
積極的に創造的になってください。 必要とされる場合は、スキルの語彙を拡張してください。参照にビジョンに必要なものがなければ、それを構築してください。ユーザーが依頼しなかったが、感謝するであろう視覚的瞬間を少なくとも1つ含めてください — トランジション、エフェクト、作品全体を引き上げる色の選択。
技術的な正確さよりも、まとまりのある美学。 ビデオ内のすべてのシーンは、統一された視覚言語 — 共有された色温度、関連する文字パレット、一貫した動きの語彙 — によって結びついている必要があります。すべてのシーンがランダムに異なるエフェクトを使っている技術的に正しいビデオは、美学的な失敗です。
密度が高く、階層的で、考慮されていること。 すべてのフレームが鑑賞に値するものであること。決してフラットな黒背景にしてはいけません。常にマルチグリッド構成。常にシーンごとのバリエーション。常に意図的な色。
モード
| モード | 入力 | 出力 | 参照 |
|---|---|---|---|
| ビデオ→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 → SHADE → ENCODE
- INPUT — ソースマテリアル（ビデオフレーム、音声サンプル、画像、または何もなし）をロード/デコード
- ANALYZE — フレームごとの特徴（音声帯域、ビデオ輝度/エッジ、動きベクトル）を抽出
- SCENE_FN — シーン関数がピクセルキャンバス（
uint8 H,W,3）をレンダリング。_render_vf()+ ピクセルブレンドモードを介して複数の文字グリッドを合成。references/composition.md参照 - TONEMAP — パーセンタイルベースの適応明るさ正規化。
references/composition.md§ 適応トーンマップ 参照 - SHADE —
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 |
| パーティクル | スパーク、雪、雨、バブル、ルーン文字、軌道、群れボイド、フローフィールドフォロワー、軌跡 | effects.md § パーティクル |
| シェーダームード | レトロCRT、クリーンモダン、グリッチアート、シネマティック、ドリーミー、インダストリアル、サイケデリック | shaders.md |
| グリッド密度 | xs(8px) から xxl(40px)、レイヤーごとに混合 | architecture.md § グリッドシステム |
| 座標空間 | デカルト、極座標、タイル、回転、魚眼、メビウス、ドメインワープ | effects.md § 変換 |
| フィードバック | ズームトンネル、虹色の軌跡、幽霊のようなエコー、回転曼荼羅、色進化 | composition.md § フィードバック |
| マスキング | 円、リング、グラデーション、テキストステンシル、アニメーションアイリス/ワイプ/ディゾルブ | composition.md § マスキング |
| トランジション | クロスフェード、ワイプ、ディゾルブ、グリッチカット、アイリス、マスクベースのリビール | shaders.md § トランジション |
セクションごとのバリエーション
ビデオ全体で同じ設定を使ってはいけません。各セクション/シーンごとに：
- 異なる背景エフェクト（または2〜3を合成）
- 異なる文字パレット（ムードに合わせる）
- 異なる色戦略（または最低でも異なる色相）
- シェーダー強度を変える（ピーク時はより多くのブルーム、静かな時はより多くのグレイン）
- 異なるパーティクルタイプ（パーティクルがアクティブな場合）
プロジェクト固有の発明
すべてのプロジェクトで、以下を少なくとも1つ発明してください：
- テーマに合ったカスタム文字パレット
- カスタム背景エフェクト（既存のビルディングブロックを組み合わせ/修正）
- カスタムカラーパレット（ブランド/ムードに合った離散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 - トーンマップ — 適応明るさ正規化;
references/composition.md - シェーダーパイプライン —
ShaderChain+FeedbackBuffer;references/shaders.md - シーンテーブル + ディスパッチャー — 時間 → シーン関数 + 設定;
references/scenes.md - 並列エンコーダー — ffmpegパイプを使用したNワーカークリップレンダリング
- メイン — 完全なパイプラインを調整
ステップ 4: 品質検証
- まずテストフレーム: フルレンダリングの前に、主要なタイムスタンプで単一フレームをレンダリング
- 明るさチェック: すべてのASCIIコンテンツで
canvas.mean() > 8。暗い場合はガンマを下げる - 視覚的一貫性: すべてのシーンが同じビデオに属しているように感じられるか？
- クリエイティブビジョンチェック: 出力はステップ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
シーンごとのガンマ: デフォルト 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/ドメインワープ、ボロノイ、反応拡散、セルオートマトン、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の問題、フォントの問題、よくある間違い |
クリエイティブ・ダイバージェンス（ユーザーが実験的/創造的/ユニークな出力を求める場合のみ使用）
ユーザーが創造的、実験的、驚きのある、または型にはまらない出力を求める場合は、最適な戦略を選択し、コードを生成する前にそのステップを検討してください。
- 強制結合 — ユーザーが分野横断的なインスピレーションを求める場合（「有機的に見せて」、「工業的な美学」）
- 概念ブレンディング — ユーザーが2つのものを組み合わせることを指定する場合（「海と音楽の出会い」、「宇宙＋書道」）
- 斜め戦略 — ユーザーが最大限にオープンな場合（「驚かせて」、「今まで見たことのないものを見せて」）
強制結合
- 視覚目標とは無関係なドメインを選ぶ（気象システム、微生物学、建築、流体力学、織物）
- その中核的な視覚的/構造的要素をリストアップする（侵食 → 漸進的なリビール；有糸分裂 → 分割複製；織物 → 連動パターン）
- それらの要素をASCII文字とアニメーションパターンにマッピングする
- 統合する — キャラクターグリッドで「侵食」や「結晶化」はどのように見えるか？
概念ブレンディング
- 2つの異なる視覚的/概念的領域を特定する
- 両方のコア属性を抽出する（形、動き、色、リズム、質感）
- それらの属性をブレンドして新しいハイブリッドを作り出す
- 結果として生じる視覚言語をASCIIとアニメーションの語彙に変換する