media-processing

メディア処理

標準的な CLI ツール（FFmpeg、ImageMagick）と Python ヘルパーを使って、画像、音声、動画を再現性のあるスクリプト化可能な方法で扱うためのツールとワークフローです。

使用する場面

• 画像の一括処理（サムネイル作成、サイズ変更、形式変換）
• メディア形式の相互変換（動画 ↔ 音声 ↔ 画像）
• 許容できる品質を維持しながら動画サイズを最適化する
• Web、モバイル、アーカイブ用の素材を準備する
• FFmpeg／ImageMagick を使った CLI ワークフローを設計または改善する

主な原則

• CLI 優先のワークフロー：コマンドラインツール（FFmpeg、ImageMagick）と、CI やローカルツールで自動化できるスクリプトを優先します。
• 決定論的なスクリプト：スクリプトは、予測可能な出力先とオプションで安全に繰り返し実行できるようにします。
• 非破壊的なデフォルト設定：元のファイルを上書きするのではなく、新しいファイルやディレクトリに出力することをデフォルトとします。
• クロスプラットフォーム対応：可能な限り、Linux、macOS、Windows で使用できる例やスクリプトにします。
• エージェントに依存しない：特定の環境ではなく、あらゆるコーディングエージェント（Cursor、Claude、Copilot など）で使えるガイダンスにします。

機能

• 画像ワークフロー

  • 画像の一括サイズ変更とサムネイル生成
  • アスペクト比を考慮したサイズ変更（fit、fill、cover、exact）
  • 透かしの任意追加
  • 形式変換（例：PNG → WebP、JPEG）

• メディア変換

  • 拡張子からメディアの種類（動画、音声、画像）を検出
  • 動画／音声には FFmpeg、画像には ImageMagick を使用
  • web、archive、mobile の用途別品質プリセット
  • ドライランモードと詳細モードでの一括変換

• 動画の最適化

  • 解像度とフレームレートの調整
  • 1 パス（CRF）または 2 パスのエンコード
  • 音声ビットレートの調整
  • 基本的な変換前後の比較（サイズ、ビットレート、解像度、FPS）

スクリプト

スクリプトは scripts/ にあり、シェルから直接実行することを想定しています。

• batch_resize.py

  • 複数の方法（fit、fill、cover、exact、thumbnail）による画像の一括サイズ変更
  • 透かしの任意追加
  • 並列処理とドライランモードに対応

• media_convert.py

  • 動画、音声、画像に対応する統合変換ツール
  • FFmpeg または ImageMagick を自動選択
  • 品質プリセット（web、archive、mobile）を使用
  • 一括変換と形式変更に対応（例：.mov → .mp4、.wav → .mp3）

• video_optimize.py

  • 動画サイズと品質のトレードオフに特化
  • 解像度の上限設定、FPS の削減、CRF の調整、2 パスエンコードの任意設定
  • 元の出力と最適化後の出力を比較するサマリーの任意生成

環境要件（Python 3.10 以降、FFmpeg、ImageMagick）とシステムへのインストール方法のヒントについては、scripts/requirements.txt を参照してください。

使用ガイドライン

• 最初に依存関係を確認する

  • 動画／音声の処理では、ffmpeg と ffprobe がインストールされ、PATH に含まれていることを確認します。
  • 画像の処理では、magick（ImageMagick）がインストールされ、PATH に含まれていることを確認します。

• 試すときはドライランを優先する

  • スクリプトの --dry-run や --verbose フラグを使って、実行前に生成されるコマンドを確認します。

• 元のファイルを保持する

  • 初回は出力先を別のディレクトリ（例：--output ./out/）に指定し、誤って上書きしないようにします。

• ワークフローを文書化する

  • 有用なコマンドラインやスクリプトの実行方法が見つかったら、プロジェクトのスクリプト（例：just、npm scripts、CI ジョブ）に追加し、繰り返し実行できるようにします。

参考資料

ツール固有の詳細なメモ（現在はプレースホルダーです。必要に応じて拡充してください）については、以下を参照してください。

• references/ffmpeg-encoding.md – FFmpeg のエンコードパターンとフラグ
• references/ffmpeg-filters.md – 一般的なフィルターグラフ（スケール、クロップ、オーディオフィルター）
• references/ffmpeg-streaming.md – ストリーミングに適した設定と HLS/DASH のヒント
• references/format-compatibility.md – コンテナー／コーデックの互換性に関するメモ（ウェブ、モバイル、デスクトップ）
• references/imagemagick-batch.md – ImageMagick を使用した画像の一括処理パターン
• references/imagemagick-editing.md – 画像編集操作（クロップ、サイズ変更、合成、テキストなど）