概要

本機能は、SFU を経由した音声と映像を録音・録画し、生成したファイルを指定のクラウドストレージにアップロードする機能です。

利用するには、Recording API (REST API) をお客様のサーバーから操作する必要があります。

概要図

録音・録画を行う際には、エンドユーザーへの説明および同意取得が必要です。詳しくはSkyWay 利用規約 第 34 条 「録音・録画の取扱い」をご確認ください。

Base URL

以下の Base URL から SkyWay Recording API を利用できます。

https://recording.skyway.ntt.com

対応クラウドストレージ

現在次のクラウドストレージに対応しています。

  • Google Cloud Storage
  • Amazon S3
  • Wasabi

保存コーデック

  • VP8
  • H264
  • OPUS

保存ファイルフォーマット

  • WebM

対応している通信方式

録音・録画は SFU を利用している場合のみ利用可能です。

Room ライブラリを用いて P2P ルームを利用している場合と、SFU Bot ライブラリを使わずに Core ライブラリを利用している場合は録音・録画機能は利用できません。

認証

SkyWay Recording API のリクエストには SkyWay Admin Auth Token による認証が必要です。

SkyWay Admin Auth Token の仕様については次のリンクを参照してください。

SkyWay Admin Auth Token

SkyWay Recording API の HTTP リクエストのリクエストヘッダーには Authorization: Bearer <token> が含まれている必要があります。

以下に curl コマンドでリクエストヘッダーを指定する例を示します。

curl -X POST ENDPOINT_URL \ -H "Authorization: Bearer YOUR_SKYWAY_ADMIN_AUTH_TOKEN"

各クラウドストレージに必要な資格情報

クラウドストレージに対して Recording サーバーから操作を行うため、録音・録画機能を利用する際に必要な権限を付与したクラウドストレージ認証情報を RecordingSession 作成時に渡す必要があります。このときに付与する権限は、セキュリティの観点から最小限であることが望ましいです。

録音・録画機能を利用する際に必要となる権限について、各クラウドストレージごとに説明します。

Google Cloud Storage

録音・録画機能を利用する際に必要となる Google Cloud のサービスアカウントの権限は、以下の 4 つです。

  • storage.objects.create
  • storage.objects.delete
  • storage.objects.get
  • storage.objects.list

Amazon S3

録音・録画機能を利用する際に必要となる AWS の権限は、以下の 2 つです。

  • DeleteObject
  • PutObject

Wasabi

録音・録画機能を利用する際に必要となる Wasabi の権限は、以下の 2 つです。

  • DeleteObject
  • PutObject

録音・録画ファイル

共通事項: アップロード完了時のパス構造

RecordingSession が削除されたり RecordingSession の録音・録画対象の Publication が unpublish されると、それに紐付く録音・録画ファイルのステータスが SUCCEEDED に変化します。

録音・録画ファイルのステータスが SUCCEEDED の場合、クラウドストレージ上の録音・録画ファイルのパスは次のようになります。

  • contentType: AUDIO
    • /channel_{channelId}/publisher_{publisherName}_{publisherId}/audio_{audioPublicationId}_{timestamp}.webm
  • contentType: VIDEO
    • /channel_{channelId}/publisher_{publisherName}_{publisherId}/video_{videoPublicationId}_{timestamp}.webm
  • contentType: AUDIO_AND_VIDEO
    • /channel_{channelId}/publisher_{publisherName}_{publisherId}/video_{videoPublicationId}_audio_{audioPublicationId}_{timestamp}.webm

timestamp は次の形式で表されます。

yyyyMMdd_HHmm_ssSSSSSSSSS

同じパスに録音・録画ファイルのメタデータファイルが拡張子 .json で保存されます。

また、録音・録画ファイルのパスは GetRecordingSession API のレスポンスから取得することもできます。

なお、Publication の mute が 1 分以上継続した場合、保存される録音・録画ファイルは mute 前後で分割されます。

Google Cloud Storage

