agora.io Cloud Recording SDK 録画モード(Individual/Composite)の違い

#概要
agora.ioに[Cloud Recording SDK](https://docs.agora.io/en/cloud-recording/product_cloud_recording%20?platform=Linux)が公開されています。

Cloud Recording SDKには2つの録画モードが存在し、
目的や用途により使い分けることができます。
・Individualモード
・Compositeモード

この記事では、Cloud Recording SDKの
・録画モードの種類と違い
・録画モードごとの動作確認(サンプルコードあり）
・録画ファイルのマージとコンバート(トランスコード)
についてご説明いたします。

なお、[agora.io Cloud Recording SDKのクイックスタートガイド](https://qiita.com/v-cube/items/bd119f39239b6e6a7c22)も併せてご参照ください。

##サンプル
本記事で利用するサンプルは[こちら](https://github.com/Nakamu987/agoraCloudRecording/tree/master/CloudRecordingSTSample)です。
(phpにてRestful APIをコールするサンプルです)

なお、Restful APIについては[Agora Cloud Recording RESTful API](https://docs.agora.io/en/cloud-recording/cloud_recording_api_rest?platform=All%20Platforms)をご参照ください。

##Cloud Recording SDKの録画モード

Cloud Recording SDKの録画モードは2種類あります。
・[Individualモード](https://docs.agora.io/en/cloud-recording/cloud_recording_individual_mode?platform=All%20Platforms#overview)
・[Compositeモード](https://docs.agora.io/en/cloud-recording/cloud_recording_composite_mode?platform=All%20Platforms#overview)

##Individualモード
###Individualモードとは?
[Individualモード](https://docs.agora.io/en/cloud-recording/cloud_recording_individual_mode?platform=All%20Platforms)は、各UIDの音声、映像を別々に保存します。

###Individualモードの概要図
[イメージ] *[公式サイト](https://docs.agora.io/en/cloud-recording/cloud_recording_individual_mode?platform=All%20Platforms)より
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/505696/2f0af0d5-dd3d-9e8a-5765-545b15a8b84c.png" width="98%">

**[図の説明]**
(左側)チャネルにuid1とuid2が入室し、録画を実施
(中央)録画後、各uidの音声、映像を4セット生成
(右側)マージ処理により、mp4(2ファイル)が生成

###Individualモードの録画ファイル

**ファイル種類**
各uidに対し音声と映像がそれぞれ作成されます。
図の例のように2名の場合は4つになります。

**ファイル形式**

- m3u8 : 1ファイル
- ts : 複数ファイル

m3u8とtsファイルで1セットです。
Individualモードの場合は、1つのuidで音声、映像の2セット作成されます。

※tsファイルは15秒単位で作成されます。([slicing](https://docs.agora.io/en/cloud-recording/cloud_recording_manage_files?platform=All%20Platforms#slicing)を参照)
※vp8の場合はtsではなくwebmが作成されます。

###Individualモードのメリット
各uidの音声、映像ファイルを別々に持つことで、
後で自由に映像を作ることができます。

###Individualモードの用途
例えば、オンラインレッスンで、1名の先生、複数の生徒がいる場合、
後で先生と生徒1名ごとの映像を全生徒分作成し配布することができます。

###録画ファイルのマージ
Individualモードで別々に保存された各uidの音声、映像ファイルを1ファイルにマージすることができます。
図の例のようにマージ処理によりmp4ファイルが作成されます。

※マージ方法については「[トランスコード環境](#トランスコード環境)」を参照

※公式ページ[Merge Audio and Video Files](https://docs.agora.io/en/cloud-recording/cloud_recording_merge_files?platform=All%20Platforms#overview)

##Compositeモード
###Compositeモードとは?
[Compositeモード](https://docs.agora.io/en/cloud-recording/cloud_recording_composite_mode?platform=All%20Platforms#overview)は、全UIDの音声、映像をまとめて保存します。

[イメージ] *[公式サイト](https://docs.agora.io/en/cloud-recording/cloud_recording_composite_mode?platform=All%20Platforms)のイメージを使用
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/505696/9f248c46-f711-e1ee-afc5-499307a8c9ec.png" width="98%">

**[図の説明]**
(左側)チャネルにuid1とuid2が入室し、録画を実施
(中央)録画後、全uidの音声、映像が結合されたものを1セット生成
(右側)コンバート処理により、mp4ファイルに変換

###Compositeモードの録画ファイル

**ファイル種類**
全uidの音声、映像が結合されたものが作成されます。

**ファイル形式**
m3u8とts/webm
※詳細はIndividualモードの「ファイル形式」を参照してください。
Compositeモードの場合は、1セットのみ作成されます。

###Compositeモードのメリット
Compositeモードのメリットは2つあります。

1. 既に全uidの音声、映像を結合してあるので、マージせずにすぐに利用できます。

2. 「カスタムレイアウト」があり、独自にレイアウトを作成でき、録画中にそれを変更することもできます。また各映像のuidの指定も可能です。
※詳細は[Updates the video mixing layout](https://docs.agora.io/en/cloud-recording/cloud_recording_api_rest?platform=All%20Platforms#a-nameupdateaupdates-the-video-mixing-layout)を参照
※定型レイアウト(Flating/BestFit/Vertical)もあります([Set Video Layout](https://docs.agora.io/en/cloud-recording/cloud_recording_layout?platform=All%20Platforms#overview))

###Compositeモードの用途
・ライブ配信後にすぐに映像を公開したい場合
・1:1の面談などでレイアウトが固定の場合
などに適しています。

###録画ファイルのコンバート
必要に応じて作成された録画ファイルをコンバートすることができます。
図の例ではmp4ファイルに変換しています。

※コンバート方法については「[トランスコード環境](#トランスコード環境)」を参照

※公式ページ[Convert File Format](https://docs.agora.io/en/cloud-recording/cloud_recording_convert_format?platform=All%20Platforms#overview)


##動作確認
各モード毎に動作確認をしてみます。

###前準備
下記環境をご準備ください。
・APPID ※コンソールより発行
・[サンプルコード](https://github.com/Nakamu987/agoraCloudRecording/tree/master/CloudRecordingSTSample)
・外部ストレージ環境（S3）
　※利用可能な外部ストレージについては[公式サイト](https://docs.agora.io/en/cloud-recording/product_cloud_recording?platform=Linux
)を参照
・アプリケーションサーバ環境(XAMPP)
・トランスコード環境(Ubuntu) 
　※[トランスコード環境](#トランスコード環境)を参照
・デモアプリ([Web](https://github.com/AgoraIO/Basic-Video-Call/tree/master/One-to-One-Video/Agora-Web-Tutorial-1to1))

###Individualモードの動作確認

1.params.phpにmode(individual)をセットします。

```php:params.php
$mode = 'individual';
```
2.デモアプリに指定したChannel名で入室しておきます。
※Channel名はparams.phpの$cnameで指定した値になります。
3.【acquire実行】http\://localhost/acquire.phpを実行します。

ブラウザ上に以下のようなレスポンスが表示されます。

```php:http://localhost/acquire.php
{"resourceId":"IL0B7AstDJPJLomAtRqYZ(省略)jC3bVHSX885c0AW7PG4p0Wsufq"} 
```
acquireコールにてresourceIdが発行されていることがわかります。

4.サンプルソース(params.php)にresourceIdを保存します。

```php:params.php
$resourceid = "IL0B7AstDJPJLomAtRqYZ(省略)jC3bVHSX885c0AW7PG4p0Wsufq";
```


5.【start実行】http\://localhost/start_individual.phpを実行します。

ブラウザ上に以下のようなレスポンスが表示されます。

```php:http://localhost/start.phpのレスポンス
{"resourceId":"IL0B7AstDJPJLomAtRqYZ(省略)jC3bVHSX885c0AW7PG4p0Wsufq",
"sid":"5a0ae8c8374aab7fe1110993b205eae5"}"
```
startコールにて録画が開始され、sidが発行されています。

6.サンプルソース(params.php)にsidを保存します。

```php:params.php
$sid = '5a0ae8c8374aab7fe1110993b205eae5';
```

7.【stop実行】http\://localhost/stop.phpを実行します。

ブラウザ上に以下のレスポンスが表示されます。

```php:http://localhost/start.phpのレスポンス
{"resourceId":"IL0B7AstDJPJLomAtRqYZ(省略)jC3bVHSX885c0AW7PG4p0Wsufq",
"sid":"5a0ae8c8374aab7fe1110993b205eae5",
"serverResponse":{
"fileListMode":"string",
"fileList":"directory1/directory2/5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_2262050709__uid_e_audio.m3u8",
"uploadingStatus":"uploaded"}
}"
/*省略*/
```
stopコールにて録画が停止し、結果(serverResponse)が表示されています。
※保存されるファイルは複数個あるため、実際は上記のレスポンスが複数個出力されます。


8.クラウドストレージに接続してファイルが作成されていることを確認します。

Individualモードの通り、各uidの音声、映像が別々に保存されていることが分かります。

```
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_2262050709__uid_e_audio.m3u8
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_2262050709__uid_e_audio_20200519064015088.ts
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_2262050709__uid_e_audio_20200519064030098.ts
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_2262050709__uid_e_audio_20200519064045118.ts
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_2262050709__uid_e_audio_20200519064100138.ts
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_2262050709__uid_e_video.m3u8
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_2262050709__uid_e_video_20200519064015115.ts
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_2262050709__uid_e_video_20200519064030543.ts
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_2262050709__uid_e_video_20200519064045751.ts
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_2262050709__uid_e_video_20200519064101695.ts
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_547851663__uid_e_audio.m3u8
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_547851663__uid_e_audio_20200519064018868.ts
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_547851663__uid_e_audio_20200519064033878.ts
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_547851663__uid_e_audio_20200519064048898.ts
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_547851663__uid_e_audio_20200519064103918.ts
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_547851663__uid_e_video.m3u8
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_547851663__uid_e_video_20200519064018999.ts
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_547851663__uid_e_video_20200519064034129.ts
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_547851663__uid_e_video_20200519064049318.ts
5a0ae8c8374aab7fe1110993b205eae5_demo__uid_s_547851663__uid_e_video_20200519064105302.ts
```

9.【マージ処理実行】ファイルをマージします。
(トランスコード環境にコピー後)マージスクリプトを実行します。

```
python convert.py -f /home/individual -m 0 -p 30 -r 640 360
```

詳細は[トランスコード環境](#トランスコード環境)を参照

10.マージ処理後のファイルを確認します。
uid(547851663)とuid(2262050709)の2名のmp4が作られています。

```
2262050709_0_merge_av.mp4
547851663_0_merge_av.mp4
```

11.【映像の再生】映像を確認します。
※映像は一部隠しています。

[547851663_0_merge_av.mp4]
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/505696/3b1bcc9a-7d65-82a0-5265-0c4c910cf180.png" width="50%">

[2262050709_0_merge_av.mp4]
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/505696/d06d76b0-a00e-016d-aa8b-c72f414bd303.png" width="50%">

Individualモードでの録画実施と映像の確認ができました。

###Compositeモードの動作確認

1.params.phpにmode(mix)をセットします。

```php:params.php
$mode = 'mix';
```
2.デモアプリに指定したChannel名で1名だけ入室しておきます。
※Channel名はparams.phpの$cnameで指定した値になります。

(3から6はindividualと同じ手順です)
3.【acquire実行】http\://localhost/acquire.phpを実行します。
4.サンプルソース(params.php)にresourceIdを保存します。
5.【start実行】http\://localhost/start_composite.phpを実行します。
6.サンプルソース(params.php)にsidを保存します。

7.【updateLayout実行】http\://localhost/updateLayout.phpを実行します。
1名用レイアウトから2名用レイアウトに変更します。
[before]
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/300377/5156ef98-f8a8-b3de-cafa-7c30558fcecf.png" width="15%">
[after]
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/300377/842919eb-d60c-9fbe-1b65-b12b00454c84.png" width="15%">
(注)レイアウト更新時に解像度の変更はできません。

8.デモアプリにもう1名入室します。
2名入室状態になります。

9.【query実行】http\://localhost/query.phpを実行します。
[query](https://docs.agora.io/en/cloud-recording/cloud_recording_api_rest?platform=All%20Platforms#query)は録画中の状況を確認するためのものです。
録画実行中の場合、statsに5(recording is running)が返ってきます。

```json:response(query)
{
  /*省略*/
  "serverResponse":{
    "status": "5",
  /*省略*/
   }       
}
```

詳細は[Queries the recording status](https://docs.agora.io/en/cloud-recording/cloud_recording_api_rest?platform=All%20Platforms#a-namequeryaqueries-the-recording-status)を参照


(10秒程度経過後)
10.【stop実行】http\://localhost/stop.phpを実行します。
録画が停止します。

11.クラウドストレージに接続してファイルが作成されていることを確認します。

Compositeモードの通り、全uidの音声、映像を1つにまとめて保存します。

```
be2b10c1a24bf3ac0c7e8593ec3e1d83_demo.m3u8
be2b10c1a24bf3ac0c7e8593ec3e1d83_demo_20200519033733096.ts
be2b10c1a24bf3ac0c7e8593ec3e1d83_demo_20200519033749339.ts
be2b10c1a24bf3ac0c7e8593ec3e1d83_demo_20200519033805381.ts
be2b10c1a24bf3ac0c7e8593ec3e1d83_demo_20200519033821354.ts
```

12.【コンバート処理実行】ファイルをコンバートします。
(トランスコード環境にコピー後)コンバートスクリプトを実行します。

```
python format_convert.py /home/composite m3u8 mp4
```

※詳細は[トランスコード環境](#トランスコード環境)を参照

13.ファイルがコンバートされていることを確認します。

```
be2b10c1a24bf3ac0c7e8593ec3e1d83_demo.m3u8
be2b10c1a24bf3ac0c7e8593ec3e1d83_demo_20200519033733096.ts
be2b10c1a24bf3ac0c7e8593ec3e1d83_demo_20200519033749339.ts
be2b10c1a24bf3ac0c7e8593ec3e1d83_demo_20200519033805381.ts
be2b10c1a24bf3ac0c7e8593ec3e1d83_demo_20200519033821354.ts
be2b10c1a24bf3ac0c7e8593ec3e1d83_demo.mp4   ←ここ
```

14.【映像の再生】映像を確認します。
※映像は一部隠しています。

・1拠点レイアウト時
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/505696/606b647b-1947-27a9-ea45-f8cce9ecc72a.png" width="50%">

・2拠点レイアウト時(updateLayout実行後、2拠点目未入室)
映像枠に表示する映像がない場合は、背景色(updateLayout実行時設定)が設定されます。
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/505696/5304489c-e03e-4933-32bd-73940385eb07.png" width="50%">

・2拠点レイアウト時(updateLayout実行後、2拠点目入室後)
<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/505696/a95e03cf-bcd8-b57f-ed7a-5dc3554ac4f8.png" width="50%">

Compositeモードでの録画の実施と映像視聴までできました。

##トランスコード環境

トランスコード環境では、以下のことを実施することができます。

・録画ファイルのマージ
　※Individualモードで作成された録画ファイルに利用します。
・録画ファイルのコンバート
　※主にCompositeモードで利用します(Individualモードでも利用可能)。

###前準備
下記環境をご準備ください。
・Linux環境
　※動作バージョンは[Prerequisites](https://docs.agora.io/en/cloud-recording/cloud_recording_merge_files?platform=All%20Platforms#prerequisites)を参照
・マージ用スクリプト：[Agora Audio & Video File Merging](https://download.agora.io/acrsdk/release/format_convert_1.0.tar.gz?_ga=2.230024284.1748610585.1589774813-1196671664.1573546659)
・コンバート用スクリプト：[Agora Format Converter](https://download.agora.io/acrsdk/release/format_convert_1.0.tar.gz?_ga=2.163432700.1748610585.1589774813-1196671664.1573546659)
※スクリプトは2020/05現在のリンクです。

###マージ用
####マージ用スクリプト準備
1. Linux環境にログインします。

2. Pythonをインストールしておきます。

3. マージ用スクリプトをダウンロードします。
[Merge Audio and Video Files](https://docs.agora.io/en/cloud-recording/cloud_recording_merge_files?platform=All%20Platforms#overview)より、[Agora Audio & Video File Merging(マージ用スクリプト)](https://download.agora.io/acrsdk/release/Agora_Cloud_Recording_Tools_v1.14.1_20201026-1603685854_1361.tar.gz)をダウンロードします。

4. ダウンロードしたファイルを解凍します。
解凍後、フォルダ内にconvert.pyとffmpeg.tar.gzがあることを確認します。

```:/home
Agora_Cloud_Recording_Tools_v1.0.0.7_20191009-1570616811_830.tar
Cloud_Recording_tools
```

```:/home/Cloud_Recording_tools
convert.py
ffmpeg.tar.gz
```

5．ffmpeg.tar.gzも同フォルダ内に解凍しておきます。

```:/home/Cloud_Recording_tools
convert.py
ffmpeg.tar.gz
ffmpeg
```

####マージ用スクリプト実行

コマンド例

```
python convert.py -f <directory> -m 0 -p 30 -r 640 360
```
[オプション]
・f : ディレクトリを指定 (例：/home/targetfiles/)
・m : (同uidの)ファイル結合の種類
　　　0:映像+音声
　　　1:音声
　　　2:映像
・p : フレームレート(5～20fpsまで)
・r : 解像度(指定値は[Set the Video Profile](https://docs.agora.io/en/cloud-recording/recording_video_profile)を参照)　

※オプションは上記以外にもあります。
詳細は[Execute the Audio & Video File Merging script](https://docs.agora.io/en/cloud-recording/cloud_recording_merge_files?platform=All%20Platforms#2-execute-the-audio--video-file-merging-script)を参照



###コンバート用
####コンバート用スクリプト準備

1. Linux環境にログインします。

2. Pythonとffmpegをインストールしておきます。

3. コンバート用スクリプトをダウンロードします。
[Convert File Format](https://docs.agora.io/en/cloud-recording/cloud_recording_convert_format?platform=RESTful)より、[Agora Format Converter(コンバート用スクリプト)](https://download.agora.io/acrsdk/release/format_convert_1.0.tar.gz)をダウンロードします。

4. ダウンロードしたtarファイルを解凍します。

解凍後

```/home
format_convert_1.0.tar.gz
format_convert.py
```

####コンバート用スクリプト実行
コンバートの方法は2つあります。
・スクリプトを利用する方法
・ffmpegを利用する方法

**スクリプトの場合**

コマンド例

```
python format_convert.py <directory> <source_format> <destination_format>
```

・directory : ディレクトリを設定(例：/home/targetfiles/)
・source_format : 変換元フォーマット
　　"m3u8"をセット
　　※他のフォーマット(ts/webm)も指定可能
・destination_format : 変換先フォーマット
　　・映像 : mp4, ts
　　・音声 : mp3, wav, aac

詳細は[Convert using the script](https://docs.agora.io/en/cloud-recording/cloud_recording_convert_format?platform=All%20Platforms#convert-using-the-script)を参照

具体例

```
python format_convert.py /home/Composite m3u8 mp4
```
この例では/home/individual以下に保存したファイルに対し、m3u8をmp4へ変換します。


**ffmpegの場合**
専用スクリプトに限らずffmpegでより高度なコンバートが可能です。

コマンド例

```
ffmpeg -i <input_filename> -vcodec <video_codec> -acodec <audio_codec> -absf <bitstream_filter> <output_filename>
```

詳細は[ffmpeg](https://www.ffmpeg.org/ffmpeg.html)を参照

具体例

```
ffmpeg -i /home/Composite/be2b10c1a24bf3ac0c7e8593ec3e1d83_demo.m3u8 -vcodec copy -acodec copy -absf aac_adtstoasc output.mp4
```
/home/Compositeにあるbe2b10c1a24bf3ac0c7e8593ec3e1d83_demo.m3u8ファイルを
output.mp4で出力する例になります。



#最後に
[**agora.ioに関するお問い合わせはこちらから**](https://jp.vcube.com/lp/agora?utm_campaign=Agora&utm_source=Qiita&arc_id=d968a315266c17acf3a4)
[<img width="912" alt="スクリーンショット 0001-08-15 13.41.56.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/300377/5d815376-9b89-08fa-9434-6fa7e8e67bcf.png">](https://jp.vcube.com/lp/agora?utm_campaign=Agora&utm_source=Qiita&arc_id=d968a315266c17acf3a4)