# マスク合成

> マスク動画を通して、前景の動画を背景の動画の上に重ねます。反転、ぼかし、拡大／縮小、音声を選べます。キーなしで、すべてのエディションで動作します。

Source: https://nodaro.ai/ja/docs/nodes/video/mask-composite

**マスク合成**ノードは、マスク動画を通して、前景の動画を背景の動画の上に重ねます。マスクが白い部分には前景が、黒い部分には背景が表示され、グレーの部分では両方が混ざります。マスク合成は AI モデルを使わないため、同じ入力からは常に同じ結果が得られます。

- Found in: Video › Cut & Assemble
- API type: `mask-composite`

主な組み合わせ先は[**動画マスク**](https://nodaro.ai/docs/nodes/video/video-mask)です。動画マスクで被写体を元の映像の中でマスクし、その映像を前景に、別の動画を背景に使います。すると、被写体が新しいシーンの中に現れます。

マスク合成はプロバイダーキーを必要としないため、キーをまったく設定していない Community エディションを含む、すべてのエディションで動作します。

## 使いどころ
- 被写体を新しいシーンに移します。たとえば、ダンサーをビーチに移します。
- 製品やプレゼンターの背景を差し替えます。
- **マスクを反転**を使って被写体以外のすべてを残し、その場所に新しい被写体を入れます。
- 別のツールで作った白黒のマットを通して、2 本のクリップを合成します。

## クイックスタート
### ノードを追加する
キャンバス上で Tab を押し、**動画 › カットと結合 › マスク合成**を選びます。

### 3 本の動画を接続する
被写体の映っている映像を**前景**に、新しいシーンを**背景**に、マスク動画を**マスク**に接続します。マスク動画には、たとえば[**動画マスク**](https://nodaro.ai/docs/nodes/video/video-mask)ノードの**マスク**出力を使います。

### 境界を調整する
設定パネルを開きます。やわらかい境界にするには**ぼかし**を 2 ピクセルのままにします。被写体のまわりに元の背景が細い線として見える場合は、**拡大／縮小**を 0 より小さくします。

### 実行する
ノードの**実行**をクリックします。合成された動画がノードに表示されます。

Workflow: 動画マスクがダンサーを追跡し、マスク合成がマスクの白い部分にダンサーを、それ以外の部分にビーチを表示します。

- 動画アップロード → 動画マスク (動画)
- 動画アップロード → マスク合成 (前景)
- 動画アップロード → マスク合成 (背景)
- 動画マスク → マスク合成 (マスク)

## 入力
| 入力 | 受け付けるもの | 役割 |
| --- | --- | --- |
| **前景** | **動画アップロード**、**動画生成**などの動画ノード | マスクの白い領域を残す映像です。出力はこの映像のサイズ、フレームレート、長さになります。必須です。 |
| **背景** | 動画ノード | マスクが黒い部分に表示される動画です。必須です。 |
| **マスク** | **動画マスク**などの動画ノード | マスク動画です。白い部分に前景が、黒い部分に背景が表示されます。必須です。 |

背景は、**背景のフィット**の設定に従って前景のフレームに合わせて調整され、前景より短い場合はループします。マスクは前景のフレームに合わせて引き伸ばされ、短い場合は最後のフレームのまま止まります。ほぼ黒は完全に背景、ほぼ白は完全に前景として扱われるため、圧縮によるノイズで薄い残像が出ることはありません。

## 出力
| 出力 | 内容 |
| --- | --- |
| **動画** | 合成された動画です。前景のサイズ、フレームレート、長さの MP4 です。**音声**の設定で音声トラックを残した場合は、音声が入ります。 |

出力にウォーターマークが入ることはありません。

## 設定
| 設定 | 役割 |
| --- | --- |
| **マスクを反転** | 表示を入れ替えます。白い部分に背景が、黒い部分に前景が表示されます。被写体以外のすべてを残したいときに使います。既定はオフです。 |
| **ぼかし** | マスクの境界をやわらげます。0〜20 ピクセルです。既定値は 2 です。0 ではくっきりした境界になります。数ピクセルにすると、追跡したマスクの境界のギザギザが目立たなくなります。 |
| **拡大／縮小** | 境界をやわらげる前に、白い領域を広げ（正の値）、または狭めます（負の値）。−10〜10 ピクセルです。既定値は 0 です。負の値にすると、被写体のまわりに残る元の背景の細い線を削れます。 |
| **背景のフィット** | 背景で前景のフレームをどう埋めるかを決めます。既定の**カバー（切り抜いて埋める）**は、フレームを埋め、はみ出た部分を切り抜きます。**全体を表示（レターボックス）**は、黒帯を付けて背景全体を表示します。**引き伸ばし**は、背景をフレームに合わせて引き伸ばします。 |
| **音声** | 出力に入れる音声です。既定は**前景の音声**です。ほかに、**背景の音声**、同じ音量で混ぜる**両方をミックス**、**音声なし**を選べます。選んだトラックが存在しない場合、出力は無音になります。トラックが 1 本しかない場合、**両方をミックス**はそのトラックを使います。 |

## 制限
- **長さ：** 前景は最長 300 秒です。

Nodaro が読み込めない前景や、300 秒を超える前景は、料金がかかる前に拒否されます。

## クレジット
マスク合成は、出力の 5 秒ごと（開始した区間ごと）に 11 クレジットです。出力の長さは前景と同じです。1 回の実行は少なくとも 5 秒 1 区間として数えられます。3 秒の出力は 1 区間、10 秒の出力は 2 区間、61 秒の出力は 13 区間です。

実行前のノードが前景の長さを知っているのは、ワークフローから長さがわかる場合だけです。それ以外の場合、ノードは 5 秒 1 区間の料金から 300 秒の出力の料金までの範囲を表示します。実行時には、料金がかかる前に前景を測定し、実際の長さの分だけ支払います。

## ヒント
- **先に前景をトリミングします。** 出力の長さは前景と同じなので、[**動画のトリミング**](https://nodaro.ai/docs/nodes/video/trim-video)で必要な場面だけにカットしてください。
- **背景は前景と同じ長さ以上にします。** 短い背景はループするため、つなぎ目が見えることがあります。
- **負の値で縁を削ります。** 被写体のまわりに元の背景の細い線が見える場合は、**拡大／縮小**を小さな負の値にします。
- **ぼかしを少し残します。** **ぼかし**を数ピクセルにすると、追跡したマスクの境界のギザギザが目立たなくなります。
- **どんなマットでも使えます。** レンダリングした図形のアニメーションなど、別のツールで作った白黒またはグレースケールの動画もマスクとして使えます。

## トラブルシューティング
**被写体のまわりに元の背景の細い輪郭が残る。** **拡大／縮小**を小さな負の値にし、**ぼかし**を少し残してください。

**被写体があるはずの場所に背景が表示される。** マスクの白黒が逆になっています。**マスクを反転**をオンにしてください。

**出力に音声がない。** **音声**で選んだトラックが、その動画にありません。もう一方の動画の音声か、**両方をミックス**を選んでください。

**背景に黒帯が入る、または切り抜かれる。** **背景のフィット**を変えてください。**カバー（切り抜いて埋める）**は切り抜き、**全体を表示（レターボックス）**は黒帯を付け、**引き伸ばし**はどちらもせずにフレームを埋めます。

## API から
`POST /v1/mask-composite` は、`foregroundUrl`、`backgroundUrl`、`maskUrl` と、任意の `invertMask`、`feather`（0〜20）、`grow`（−10〜10）、`backgroundFit`（`cover`、`contain`、`stretch` のいずれか）、`audioSource`（`foreground`、`background`、`mix`、`none` のいずれか）を受け取ります。ジョブを返します。完了したジョブの出力には、`videoUrl`、`thumbnailUrl`、`width`、`height`、`durationSec` が含まれます。300 秒を超える前景は、料金がかかる前に 400 エラーで拒否されます。

- **SDK：** `maskComposite({ foregroundUrl, backgroundUrl, maskUrl, invertMask, feather, grow, backgroundFit, audioSource })`。[メディアとアップロード](https://nodaro.ai/docs/developers/sdk/media-and-uploads)を参照してください。
- **MCP：** `mask_composite` ツールは、3 本の動画をそれぞれ `<name>_url` または `<name>_asset_id`（`foreground`、`background`、`mask`）として受け取ります。そのため、`video_mask` のジョブ ID を `mask_asset_id` に使えます。設定は `invert_mask`、`feather`、`grow`、`background_fit`、`audio_source` です。[MCP ツールリファレンス](https://nodaro.ai/docs/mcp/tools)を参照してください。
- **CLI：** `nodaro media mask-composite <foregroundUrl> <backgroundUrl> <maskUrl> [--invert] [--feather <px>] [--grow <px>] [--background-fit cover|contain|stretch] [--audio foreground|background|mix|none]`。[メディアと音声のコマンド](https://nodaro.ai/docs/developers/cli/media-commands)を参照してください。

[単体のノードを実行する](https://nodaro.ai/docs/developers/api/nodes)と[ジョブ](https://nodaro.ai/docs/developers/api/jobs)を参照してください。

## よくある質問

### マスク合成ノードは何をしますか？

マスク合成は、3 本の動画を 1 本にまとめます。マスクが白い部分には前景の動画が、黒い部分には背景の動画が表示され、グレーの部分では両方が混ざります。

### マスク動画はどこから用意しますか？

よく使うのは動画マスクノードです。動画マスクは、説明した被写体を前景の動画全体にわたって追跡します。白黒またはグレースケールの動画なら、別のツールで作ったマットなど、どれでもマスクとして使えます。

### 背景が短い場合やサイズが違う場合はどうなりますか？

出力は、前景のサイズ、フレームレート、長さに合わせます。背景は前景のフレームに合わせて調整され、短い場合はループします。マスクはフレームに合わせて引き伸ばされ、短い場合は最後のフレームのまま止まります。

### マスク合成のクレジットはいくらですか？

マスク合成は、出力の 5 秒ごと（開始した区間ごと）に 11 クレジットです。出力の長さは前景と同じです。前景は最長 300 秒です。

### セルフホスティング環境で、マスク合成に API キーは必要ですか？

いいえ。マスク合成は AI モデルを使わず、プロバイダーキーも不要です。そのため、キーをまったく設定していない Community エディションを含む、すべてのエディションで動作します。