# 録画 (セッション単位) API

録画されたファイルは `sora.conf` の [archive_dir](SORA_CONF.html#ad2156) に指定したディレクトリに置かれます。


## StartRecording

*バージョン 2023.2.0 で追加。*

**x-sora-target**: Sora_20231220.StartRecording

指定したチャネルの録画を開始します。

クラスター機能利用時には、クラスター内のどのノードで実行しても開始された録画情報はすべてのノードで共有されます。

* - キー
  - 型
* - channel_id
  - string
* - expire_time (オプション)
  - integer
* - split_duration (オプション)
  - integer
* - split_only (オプション)
  - boolean
* - metadata (オプション)
  - JSONValue
* - format (オプション)
  - string

- `expire_time` を指定しない場合は未指定になります- `expire_time` を指定しない場合、録画の期限が無くなります
- `expire_time` を指定する範囲は `1` から `86400` までで、秒数を指定してください- 指定できる最大値はデフォルトで `86400` で [recording_max_expire_time](SORA_CONF.html#f3ff8d) に指定した値で変わります
- `split_only` は `true` か `false` を指定してください。指定しない場合は `false` が指定されます
- `split_only` を `true` に指定する場合は `split_duration` を指定する必要があります
- `split_duration` を指定する範囲は `1` から `86400` までで、秒数を指定してください- 指定できる最大値はデフォルトで `86400` で、 [recording_max_split_duration](SORA_CONF.html#927da9) に指定した値で変わります
- `metadata` は `recording.report` ウェブフックやレポートファイルに `recording_metadata` として含まれるようになります。
- `format` は `webm` または `mp4` を指定してください- `format` が未指定の場合は [default_recording_format](SORA_CONF.html#f9fa7d) の値が利用されます
  - 映像コーデックが H.265 の場合 `format` に `mp4` を指定しない場合、録画が行われません

### 一括録画を行いたい場合

- `split_only` を `false` に指定するか、未指定にしてください

### 分割録画を行いたい場合

- `split_only` を `true` に指定してください
- `split_duration` を指定してください

### 一括＆分割録画を行いたい場合

- `sora.conf` の [recording_dual_output](SORA_CONF.html#4cc9c0) を `true` に指定してください
- `split_only` を `false` に指定するか、未指定にしてください
- `split_duration` を指定してください

### expire_time が指定無し

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20231220.StartRecording" \
    --json '{"channel_id":"sora"}' \
    | jq .
{
    "channel_id": "sora",
    "expire_time": 0,
    "session_id": "96D7CQDEMS5CHCKDX46REWWTX4",
    "recording_id": "C0YTCRZM715BKATBXWFPKTYGRM"
}
```

### expire_time が 3600

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20231220.StartRecording" \
    --json '{"channel_id":"sora","expire_time":3600}' \
    | jq .
{
    "channel_id": "sora",
    "expire_time": 3600,
    "session_id": "96D7CQDEMS5CHCKDX46REWWTX4",
    "recording_id": "C0YTCRZM715BKATBXWFPKTYGRM"
}
```

### split_only が true

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20231220.StartRecording" \
    --json '{"channel_id":"sora","split_duration":3600,"split_only":true}' \
    | jq .
{
    "channel_id": "sora",
    "expire_time": 0,
    "session_id": "96D7CQDEMS5CHCKDX46REWWTX4",
    "recording_id": "MK4J54QBGS4ES0MCSZMF6C9M9M",
    "split_duration": 3600,
    "split_only": true
}
```

### エラー

- "STARTED-RECORDING"- 指定したチャネル ID で、すでに録画が開始している
- "NOT-CLUSTER-MAJORITY"- クラスターで半数以下のグループに所属している

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20231220.StartRecording" \
    --json '{"channel_id":"sora","expire_time":3600}' \
    | jq .
{
    "error_type": "STARTED-RECORDING"
}
```


## StopRecording

*バージョン 2023.2.0 で追加。*

**x-sora-target**: Sora_20231220.StopRecording

指定したチャネルの録画を停止します。

この API は非同期です。200 が返ってきた場合でも録画ファイルや録画メタデータファイルが生成されていることを保証しません。
イベントウェブフックの [archive.available](EVENT_WEBHOOK.html#de9132) または [recording.report](SESSION_WEBHOOK.html#920a02) の通知を利用してください。

* - キー
  - 型
* - channel_id
  - string

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20231220.StopRecording" \
    --json '{"channel_id":"sora"}' \
    | jq .
{
    "channel_id": "sora",
    "session_id": "96D7CQDEMS5CHCKDX46REWWTX4",
    "recording_id": "C0YTCRZM715BKATBXWFPKTYGRM"
}
```

### エラー

- "NOT-STARTED-RECORDING"- 指定したチャネルの録画が開始されていない
- "NOT-CLUSTER-MAJORITY"- クラスターで半数以下のグループに所属している