Imported from shiguredo/sora-rust-sdk (skills/sora-rust-sdk/SKILL.md). Install upstream with npx skills add shiguredo/sora-rust-sdk --skill sora-rust-sdk. Copyright stays with the author.

sora_sdk

WebRTC SFU Sora のクライアントを Rust で実装するための SDK。シグナリング、メディア送受信、DataChannel メッセージング、JSON-RPC、コーデックバックエンド統合を提供する。

特徴

• Sora シグナリング: WebSocket / DataChannel シグナリング両対応。複数シグナリング URL のレース接続、リダイレクト対応。
• 複数ロール: sendonly / recvonly / sendrecv をサポート。
• メディア機能: マルチストリーム、サイマルキャスト、スポットライト、転送フィルター、シグナリング通知。
• コーデック: VP8 / VP9 / AV1 / H.264 / H.265。OpenH264 / Apple VideoToolbox / AMD AMF / NVIDIA Video Codec / Intel VPL / V4L2-M2M のバックエンド統合。
• MP4 無変換送信: Mp4PassthroughVideoCodecCapability で MP4 ファイルの映像トラックをデコード / エンコードを挟まずに Sora へ送信し、音声トラックは無視する。capability は Mp4SampleReader::passthrough_capability() から生成する。
• DataChannel メッセージング: # プレフィックスのユーザー定義 DataChannel でバイナリ送受信。
• JSON-RPC 2.0 over DataChannel: SDK が id 採番とエンベロープを担当。
• TURN-TLS: 独自 CA 証明書 (DER) による検証。
• HTTP プロキシ (CONNECT): http:// のみ対応。Basic 認証可。
• 複数クライアント同時実行: 1 つの SoraConnectionContext を Arc で共有して N 接続。

バージョン情報

• crate 名: sora_sdk
• バージョン: 2026.1.0
• Rust Edition: 2024
• 最小 Rust バージョン: 1.93
• ライセンス: Apache-2.0
• 対応 Sora: 2025.2.0 以降
• 対応プラットフォーム: Ubuntu 22.04 / 24.04 / 26.04 (x86_64, arm64), macOS 15 / 26 (arm64), Windows 11 / Server 2025 (x86_64), Raspberry Pi (Linux, arm64)

shiguredo_webrtc クレートが提供する AudioTrack / VideoTrack / VideoTrackSource / RtpTransceiver / RtpReceiver / IceServer 等を直接受け取る公開 API があるため、利用側の Cargo.toml に shiguredo_webrtc を追加する必要がある。

Cargo features

機能フラグは加算式。複数バックエンドを同時に有効化可能。フラグを有効にしても GPU / ドライバが無ければ各 *::new() がランタイムでエラーを返す。vpl は Linux 専用で、他の OS ではフラグを有効にしてもモジュールごとコンパイルされない。

コア API

接続コンテキスト

AudioTrackSource はコンテキストから生成する。VideoTrackSource は shiguredo_webrtc 側 (FakeVideoCapturer / AdaptedVideoTrackSource) または本クレートの Mp4VideoCapturer / LibcameraVideoCapturer から生成する。

接続ビルダー

SoraConnection::builder(context, signaling_urls, channel_id, role, event_handler) -> SoraConnectionBuilder で開始。signaling_urls は Vec<String>、channel_id は String、role は Role、event_handler は SoraConnectionEventHandler トレイトを実装した任意の型のインスタンス（impl SoraConnectionEventHandler + 'static）。WebSocket TLS の設定（insecure / ca_cert / client_cert）は Builder の各メソッド経由で行う。

イベントハンドラ (SoraConnectionEventHandler トレイト)

イベント通知は Builder のチェーンメソッドではなく、SoraConnectionEventHandler トレイトを実装したユーザー定義型で受け取る。実装型のインスタンスを SoraConnection::builder(...) の第 5 引数に渡す。

• トレイトは Send（Sync は不要。各コールバックは単一タスクから直列に呼ばれるため）
• 全メソッドにデフォルト空実装が用意されているため、必要なメソッドだけオーバーライドすればよい
• コールバックは内部タスクから直列に呼ばれるためブロックさせないこと。重い処理はチャンネルで自分のタスクへ転送する
• ユーザー定義 struct に状態を持たせ &mut self で共有できる

送信トラック

接続オプション

タイムアウト

TLS / TURN-TLS / プロキシ

WebSocket TLS は PEM、TURN-TLS は DER である点に注意。

接続ハンドル

run() 終了後はいずれも Error::CommandSendFailed などのエラーを返す。

