ascii-video

ASCII 動画制作パイプライン

使用する場面

ユーザーから、ASCII 動画、テキストアート動画、ターミナル風動画、文字アートアニメーション、レトロなテキスト表現、ASCII 音声ビジュアライザー、動画の ASCII アート変換、マトリックス風エフェクト、またはアニメーション付き ASCII 出力を求められた場合に使用します。

内容

あらゆる形式に対応する、ASCII アート動画の制作パイプラインです。動画、音声、画像、生成系の入力を、カラーの ASCII 文字動画出力（MP4、GIF、画像シーケンス）に変換します。動画から ASCII への変換、音声に反応するミュージックビジュアライザー、生成系 ASCII アートアニメーション、動画と音声の反応を組み合わせたハイブリッド表現、テキスト／歌詞のオーバーレイ、リアルタイムのターミナル描画に対応します。

クリエイティブ基準

これはビジュアルアートです。ASCII 文字が表現手段であり、基準となるのは映画です。

コードを1行でも書く前に、クリエイティブコンセプトを明確にしてください。どんなムードにするのか。どのようなビジュアルストーリーを伝えるのか。このプロジェクトを、ほかのどの ASCII 動画とも違うものにする要素は何か。ユーザーのプロンプトは出発点です。文字どおりに再現するのではなく、創造的な意欲を持って解釈してください。

初回レンダリングの完成度は譲れません。 出力は、修正を重ねなくても視覚的に際立っていなければなりません。ありきたりだったり、平板だったり、「AI が生成した ASCII アート」のように見えたりする場合は、失敗です。公開する前にクリエイティブコンセプトを練り直してください。

参考資料の表現にとどまらないでください。 参考資料にあるエフェクトカタログ、シェーダープリセット、パレットライブラリは、表現の出発点です。プロジェクトごとに、パターンを組み合わせ、変更し、新たに考案してください。カタログは絵の具のパレットであり、絵を描くのはあなたです。

先回りして創造性を発揮してください。 プロジェクトに必要であれば、このスキルの表現の幅を広げてください。ビジョンの実現に参考資料の内容が足りない場合は、作りましょう。ユーザーが求めてはいないものの、喜んでもらえるビジュアル上の見せ場を少なくとも1つ盛り込んでください。トランジション、エフェクト、作品全体を引き立てる色使いなどが考えられます。

技術的な正しさより、美的な統一感を重視してください。 動画内のすべてのシーンが、共通するビジュアル言語によって結び付いていなければなりません。色温度、関連性のある文字パレット、一貫した動きの表現を共有させてください。シーンごとに異なるエフェクトを無作為に使う技術的には正しい動画は、美的には失敗です。

密度が高く、重層的で、練り上げられた表現にしてください。 すべてのフレームに、見返す価値を持たせてください。単調な黒背景は避けてください。常に複数のグリッドで構成してください。常にシーンごとに変化を付けてください。常に色を意図的に選んでください。

モード

モード	入力	出力	参考資料
動画から 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 スクリプトを1つ使用します。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 § Adaptive Tonemap を参照してください。
5. SHADE — ShaderChain と FeedbackBuffer による後処理を行います。references/shaders.md を参照してください。
6. ENCODE — 生のRGBフレームをffmpegにパイプし、H.264／GIFにエンコードします。

クリエイティブディレクション

美的要素

要素	選択肢	参照
キャラクターパレット	密度ランプ、ブロック要素、記号、文字体系（カタカナ、ギリシャ文字、ルーン文字、点字）、プロジェクト固有	architecture.md § Palettes
カラー戦略	HSV、OKLAB／OKLCH、離散RGBパレット、自動生成ハーモニー、モノクロ、色温度	architecture.md § Color System
背景テクスチャ	サイン波フィールド、fBMノイズ、ドメインワープ、ボロノイ、反応拡散、セルオートマトン、動画	effects.md
主なエフェクト	リング、らせん、トンネル、渦、波、干渉、オーロラ、炎、SDF、ストレンジアトラクター	effects.md
パーティクル	火花、雪、雨、泡、ルーン文字、軌道、群れをなすボイド、フローフィールド追従、軌跡	effects.md § Particles
シェーダーの雰囲気	レトロCRT、クリーンでモダン、グリッチアート、シネマティック、夢幻的、インダストリアル、サイケデリック	shaders.md
グリッド密度	xs（8px）からxxl（40px）まで、レイヤーごとに組み合わせ可能	architecture.md § Grid System
座標空間	デカルト、極座標、タイル、回転、魚眼、メビウス、ドメインワープ	effects.md § Transforms
フィードバック	ズームトンネル、虹色の軌跡、幽霊のような残響、回転するマンダラ、色の変化	composition.md § Feedback
マスキング	円、リング、グラデーション、テキストステンシル、アニメーションするアイリス／ワイプ／ディゾルブ	composition.md § Masking
トランジション	クロスフェード、ワイプ、ディゾルブ、グリッチカット、アイリス、マスクによる表示	shaders.md § Transitions

