# メタデータ

## 概要

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

## 接続時の認証メタデータ指定

クライアントが Sora へ接続する際に、認証に利用する `metadata` を指定できます。
これは認証ウェブフックに `metadata` として含まれます。

```javascript
{
  "type": "connect",
  "role": "sendrecv",
  "channel_id": "sora",
  "metadata": {"spam": "egg"}
}
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

### シグナリング通知メタデータ拡張が有効な場合

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

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

もしこのシグナリング通知メタデータを接続時にしていさせたくない場合、
[signaling_notify_authn_metadata_max_size](SORA_CONF.html#a8c147) を `0` に設定してください。

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

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

もし接続時に `signaling_notify_metadata` が指定されていた場合は、
認証成功時のシグナリング通知メタデータ払い出しで **上書き** されます。

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

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

### シグナリング通知メタデータ拡張が有効な場合

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

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

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

**[シグナリング通知メタデータ拡張](SIGNALING_NOTIFY_METADATA_EXT.html) を利用すると接続ごとに状態を持てるようになり、**
: API でそのメタデータを変更し、通知することができるようになります。

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

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

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

セッション生成時に送信される [session.created](SESSION_WEBHOOK.html#1d1984) の戻り値に指定することで `session_metadata` を払い出すことができます。
この値は一定間隔で送られる [session.updated](SESSION_WEBHOOK.html#2a5b1b) と、
このセッションが破棄された時に送られる [session.destroyed](SESSION_WEBHOOK.html#ccb165) に含まれます。

```javascript
{
  "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` ファイルとペアになります。

## 録画(セッション単位) の StartRecording API で指定するメタデータ

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

この値は以下のセッションウェブフックに `recording_metadata` として含まれます。

- [recording.started](SESSION_WEBHOOK.html#9b5c58)
- [recording.report](SESSION_WEBHOOK.html#920a02)
- [session.updated](SESSION_WEBHOOK.html#2a5b1b)

また、 `report-<recording_id>.json` ファイルにも記録されます。

## 録画(セッション単位) のセッションウェブフック `session.created` で指定するメタデータ

録画(セッション単位) ではセッションウェブフック `session.created` の戻り値として、
`recording_metadata` を払い出すことができます。

```
{
  "recording": true,
  "recording_metadata": "<JSON>"
}
```

この値は以下のセッションウェブフックに `recording_metadata` として含まれます。

- [recording.started](SESSION_WEBHOOK.html#9b5c58)
- [recording.report](SESSION_WEBHOOK.html#920a02)
- [session.updated](SESSION_WEBHOOK.html#2a5b1b)

また、 `report-<recording_id>.json` ファイルにも記録されます。