API docs by Redocly

RICOH Live Streaming REST API: 録画 API (v1)

Download OpenAPI specification:Download

RICOH Live Streaming REST API は Live Streaming サービスの公開 REST API です。

本ページは録画 API の仕様について記載します。

録画機能について

クラウド録画機能 は、現在 β 版として提供しております。
そのため、商用サービスでの利用をご検討される際には、必ず事前にお問い合わせください。
β 版のクラウド録画機能の利用料金は無料です。正式版は有償での提供を検討しておりますので、あらかじめご了承ください。
正式版を公開せずに β 版の公開を終了する、もしくは、正式版では β 版から機能や仕様が変更される可能性がありますので、あらかじめご了承ください。
クラウド録画機能に関連して現在発生している問題はRICOH Live Streaming クラウド既知の問題を確認してください。

録画 API について

RoomInstance に対する録画の開始と停止を行うには、Room 管理 API にある Room 録画 API を使用します。
Room 録画 API を使用することで、ある RoomInstance に対して、任意のタイミングでの録画の開始、停止、再開が可能です。
また、Room 録画 API から録画開始を指定する以外にも、AccessToken にある recording_on_start 設定を使用することで、RoomInstance の生成時点からの録画が可能です。

ただし、録画データの保存先として、事前に本ページの 録画ストレージ設定 API を利用してお客様の管理するクラウドストレージを設定しておく必要があります。

お客様ストレージに保存する録画ファイル仕様

お客様のストレージに録画データを保存することを指定した場合、 保存先に指定されたURLから以下の保存パス仕様に示すパスに録画ファイルと録画ファイルに関連するメタデータファイルが保存されます。 録画ファイルには以下の種類があり、どの録画ファイルを保存するかを AccessToken で設定できます。

  • 単一拠点録画ファイル: プレイヤーでの再生を考慮して、コーデックやフォーマット変換、I フレーム挿入などのトランスコーディングが行われた単一の拠点ごとに録画されたファイル
  • 生の録画ファイル: 単一拠点録画ファイルは上述のようなトランスコーディングが行われますが、それを行わずに配信時の映像/音声データをそのまま保存したものを生の録画ファイルと呼びます
    • 配信側のクライアントで不可逆圧縮されているので、主にプロユースにおける可逆圧縮という意味でのいわゆる「Raw 動画」とは異なります
  • 合成録画ファイル: 指定された単一拠点録画ファイルを合成して 1 つにした録画ファイル

録画を実行した場合、各拠点について、単一拠点録画メタデータファイル、Connection 履歴ファイル、Video Track 履歴ファイル、Audio Track 履歴ファイルは常に保存されます。 また、合成録画を有効にした場合、合成録画メタデータファイルが保存されます。

