agora.io Cloud Recordingのよくあるトラブルの原因と対策

概要

agora.io Cloud Recordingのよくあるトラブルの原因と対策についてご紹介します。

参考リファレンス

・Cloud Recording RESTful APIリファレンス
・Rotate the Video(映像回転の仕様)
・Video profile table(画質設定)

[Cloud Recordingの参考記事]
・agora.io Cloud Recording クイックスタートガイド
・agora.io Cloud Recording 録画モード(Individual/Composite)の違い

1.stop()時にステータスコード404(エラー)発生

stop.php

//stop()時レスポンス
string(369) " {"resourceId":"***","sid":"***",` "code":404'`}" 

・症状

acquire()、start()時はステータスコード200(成功)だったが、stop()時に404(エラー)が発生する。

[再現手順]
1. acquire()時、ステータスコードは200(成功)。
2. start()時、ステータスコードは200(成功)。
3. stop()時、ステータスコードは404(エラー)。

・原因と対策

start()時のリクエスト値に不備があります。(以下参照)

1.maxIdleTime(待機時間)が過ぎて録画が自動停止した

Cloud Recordingは、録画するChannelに誰もJoinしないままmaxIdleTimeを過ぎると、自動で録画を停止します。

[対策]

・ChannelにJoinをしてから録画を開始する

・maxIdleTime(5から2,592,000まで)を長くする

設定例

start.php

/*--省略--*/
$recordingConfig = [
   'maxIdleTime' => 1000,　//★ここ
   'streamTypes' => 2,
   'audioProfile' => 0,
   'channelType' => 1, 
   'videoStreamType' => 0
];
/*--省略--*/

サンプルソース

2.Tokenの値が間違えている

Tokenの値に不備があることが考えられます。
特にTokenの有効期限が切れていた原因が多いです。

[対策]

・Tokenの有効期限が正しいことを確認する

・ひとまずTokenを利用しないで録画ができるかどうか確認する
(※TokenはCloud Recording側、VideoSDK側の両方に設定します)

設定例

start.php

/*--省略--*/
$clientRequest = [
  'token' => "",   //★ここ
  'recordingConfig' => $recordingConfig,
  'storageConfig' => $storageConfig
];
/*--省略--*/

サンプルソース

　

3.ストレージのキーが間違えている

ストレージのアクセスキーやシークレットキーの不備が考えられます。

[対策]

・転送ツール(aswcliやwinscp)でローカルからストレージ(またはその逆)にファイルが転送できることを確認する

設定例

start.php

/*--省略--*/
$storageConfig= [
  'accessKey' => '*****',   //★ここ
  'region' => 10,　　　　　　//★
  'bucket' => '*****',　　　//★
  'secretKey' => '*****',  //★
  'vendor' => 1,  　　　　　//★
  'fileNamePrefix' => 'record'　  //★
];
/*--省略--*/

サンプルソース

　

4.画質の設定値が間違えている

Cloud Recordingの画質の設定値(transcodingConfigのwidth、height、fps、bitrate)は、Video profile tableに対応した値を設定する必要があります。

[対策]

・画質の設定値(transcodingConfigのwidth、height、fps、bitrate)が[Video profile table]に対応した値を正しく設定していることを確認し、適宜修正する

※Video profile table

設定例

start.php

/*--省略--*/
$transcodingConfig = [
  'height' => 640,　　//★ここ
  'width' => 360,　　　//★ここ　
  'bitrate' => 500,　　//★ここ
  'fps' => 15,　　　　　//★ここ
  'mixedVideoLayout' => 1
];
/*--省略--*/

サンプルソース

　

5.暗号キーが間違えている

暗号キー(Cloud Recording側の[decryptionMode]、[secret])の設定は、Cloud Recording側とVideoSDK側の両方に同じ値を設定する必要があります。

[対策]

・Video SDK側の[encryptionMode]､[ encryptionKey]とCloud Recording側の[decryptionMode]、[secret]を同じ設定にする

※Video SDK側のencryptionMode、 encryptionKey
※Cloud Recording側のdecryptionMode、secret

6.録画のuidがChannelのuidと競合している