接続実行

SoraConnection::run(self) -> Result<()> は async fn で、接続が終了するまでブロックする。通常は tokio::spawn で別タスクに渡し、SoraConnectionHandle で外部から disconnect() を呼び出す。

接続設定の型

Role

pub enum Role { SendOnly, RecvOnly, SendRecv }

Audio / Video

コンストラクタ:

H.264 / H.265 の b_frame: true は Sora 側の sora.conf で対応する設定が必要。

DataChannel / 転送フィルター / 通知

コーデック選択

標準のコーデックバックエンド

新しい capability を加えるたびに、対応する VideoCodecPreference を merge して preference 側にも追加すること。SoraConnectionContextConfig::default() は Internal と (macOS/iOS 上では) InternalApple を自動登録する。

MP4 / libcamera

MP4 入力は映像トラックだけを送信し、音声トラックは無視する。 MP4 パススルーの入力制約 (いずれも Mp4SampleReader::new がエラーを返す):

• 対応映像コーデックは H.264 / H.265 / VP8 / VP9 / AV1
• 非ゼロの composition time offset (B フレーム) を含む MP4 は拒否 (Mp4Error::UnsupportedCompositionTimeOffset)
• 途中でサンプルエントリー (コーデック・解像度など) が切り替わる MP4 は拒否 (Mp4Error::InconsistentSampleDescription)
• 不正な H.264 トラックを含む MP4 は拒否 (Mp4Error::InvalidH264Track)
• 不正な AV1 トラックを含む MP4 は拒否 (Mp4Error::InvalidAv1Track)

同じ Mp4VideoCapturer の video_source() を複数の PeerConnection の映像 encoder に渡してはならない (debug ビルドでは abort する)。PeerConnection ごとに capturer を分け、各 capturer の video_source() を その接続の encoder に渡すこと。capturer を分けても、1 つの Mp4SampleReader は clone() して共有できる。

use sora_sdk::{Mp4SampleReader, Mp4VideoCapturer};

let reader = Mp4SampleReader::new("input.mp4")?;

// capability は reader から生成して context config に登録する
let capability = reader.passthrough_capability();
// (VideoCodecPreference への merge と video_codec_capabilities への push は
//  「コーデックバックエンドを明示的に組み立てる」と同じ手順)

// 複数の PeerConnection に送る場合は capturer を分け、各 capturer の
// video_source() をその接続の encoder に渡す。reader は clone して共有する。
let capturer1 = Mp4VideoCapturer::new(reader.clone())?;
let video_source1 = capturer1.video_source();
let video_track1 = context.create_video_track(&video_source1)?;

let capturer2 = Mp4VideoCapturer::new(reader.clone())?;
let video_source2 = capturer2.video_source();
let video_track2 = context.create_video_track(&video_source2)?;

LibcameraVideoCapturer::builder() は camera_index() / width() / height() / native_frame_output() / control() / controls() / build() を提供する。生成したキャプチャラーは start() / stop() / video_source() で制御する。

LibcameraNativeFrameBuffer は fd() / size() / stride() / raw_width() / raw_height() / scaled_width() / scaled_height() / is_i420() / is_nv12() を提供する。

DataChannel メッセージング / JSON-RPC 2.0

JSON-RPC 2.0 は SDK 側で { "jsonrpc": "2.0", "method": ..., "params": ..., "id": ... } を組み立てる。利用側は内側の params を Option<JsonString> で渡すだけ (パラメータ不要なら None)。

notification: true の場合は SDK が id を発番せず、Ok(None) を即返す。 応答は JSON-RPC 2.0 の Response Object として検証する。 応答待機中の Request ID と対応付けられる不正応答は Error::RpcProtocolViolation { id: Some(...) } を返す。 対応付けられない不正応答や未知の id を持つ応答はメッセージ単位で破棄し、接続を継続する。

コード例

sendrecv で接続する

use shiguredo_webrtc::RtpTransceiver;
use sora_sdk::{Role, SoraConnection, SoraConnectionContext, SoraConnectionEventHandler};

struct MyEventHandler;

impl SoraConnectionEventHandler for MyEventHandler {
    fn on_notify(&mut self, text: &str) {
        println!("notify: {text}");
    }
    fn on_track(&mut self, transceiver: RtpTransceiver) {
        println!("track: {:?}", transceiver.receiver().track().id());
    }
}

let context = SoraConnectionContext::new()?;

// AudioTrack はコンテキストから生成する
let audio_source = context.create_audio_source()?;
let audio_track = context.create_audio_track(&audio_source)?;