保存ファイル仕様

  • 単一拠点録画ファイル

    • 保存パス: /{room_id}/{RoomInstanceの開始時刻}/{Sequence}/{connection_id}-{ConnectionInstance の存在開始時刻}-{ConnectionInstance の存在終了時刻}.mp4
    • 拠点の Connection が以下のいずれかの条件を満たす場合、単一拠点録画ファイルは保存されません
      • AccessToken の JWTClaims で connection_spec.recording.store の値を false にした
      • 録画期間中、常に映像/音声ともに HardMute だった

  • 生の録画ファイル

    • 保存パス: /{room_id}/{RoomInstanceの開始時刻}/{Sequence}/{connection_id}-{ConnectionInstanceの録画開始時刻}-{ConnectionInstanceの録画終了時刻}_raw.webm
    • 拠点の Connection が以下のいずれかの条件を満たす場合、生の録画ファイルは保存されません
      • AccessToken の JWTClaims で connection_spec.recording.store_raw の値を false か未設定にした
      • 録画期間中、常に映像/音声ともに HardMute だった

  • 単一拠点録画メタデータファイル

    • 保存パス: /{room_id}/{RoomInstanceの開始時刻}/{Sequence}/{connection_id}-{ConnectionInstance の存在開始時刻}-{ConnectionInstance の存在終了時刻}.json
    • 本ページの ConnectionRecordingMetadata のスキーマを持つ JSON であり、以下のどちらかの形式を持ちます
      • ConnectionRecordingMetadataWithMediaFile: 単一拠点録画ファイルが保存される拠点のメタデータ形式
      • ConnectionRecordingMetadataWithoutMediaFile: 単一拠点録画ファイルが保存されない拠点のメタデータ形式
    • 単一拠点録画ファイルが保存されない拠点の Connection でも、録画期間中に RoomInstance に参加していれば、単一拠点録画メタデータファイルは保存されます

  • 合成録画ファイル

    • 保存パス: /{room_id}/{RoomInstanceの開始時刻}/{Sequence}/compositions/{RoomInstance の録画開始時刻}-{RoomInstance の録画終了時刻}.mp4
    • 録画期間中、すべての参加拠点の単一拠点録画ファイルが常に映像/音声ともに HardMute だった場合は合成録画ファイルも保存されません

  • 合成録画メタデータファイル

    • 保存パス: /{room_id}/{RoomInstanceの開始時刻}/{Sequence}/compositions/{RoomInstance の録画開始時刻}-{RoomInstance の録画終了時刻}.json
    • 本ページの CompositionRecordingMetadata のスキーマを持つ JSON 形式
    • 録画期間中、常に映像/音声ともに HardMute だった Connection については CompositionRecordingMetadata の connection 属性の配列に含まれません

保存ファイル仕様の詳細説明

  • 保存パスに含まれる時刻は UTC で yyyyMMddhhmmss の形式になります

  • Sequence は、1 つの RoomInstance の生存期間中に行った録画の通し番号です

    • 1 から始まり、録画を開始する度にインクリメントされます
    • 現状は AccessToken の recording_on_start 設定による RoomInstance 全体の録画のみ可能ですが、今後 REST API による任意のタイミングでの録画の開始/停止に対応予定です

  • ConnectionInstance の存在開始時刻/存在終了時刻 とは、ConnectionInstance が RoomInstanceに入室/退出した期間と RoomInstance の録画期間の重なる期間です

単一拠点録画ファイルの詳細な仕様

途中で解像度が変わる映像の仕様

配信中にカメラを縦向きから横向きに回転させた場合など、映像の解像度が途中で切り替わるケースがあります。 このときの録画データは次の仕様となります。

  • 1 フレーム目の解像度から以下のルールにより、映像全体の解像度が定まり固定されます
    • 幅が高さ以上の場合
      • そのままの解像度が採用されます
      • 解像度が 1280x720 だった場合、解像度は 1280x720 となります
    • 幅が高さ未満の場合
      • 1 フレーム目の高さに合わせて 16:9 の解像度となります
      • 解像度が 720x1280 だった場合、解像度は 2276x1280 となります
  • 2 フレーム以降で解像度の変化があったとき、固定された解像度にあわせて映像が拡大または縮小します
    • 映像のアスペクト比を維持するために必要な場合、黒色の余白が追加されます

解像度の高さか幅が奇数になる映像の仕様

1フレーム目の解像度の高さか幅が奇数の場合、録画ファイルでは偶数に調整されます。
たとえば、解像度が 321x243 の場合、出力解像度は 322x244 となります。
また、「途中で解像度が変わる映像について」に記載の通りに解像度を算出後、解像度の高さか幅が奇数であった場合は調整が実施されます。
たとえば、解像度が 720x1283 だった場合、算出後の解像度は 2281x1283 となりますが、出力解像度は 2282x1284 となります。 映像のアスペクト比を維持するために必要な場合、黒色の余白が追加されます。

共通仕様

  • API の認証/認可に失敗した場合、ステータスコード 401 のレスポンスが返却されます

録画ストレージ設定 API

AWS S3 録画ストレージ設定登録

  • レスポンスボディからsecret_access_keyフィールドは取り除かれます
  • すでに録画ストレージ設定が登録済みだった場合、既存の設定は上書きされます
Authorizations:
ClientBasic
path Parameters
client_id
required
string
  • Client ID
Request Body schema: application/json