channel内のuidと重複しているため、競合が発生しエラーになりますので、重複しないuidを設定する必要があります。

[対策]

・acquire、start実行時に指定するuidは、録画インスタンス用uidとして、channel内に入室しているuidとは重複しないユニークなuidを指定する。

7.その他

以下ケースは(404ではなく)各エラーコードが返却されます。

・start()リクエスト値がデータ型、指定範囲外の値、必須項目なしの場合 →ステータスコード=2
・誰もJoinせずにmaxIdletime以内にstop()した場合 →ステータスコード=435

※その他のケースはエラーコードを参照

２.録画したのに録画ファイルが存在しない

・症状

録画後にストレージを確認したところ、録画ファイルが存在しなかった。

良くある症状としては、
・録画開始(start)は成功しているのに、ファイルが1つも作成されなかった。
・(Individualモードで)１ユーザの音声ファイルだけが作成されていなかった。
・(Compositeモードで)m3u8ファイルが1つのみだった(tsファイルは0件)。
など

・原因と対策

1.録画に失敗している

start時の録画パラメータに不備があったため、録画に失敗している可能性があります。(stop時レスポンスに404が発生していた可能性があります)

[対策]

・start時の録画パラメータを見直す

1.stop()時にステータスコード404(エラー)発生を参照

2.映像、音声がミュートだった

Cloud Recordingの仕様として、映像、音声のストリームが作成されないと録画ファイルも作成されない仕様となっています。

たとえば、ユーザはJoinしていたが、音声(映像)がずっとミュートだった場合、
Individualモードの場合、音声(又は映像)ストリームが作成されないため、録音(録画)ファイルは作成されません。
Compositeモードの場合は、(映像、音声の両方がミュートだった場合)m3u8ファイルのみでtsファイルは作成されません。

[対策]

・録画したいユーザの映像、または音声をミュートしてないことを確認する

3.Channelに誰もJoinしていない

ユーザがChannelにJoinしていなかった可能性があります。

[対策]

・[コンソール]にて[Call Search]を利用して、そのユーザがChannelにJoinしていたかどうか確認してください。

※Call Search

3.録画した映像の向きが違う

・症状

ビデオ通話の際にモバイルデバイスを横から縦(又はその逆)にしたら、録画の映像が90度回転していた。

・原因と対策

1.VideoSDK側の映像の回転設定が合っていない

映像の回転設定は、以下の組み合わせにより影響します。
・VideoSDK側のsetVideoEncoderConfigurationのorientationMode
・モバイルデバイスの画面回転の設定(回転する/しない)

agoraの映像回転の仕様は、「Rotate the Video」(イメージ付き)に記載がありますので確認してください。

[対策]

・Video SDK側の設定(setVideoEncoderConfigurationのorientationMode="ADAPTIVE")、モバイルデバイスの設定(画面回転の設定を"回転する")を正しく設定する

4.録画した映像が切れている

・症状

録画の映像の縦横または左右が切れていた。

・原因と対策

1.VideoSDK側とCloudRecording側の映像サイズが合っていない

Cloud Recordingの定型レイアウト(Floating/BestFit/Vertical)の場合は、
VideoSDK側の映像のアスペクト比と合わないとクロップされます。(Verticalは最大サイズのみFit)
そのため、画面サイズを合わせる必要があります。

[対策]

・VideoSDK側とCloudRecording側のアスペクト比を合わせる。

・カスタムレイアウトを利用する(下記参照)

カスタムレイアウトを利用するには、
・[mixedVideoLayout=3(Customized layout)"]
・[layoutConfig]を[render_mode=1(fit)]
に設定します。
※CloudRecordingのレイアウト

5.その他

全てに該当しない場合、ログ調査をすることも可能です。
以下の情報と共にお問い合わせください。

[必要情報]
・APPID
・発生日時
・症状
・SID（start()時に発行されるセッションidのことです)

関連リンク

・Cloud Recordingで録画ファイルが作成されません。
・録画するユーザ(uid)を限定したいのですが、方法はありますか？
・Cloud Recordingで生成されたm3u8+tsファイルをmp4に変換したい

最後に

agora.ioに関するお問い合わせはこちらから