概要

• h3-metal はApple Silicon向けの MiniMax-H3推論 を実現するプロジェクト
• Metal最適化 と メモリ効率化 を段階的に実装
• コマンドラインと 対話型セッション による操作が可能
• 速度・品質プリセット や リファレンス品質 への調整が可能
• 解像度や動画長、プロンプトの工夫で柔軟な生成に対応

h3-metalの概要とビルド

• Apple Silicon （M3 Max, M5 Max）向けのMetalネイティブ推論実装
• 開発は 垂直スライス 方式で段階的に進行
  • ホスト/モデルメタデータ → Metalブロック互換 → プロンプトエンコード → プロンプトから動画/音声生成 → フレーム条件付け・参照
• Ref2VA による画像・動画・音声参照もサポート
• 最新作業は H3専用Metalパフォーマンス・メモリ最適化

モデルのビルドと検証

• Hugging Face スナップショットを./MiniMax-H3に配置
• FFmpeg/FFprobe がPATHに必要
• ビルド例:
  • make -j8
  • モデル情報確認: ./h3 --info -d ./MiniMax-H3
• CLIリファレンスは./h3 --helpで表示

対話型セッションの利用

• コマンド例:
  • ./h3 -d ./MiniMax-H3 --width 512 --height 512 --steps 6
• プロンプト入力で 連番動画生成
• セッションでは プロンプト条件付け ・ DiT ・ デコーダ をメモリ常駐
• 再利用による高速化 が可能
• 便利コマンド例:
  • !status, !seed random, !seconds 2, !show, !save output.mp4, !cache, !help
• ファースト/ラストフレーム条件付け:
  • !first opening.png, !last ending.png
  • 解除は!first clear, !last clear
• Ref2VA画像参照:
  • !ref-image PATH
  • <Picture 1>, <Picture 2>として順序付け
  • !refsで一覧, !ref-remove Nで削除, !refs clearで全削除
  • Ref2VAとファースト/ラストアンカーは 併用不可

最初の高速動画生成

• バランスプリセット 推奨
• 例:

  ./h3 --profile \
    -d ./MiniMax-H3 \
    -p "A red fox walks through fresh snow in a pine forest. Medium tracking shot, natural winter light, realistic fur, soft footsteps and wind." \
    --width 512 --height 512 \
    --frames 22 --steps 20 \
    --layers 45 --reuse 2 \
    --show \
    -o outputs/fox-fast.mp4
  

• --steps 20: 20回ノイズ除去
• --reuse 2: 11回新規計算、残りは補間
• --layers 45: 50ブロック中45使用で計算&メモリ削減
• --show: 対応ターミナルで中間フレーム表示
• --profile: パフォーマンス測定用（生成経路は変わらない）

反復・高速イテレーション

• 超短時間生成 例:

  ./h3 --profile \
    -d ./MiniMax-H3 \
    -p "A red fox walks through fresh snow in a pine forest. Medium tracking shot, natural winter light, realistic fur." \
    --width 512 --height 512 --frames 22 \
    --steps 4 --layers 50 --reuse 1 \
    --show \
    -o outputs/fox-four-step.mp4
  

• --steps N は実際のノイズ除去回数を指定
• 4～7回でディテール・動きが徐々に向上
• --reuse 1 推奨（全パスで新規計算）

リファレンス品質への調整

• 一度に一つのパラメータ を変更して品質検証
• 例（高品質）:

  ./h3 --profile \
    -d ./MiniMax-H3 \
    -p "A red fox walks through fresh snow in a pine forest. Medium tracking shot, natural winter light, realistic fur, soft footsteps and wind." \
    --width 512 --height 512 \
    --frames 22 --steps 50 \
    --layers 50 --reuse 1 \
    -o outputs/fox-close.mp4
  

• --steps 50 でフル50回推論
• MLXとのピクセル一致は非保証 （乱数生成・実行エンジン差異）

速度・品質プリセットの選択

• 主なコントロール:
  • ノイズ除去回数: --steps
  • 再利用回数: --reuse
  • DiTブロック数: --layers
  • コア再利用: --core-reuse
  • トークン削減: --token-reduction
  • 内部出力サイズ: --render-width, --render-height
  • INT8最適化: --use-int8-row-fc2
• 組み合わせ例:
  • 速度重視: --steps 4..7, --reuse 3, --layers 40, --core-reuse 6, --token-reduction, --render-width 320
  • 品質重視: --steps 50, --reuse 1, --layers 50, --core-reuse 1, トークン削減なし
• 注意: --reuseと--core-reuseは併用不可、--token-reductionは一部組み合わせ非推奨

解像度・動画長の設定

• 幅・高さは32の倍数、各32以上、合計768*1344以下
• H3-Baseは768pモデル
• 検証済みキャンバス例:
  • 512x512: 開発用・検証済み
  • 768x768: 高品質出力
  • 1344x768, 768x1344: 768pワイド/縦長
  • 384x384→512x512: 高速スケーリング
  • 320x320→512x512: アグレッシブスケーリング
  • 256x256: ネイティブ高速プレビュー
• 256x256以下は非推奨
• --render-width/--render-heightは出力と同じアスペクト比で指定

フレーム数・動画秒数の指定

• 24fps固定
• --seconds N または --frames N で指定（併用不可）
• フレーム数は5+17nに切り上げ
• 例: --seconds 10 → 243フレーム（約10.1秒）
• 開発には短尺クリップ推奨（4～15秒）

プロンプトの工夫

• 短いプロンプトも可 だが、 Context-IR風 が推奨
• 主題・動作・背景・カメラ・スタイル・音声 を明記
  • 例:
    • Scene: a single red fox in a snow-covered pine forest at dawn.
    • Action: the fox walks steadily left to right and looks toward the camera once.
    • Camera: medium-height lateral tracking shot, 50 mm lens, stable framing.
    • Look: photorealistic fur, cold blue ambient light, warm sunrise rim light.
    • Audio: ...