録音・録画中に、クラウドストレージ上の録音・録画ファイルは次のような構造の一時保存ファイルとして複数に分割されてアップロードされます。この時、録音・録画ファイルのステータスは RECORDING となります。

  • contentType: AUDIO
    • /channel_{channelId}/publisher_{publisherName}_{publisherId}/audio_{audioPublicationId}_{timestamp}/***.webm
  • contentType: VIDEO
    • /channel_{channelId}/publisher_{publisherName}_{publisherId}/video_{videoPublicationId}_{timestamp}/***.webm
  • contentType: AUDIO_AND_VIDEO
    • /channel_{channelId}/publisher_{publisherName}_{publisherId}/video_{videoPublicationId}_audio_{audioPublicationId}_{timestamp}/***.webm

これらの分割された一時保存ファイルは通常は自動での結合が行われ、再生可能となります。しかし、何らかの理由で自動での結合が行われなかった場合でも、手動で結合することで再生できるようになります。

分割された一時保存ファイルの結合、もしくはアップロードに失敗した録音・録画ファイルの修復方法は開発ガイドのエラーとなった場合の録音・録画ファイルの取得を参照してください。

Amazon S3

アップロード中のパス構造は共通事項のアップロード完了時のパス構造と同じです。

アップロードに失敗した場合の修復方法は開発ガイドのエラーとなった場合の録音・録画ファイルの取得を参照してください。

また、メディアを再生する際にシークの機能が適切に機能しなかったり、ファイルが破損していると表示される場合があります。この際の修復方法は開発ガイドの録音・録画ファイルの修正方法を参照してください。

Wasabi

アップロード中のパス構造は共通事項のアップロード完了時のパス構造と同じです。

アップロードに失敗した場合の修復方法は開発ガイドのエラーとなった場合の録音・録画ファイルの取得を参照してください。

また、メディアを再生する際にシークの機能が適切に機能しなかったり、ファイルが破損していると表示される場合があります。この際の修復方法は開発ガイドの録音・録画ファイルの修正方法を参照してください。

録音・録画実行時の映像と音声の合成処理

録音・録画処理では、Publisher ごとに映像と音声の合成処理を行います。

保存される録音・録画ファイルは、Publisher が publish している Publication の数、ContentType、操作の順序によって異なります。

保存される録音・録画ファイルは以下の仕様になっています。

映像の Publication が N 個、音声の Publication が 1 個の場合

  • 各映像それぞれに対して音声が合成され、ファイルとして保存されます。
  • 加えて、音声のみのファイルも保存されます。
  • したがって、保存される録音・録画ファイルは、映像と音声が含まれたファイルが N 個と、音声のみのファイルが 1 個となります。

映像のPublicationがN個、音声のPublicationが1個の場合

映像の Publication が 1 個、音声の Publication が N 個の場合

  • 映像に対して、最初に publish が行われた音声の Publication が合成され、ファイルとして保存されます。
  • 加えて、音声のみのファイルも保存されます。
  • したがって、保存される録音・録画ファイルは、映像と最初に publish された音声が含まれたファイルが 1 個と、音声のみのファイルが N 個となります。

映像のPublicationが1個、音声のPublicationがN個の場合

映像の Publication が N 個、音声の Publication が M 個の場合

  • 各映像それぞれに対して、最初に publish が行われた音声の Publication が合成され、ファイルとして保存されます。
  • 加えて、音声のみのファイルも保存されます。
  • したがって、保存されるファイルは、映像と最初に publish された音声が含まれたファイルが N 個と、音声のみのファイルが M 個となります。

映像のPublicationがN個、音声のPublicationがM個の場合

補足: 音声の Publication が unpublish され、映像の Publication は引き続き存在している場合

最初に publish が行われた音声の Publication が unpublish され、映像の Publication は引き続き存在している場合、音声の Publication の unpublish と同時に映像と音声のファイルの保存が終了し、映像の Publication については新たに映像のみのファイルとして保存が開始されます。unpublish していない音声の Publication については継続して保存が行われるため、映像との合成が必要な場合は、録音・録画終了後にユーザー側で合成処理を行ってください。

音声のPublicationがunpublishされ、映像のPublicationは引き続き存在している場合