コネクション API¶

RequestKeyFrame¶

バージョン 2024.2.0 で追加。

x-sora-target:: Sora_20241218.RequestKeyFrame

指定したチャネルで配信している接続に対してキーフレームを要求します。

この API は role が sendrecv または sendonly の接続にのみ有効です。

キーフレーム要求を送ってからキーフレームが送られてくるまでは、 1 秒間隔で最大 5 回までリクエストを送信します。

channel_id や connection_id が存在しない場合はエラーとなります。

キー	型
channel_id	string
connection_id	string
rid (オプション)	string (r0 \| r1 \| r2)

rid は Sora 2026.1.3 以降で指定できます。サイマルキャスト利用時に、キーフレームを要求する RID を指定します。

rid を省略した場合は、視聴者が受信している RID を対象にします。ただし、クラスターリレー、録画、RTP 転送のいずれかがある場合は、配信者が送信しているすべての RID を対象にします。

要求は、対象の RID を視聴する接続、クラスターリレー、録画、RTP 転送のいずれかがある場合に送信します。配信者が送信していない RID には要求しません。要求を送信しない場合も API は成功を返します。

サイマルキャストを利用していない配信者に rid を指定した場合は、省略した場合と同じ動作です。

rid を省略した場合

$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20241218.RequestKeyFrame" \
    --json '{"channel_id":"sora","connection_id":"KDBN2YD1A919V5BA2JX6TG2RP8"}' \
    | jq .
{
    "channel_id": "sora",
    "connection_id": "KDBN2YD1A919V5BA2JX6TG2RP8"
}

rid を指定した場合

$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20241218.RequestKeyFrame" \
    --json '{"channel_id":"sora","connection_id":"KDBN2YD1A919V5BA2JX6TG2RP8","rid":"r1"}' \
    | jq .
{
    "channel_id": "sora",
    "connection_id": "KDBN2YD1A919V5BA2JX6TG2RP8",
    "rid": "r1"
}