// VideoTrackSource は shiguredo_webrtc 側で用意する
// (FakeVideoCapturer / AdaptedVideoTrackSource / Mp4VideoCapturer 等)

let (connection, handle) = SoraConnection::builder(
    context,
    vec!["wss://sora.example.com/signaling".to_string()],
    "channel-id".to_string(),
    Role::SendRecv,
    MyEventHandler,
)
.sender_audio_track(audio_track)
.build()?;

tokio::spawn(async move {
    let _ = connection.run().await;
});

// ... 別の場所で disconnect
handle.disconnect().await?;

コーデックバックエンドを明示的に組み立てる

use sora_sdk::{
    InternalVideoCodecCapability, SoraConnectionContext,
    SoraConnectionContextConfig, VideoCodecCapability, VideoCodecPreference,
};

let mut config = SoraConnectionContextConfig {
    video_codec_preference: VideoCodecPreference::default(),
    video_codec_capabilities: Vec::new(),
    ..Default::default()
};

let cap: Box<dyn VideoCodecCapability> = Box::new(InternalVideoCodecCapability::new());
config
    .video_codec_preference
    .merge(&VideoCodecPreference::new_from_capability(cap.as_ref()));
config.video_codec_capabilities.push(cap);

// nvcodec 等を追加する場合も同じ手順を繰り返す。
let context = SoraConnectionContext::new_with_config(config)?;

new_with_config は内部で validate_video_codec_preference を呼び出すため、preference と capabilities の整合が崩れていると Error::InvalidVideoCodecPreference を返す。

Audio / Video 設定

use sora_sdk::{Audio, AudioOpusParams, Video, VideoH264Params};

let audio = Audio::new_opus(
    Some(64),
    Some(AudioOpusParams { stereo: Some(true), ..Default::default() }),
);
let video = Video::new_h264(
    Some(2_500),
    Some(VideoH264Params {
        profile_level_id: Some("42e01f".to_string()),
        b_frame: None,
    }),
);

builder = builder.audio(audio).video(video);

DataChannel メッセージング

use sora_sdk::SoraConnectionEventHandler;

struct MyEventHandler;

impl SoraConnectionEventHandler for MyEventHandler {
    fn on_message(&mut self, label: &str, data: &[u8]) {
        println!("recv {label}: {} bytes", data.len());
    }
}

// SoraConnection::builder(context, urls, channel_id, role, MyEventHandler)
let (_conn, handle) = SoraConnection::builder(/* ... 5 引数、末尾に MyEventHandler ... */)
    .build()?;

handle.send_message("#chat", b"hello").await?;

JSON-RPC 2.0 over DataChannel

use sora_sdk::{JsonString, RpcRequestOptions, RpcResponse};

let params: JsonString = r#"{"key":"value"}"#.parse()?;

// 通常のリクエスト (既定タイムアウト 5 秒)
match handle
    .send_rpc_request("method_name", Some(params), RpcRequestOptions::default())
    .await?
{
    Some(RpcResponse::Success { result }) => { /* result: JsonString */ }
    Some(RpcResponse::Error { code, message, data }) => { /* ... */ }
    None => { /* notification (通常はここに来ない) */ }
}

// notification (レスポンスを待たない)
let _ = handle
    .send_rpc_request(
        "event",
        None,
        RpcRequestOptions { notification: true, ..Default::default() },
    )
    .await?;
// 戻り値は Ok(None)

// タイムアウト変更
let _ = handle
    .send_rpc_request(
        "slow_method",
        None,
        RpcRequestOptions {
            timeout: std::time::Duration::from_secs(10),
            ..Default::default()
        },
    )
    .await?;

統計情報の取得と切断

let h = handle.clone();
tokio::spawn(async move {
    tokio::time::sleep(std::time::Duration::from_secs(60)).await;
    if let Ok(stats) = h.get_stats().await {
        println!("stats: {stats}");
    }
    let _ = h.disconnect().await;
});

複数クライアントを 1 コンテキストで実行する

use sora_sdk::SoraConnectionEventHandler;

struct MyEventHandler;
impl SoraConnectionEventHandler for MyEventHandler {}

let context = SoraConnectionContext::new()?;
let urls = vec!["wss://sora.example.com/signaling".to_string()];

for i in 0..5 {
    let ctx = context.clone();
    let urls = urls.clone();
    tokio::spawn(async move {
        let (conn, _h) = SoraConnection::builder(
            ctx,
            urls,
            format!("channel-{i}"),
            sora_sdk::Role::RecvOnly,
            MyEventHandler,
        )
        .build()?;
        conn.run().await
    });
}