AWS S3 の録画ストレージ設定を更新するための AwsS3RecordingStorageConfig オブジェクト

s3_url
required
string <= 255 characters
  • 録画ファイルを保存するための S3 バケットの仮想ホスティング URL
  • バケットの仮想ホスティングについては以下のドキュメントを参照のこと
  • URL のスタイルとして、仮想ホスティング形式を利用すること
    • https://<bucket-name>.s3.<region>.amazonaws.com/<key-name>
access_key_id
required
string
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "DenyAll",
            "Effect": "Deny",
            "NotAction": "*",
            "Resource": "*"
        },
        {
            "Sid": "AllowS3Upload",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:AbortMultipartUpload"
            ],
            "Resource": [
                "arn:aws:s3:::<bucket-name>/<key-name>*"
            ]
        }
    ]
}
secret_access_key
required
string
  • S3 バケットにアクセスするための IAM ユーザのシークレットアクセスキー
  • アクセスキーと共に生成されたシークレット

Responses

Request samples

Content type
application/json
{
  • "s3_url": "string",
  • "access_key_id": "string",
  • "secret_access_key": "string"
}

Response samples

Content type
application/json
{
  • "s3_url": "string",
  • "access_key_id": "string",
  • "secret_access_key": "string"
}

AWS S3 録画ストレージ設定取得

レスポンスボディから secret_access_key フィールドは取り除かれます

Authorizations:
ClientBasic
path Parameters
client_id
required
string
  • Client ID

Responses

Response samples

Content type
application/json
{
  • "s3_url": "string",
  • "access_key_id": "string",
  • "secret_access_key": "string"
}

AWS S3 録画ストレージ設定リセット

Authorizations:
ClientBasic
path Parameters
client_id
required
string
  • Client ID

Responses

Room 録画 API

Room の録画開始

  • sfu または sfu_large が指定された Room の録画を開始します
    • p2p または p2p_turn 指定の Room は録画に非対応です
  • 録画中に呼び出した場合は、何もせず 200 を返します
  • 現在の録画状態は、Room API のGETで取得できます
  • 録画の停止直後に開始を実行すると、waiting_recording_complete エラーが発生します
Authorizations:
ClientBasic
path Parameters
client_id
required
string
  • Client ID
room_id
required
string
  • Room ID
query Parameters
env
string (LSEnv)
Enum: "prod" "dev"

操作対象の環境。複数指定不可

Responses

Response samples

Content type
application/json
{
  • "in_recording": true
}

Room の録画停止

  • sfu または sfu_large が指定された Room の録画を停止します
    • p2p または p2p_turn 指定の Room は録画に非対応です
  • 録画の停止中に呼び出した場合は、何もせず 200 を返します
  • 現在の録画状態は、Room API の GET で取得できます
Authorizations:
ClientBasic
path Parameters
client_id
required
string
  • Client ID
room_id
required
string
  • Room ID
query Parameters
env
string (LSEnv)
Enum: "prod" "dev"

操作対象の環境。複数指定不可

Responses

Response samples

Content type
application/json
{
  • "in_recording": true
}

AwsS3RecordingStorageConfig

s3_url
required
string <= 255 characters
  • 録画ファイルを保存するための S3 バケットの仮想ホスティング URL
  • バケットの仮想ホスティングについては以下のドキュメントを参照のこと
  • URL のスタイルとして、仮想ホスティング形式を利用すること
    • https://<bucket-name>.s3.<region>.amazonaws.com/<key-name>
access_key_id
required
string
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "DenyAll",
            "Effect": "Deny",
            "NotAction": "*",
            "Resource": "*"
        },
        {
            "Sid": "AllowS3Upload",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:AbortMultipartUpload"
            ],
            "Resource": [
                "arn:aws:s3:::<bucket-name>/<key-name>*"
            ]
        }
    ]
}
secret_access_key
required
string
  • S3 バケットにアクセスするための IAM ユーザのシークレットアクセスキー
  • アクセスキーと共に生成されたシークレット
{
  • "s3_url": "string",
  • "access_key_id": "string",
  • "secret_access_key": "string"
}

