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

#概要
agora.ioにCloud Recording SDKが公開されています。

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

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

なお、agora.io Cloud Recording SDKのクイックスタートガイドも併せてご参照ください。

##サンプル
本記事で利用するサンプルはこちらです。
(phpにてRestful APIをコールするサンプルです)

なお、Restful APIについてはAgora Cloud Recording RESTful APIをご参照ください。

##Cloud Recording SDKの録画モード

Cloud Recording SDKの録画モードは2種類あります。
・Individualモード
・Compositeモード

##Individualモード
###Individualモードとは?
Individualモードは、各UIDの音声、映像を別々に保存します。

###Individualモードの概要図
[イメージ] *公式サイトより

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

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

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

ファイル形式

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

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

※tsファイルは15秒単位で作成されます。(slicingを参照)
※vp8の場合はtsではなくwebmが作成されます。

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

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

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

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

※公式ページMerge Audio and Video Files

##Compositeモード
###Compositeモードとは?
Compositeモードは、全UIDの音声、映像をまとめて保存します。

[イメージ] *公式サイトのイメージを使用

[図の説明]
(左側)チャネルに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を参照
   ※定型レイアウト(Flating/BestFit/Vertical)もあります(Set Video Layout)

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

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

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

※公式ページConvert File Format

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

###前準備
下記環境をご準備ください。
・APPID ※コンソールより発行
・サンプルコード
・外部ストレージ環境（S3）
　※利用可能な外部ストレージについては公式サイトを参照
・アプリケーションサーバ環境(XAMPP)
・トランスコード環境(Ubuntu)
　※トランスコード環境を参照
・デモアプリ(Web)

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

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

params.php

$mode = 'individual';

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

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

http://localhost/acquire.php

{"resourceId":"IL0B7AstDJPJLomAtRqYZ(省略)jC3bVHSX885c0AW7PG4p0Wsufq"} 

acquireコールにてresourceIdが発行されていることがわかります。

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

params.php

$resourceid = "IL0B7AstDJPJLomAtRqYZ(省略)jC3bVHSX885c0AW7PG4p0Wsufq";

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

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

http://localhost/start.phpのレスポンス

{"resourceId":"IL0B7AstDJPJLomAtRqYZ(省略)jC3bVHSX885c0AW7PG4p0Wsufq",
"sid":"5a0ae8c8374aab7fe1110993b205eae5"}"

startコールにて録画が開始され、sidが発行されています。

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

params.php

$sid = '5a0ae8c8374aab7fe1110993b205eae5';

7.【stop実行】http://localhost/stop.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]

[2262050709_0_merge_av.mp4]

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

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

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

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]

[after]

(注)レイアウト更新時に解像度の変更はできません。

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

9.【query実行】http://localhost/query.phpを実行します。
queryは録画中の状況を確認するためのものです。
録画実行中の場合、statsに5(recording is running)が返ってきます。

response(query)

{
  /*省略*/
  "serverResponse":{
    "status": "5",
  /*省略*/
   }       
}

詳細はQueries 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拠点レイアウト時

・2拠点レイアウト時(updateLayout実行後、2拠点目未入室)
映像枠に表示する映像がない場合は、背景色(updateLayout実行時設定)が設定されます。

・2拠点レイアウト時(updateLayout実行後、2拠点目入室後)

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

##トランスコード環境

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

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

###前準備
下記環境をご準備ください。
・Linux環境
　※動作バージョンはPrerequisitesを参照
・マージ用スクリプト：Agora Audio & Video File Merging
・コンバート用スクリプト：Agora Format Converter
※スクリプトは2020/05現在のリンクです。

###マージ用
####マージ用スクリプト準備

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

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

3. マージ用スクリプトをダウンロードします。
   Merge Audio and Video Filesより、Agora Audio & Video File Merging(マージ用スクリプト)をダウンロードします。

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を参照)　

※オプションは上記以外にもあります。
詳細はExecute the Audio & Video File Merging scriptを参照

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

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

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

3. コンバート用スクリプトをダウンロードします。
   Convert File Formatより、Agora Format Converter(コンバート用スクリプト)をダウンロードします。

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

解凍後

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を参照

具体例

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を参照

具体例

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に関するお問い合わせはこちらから