TLS / TURN-TLS / プロキシ

use sora_sdk::ProxyInfo;

builder = builder
    .client_cert(client_pem, key_pem)        // PEM
    .ca_cert(ca_pem)                          // PEM
    .turn_tls_ca_cert(turn_ca_der)            // DER
    .proxy(ProxyInfo {
        url: "http://proxy.example.com:3128".to_string(),
        username: Some("user".to_string()),
        password: Some("pass".to_string()),
        user_agent: None,
    });

複数シグナリング URL のレース

use sora_sdk::SoraConnectionEventHandler;

struct MyEventHandler;
impl SoraConnectionEventHandler for MyEventHandler {}

let urls = vec![
    "wss://sora1.example.com/signaling".to_string(),
    "wss://sora2.example.com/signaling".to_string(),
];

let (conn, handle) = SoraConnection::builder(
    context, urls, "channel-id".into(), Role::SendRecv, MyEventHandler,
).build()?;

tokio::spawn(async move { let _ = conn.run().await; });

// 接続成立後、勝者の URL を確認できる
if let Some(url) = handle.selected_signaling_url().await? {
    println!("connected via {url}");
}
// リダイレクト後の URL は connected_signaling_url() で取得する

エラー型

Error / Result = std::result::Result<T, Error>。anyhow / thiserror は使わない。主な分類:

エラーメッセージ (Display) は日本語。ログメッセージは英語、というプロジェクト方針と分けて扱うこと。

既知の制限事項・注意点

• コンテキスト生成は重い: SoraConnectionContext::new() は内部スレッドを 3 本起動するため、プロセスあたり 1 つに集約し Arc で共有する。
• connection.run() はブロッキング: 別タスクで実行し、外部制御は SoraConnectionHandle (Clone) を介する。
• コールバックを長時間ブロックしない: 内部タスクから呼ばれるため、重い処理は自分の async タスクへ転送する。
• HTTP プロキシは http:// のみ: https:// プロキシ、パス、クエリ、userinfo はサポート外。
• TLS 設定の単位の違い: WebSocket TLS の証明書は PEM、TURN-TLS の CA 証明書は DER。
• ハードウェアコーデックは feature + runtime 両方の条件: feature 有効化だけでなく GPU / ドライバが揃わないと *Capability::new() がエラーを返す。
• VPL は Linux 専用: vpl feature は Linux 以外の OS ではコンパイルされず、VplVideoCodecCapability と Error::Vpl 系のバリアントも Linux 限定。
• VideoTrackSource は本クレートでは作らない: shiguredo_webrtc 側の capturer / source、もしくは本クレートの Mp4VideoCapturer / LibcameraVideoCapturer から生成する。
• MP4 パススルーの入力制約: B フレーム (非ゼロ composition time offset) を含む MP4、途中でサンプルエントリー (コーデック・解像度など) が切り替わる MP4、不正な H.264 / AV1 トラックを含む MP4 は Mp4SampleReader::new() が拒否する。
• send_message のラベル制約: SDK 内部用ラベル（signaling、stats、push、notify、rpc）および # プレフィックスのないラベル、Offer 応答の data_channels に含まれていないラベルを渡すと Error::InvalidDataChannelLabel を返す。on_message は # プレフィックスのユーザー定義 DataChannel 専用。
• JSON-RPC の id は SDK が管理する: 利用側が id を組み立てる必要はない。params の中身だけ渡す。
• DataChannel の展開後サイズ上限: compress: true の DataChannel メッセージは zlib 展開後 16 MiB まで。 上限超過や不正な zlib ストリームはメッセージ単位で破棄し、接続を継続する。
• DataChannel シグナリングの切替条件: WebSocket で switched を受信し、Offer の data_channels に含まれる全 DataChannel が Open になってから切り替える。
• DataChannel シグナリング中の Close: signaling ラベルで Sora から {"type": "close"} を受信すると接続を終了する。 他のラベルで受信した Close は接続終了として扱わない。
• MP4 入力は映像専用: 音声トラックは無視する。 B フレームなどの非ゼロ composition time offset を含む映像は受理しない。
• ロギングは shiguredo_webrtc の rtc_log_* マクロ: SDK 内のログは libwebrtc 側 (rtc_log_verbose! / rtc_log_info! / rtc_log_warning! / rtc_log_error!) に流れる。log / tracing クレートには依存していない。
• デフォルトの ADM は Dummy: マイク入力が必要な場合は AdmConfig::UseBuiltIn か UseExternal を明示する。