ConnectionRecordingMetadata

One of
room_id
required
string <IDString>

Room の ID

room_instance_id
required
string <UUIDv4>

ある Room の生死単位で割り振られる ID

recording_id
required
string

Recording の ID

connection_id
required
string <IDString>

Connection の ID

connection_instance_id
required
string <UUIDv4>

ある Connection の生死単位で割り振られる ID

exists_since
required
string <date-time>

ConnectionInstance の存在開始時刻。ConnectionInstance が RoomInstance に入室した時刻と RoomInstance の録画開始時刻の内遅い時刻 (ISO8601)

exists_until
required
string <date-time>

ConnectionInstance の存在終了時刻。ConnectionInstance が RoomInstance から退出した時刻と RoomInstance の録画終了時刻の内早い時刻 (ISO8601)

started_at
required
string <date-time>

ConnectionInstance の録画開始時刻。ただし、録画開始時に ConnectionInstance の映像音声の双方が hardmute であった場合、最初にどちらかが unmute になった時刻 (ISO8601)

ended_at
required
string <date-time>

ConnectionInstance の録画終了時刻。ただし、録画終了時に ConnectionInstance の映像音声の双方が hardmute であった場合、最後に双方が hardmute になった時刻 (ISO8601)

format
string
Value: "mp4"

メディアファイルのフォーマット

  • 単一拠点録画ファイルを保存せずに生の録画ファイルのみを保存する場合は空
object (ConnectionRecordingVideoMetadata)

録画の映像データに関するメタデータ

  • 録画ファイルが映像データを持たない場合は空
object (RecordingAudioMetadata)

録画の音声データに関するメタデータ

  • 録画ファイルが音声データを持たない場合は空
object (RawConnectionRecordingMetadata)

生の録画に関するメタデータ

  • 生の録画ファイルを保存せずに単一拠点録画ファイルのみを保存する場合は空
Example
{
  • "room_id": "string",
  • "room_instance_id": "string",
  • "recording_id": "string",
  • "connection_id": "string",
  • "connection_instance_id": "string",
  • "exists_since": "2019-08-24T14:15:22Z",
  • "exists_until": "2019-08-24T14:15:22Z",
  • "started_at": "2019-08-24T14:15:22Z",
  • "ended_at": "2019-08-24T14:15:22Z",
  • "format": "mp4",
  • "video": {
    },
  • "audio": {
    },
  • "raw_recording": {
    }
}

CompositionRecordingMetadata

room_id
required
string <IDString>

Room の ID

recording_id
required
string

Recording の ID

required
Array of objects (ConnectionMetadata)

合成録画に含まれる ConnectionMetadata の配列

started_at
required
string <date-time>

RoomInstance の録画開始時刻。ただし、録画開始時に全 ConnectionInstance の映像音声の双方が hardmute であった場合、最初にある ConnectionInstance のどちらかが unmute になった時刻 (ISO8601)

ended_at
required
string <date-time>

RoomInstance の録画終了時刻。ただし、録画終了時に全 ConnectionInstance の映像音声の双方が hardmute であった場合、最後にある ConnectionInstance の双方が hardmute になった時刻 (ISO8601)

format
required
string
Value: "mp4"

メディアファイルのフォーマット

object (CompositionRecordingVideoMetadata)

録画の映像データに関するメタデータ

object (RecordingAudioMetadata)

録画の音声データに関するメタデータ

  • 録画ファイルが音声データを持たない場合は空
{
  • "room_id": "string",
  • "recording_id": "string",
  • "connections": [
    ],
  • "started_at": "2019-08-24T14:15:22Z",
  • "ended_at": "2019-08-24T14:15:22Z",
  • "format": "mp4",
  • "video": {
    },
  • "audio": {
    }
}

IDString

string (IDString) ^[a-zA-Z0-9.%+^_"`{|}~<>\\\\-]{1,255}$
  • 1 文字以上 255 文字以下
  • ASCII
  • 以下の文字のみ許可
    • 英数字
    • 次の記号: .%+^_"`{|}~<>\-
"string"