レイアウト機能

September 26, 2025 · View on GitHub

Hisui では、レイアウトを定義した JSON ファイルを使うことで、複数映像ソースを合成する際の配置を細かく指定できます。また、レイアウト JSON では、映像ソースの配置以外に、映像や音声のエンコード設定も指定できます。

hisui compose コマンドの場合は、以下のように -l オプションでレイアウトファイルを指定できます。

hisui compose -l /path/to/layout.jsonc /path/to/archive/RECORDING_ID/

レイアウトファイルを指定しない場合は layout-examples/compose-default.jsonc が使用されます。

レイアウト JSON の概要

レイアウト JSON には、以下が指定できます。

音声の合成に使用するファイル一覧（未指定時には音声なし合成）
映像の合成に使用するファイル一覧（未指定時には映像なし合成）
合成後の音声のエンコードに使用するコーデックとビットレート
合成後の映像のエンコードに使用するコーデックとビットレート、エンコーダーに固有のエンコードパラメーター
映像の合成レイアウト

具体的に指定可能な項目についてはレイアウト JSON の仕様を参照してください。

また、映像の合成では、柔軟にレイアウト（各映像ソースをどう配置するか）が指定できるようになっています。こちらも詳細はリージョン（映像の配置方法指定）についてが詳しいですが、以降ではいくつかの例を記載しています。

レイアウトの例: グリッド（デフォルトレイアウト）

以下は layout-examples/compose-default.jsonc でも採用されている、一番ベーシックな配信者の映像をグリッド状に配置するレイアウト JSON の例です。

{
  "audio_sources": [
    "archive-*.json"
  ],
  "video_layout": {
    "main": {
      "max_columns": 3,
      "max_rows": 2,
      "video_sources": [
        "archive-*.json"
      ]
    }
  },
  "resolution": "960x480"
}

JSON の各項目の概要は以下の通りです。

audio_sources: 音声合成に使用するソースファイル一覧です
- archive-*.json というワイルドカード指定により、録画ディレクトリ内の全ての配信者の音声が合成されます
video_layout: 映像のレイアウト定義です
- main: 映像のレイアウトは「リージョン」という単位で指定しますが、その各リージョンの名前です（任意の名前が指定可能）
  - max_columns: リージョン内のグリッドの最大列数です（省略時は上限なし）
  - max_rows: リージョン内のグリッドの最大行数です（省略時は上限なし）
  - video_sources: 映像合成に使用するソースファイル一覧です
resolution: 合成後の映像の解像度です

ここでは main という名前のリージョンを一つだけ定義しています。リージョン内に各映像ソースを配置するグリッドの形状は、 max_columns および max_rows の設定、映像ソースの数などに基づいて決定されます。今回の設定では、最大で 3x2 のグリッドが形成されることになります。

合成結果のイメージ

配信者が 5 人いる場合の合成結果のイメージは以下の通りです（2行3列のグリッド）：

┌─ main ──────────────────────────────────────────────┐
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │   Source A  │  │   Source B  │  │   Source C  │  │
│  │             │  │             │  │             │  │
│  │             │  │             │  │             │  │
│  └─────────────┘  └─────────────┘  └─────────────┘  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │   Source D  │  │   Source E  │  │    Empty    │  │
│  │             │  │             │  │             │  │
│  │             │  │             │  │             │  │
│  └─────────────┘  └─────────────┘  └─────────────┘  │
└─────────────────────────────────────────────────────┘
``$

このグリッドレイアウトでは、最大 6 つのセル（2行 \times 3列）が利用可能で、
配信者が 5 人の場合は上記のような配置になります。

もし配信者が 6 人を超える場合は、$reuse` という項目の設定に従って表示する映像ソースが決定されます。
グリッドの行列数の決定方法や、より詳細な配置ルールについては [リージョン（映像の配置方法指定）について](./layout_region.md) を参照してください。

このデフォルトレイアウトは、参加者数が適度で、全員の映像を同じサイズで表示したい会議録画などに適しています。

## レイアウトの例: Picture-in-Picture

以下は、二つのリージョンを使って、
メイン映像と小さなサブ映像を組み合わせた Picture-in-Picture レイアウトの例です。

```json
{
  "audio_sources": [
    "archive-*.json"
  ],
  "video_layout": {
    "main": {
      "video_sources": [
        "archive-presenter.json"
      ],
      "width": 1280,
      "height": 720,
      "x_pos": 0,
      "y_pos": 0,
      "z_pos": 0
    },
    "pip": {
      "video_sources": [
        "archive-*.json"
      ],
      "video_sources_excluded": [
        "archive-presenter.json"
      ],
      "max_columns": 6,
      "max_rows": 1,
      "width": 480,
      "height": 180,
      "x_pos": 780,
      "y_pos": 520,
      "z_pos": 10
    }
  },
  "resolution": "1280x720"
}

JSON の各項目の概要は以下の通りです。

audio_sources: 音声合成に使用するソースファイル一覧です
- archive-*.json というワイルドカード指定により、録画ディレクトリ内の全ての配信者の音声が合成されます
video_layout: 映像のレイアウト定義です
- main: メインリージョン（発表者の映像）
  - video_sources: 発表者の映像ファイルを指定
  - width, height: リージョンのサイズ（1280x720）
  - x_pos, y_pos: リージョンの位置（左上角）
  - z_pos: 重ね合わせ順序（0 なので背景側）
- pip: Picture-in-Picture リージョン（聴衆の映像）
  - video_sources: archive-*.json で全ての映像ファイルにマッチ
  - video_sources_excluded: 発表者の映像を除外
  - max_columns: グリッドの最大列数（6 列まで表示）
  - max_rows: グリッドの最大行数（1 列まで表示）
  - width, height: 小さなリージョンのサイズ（480x180）
  - x_pos, y_pos: 右下に配置する位置座標
  - z_pos: 重ね合わせ順序（10 なのでメインより前面）

合成結果のイメージ

Picture-in-Picture レイアウトの合成結果のイメージは以下の通りです。

┌─ main ─────────────────────────────────────────────────────────────┐
│                                                                    │
│                                                                    │
│                    Presenter Video                                 │
│                  (Main Content Area)                               │
│                                                                    │
│                                                                    │
│                                                                    │
│                                                                    │
│                      ┌─ pip ────────────────────────┐              │
│                      │ Aud1 │ Aud2 │ Aud3 │ ...     │              │
│                      └──────────────────────────────┘              │
└────────────────────────────────────────────────────────────────────┘

このレイアウトは、プレゼンテーションや講演の録画で、発表者をメインに表示しつつ、聴衆の反応も同時に確認したい場合に適しています。ワイルドカードパターンと除外設定を使用することで、発表者以外の全ての参加者を自動的に pip リージョンに含めることができ、参加者の増減にも柔軟に対応できます。