# メタデータ

## 概要

Sora では様々なメタデータを扱っているため、それぞれのメタデータの説明をしています。

## 認証ウェブフック成功時のメタデータ払い出し

認証ウェブフック成功時に `metadata` を払い出すことができます。
この値は Sora が `"type": "offer"` をクライアントへ送る際に `metadata` として送られます。

```json
{
    "allowed": true,
    "metadata": {"spam": "egg"}
}
```

```json
{
    "type": "offer",
    "sdp": "...",
    "metadata": {"spam": "egg"}
}
```

この値は Sora とクライアントだけで共有される値です。他のクライアントには一切共有されません。

## 認証ウェブフック成功時のイベントメタデータ払い出し

認証ウェブフック成功時に `event_metadata` を払い出すことができます。
この値は Sora がイベントウェブフックリクエストを送信する際に `event_metadata` として含まれます。

```json
{
    "allowed": true,
    "event_metadata": {"spam": "egg"}
}
```

```json
{
    "type": "connection.created",
    "event_metadata": {"spam": "egg"}
}
```

この値は Sora と認証ウェブフックとイベントウェブフック先のサーバーとのみで共有されます。
クライアントには通知されません。

## 接続時のシグナリング通知メタデータ指定

シグナリング接続時の `"type": "connect"` で `signaling_notify_metadata` が指定できます。
ここで指定した値は同じチャネルに参加しているクライアントと新しく参加するクライアントに通知されます。

```json
{
    "type": "connect",
    "signaling_notify_metadata": {"spam": "egg"}
}
```

```json
{
    "type": "connection.created",
    "authn_metadata": {"spam": "egg"}
    "metadata": {"spam": "egg"}
}
```

この通知はシグナリング通知メタデータ拡張が無効になっているときの通知です。
有効になっている場合は以下のように `authn_metadata` のみに値が含まれます。

```json
{
    "type": "connection.created",
    "authn_metadata": {"spam": "egg"}
    "metadata": {}
}
```

## 認証ウェブフック成功時のシグナリング通知メタデータ払い出し

認証ウェブフック成功時に `signaling_notify_metadata` を払い出すことができます。
この値は同じチャネルに参加しているクライアントと新しく参加するクライアントに通知されます。

```json
{
    "allowed": true,
    "signaling_notify_metadata": {"spam": "egg"}
}
```

```json
{
    "type": "connection.created",
    "authz_metadata": {"spam": "egg"}
    "metadata": {"spam": "egg"}
}
```

この通知はシグナリング通知メタデータ拡張が無効になっているときの通知です。
有効になっている場合は以下のように `authz_metadata` のみに値が含まれます。

```json
{
    "type": "connection.created",
    "authz_metadata": {"spam": "egg"}
    "metadata": {}
}
```

## シグナリング通知メタデータ拡張

[シグナリング通知メタデータ拡張](SIGNALING_NOTIFY_METADATA_EXT.html) を利用すると接続毎に状態を持つことが可能になります。

本来、シグナリング通知メタデータは接続時か認証成功払い出し時にしか指定できず一度指定したら変更できません。
シグナリング通知メタデータ拡張を利用した場合は HTTP API を利用して途中でメタデータの値を変更することができます。

この機能を有効にするとシグナリング時の通知メタデータに指定した値は `metadata` に含まれなくなります。

## セッション生成時のセッションメタデータ払い出し

セッション生成時に送信される [session.created ウェブフック](SESSION_WEBHOOK.html#3cec61) の戻り値に指定することで `session_metadata` を払い出すことができます。
この値はこのセッションが終了した時に [session.destoryed ウェブフック](SESSION_WEBHOOK.html#4e36be) に送信されます。

```json
{
  "session_metadata": "<JSON>"
}
```

## 一括録画ファイルメタデータ archive-<connection_id>.json

録画機能で一括録画を指定した際に `archive/<recording-id>/` 以下に生成されるファイルです。
かならず `archive-<connection_id>.webm` ファイルとペアになります。

## 分割録画ファイルメタデータ split-archive-<connection_id>_<index>.json

録画機能で分割録画を指定した際に `archive/<recording-id>/` 以下に生成されるファイルです。
かならず `split-archive-<connection_id>_<index>.webm` ファイルとペアになります。

## StartRecodirng API で指定するメタデータ

[StartRecording](API.html#c5b527) API では `metadata` を指定することができます。

この値は、録画終了時に [recording.report](EVENT_WEBHOOK.html#920a02) に送信されます。
また、 `report-<recording_id>.json` ファイルにも記録されます。