セクションごとの変化

動画全体で同じ設定を使わないでください。セクション／シーンごとに、次の要素を変えます。

• 背景エフェクトを変える（または2～3種類を合成する）
• キャラクターパレットを変える（雰囲気に合わせる）
• カラー戦略を変える（少なくとも色相を変える）
• シェーダーの強度に変化をつける（盛り上がる場面ではブルームを強め、静かな場面ではグレインを増やす）
• パーティクルを使う場合は、パーティクルの種類を変える

プロジェクト固有の創意工夫

プロジェクトごとに、次のうち少なくとも1つを考案してください。

• テーマに合ったカスタムキャラクターパレット
• カスタム背景エフェクト（既存の構成要素を組み合わせたり、変更したりする）
• カスタムカラーパレット（ブランド／雰囲気に合わせた離散RGBセット）
• カスタムパーティクル文字セット
• 独創的なシーントランジションまたは視覚的な演出

カタログから選ぶだけにしないでください。カタログは語彙です。詩を書くのはあなたです。

ワークフロー

ステップ1：クリエイティブビジョン

コードを書く前に、クリエイティブコンセプトを明確にします。

• 雰囲気／空気感：視聴者にどんな気持ちになってほしいですか？活気に満ちた、瞑想的、混沌とした、優雅、不穏？
• 視覚的なストーリー：再生時間を通じて何が起こりますか？緊張感を高めますか？変化しますか？溶けていきますか？
• 色の世界：暖色／寒色？モノクロ？ネオン？アースカラー？主役となる色相は何ですか？
• 文字のテクスチャ：密度の高いデータ？まばらな星？有機的なドット？幾何学的なブロック？
• このプロジェクトならではの特徴：このプロジェクトを独自のものにする要素は何ですか？
• 感情の展開：シーンはどのように進行しますか？勢いよく始まり、クライマックスへ高まり、解決へ向かいますか？

ユーザーのプロンプトを美的な選択に反映させます。「落ち着いたローファイビジュアライザー」と「グリッチ系サイバーパンクのデータストリーム」では、あらゆる要素が異なります。

ステップ 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 を満たすこと。暗い場合はガンマを下げます
• 視覚的な一貫性：すべてのシーンが同じ動画の一部に見えますか？
• クリエイティブビジョンの確認：出力はステップ 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

シーンごとのガンマ：デフォルトは 0.75、solarize は 0.55、posterize は 0.50、明るいシーンは 0.85 です。暗いレイヤーには overlay ではなく screen ブレンドを使用してください。

フォントセルの高さ

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/frame

リファレンス

ファイル	内容
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つのものを指定している場合（「海と音楽」「宇宙＋カリグラフィー」）
• オブリーク・ストラテジー — ユーザーが最大限に自由な発想を求めている場合（「驚かせて」「今まで見たことがないもの」）

強制的な結び付け

1. 視覚的な目標とは関係のない領域を選びます（気象システム、微生物学、建築、流体力学、織物）
2. その領域の視覚的／構造的な要素を列挙します（侵食 → 徐々に現れること、有糸分裂 → 分裂と複製、織物 → 交差するパターン）
3. それらの要素をASCII文字とアニメーションパターンに対応付けます
4. 組み立てます。文字グリッドでは「侵食」や「結晶化」はどのように見えるでしょうか？

概念のブレンド

1. 異なる2つの視覚的／概念的な領域を挙げます（例：海の波＋楽譜）
2. 対応関係を割り当てます（波頭 = 高音、谷 = 休符、泡 = スタッカート）
3. 選択的にブレンドします。最も興味深い対応関係を残し、無理のあるものは捨てます
4. ブレンドによってのみ生まれる、新たな特性を展開します

オブリーク・ストラテジー

1. 次のいずれかを選びます：「誤りを隠された意図として尊重する」／「古いアイデアを使う」／「親しい友人ならどうするか？」／「欠点を強調する」／「ひっくり返す」／「全体ではなく一部だけ」／「逆にする」
2. その指示を、現在のASCIIアニメーションの課題に照らして解釈します
3. コードを書く前に、横方向のひらめきを視覚的なデザインに取り入れます