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 クラウド既知の問題を確認してください。

クラウド録画機能とは

クラウド録画機能は、配信した映像を Live Streaming サービスのクラウド上で記録し、お客様のご用意したクラウドストレージに保存できる機能です。
大きく2つの種類があり、接続時に RoomSpec や ConnectionSpec で挙動の変更が可能です。

  • 単一拠点録画機能
    • あるRoomInstanceにおいて、Connection 毎の映像と音声を録画して、単一拠点録画ファイルと 単一拠点録画メタデータファイルを生成します
  • 録画合成機能
    • あるRoomInstanceでの会議に参加していた各 Connection の単一拠点録画ファイルの内容をマージして、 1 つの動画ファイルに合成する機能です
    • 合成録画ファイルと合成録画メタデータファイルを生成します
      • これにより、実際の会議の様子を 1 つの動画ファイルだけで確認することができます

クラウド録画機能の詳細については、別途クラウド録画 開発ガイドも参照してください。

クラウド録画機能の利用方法

  • 事前準備
  • 録画の開始
    • AccessToken にある recording_on_start 設定を使用することで、RoomInstance の生成時点から自動で録画を開始できます
    • Room 管理 API の Room の録画開始 API を使用して録画を開始します
  • 録画の停止
    • Room 管理 API の Room の録画停止 API を使用して録画を停止します
    • RoomInstance が終了した時に録画中だった場合、自動的に録画も終了します
    • 録画の停止後、保存先ストレージに実際に録画ファイルが生成されるまでには多少時間がかかります

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

録画ストレージ設定 API を利用して録画ストレージを設定すると、保存ファイル仕様に示す保存パスに録画ファイルおよびメタデータファイルが保存されます。
録画ファイルには以下の種類があり、どの録画ファイルを保存するかを AccessToken で設定できます。

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

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

保存ファイル仕様

  • 単一拠点録画ファイル
    • 保存パスは以下のルールに従います
      • /{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 が以下の条件を満たす場合、単一拠点録画メタデータファイルは保存されません
      • AccessToken の JWTClaims で connection_spec.recording.store の値を false にして、かつ connection_spec.recording.store_raw の値を false か未設定にした
  • 合成録画ファイル
    • 保存パスは以下のルールに従います
      • /{room_id}/{RoomInstanceの開始時刻}/{Sequence}/compositions/{RoomInstance の録画開始時刻}-{RoomInstance の録画終了時刻}.mp4
    • 録画期間中、すべての参加拠点の単一拠点録画ファイルが常に映像/音声ともに HardMute だった場合は合成録画ファイルも保存されません
  • 合成録画メタデータファイル
    • 保存パスは以下のルールに従います
      • /{room_id}/{RoomInstanceの開始時刻}/{Sequence}/compositions/{RoomInstance の録画開始時刻}-{RoomInstance の録画終了時刻}.json
    • 本ページの CompositionRecordingMetadata のスキーマを持つ JSON 形式のファイルです
    • 録画期間中、常に映像/音声ともに HardMute だった Connection については CompositionRecordingMetadata の connection 属性の配列に含まれません
  • Connection 履歴ファイル
    • 保存パスは以下のルールに従います
      • /{room_id}/{RoomInstanceの開始時刻}/{Sequence}/{connection_id}-{ConnectionInstanceの存在開始時刻}-{ConnectionInstanceの存在終了時刻}-connection-history.jsonl
    • 各行が本ページの ConnectionHistory のスキーマを持つ JSONL 形式のファイルです
      • JSONL 形式は、改行 \n を区切り文字とし、複数のJSON形式を一つのファイルにまとめた形式です
    • 拠点の Connection が以下の条件を満たす場合、Connection 履歴ファイルは保存されません
      • AccessToken の JWTClaims で connection_spec.recording.store の値を false にして、かつ connection_spec.recording.store_raw の値を false か未設定にした
  • Video Track 履歴ファイル
    • 保存パスは以下のルールに従います
      • /{room_id}/{RoomInstanceの開始時刻}/{Sequence}/{connection_id}-{ConnectionInstanceの存在開始時刻}-{ConnectionInstanceの存在終了時刻}-video-track-history.jsonl
    • 各行が本ページの TrackHistory のスキーマを持つ JSONL 形式のファイルです
      • JSONL 形式は、改行 \n を区切り文字とし、複数のJSON形式を一つのファイルにまとめた形式です
    • 拠点の Connection が以下の条件を満たす場合、Video Track 履歴ファイルは保存されません
      • connect 時に sending.enabled を false にした場合
      • AccessToken の JWTClaims で connection_spec.recording.store` の値を false にして、かつ connection_spec.recording.store_raw の値を false か未設定にした
  • Audio Track 履歴ファイル
    • 保存パスは以下のルールに従います
      • /{room_id}/{RoomInstanceの開始時刻}/{Sequence}/{connection_id}-{ConnectionInstanceの存在開始時刻}-{ConnectionInstanceの存在終了時刻}-audio-track-history.jsonl
    • 各行が本ページの TrackHistory のスキーマを持つ JSONL 形式のファイルです
      • JSONL 形式は、改行 \n を区切り文字とし、複数のJSON形式を一つのファイルにまとめた形式です
    • 拠点の Connection が以下の条件を満たす場合、Audio Track 履歴ファイルは保存されません
      • connect 時に sending.enabled を false にした場合
      • AccessToken の JWTClaims で connection_spec.recording.store の値を false にして、かつ connection_spec.recording.store_raw の値を false か未設定にした

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

  • 記録される時刻について

    • 存在期間 (存在開始時刻、存在終了時刻)
      • ConnectionInstance が RoomInstance に入室/退出した期間と RoomInstance の録画期間の重なる期間です
      • 保存パスに含まれる時刻は UTC で yyyyMMddhhmmss の形式になります
    • 録画期間 (録画開始時刻、録画終了時刻)
      • 次のいずれかの方法で録画を開始し、停止するまでの期間です
        • AccessToken の recording_on_start 設定
        • Room 録画 API
      • 保存パスに含まれる時刻は UTC で yyyyMMddhhmmss の形式になります

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

    • 1 から始まり、 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

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": {
    }
}

ConnectionHistory

timestamp
required
string

イベントの発生時刻 (ISO8601)

meta
required
object (Meta)

Connect および Track の各種アプリで定義したメタデータ。

{
  • "timestamp": "string",
  • "meta": { }
}

TrackHistory

timestamp
required
string

イベントの発生時刻 (ISO8601)

meta
object (Meta)

Connect および Track の各種アプリで定義したメタデータ。

object (TrackSdkMeta)

RICOH Live Streaming Client SDK から Track に送信されるメタデータ。

{
  • "timestamp": "string",
  • "meta": { },
  • "sdk_meta": {
    }
}

IDString

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