<!-- mikan:page doc="index" -->

# Sora Unity SDK ドキュメント

このドキュメントは Sora Unity SDK バージョン 2026.1.0 に対応しています。

Sora 自体の製品お問い合わせは sora at shiguredo dot jp までお願い致します。
(このメールアドレスへの特定電子メールの送信を拒否いたします)

## LLM 向け

LLM が読み込みやすい形式でドキュメントを提供しています。

- 目次は [llms.txt](/llms.txt) にあります
- 全文は [llms-full.txt](/llms-full.txt) にあります

## 問い合わせについて

Sora Unity SDK の質問などについては Discord の `#sora-sdk-faq` チャンネルをご利用ください。
ただし、 Sora のライセンス契約の有無に関わらず、応答時間と問題の解決を保証しませんのでご了承ください。


Sora Unity SDK に対する有償のサポートについては提供しておりません。

- [リリースノート](release.html)
- [Sora Unity SDK 概要](overview.html)
- [FAQ](faq.html)
- [既知の問題](known_bugs.html)

- [2025.2.x から 2025.3.x への移行](2025_2_to_2025_3.html)

- [音声の送信と受信](functions_audio.html)
- [音声データ取得機能](functions_audio_sink.html)
- [映像の送信と受信](functions_video.html)
- [サイマルキャスト機能](functions_simulcast.html)
- [統計情報](functions_getstats.html)
- [ハンズフリー](functions_iaudiooutputhelper.html)
- [リアルタイムメッセージング機能](functions_messaging.html)
- [転送フィルター](functions_forwarding_filters.html)
- [証明書の指定](functions_ca_cert.html)
- [DegradationPreference](functions_degradation_preference.html)
- [エンコーダー / デコーダーの指定](functions_hardware_acceleration.html)
- [RPC 機能](functions_rpc.html)

- [サンプル集を使った接続確認](samples_tutorial.html)
- [接続の設定](samples_connect_settings.html)
- [映像と音声の設定](samples_video_audio_settings.html)
- [メタデータ](samples_metadata.html)
- [サイマルキャスト機能](samples_simulcast.html)
- [スポットライト機能](samples_spotlight.html)
- [リアルタイムメッセージング機能](samples_data_channels.html)
- [転送フィルター機能](samples_forwarding_filters.html)

- [H.264 を利用する](use_h264.html)
- [解像度の変更方法](set_video_size.html)

- [プロジェクトにインストールする](use.html)
- [macOS で使ってみる](use_macos.html)
- [Android で使ってみる](use_android.html)
- [iOS で使ってみる](use_ios.html)
- [visionOS で使ってみる](use_visionos.html)
- [Linux (Ubuntu) で使ってみる](use_linux.html)

- [Windows 10 x86_64 向けにビルドする](build_windows.html)
- [macOS x86_64 向けにビルドする](build_macos.html)
- [Linux x86_64 向けにビルドする](build_linux.html)
- [Android 向けにビルドする](build_android.html)
- [iOS 向けにビルドする](build_ios.html)
- [visionOS 向けにビルドする](build_visionos.html)

- [2025.1.x から 2025.2.x への移行](2025_1_to_2025_2.html)
- [2024.1.x から 2024.2.x への移行](2024_1_to_2024_2.html)
- [2023.3.x から 2023.4.x への移行](2023_3_to_2023_4.html)

<!-- mikan:page doc="release" -->

# リリースノート

**CHANGE**
: 後方互換性のない変更

**UPDATE**
: 後方互換性がある変更

**ADD**
: 後方互換性がある追加

**FIX**
: バグ修正

## 2026.1.0

**日付**: 2026-02-18
**対応 Sora C++ SDK**: 2026.1.0
**対応 Sora**: 2025.2.0 以降

### ハイライト

- RPC 機能を追加しました- Sora 2025.2.0 以降で利用可能な RPC 機能に対応しました
  - 詳細は [RPC 機能](functions_rpc.html) をご確認ください
- `simulcast_request_rid` に対応しました- Sora 2025.2.0 以降で利用可能な simulcast_request_rid に対応しました

### 非推奨情報

- 2027 年 12 月リリースの Sora にてシグナリング接続時の `simulcast_rid` が廃止予定であるため `Sora.Config.SimulcastRid` を非推奨化しました- 今後は `Sora.Config.SimulcastRequestRid` を利用してください

### 変更履歴

- [UPDATE] Sora C++ SDK を `2026.1.0` に上げました- libwebrtc を `m144.7559.2.1` に上げました
  - BOOST_VERSION を `1.90.0` にアップデートしました
  - CMAKE_VERSION を `4.2.1` にアップデートしました
- [UPDATE] DataChannel メッセージングをリアルタイムメッセージングに名称変更しました- Sora.cs のコメントを修正する
  - SoraSample.cs のラベルとコメントを修正する
- [ADD] `simulcast_request_rid` に対応しました- Sora 2025.2.0 以降で利用可能な simulcast_request_rid に対応しました
  - `Sora.Config.SimulcastRequestRid` プロパティを追加しました
  - `Sora.Config.SimulcastRid` を非推奨化しました
  - `simulcast_request_rid` は未指定の場合、項目も含めないようにしました
- [ADD] RPC 機能を追加しました- Sora 2025.2.0 以降で利用可能な RPC 機能に対応しました
  - `Sora.RequestRpcNotification()` メソッドを追加しました- JSON-RPC 2.0 の通知 (Notification) を送信します
    - Sora からのレスポンスは返ってきません
  - `Sora.RequestRpc()` メソッドを追加しました- JSON-RPC 2.0 のリクエスト (Request) を送信します
    - レスポンスが返ってくるまでのタイムアウトを `timeoutMillis` でミリ秒単位で指定できます- 指定しない場合はデフォルトの 5,000ms となります
    - Sora からのレスポンスは引数で渡す `RpcResult` コールバックで受け取ります

## 2025.3.0

**日付**: 2025-12-11
**対応 Sora C++ SDK**: 2025.6.1
**対応 Sora**: 2025.1.0

### ハイライト

- Unity カメラキャプチャで DirectX 12 をサポートしました- これにより Unity のグラフィック API が DirectX 12 の場合でも Unity カメラキャプチャが利用できるようになりました
- DegradationPreference を追加し、エンコード時の劣化の優先順位を指定できるようにしました- エンコード時の劣化の優先順位を指定できるようになります
  - フレームレート優先、解像度優先、バランス優先を選択できます
  - 詳細は [DegradationPreference](functions_degradation_preference.html) を参照してください
- テクスチャキャプチャの機能を追加しました- CameraConfig にて Texture を指定してキャプチャした映像を送信できるようになりました
- 音声トラックごとの音声データが取得できるようになりました- 送信する音声、受信した一接続ごとの音声データを個別に取得できるようになりました
  - 詳細は [音声データ取得機能](functions_audio_sink.html) を参照してください
- 受信した音声トラックごとに音量を調整できるようになりました- 受信した音声トラックを個別に音量調整できるようになりました
  - 詳細は [音声の送信と受信](functions_audio.html) の Sora.AudioTrack クラスの API セクションを参照してください

### 破壊的変更

- [CHANGE] VideoCodecImplementation の NvidiaVideoCodecSdk を NvidiaVideoCodec に変更しました- 既存コードへの影響があります
  - 修正方法は [2025.2.x から 2025.3.x への移行](2025_2_to_2025_3.html) を参照してください
- [CHANGE] Sora.cs を Nullable に対応しました- `#nullable enable` を有効にしました- 破壊的変更ですが、既存コードへの影響はありません
  - nullable 対応に伴い、Unity のワーニングを解消するため以下の変更を行いました- GetVideoCapturerDevices, GetAudioRecordingDevices, GetAudioPlayoutDevices が `null` を返す可能性があるように変更しました- デバイス情報の取得に失敗した場合や、デバイスが存在しない場合に `null` が返されます
    - コールバック呼び出しを `callback!(...)` に統一しました
    - CameraConfig および ForwardingFilter 周辺の nullable 対応と null 安全性を強化しました
    - AudioOutputHelper の null 安全性向上を行いました
- [CHANGE] GetHardwareAcceleratorPreference() で AMD AMF を優先リストから除外しました- AMD AMF は一時的に非推奨化しているため、優先リストから除外しました
- [UPDATE] selfHandle を利用してコードを整理しました- selfHandle 対応に合わせて各種コールバックを nullable に対応しました
  - 破壊的変更ですが、既存のユーザーコードへの影響はありません
- [UPDATE] [sora-unity-sdk-samples のプロジェクトと統合しました](https://github.com/shiguredo/sora-unity-sdk-samples)- sora-unity-sdk-samples のプロジェクトを sora-unity-sdk リポジトリに統合しました

### 非推奨情報

- [CHANGE] AMD AMF ハードウェアアクセラレーターを非推奨化しました- 一時的に AMD AMF ハードウェアエンコーダーとデコーダーを非推奨化しました
  - AMD 以外のハードウェアアクセラレーターを利用するようにしてください

### 変更履歴

- [ADD] Unity カメラキャプチャで DirectX 12 をサポートしました
- [ADD] DegradationPreference を追加し、エンコード時の劣化の優先順位を指定できるようにしました- `enum DegradationPreference` を追加
  - `Disabled`: 無効
  - `MaintainFramerate`: フレームレート優先
  - `MaintainResolution`: 解像度優先
  - `Balanced`: バランス優先
- [ADD] テクスチャキャプチャの機能を追加しました- CameraConfig を使って、デバイス、UnityCamera に加えて Texture を指定できるようにしました
- [ADD] `Sora.SenderAudioTrackSink` を使って送信するオーディオデータを取得できるようになりました
- [ADD] ADM の音量を設定する関数 `Sora.SetSpeakerVolume()`, `Sora.SetMicrophoneVolume()` を追加しました
- [ADD] ADM の初期音量の設定として `Sora.Config.AudioSpeakerVolume`, `Sora.Config.AudioMicrophoneVolume` を追加しました
- [ADD] オーディオトラックの音量を設定する関数 `Sora.AudioTrack.SetVolume()` を追加しました
- [ADD] オーディオやビデオが追加/削除された時に呼ばれるコールバック `OnMediaStreamTrack` と `OnRemoveMediaStreamTrack` を追加しました- Sora C++ SDK の `webrtc::PeerConnectionObserver` の `OnTrack()` と `OnRemoveTrack()` に相当する機能です
- [ADD] `MediaStreamTrack`, `VideoTrack` , `AudioTrack` , `RtpTransceiver`, `RtpReceiver` クラスを追加しました- これらは `OnMediaStreamTrack` と `OnRemoveMediaStreamTrack` の引数として渡されます
- [ADD] trackId という名前を videoSinkId に変更し、videoSinkId から `VideoTrack` を取得する関数 `GetVideoTrackFromVideoSinkId()` を追加しました- 既存の仕様から破壊的変更せずに `VideoTrack` を利用できるようにするための仕組みです
- [UPDATE] libwebrtc を `m143.7499.1.0` に上げました
- [UPDATE] Sora C++ SDK を `2025.6.1` に上げました- `BOOST_VERSION` を `1.89.0` にアップデートしました
  - `CMAKE_VERSION` を `4.1.3` にアップデートしました
- [UPDATE] Unity が提供しているヘッダーを `6000.0.38f1` のヘッダーファイルにするようにしました
- [FIX] Unity カメラキャプチャがサポートしていないグラフィックエンジンを利用すると SDK 全体が動作しないのを修正し、Unity カメラキャプチャを利用しない場合は正常に動作するようにしました

## 2025.2.0

**日付**: 2025-08-26
**対応 Sora C++ SDK**: 2025.4.0
**対応 Sora**: 2025.1.0

### 廃止情報

- [CHANGE] Ubuntu 20.04 の対応を廃止しました- Ubuntu 20.04 をご利用の方は、Ubuntu 22.04 または Ubuntu 24.04 に移行してください

### 破壊的変更

破壊的変更のより詳細な情報は [2025.1.x から 2025.2.x への移行](2025_1_to_2025_2.html) を参照してください。

- [CHANGE] Sora.Config.UseHardwareEncoder フラグを削除しました- 代わりに `Sora.Config.VideoCodecPreference` を利用して下さい
- [CHANGE] Sora.IsH264Supported() 関数を削除しました- 代わりに `Sora.GetVideoCodecCapability()` 関数を利用して下さい
- [CHANGE] Sora.Config.VideoCodecType を Nullable 型に変更し、デフォルト値を `VP9` から未指定に変更しました- 未指定の場合、シグナリング "type": "connect" で映像コーデック指定を行いません
  - 映像コーデック指定を行わない場合は Sora のデフォルト値 `VP9` が利用されます
- [CHANGE] Sora.Config.AudioCodecType を Nullable 型に変更し、デフォルト値を `OPUS` から未指定に変更しました- 未指定の場合、シグナリング "type": "connect" で音声コーデック指定を行いません
  - 音声コーデック指定を行わない場合は Sora のデフォルト値 `OPUS` が利用されます

### 変更履歴

- [UPDATE] Sora C++ SDK を `2025.4.0` に上げました- `CMAKE_VERSION` を `4.0.3` にアップデートしました
  - `WEBRTC_BUILD_VERSION` を `m138.7204.0.1` にアップデートしました
  - `BOOST_VERSION` を `1.88.0` にアップデートしました
  - `ANDROID_NDK_VERSION` を `r28b` にアップデートしました
- [ADD] 利用する映像コーデックを詳細に指定するための enum やクラス、関数などを追加しました- `Sora.VideoCodecImplementation` 列挙型
  - `Sora.VideoCodecCapabilityConfig` クラス
  - `Sora.VideoCodecCapability` クラス
  - `Sora.VideoCodecPreference` クラス
  - `Sora.GetVideoCodecPreference()` 関数
  - `Sora.Config.VideoCodecPreference` フィールド
- [ADD] AMD AMF のサポートを追加しました- Sora.cs に AMD AMF のサポートを追加しました- `VideoCodecImplementation` 列挙型に `AmdAmf` を追加しました
    - `VideoCodecImplementationToString()` と `VideoCodecImplementationFromString()` に `AmdAmf` 用の case を追加しました
    - `VideoCodecPreference.GetHardwareAcceleratorPreference()` に AMD AMF 用の `VideoCodecPreference` を追加しました- 次の順序で上から優先されるように追加しました- Intel VPL
        - AMD AMF
        - NVIDIA Video Codec
        - Internal
      - `preference.Merge()` は同じコーデックが既に存在する場合、引数に渡した `VideoCodecPreference` で上書きされるため、コード上では優先度の低い順に並べている
    - converter.cpp に `AMFContext` の初期化を追加しました
    - `sora::VideoCodecCapabilityConfig` の `amf_context` に `AMFContext` の値を設定することで AMD AMF を利用可能にする
- [ADD] Ubuntu 24.04 の対応を追加しました- Plugins/SoraUnitySdk/linux ディレクトリを Plugins/SoraUnitySdk/ubuntu-22.04 と Plugins/SoraUnitySdk/ubuntu-24.04 に分けました
  - ご利用になる Ubuntu のバージョンに応じて、Plugins/SoraUnitySdk/ubuntu-22.04 または Plugins/SoraUnitySdk/ubuntu-24.04 を利用してください

## 2025.1.0

**日付**: 2025-01-29
**対応 Sora C++ SDK**: 2025.1.0
**対応 Sora**: 2024.2.0

- [CHANGE] ForwardingFilter は非推奨になりました。
- [UPDATE] Sora C++ SDK を `2025.1.0` にアップデートしました- WEBRTC_BUILD_VERSION を `m132.6834.5.2` にアップデートしました
  - BOOST_VERSION を `1.87.0` にアップデートしました
  - `rtc::CreateRandomString` のヘッダを追加しました
  - CMAKE_VERSION を `3.30.5` にアップデートしました
- [ADD] Sora.Config に `ClientCert`, `ClientKey`, `CACert` を追加しました
- [ADD] DataChannels に `Header` を追加しました
- [ADD] ForwardingFilters を追加しました- ForwardingFilter の代わりにこちらを利用してください
  - 詳細は [転送フィルター](functions_forwarding_filters.html) をご確認ください
- [ADD] ForwardingFilters に `name` と `priority` を追加しました

## 2024.4.0

**日付**: 2024-07-29
**対応 Sora C++ SDK**: 2024.7.0
**対応 Sora**: 2024.1.0

- [UPDATE] Sora C++ SDK を `2024.7.0` にアップデートしました- Windows, Ubuntu 22.04 の NVIDIA Video Codec を利用した環境で H.265 が利用できるようになりました
- [UPDATE] libwebrtc を `m127.6533.1.1` にアップデートしました
- [ADD] WebSocket での接続時に User-Agent が設定されるようになりました- `Mozilla/5.0 (Sora Unity SDK/<Sora Unity SDK のバージョン>)` を設定します
  - 例: Mozilla/5.0 (Sora Unity SDK/2024.4.0)

## 2024.3.0

**日付**: 2024-04-18
**対応 Sora C++ SDK**: 2024.6.1
**対応 Sora**: 2023.2.0

- [UPDATE] Sora C++ SDK を `2024.6.1` にアップデートしました- Windows, Ubuntu 22.04 の Intel VPL を利用した環境で H.265 が利用できるようになりました
- [UPDATE] libwebrtc を `m122.6261.1.0` にアップデートしました- libwebrtc の AV1 デコード機能の脆弱性対応が含まれています
- [UPDATE] 対応プラットフォームに Ubuntu 22.04 x86_64 を追加しました- コード変更はありませんが、Ubuntu 20.04 版の Unity SDK で Ubuntu 22.04 も動作することを確認しました

## 2024.2.0

**日付**: 2024-03-13
**対応 Sora C++ SDK**: 2024.4.0
**対応 Sora**: 2023.2.0

- [CHANGE] 音声コーデック Lyra を削除しました- 音声コーデック Lyra への対応を廃止しました
  - Sora.Config から Lyra に関する設定を削除しました- `Sora.Config` から `AudioCodecLyraBitrate` を削除しました
    - `Sora.Config` から `AudioCodecLyraUsedtx` を削除しました
    - `Sora.Config` から `CheckLyraVersion` を削除しました
    - `Sora.Config.AudioCodecType` から `Lyra` を削除しました
- [CHANGE] Android デバイスのハンズフリー対応に伴い `AudioOutputHelper` を `IAudioOutputHelper` に変更しました- ハンズフリー機能を利用していた方は移行を行う必要があります
  - 修正方法は [2024.1.x から 2024.2.x への移行](2024_1_to_2024_2.html) を参照してください
- [UPDATE] Sora C++ SDK を `2024.4.0` にアップデートしました
- [UPDATE] libwebrtc を `m121.6167.3.0` にアップデートしました
- [UPDATE] Boost を `1.84.0` にアップデートしました
- [UPDATE] CMake を `3.28.1` にアップデートしました
- [ADD] Android のハンズフリー機能に対応しました- 詳細は [ハンズフリーで利用できますか？](faq.html#421347) をご確認ください

## 2024.1.0

**日付**: 2024-01-22
**対応 Sora C++ SDK**: 2024.1.0
**対応 Sora**: 2023.2.0

- [UPDATE] Sora C++ SDK を `2024.1.0` にアップデートしました
- [UPDATE] libwebrtc を `m120.6099.1.2` にアップデートしました
- [ADD] `VideoCodecType` に `H265` を追加しました- Android, iOS, macOS で H265 を利用できるようになりました
- [ADD] `ForwardingFilter` に `version` と `metadata` を追加しました- Sora 2023.2.0 への追従です
- [FIX] `ForwardingFilter` の `action` を必須項目からオプション項目に変更しました- Sora の仕様に合うよう修正しました

## 2023.5.2

**日付**: 2023-12-02
**対応 Sora C++ SDK**: 2023.16.1
**対応 Sora**: 2023.1.0

- [FIX] Sora C++ SDK を `2023.16.2` にアップデートしました- Apple 非公開 API を利用しており、Apple からリジェクトされる問題が修正されました

## 2023.5.1

**日付**: 2023-11-30
**対応 Sora C++ SDK**: 2023.15.1
**対応 Sora**: 2023.1.0

- [FIX] 受信したフレームデータについて書き込みと削除が同時に行われたときにクラッシュすることがあるため修正しました

## 2023.5.0

**日付**: 2023-11-13
**対応 Sora C++ SDK**: 2023.15.1
**対応 Sora**: 2023.1.0

- [UPDATE] Sora C++ SDK を `2023.15.1` にアップデートしました- macOS で USB 接続されたカメラが利用できなくなっていた問題が解消しました
- [UPDATE] libwebrtc を `m119.6045.2.1` にアップデートしました
- [UPDATE] CMake を `3.27.7` にアップデートしました
- [UPDATE] Android NDK を `r26b` にアップデートしました

## 2023.4.0

**日付**: 2023-10-26
**対応 Sora C++ SDK**: 2023.14.0
**対応 Sora**: 2023.1.0

- [CHANGE] `Sora.Config` 中にあるキャプチャラに関するフィールドを `Sora.CameraConfig` に移動しました- 修正方法は [2023.3.x から 2023.4.x への移行](2023_3_to_2023_4.html) を参照してください
- [UPDATE] SoraClientContext を利用してコードを簡潔にしました
- [UPDATE] libwebrtc を `m117.5938.2.0` にアップデートしました
- [ADD] Sora C++ SDK を `2023.14.0` にアップデートしました
- [ADD] iOS デバイスのハンズフリーができる `AudioOutputHelper` を追加しました- 詳細は [ハンズフリーで利用できますか？](faq.html#421347) をご確認ください
- [ADD] 接続中にキャプチャラを切り替える機能を実装しました
- [ADD] デバイスを掴まないようにする `NoVideoDevice`, `NoAudioDevice` を追加しました
- [ADD] ハードウェアエンコーダーを利用するかどうかを設定する `UseHardwareEncoder` を追加しました
- [ADD] `SelectedSignalingURL` と `ConnectedSignalingURL` プロパティを追加しました- 詳細は [接続している URL を取得することはできますか？](faq.html#53488e) をご確認ください
- [FIX] IosAudioInit を初回接続の場合のみ呼び出すようにすることで、iOS で連続して接続しようとするとクラッシュするケースを修正しました
- [FIX] `AudioOutputHelper.Dispose()` を複数回呼んでもクラッシュしないように修正しました

## 2023.3.0

**日付**: 2023-08-08
**対応 Sora C++ SDK**: 2023.9.0
**対応 Sora**: 2023.1.0

- [UPDATE] Sora C++ SDK を `2023.9.0` にアップデートしました- Target minimum iOS Version を 13.4 以上に設定した時、iOS15.x のデバイスで実行すると起動時にクラッシュする不具合が解消されています
- [UPDATE] libwebrtc を `m115.5790.7.0` にアップデートしました

## 2023.2.0

**日付**: 2023-07-19
**対応 Sora C++ SDK**: 2023.7.2
**対応 Sora**: 2023.1.0

- [UPDATE] Sora C++ SDK を `2023.7.2` にアップデートしました
- [UPDATE] libwebrtc を `m114.5735.2.0` にアップデートしました- VP9 および AV1 でサイマルキャストを利用できるようになりました
- [ADD] Sora 接続時に ForwardingFilter を指定できるようにしました- [Sora の転送フィルター機能についてのドキュメント](https://sora-doc.shiguredo.jp/FORWARDING_FILTER#86e20b) もあわせてご確認ください
- [ADD] Sora 接続時に CodecParams を指定できるようにしました- [Sora のビデオ設定についてのドキュメント](https://sora-doc.shiguredo.jp/SIGNALING#b7556a) もあわせてご確認ください
- [FIX] GetStats でデータレースによりエラーが発生するケースについて修正しました

## 2023.1.0

**日付**: 2023-04-13
**対応 Sora C++ SDK**: 2023.4.0
**対応 Sora**: 2022.2.0

- [UPDATE] Sora C++ SDK を `2023.4.0` にアップデートしました
- [UPDATE] libwebrtc を `m111.5563.4.4` にアップデートしました
- [UPDATE] Boost を `1.81.0` にアップデートしました
- [UPDATE] CMake を `3.25.1` にアップデートしました
- [ADD] 音声コーデックに Lyra を追加しました
- [ADD] `Sora.Config` に `AudioStreamingLanguageCode` を追加しました
- [ADD] `Sora.Config` に `SignalingNotifyMetadata` を追加しました
- [ADD] offer 設定時のコールバック関数 `OnSetOffer` を追加しました

## 2022.6.2

**日付**: 2023-03-25
**対応 Sora C++ SDK**: 2022.12.4
**対応 Sora**: 2022.2.0

- [FIX] IPHONE_DEPLOYMENT_TARGET を 13 にアップデートしました- Sora C++ SDK を `2022.12.4` にアップデートする際に、IPHONE_DEPLOYMENT_TARGET をあわせてあげる対応です

## 2022.6.1

**日付**: 2023-03-24
**対応 Sora C++ SDK**: 2022.12.4
**対応 Sora**: 2022.2.0

- [FIX] Sora C++ SDK を `2022.12.4` にアップデートしました- Unity で発生した、Websocket 切断時にクラッシュする不具合を修正するために、Sora C++ SDK のバージョンを上げました
  - Sora C++ SDK で WS 切断時のタイムアウトが起きた際に無効な関数オブジェクトが呼ばれていました

## 2022.6.0

**日付**: 2022-12-08
**対応 Sora C++ SDK**: 2022.12.1
**対応 Sora**: 2022.1.3

- [ADD] 実行時に音声と映像のミュート、ミュート解除をする機能を追加しました

## 2022.5.2

**日付**: 2022-10-04
**対応 Sora C++ SDK**: 2022.12.1
**対応 Sora**: 2022.1.1

- [FIX] UnityCameraCapturer がマルチスレッド下で正常に終了しないことがあるのを修正しました

## 2022.5.1

**日付**: 2022-09-24
**対応 Sora C++ SDK**: 2022.12.1
**対応 Sora**: 2022.1.1

- [UPDATE] Sora C++ SDK を `2022.12.1` にアップデートしました
- [FIX] カメラからのフレーム情報が縮小された状態で渡されていたのを修正しました

## 2022.5.0

**日付**: 2022-09-22
**対応 Sora C++ SDK**: 2022.11.0
**対応 Sora**: 2022.1.1

- [ADD] カメラからのフレーム情報を受け取るコールバックを追加しました
- [ADD] カメラデバイスの FPS の設定可能にしました

## 2022.4.0

**日付**: 2022-09-12
**対応 Sora C++ SDK**: 2022.11.0
**対応 Sora**: 2022.1.1

- [CHANGE] iOS ビルド向けに Bitcode を off にする設定を追加しました
- [UPDATE] Sora C++ SDK を `2022.11.0` にアップデートしました
- [UPDATE] libwebrtc を `m105.5195.0.0` にアップデートしました
- [UPDATE] Boost を `1.80.0` にアップデートしました
- [UPDATE] Android NDK を `r25b` にアップデートしました

## 2022.3.0

**日付**: 2022-08-31
**対応 Sora C++ SDK**: 2022.9.0
**対応 Sora**: 2022.1.1

- [UPDATE] Sora C++ SDK を `2022.9.0` にアップデートしました
- [ADD] OnDataChannel を追加しました
- [FIX] Sora Unity SDK のクライアント情報を設定するように追加しました
- [FIX] UnityAudioOutput = true で ADM を Stop しても再生中のままになっていたのを修正しました
- [FIX] ProcessAudio が機能してなかったのを修正しました

<!-- mikan:page doc="overview" -->

# Sora Unity SDK 概要

Sora Unity SDK は [株式会社時雨堂](https://shiguredo.jp) の [WebRTC SFU Sora](https://sora.shiguredo.jp) の Unity 向けクライアントフレームワークです。

## 特徴

Sora Unity SDK は Sora C++ SDK をラップした Unity 向けのライブラリです。
そのため、Sora C++ SDK がサポートする機能の大半を利用できます。

### ハードウェアアクセラレーター

時雨堂が独自に様々なハードウェアアクセラレーターに対応することで、CPU 負荷を抑えて高画質な映像配信を行えます。

- [Apple macOS Video Toolbox](https://developer.apple.com/documentation/videotoolbox)- H.264 / H.265
  - VP9 / AV1 のデコードには対応していません
- [NVIDIA Video Codec SDK](https://developer.nvidia.com/video-codec-sdk)- VP8 / VP9 / AV1 / H.264 / H.265
  - VP8 / VP9 はデコードのみの対応です
- [Intel VPL](https://github.com/intel/libvpl) (Intel Media SDK の後継)- VP9 / AV1 / H.264 / H.265
- [AMD AMF](https://github.com/GPUOpen-LibrariesAndSDKs/AMF)- VP8 / VP9 / AV1 / H.264 / H.265
  - AV1 のデコードは Ubuntu x86_64 のみ対応です
  - VP8 / VP9 はデコードのみの対応です
  > **警告**
  >
  > AMD AMF は現在非推奨です。

### ソフトウェアコーデック

libwebrtc に含まれている VP8 / VP9 / AV1 に対応しています。

## ソースコードとリポジトリ構成

- ソースコード- SDK ソースコード
  - サンプルソースコード
- リポジトリ構成- `src/` : ネイティブプラグイン（Unity 向けラッパー）の SDK 実装です
  - `SoraUnitySdkExamples/` : Unity サンプルプロジェクトです
  - `SoraUnitySdkExamples/Assets/SoraUnitySdk/` : Unity 向けの C# での SDK 実装です

## 動作環境

### 対応 Unity バージョン

- Unity 6000.3 (LTS)
- Unity 6000.0 (LTS)

### 対応プラットフォーム

- Windows 10 22H2 x86_64 以降
- macOS 13.4.1 arm64 以降
- Android 7 以降
- iOS 13 以降
- visionOS 2.0 以降
- Ubuntu 22.04 x86_64
- Ubuntu 24.04 x86_64

### 対応 Sora

[リリースノート](release.html) をご確認ください

### 対応グラフィックス API

Unity カメラキャプチャを使用する場合は、対応プラットフォームごとに以下のグラフィックス API を利用してください。

#### macOS

- Metal

#### iOS

- Metal

#### visionOS (お試し版)

- Metal

#### Windows

- Direct3D 11
- Direct3D 12

#### Android

- OpenGL ES 3
- Vulkan

#### Linux (Ubuntu)

- OpenGLCore

## 問い合わせについて

Sora Unity SDK の質問などについては Discord の `#sora-sdk-faq` チャンネルをご利用ください。
ただし、Sora のライセンス契約の有無に関わらず、応答時間と問題の解決を保証しませんのでご了承ください。


## 使ってみる

まずは [プロジェクトにインストールする](use.html) をお読みください。

<!-- mikan:page doc="faq" -->

# FAQ

## 解像度を変更することはできますか？

解像度は変更できます。

解像度の変更には「送信する映像のサイズ」、「受信するテクスチャのサイズ」、「Unity の表示上のサイズ」の 3 つの設定が必要です。
詳細は [解像度の変更方法](set_video_size.html) をご確認ください。

## カメラを無効にして音声だけ送信できますか？

カメラを無効にして音声だけ送信できます。

`NoVideoDevice = true` を指定することで映像デバイスを掴むことなく音声だけを送信することができます。
また、 `video = false` を指定することで映像デバイスを掴みながら音声だけを送信することもできます。

ただし、Unity Camera を利用している場合は `NoVideoDevice = true` を指定しても Unity Camera を掴んでしまうため、
ご注意ください。

## マイクを無効にして映像だけを送信できますか？

マイクを無効にして映像だけを送信できます。

`NoAudioDevice = true` を指定することで音声デバイスを掴むことなく映像だけを送信することができます。
`NoAudioDevice = true` を指定した場合音声の受信も行われなくなります。
また、 `audio = false` を指定することで音声デバイスを掴みながら映像だけを送信することもできます。

ただし、Unity Audio を利用している場合は `NoAudioDevice = true` を指定しても Unity Audio を掴んでしまうため、
ご注意ください。

## カメラ無しの端末を利用して送受信できますか？

カメラ無しの端末を利用して送受信できます。

`NoVideoDevice = true` を指定することでカメラ無しの端末を利用して送受信をすることができます。

## AV1 を設定して送受信できますか？

AV1 を設定して送受信できます。

AV1 は全てのプラットフォームで利用できます。

## HTTP Proxy を利用して接続できますか？

Sora.Config にて HTTP Proxy の設定を行うことで Proxy を利用して接続できます。

**ProxyUrl**: Proxy の URL とポート番号を指定します (例 : )
**ProxyUsername**: Proxy の認証に利用するユーザーを指定します
**ProxyPassword**: Proxy の認証に利用するパスワードを指定します

## Ubuntu で 利用するにはどうすればいいですか？

Ubuntu で Sora Unity SDK を利用するためには以下のコマンドで必要なパッケージをインストールしてください。

```bash
sudo apt-get install libdrm2 libva2 libva-drm2
```

## iOS または macOS から H.264 の FHD で配信するにはどうすればいいですか？

iOS または macOS から FHD で配信したい場合は Sora の H.264 のプロファイルレベル ID を 5.2 以上に設定してください。設定は以下の方法で行うことができます。

- `Config.VideoH264Params` を設定する
- Sora の設定を変更する

Sora の設定については [Sora のドキュメント](https://sora-doc.shiguredo.jp/SORA_CONF#1581db) をご確認ください。

## Sora の TURN 機能を無効にして利用できますか？

Sora の TURN 機能を無効にして利用することはできません。

Sora Unity SDK は Sora を `turn = false` に設定して利用することはできません。

## Windows で 受信した VP9 の映像が表示できない

NVIDIA ビデオカード搭載の Windows で 128x128 未満の VP9 の映像を受信することはできません。
詳細は [Sora C++ SDK の FAQ](https://github.com/shiguredo/sora-cpp-sdk/blob/develop/doc/faq.md#nvidia-%E6%90%AD%E8%BC%89%E3%81%AE-windows-%E3%81%A7-128x128-%E6%9C%AA%E6%BA%80%E3%81%AE-vp9-%E3%81%AE%E6%98%A0%E5%83%8F%E3%82%92%E5%8F%97%E4%BF%A1%E3%81%A7%E3%81%8D%E3%81%BE%E3%81%9B%E3%82%93) をご確認ください。

## リアルタイムメッセージング機能を利用するにはどうすればよいですか？

リアルタイムメッセージング機能を利用するには最低限以下の設定が必要です。

- dataChannelSignaling を有効にする必要があります
- DataChannels で label を設定する必要があります- ラベルは `#` から始める必要があります
  - これは送受信するお互いが同一のラベルである必要があります
- DataChannels の Direction で Sendrecv / Sendonly / Recvonly のいずれかを設定する必要があります

詳細は Sora のドキュメントの [リアルタイムメッセージング機能](https://sora-doc.shiguredo.jp/MESSAGING) をご確認ください。

以下にサンプル集を使った設定方法の例を示します。

サンプル集では必要な値は全て Unity Editor の inspector の以下の項目から行えるようになっています。

- DataChannel シグナリングの設定
- リアルタイムメッセージングの設定

メッセージは「送信」ボタンを押すことで送信し、メッセージ内容は固定で全てのラベルに `aaa` を送信するようになっています。
ラベルごとに指定したい場合や異なるメッセージを送信したい場合はご自身で修正していただく必要があります。


## ハンズフリーで利用できますか？

iOS と Android デバイスでのみ `IAudioOutputHelper` を利用することでハンズフリーができます。

ヘッドセットの接続有無によって以下のように挙動が変わります。

- ヘッドセットが接続されていない場合は通話用スピーカーと通常のスピーカーが切り替わります
- ヘッドセットが接続されている場合は、ヘッドセットのスピーカーとマイクから端末の通常のスピーカーとマイクへ切り替わります
- マイクなしイヤホン接続時の動作は考慮されておらず、イヤホンによりマイクが利用できなくなることがあります

ハンズフリーの詳細は [ハンズフリー](functions_iaudiooutputhelper.html) をご覧ください。

## Android の音声デバイスを変更できますか？

libwebrtc の仕様のため、Sora Unity SDK をそのまま利用して Android の音声デバイスを変更することはできません。
変更したい場合はご自身でデバイスの変更処理を作成する必要があります。

Unity SDK では libwebrtc の webrtc::AudioDeviceModule::Create を使用して音声デバイスを取得しています。
Android 以外では音声デバイスを取得したときにデバイス名も取得しており、デバイス名を変更することで音声デバイスを変更することができます。

しかし、 Android ではデバイスは常に一つであり、デバイス名を取得しようとしてもエラーが発生するため、ダミーの値を入れるようにしています。
該当のコードは Unity SDK が利用している Sora C++ SDK の `device_list.cpp` になります。

[device_list.cpp のソースコードにアクセスする](https://github.com/shiguredo/sora-cpp-sdk/blob/develop/src/device_list.cpp)

## モノラルの音声を送信することはできますか？

モノラルの音声を送信することはできません。

Sora Unity SDK ではステレオ音声のみ取り扱うことができます。
もしモノラルの音声を利用したい場合はモノラルの音声をステレオに変換するなどの処理をご自身で対応していただく必要があります。

## カメラデバイスを変更することはできますか？

カメラデバイスを変更することができます。

カメラデバイスを変更するにはまずカメラデバイスの一覧を取得する必要があります。
カメラデバイスの一覧は `SoraUnitySdk.GetVideoDevices()` で取得できます。
カメラデバイスの一覧を取得したら、その中から利用したいカメラデバイスの DeviceName か UniqueName を `videoCapturerDevice` に設定してください。

以下に Sora Unity SDK のサンプル集の `SoraSample.cs` で利用する場合の例を示します。

```csharp
// 指定したいカメラデバイスの DeviceName か UniqueName を Inspector から設定する
public string videoCapturerDevice = "";

// カメラ・オーディオデバイスの一覧を取得する
void DumpDeviceInfo(string name, Sora.DeviceInfo[] infos)
{
    Debug.LogFormat("------------ {0} --------------", name);
    foreach (var info in infos)
    {
        Debug.LogFormat("DeviceName={0} UniqueName={1}", info.DeviceName, info.UniqueName);
    }
}

void Start()
{
    // アプリ起動時にカメラデバイスの一覧を取得する
    DumpDeviceInfo("video capturer devices", Sora.GetVideoCapturerDevices());
}

public void OnClickStart()
{
    // Sora と接続時に config を設定する
    var config = new Sora.Config()
    {
        // CameraConfig に videoCapturerDevice を設定する
        CameraConfig = new Sora.CameraConfig()
        {
            VideoCapturerDevice = videoCapturerDevice,
        },
     }
}
```


## 接続している URL を取得することはできますか？

接続している URL を取得することができます。

`SelectedSignalingURL` と `ConnectedSignalingURL` を使用することで取得ができます。

`SelectedSignalingURL` は複数の候補の中から利用を決定した URL です。
`ConnectedSignalingURL` は実際に接続した URL です。

## iOS の AVAudioSession.Category は何を設定していますか？

Sora Unity SDK では Sora 接続時、マイクを初期化する際に AVAudioSession.Category を `PlayAndRecord` に設定しています。（マイクを利用しない場合は設定を行いません）

もし、AVAudioSession.Category を変更したい場合はご自身で Native コードを作成し、 AVAudioSession.Category を期待する値に変更する必要があります。
Sora Unity SDK で AVAudioSession.Category を設定している場所は以下のリンクからご確認ください。

[AVAudioSession.Category を設定している場所へアクセスする](https://github.com/shiguredo/sora-unity-sdk/blob/develop/src/mac_helper/ios_audio_init.mm)

## iOS で送受信を行ったとき、音声が小さくなる

Sora Unity SDK では AVAudioSession.Category を `PlayAndRecord` に設定しています。

iOS の仕様上 AVAudioSession.Category を `PlayAndRecord` に設定すると、スピーカー音声が小さくなるようになっています。

## マナーモードの時、受信だけをした場合に音声が聞こえない

iOS の仕様上、デフォルトの音声カテゴリではマナーモードの時に音声を再生することはできません。

もしマナーモードでも音声を出したい場合は、AVAudioSession.Category を変更する必要があります。
その場合はご自身で Native コードを作成し、 AVAudioSession.Category を Playback に変更する必要があります。

## 接続中にカメラを切り替えたい

Sora Unity SDK では、`Sora.SwitchCamera()` メソッドを使用して、実行時にアクティブなカメラを動的に切り替えることができます。

`SwitchCamera()` の詳細は Sora Unity SDK の `Sora.cs` 内の `SwitchCamera()` の定義を参照してください。

[SwitchCamera 定義へアクセスする](https://github.com/shiguredo/sora-unity-sdk/blob/develop/SoraUnitySdkExamples/Assets/SoraUnitySdk/Sora.cs)

切り替え可能なカメラのタイプは 3 つあります。

- デバイスカメラ: 実行している端末に組み込まれた物理的なカメラデバイスです。これは、スマートフォンやタブレットの背面カメラやフロントカメラなどが含まれます
- Unity カメラ: Unity のシーン内に設定されたカメラです。これは、Unity の `Camera` コンポーネントを使用して作成されたカメラです
- Texture: Unity で生成・管理している任意の `Texture` です。 `RenderTexture` の利用を推奨します

これらのカメラを切り替えるには、適切なカメラ設定を `SwitchCamera()` メソッドに渡す必要があります。これは、以下のメソッドを使用して行います。

- デバイスカメラを使用する場合 : `CameraConfig.FromDeviceCamera()` メソッドを使用して、特定のデバイスカメラ用のカメラ設定を生成します
- Unity カメラを使用する場合 : `CameraConfig.FromUnityCamera()` メソッドを使用して、特定の Unity カメラ用のカメラ設定を生成します
- Texture を使用する場合 : `CameraConfig.FromTexture()` メソッドを使用して、特定の Texture 用のカメラ設定を生成します

以下に Sora Unity SDK のサンプル集の `SoraSample.cs` で利用する場合の例を示します。

```csharp
// ここでは例としてユーザーがカメラ切り替えボタンをクリックしたときの処理を示します。
public void OnClickSwitchCamera()
{
    // Sora と接続していない場合は何もしない
    if (sora == null)
    {
        return;
    }

    int videoWidth;
    int videoHeight;

    // 映像サイズの取得
    GetVideoSize(videoSize, out videoWidth, out videoHeight);

    // captureUnityCamera の状態に基づいて、デバイスカメラと Unity カメラを切り替えます。
    if (captureUnityCamera)
    {
        // デバイスカメラに切り替えるために、Sora の SwitchCamera() メソッドを使用します。
        // FromDeviceCamera() メソッドを使って、特定のデバイスカメラ用の新しい CameraConfig を生成します。
        //  - videoCapturerDevice : 使用するデバイスカメラを指定します。
        //  - videoWidth : 切り替え後のビデオの幅を設定します。
        //  - videoHeight : 切り替え後のビデオの高さを設定します。
        //  - videoFps : 切り替え後のビデオのフレームレートを設定します。
        // CameraConfig は、CapturerType を DeviceCamera に設定し、適切なビデオキャプチャデバイスと解像度、フレームレートを指定して、ビデオストリームの設定を行います。
        sora.SwitchCamera(Sora.CameraConfig.FromDeviceCamera(videoCapturerDevice, videoWidth, videoHeight, videoFps));
        captureUnityCamera = false;
    }
    else
    {
        // Unity カメラに切り替えるために、Sora の SwitchCamera() メソッドを使用します。
        // FromUnityCamera() メソッドを使って、特定の Unity カメラ用の新しい CameraConfig を生成します。
        //  - capturedCamera : 使用する Unity カメラを指定します。
        //  - unityCameraRenderTargetDepthBuffer : Unity カメラのレンダーターゲットの深度バッファのサイズを指定します（ここでは16）。
        //  - videoWidth : 切り替え後のビデオの幅を設定します。
        //  - videoHeight : 切り替え後のビデオの高さを設定します。
        //  - videoFps : 切り替え後のビデオのフレームレートを設定します。
        // CameraConfig は、CapturerType を UnityCamera に設定し、適切な Unity カメラと解像度、フレームレートを指定して、ビデオストリームの設定を行います。
        sora.SwitchCamera(Sora.CameraConfig.FromUnityCamera(capturedCamera, 16, videoWidth, videoHeight, videoFps));
        captureUnityCamera = true;
    }
}
```

## ハードウェアエンコーダーの利用を制御することはできますか？

できます。Sora Unitay SDK では、 `Sora.VideoCodecImplementation` パラメーターを使用することでハードウェアエンコーダーの利用を制御できます。
詳細は [エンコーダー / デコーダーの指定](functions_hardware_acceleration.html) をご確認ください。

## Unity SDK のサンプル集にはどのようなシーンが用意されていますか？

Sora Unity SDK のサンプル集には以下のシーンが用意されています。
マルチストリームを推奨としているため、片方向のみのシーンは用意されていません。

- Multi_Sendonly
- Multi_Recvonly
- Multi_Sendrecv

## NVIDIA 搭載の Windows で、 width、 height のいずれかが 128 未満のサイズの VP9 の映像は受信できますか？

NVIDIA Video Codec のハードウェアデコーダでは width、 height のいずれかが 128 未満である場合 VP9 の映像をデコードできません。

width、 height のいずれかが 128 未満のサイズの映像を受信したい場合は VP9 以外のコーデックを利用するか、`Sora.VideoCodecImplementation.Internal` にして利用してください。

## iOS で画面の向きのロックを設定中に端末の向きを変更しても映像サイズ（縦長・横長）が変わらない

Sora Unity SDK では端末の向きによって送信する映像のサイズが縦長か横長に変わりますが、
iOS と SDK で利用している libwebrtc の仕様で、画面の向きのロック中に端末の向きを変更しても、映像のサイズは変わりません。

映像のサイズを変更して送信したい場合は、iOS の画面の向きのロック設定を解除してください。

## Android で物理の音量調整ボタンを押したときに、調節できる音量の種別を選択できますか？

Android の物理の音量調整ボタンで、どの種別の音声(メディア・通話など)が調節されるかは端末ごとに異なります。

物理の音量調整ボタンで好きな音量調整の種別を設定したい場合は、ご自身で Native コードを作成する必要があります。

Native コードを作成するには様々な方法がありますが、例えば Unity の [AndroidJavaClass](https://docs.unity3d.com/ja/2019.4/ScriptReference/AndroidJavaClass.html) を使用して、作成することができます。

## Android ベースのヘッドマウントディスプレイで利用できますか？

Sora Unity SDK は Android に対応していますので、Meta Quest のような Android ベースのヘッドマウントディスプレイで利用できます。

## Sora から切断後、再接続を行うとクラッシュしてしまう

Sora に再接続する時には必ず以下の手順でオブジェクトを破棄した後に、再作成をするようにしてください。

- Disconnect を呼び出す
- OnDisconnect を待つ
- Dispose を呼び出す

これらのプロセスの詳細はサンプル集の `SoraSample.cs` にも記載されていますのでそちらも参考にしてください。

[SoraSample.cs のコードへアクセスする](https://github.com/shiguredo/sora-unity-sdk/tree/master/SoraUnitySdkExamples/Assets/SoraSample.cs)

## H.265 を利用できますか？

H.265 は 以下のプラットフォームで利用できます。
Windows と Ubuntu は 以下に記載する GPU を利用した環境で利用できます。

> **注意**
>
> AMD AMF はドライバーが不安定なため、現在非推奨です。

- macOS
- iOS
- Android
- Windows- Intel VPL を利用した環境
  - AMD AMF を利用した環境
  - NVIDIA Video Codec を利用した環境
- Ubuntu 22.04 / Ubuntu 24.04- Intel VPL を利用した環境
  - AMD AMF を利用した環境
  - NVIDIA Video Codec を利用した環境

GPU の HWA を利用しない Windows や Ubuntu 22.04 / 24.04 で H.265 を利用した場合は
接続時にエラーとはなりませんが、映像の送受信は行われません。

## トラックに紐づくコネクション ID を取得することはできますか？

音声と映像のトラックに紐づくコネクション ID を取得することができます。

[映像の送信と受信](functions_video.html) と [音声の送信と受信](functions_audio.html) をご確認ください。

## Unity Camera で映像を送信するときに FPS を設定できますか？

Unity Camera の映像キャプチャを実行するサイクルを調整することで FPS を制御できます。
一例として Sora Unity SDK Samples での設定方法を以下に示します。

[Sora Unity SDK Samples で Unity Camera の映像キャプチャを行っている箇所へアクセスする](https://github.com/shiguredo/sora-unity-sdk/tree/master/SoraUnitySdkExamples/Assets/SoraSample.cs#L230-L235)

映像キャプチャを実行している箇所に以下のように修正を加えることで FPS を制御できます。
ここでは 15 fps になるように修正を加えています。

修正内容は以下の通りです。

- フレームカウンターを追加
- フレームカウンターの値を見て偶数フレームのみでキャプチャを行うように修正
- オーバーフローを避けるためのリセット処理を追加

```csharp
IEnumerator Render()
{
    int frameCounter = 0; // フレームカウンターを追加
    while (true)
    {
        yield return new WaitForEndOfFrame();
        frameCounter++; // フレームカウンターをインクリメント

        // Unity カメラの映像をキャプチャする
        // 必ず yield return new WaitForEndOfFrame() の後に呼び出すこと
        if (state == State.Started && frameCounter % 2 == 0) // 偶数フレームのみでキャプチャをする
        {
            sora.OnRender();
        }
        // Unity から出力された音を録音データとして Sora に渡す
        if (state == State.Started && unityAudioInput && !Recvonly)
        {
            var samples = AudioRenderer.GetSampleCountForCaptureFrame();
            if (AudioSettings.speakerMode == AudioSpeakerMode.Stereo)
            {
                using (var buf = new Unity.Collections.NativeArray<float>(samples * 2, Unity.Collections.Allocator.Temp))
                {
                    AudioRenderer.Render(buf);
                    sora.ProcessAudio(buf.ToArray(), 0, samples);
                }
            }
        }
        if (frameCounter >= int.MaxValue - 1) // オーバーフローを避けるためのリセット
        {
            frameCounter = 0;
        }
    }
}
```

## CA 証明書ファイルやクライアント証明書ファイルの指定や無視することはできますか？

CA 証明書ファイルやクライアント証明書ファイルの指定、および証明書の検証を行わない設定ができます。

Sora Unity SDK では証明書の検証について以下の設定を用意しています。

- `Insecure` : サーバー証明書の検証を行わないようにするフラグです。デフォルトは `false` で証明書の検証を行います。
- `CACert` : string で CA 証明書ファイルの内容を指定します。
- `ClientCert` : string でクライアント証明書ファイルの内容を指定します。
- `ClientKey` : string でクライアントプライベートキーファイルの内容を指定します。

`CACert`, `ClientCert`, `ClientKey` には、PEM 形式のファイルを指定してください。

詳細は [証明書の指定](functions_ca_cert.html) をご確認ください。

## 受信した音声の音量を調整することはできますか？

受信した音声の音量を調整することができます。

詳細は [音声の送信と受信](functions_audio.html) をご確認ください。

## Android の 16 KB ページサイズには対応していますか？

Sora Unity SDK の 2025.2.0 以降で対応しています。

Plugins も 16 KB のページサイズでビルドされています。

もし Sora Unity SDK の 2025.2.0 以降をインストールしても Unity Editor 上で警告が出ている場合は以下の手順で `.meta` ファイルの再生成を試してみてください。

1. Plugins/SoraUnitySDK/android の `.meta` ファイルを削除します。
2. Unity Editor を再起動します。

これにより `.meta` ファイルが再生成されます。

16 KB ページサイズの Unity の仕様は公式のドキュメントをご確認ください。

[Unity の 16 KB ページサイズの仕様](https://docs.unity3d.com/6000.0/Documentation/Manual/android-requirements-and-compatibility.html)

## Unity 内の音声を Sora に送信することはできますか？

はい。Unity 内の音声を Sora に送信することができます。
AudioSource を利用して Unity の音声を Sora に送信することができます。

## Unity 内の映像を Sora に送信することはできますか？

はい。Unity 内の映像を Sora に送信することができます。
Hierarchy に Unity の Camera を配置し、Sora の設定で Unity Camera を指定することで映像を送信することができます。

[映像の送信と受信](functions_video.html) をご確認ください。

## Direct3D 12 をサポートしていますか？

Sora Unity SDK は Direct3D 12 をサポートしています。
Windows では Direct3D 11 と Direct3D 12 に対応しています。

## OpenGL ES 2.0 をサポートしていますか？

Sora Unity SDK は OpenGL ES 2.0 をサポートしていません。
OpenGL ES 3.0 以降をサポートしているため、OpenGL ES 2.0 のみをサポートしている端末では Unity Camera を利用した映像の送信ができません。

## Unity カメラキャプチャを使うにあたって注意点はありますか？

Unity カメラキャプチャを使う場合、対応プラットフォームごとに必要なグラフィックス API を確認してください。

詳細は [Sora Unity SDK 概要](overview.html) の `対応グラフィックス API` をご確認ください。

## RenderTexture をインプットとして送信できますか？

RenderTexture をインプットとして送信できます。詳細は [映像の送信と受信](functions_video.html) をご確認ください。

<!-- mikan:page doc="known_bugs" -->

# 既知の問題

Sora Unity SDK では現在以下の既知の問題が存在します。

- Android 12 以降の端末で Bluetooth ヘッドセット接続 => 有線ヘッドセット接続 のあと、有線ヘッドセットを切断する操作を行った時、音声が Bluetooth ヘッドセットには戻りません。- Bluetooth ヘッドセットを再接続することでまた利用ができるようになります。
  - この問題は Android OS のイシューとして報告されています。
- ハンズフリー機能について、Android 11 以前の端末で Bluetooth ヘッドセット接続 => 有線ヘッドセット接続 のあと、有線ヘッドセットを切断する操作を行った時、ハンズフリー機能が利用できなくなります。- Bluetooth ヘッドセットの切断、再接続でまた利用ができるようになります。
  - この問題は Bluetooth ヘッドセットと有線ヘッドセットが混在したケースであり、Bluetooth ヘッドセットの切断、再接続で解消されるため、Sora Unity SDK での対応は行いません。
- 一部の Android 11 端末で USB ヘッドセット接続をしても音声が出力されない事象が発生しています。- Galaxy A21 で本事象を確認しています。
  - 該当の端末についてはイヤホン端子からイヤホンマイクを接続することで音声が出力されることを確認しています。
- Android でワイルドカード証明書やマルチドメイン証明書を利用すると、接続時に `CERTIFICATE_VERIFY_FAILED` エラーが発生し、証明書の検証に失敗することがあります。- この問題は CA 証明書を指定することで回避できるという報告を頂いています。
  - CA 証明書の指定方法は [証明書の指定](functions_ca_cert.html) を参照してください。

> **注意**
>
> AMD AMF はドライバーが不安定なため、現在非推奨です。

- Ubuntu 22.04 環境で AMD AMF (Advanced Media Framework) 6.4.3 によるハードウェアエンコードが利用できない事象が発生しています。- AMD のグラフィックドライバーをインストールしても AMF が利用できないことを確認しています。- [参考 : AMD のグラフィックドライバーインストール手順](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/install/quick-start.html#amdgpu-driver-installation)
  - Ubuntu 24.04 では AMD AMF が正常に動作することを確認しています。
  - AMD AMF を利用したい場合は Ubuntu 24.04 へのアップグレード、または NVIDIA GPU の利用をご検討ください。

<!-- mikan:page doc="2025_2_to_2025_3" -->

# 2025.2.x から 2025.3.x への移行

2025.2.x から 2025.3.x への移行についての注意点をまとめています。

変更内容の詳細については [リリースノート](release.html) を参照してください。

## VideoCodecImplementation の NvidiaVideoCodecSdk を NvidiaVideoCodec に変更しました

`VideoCodecImplementation` 列挙型の `NvidiaVideoCodecSdk` メンバーは、 `NvidiaVideoCodec` に名前が変更されました。

`NvidiaVideoCodecSdk` を使用しているコードは、 `NvidiaVideoCodec` に置き換えてください。

## AMD AMF ハードウェアアクセラレーターを非推奨化しました

`AMD AMF` ハードウェアエンコーダーとデコーダーを一時的に非推奨化しました。

`AMD AMF` 以外のハードウェアアクセラレーターを利用してください。

もし `AMD AMF` を利用する必要がある場合は、[エンコーダー / デコーダーの指定](functions_hardware_acceleration.html) を参照して個別に指定してください。

## Sora.cs を Nullable に対応しました

`Sora.cs` が Nullable に対応しました。

破壊的変更ではありますが、既存コードへの影響はありません。

## selfHandle を利用してコードを整理しました

ユーザー影響はありませんが、selfHandle を利用してコードを整理しました。

合わせて Nullable の対応も行なっています。

<!-- mikan:page doc="functions_audio" -->

# 音声の送信と受信

Sora Unity SDK で音声を送信・受信する際に必要となる設定や API について説明します。

## 音声送信と受信の提供機能について

Sora Unity SDK では以下を提供しています。

- デバイスマイクを音声送信に利用する
- Unity 内で生成した音声を送信する
- 音声送信を一時停止する (ソフトミュート)
- 録音デバイスを利用しない (ハードミュート)
- 利用可能な録音・再生デバイス一覧を取得する
- 受信した音声を任意の方法で再生する
- 音声コーデックやビットレートを指定する
- ハンズフリー切り替えなど再生経路を制御する

### 利用時の注意事項

- `Sora.OnHandleAudio` は Unity スレッドとは別スレッドで呼び出されます。バッファ操作時はロックなどで同期を取ってください
- `Sora.DispatchEvents()` を呼び出さなくても `Sora.OnHandleAudio` は発火します
- `Sora.ProcessAudio()` は 48000Hz Stereo のデータのみ受け取ることができます
- `Config.UnityAudioInput` を `true` にしている場合、`NoAudioDevice` を `true` にしても Unity 側の音声入力は継続します

## 音声関連の API リファレンス

### Sora.Config

`Sora.Config` クラスは Sora インスタンスの接続設定を定義します。音声送信・受信に関する主なプロパティは以下の通りです。

- `Audio`: 音声トラックを有効にするかどうか。`false` にすると停止します
- `NoAudioDevice`: 物理マイクデバイスを利用しない場合に `true` を設定します
- `UnityAudioInput`: Unity で生成した音声を `Sora.ProcessAudio()` から送信する場合に `true` を設定します
- `UnityAudioOutput`: OS の再生デバイスではなく `Sora.OnHandleAudio` コールバックで音声を受け取りたい場合に `true` を設定します
- `AudioRecordingDevice`: 利用する録音デバイスの `DeviceName` または `UniqueName` (空文字ならデフォルトデバイス)
- `AudioPlayoutDevice`: 利用する再生デバイスの `DeviceName` または `UniqueName` (空文字ならデフォルトデバイス)
- `AudioCodecType`: 利用する音声コーデックを指定します (現状は `Sora.AudioCodecType.OPUS` のみ)
- `AudioBitRate`: 音声のビットレート (kbps)。省略時は Sora のデフォルト値になります
- `AudioStreamingLanguageCode`: 字幕用途などで利用する言語コードを指定します

### Sora クラスの音声関連 API

- `Sora.Connect(Sora.Config config)`: 指定した設定で接続します
- `Sora.ProcessAudio(float[] data, int offset, int samples)`: `UnityAudioInput` 利用時に送信したいサンプルを渡します
- `Sora.OnHandleAudio`: `UnityAudioOutput` 利用時に受信音声を取得するコールバック
- `Sora.AudioEnabled`: ソフトミュートのためのトグルプロパティ
- `Sora.GetAudioRecordingDevices()` / `Sora.GetAudioPlayoutDevices()`: 利用可能な録音・再生デバイス一覧を `Sora.DeviceInfo[]` で取得します (列挙に失敗した場合は `null`)
- `Sora.OnMediaStreamTrack`: 受信したトラックを取得するコールバック。音声トラックの場合は `AudioTrack` と `connectionId` を取得できます。`track.Kind` で音声か映像かを判別できます
- `Sora.OnRemoveMediaStreamTrack`: トラックの削除時に通知されます
- `Sora.DispatchEvents()`: メインスレッドでイベントを処理します `OnHandleAudio` 以外のコールバックでは呼び出しが必要です

#### Sora.AudioTrack クラスの API

- `SetVolume(double volume)`: このトラックの再生音量を設定します (0.0〜10.0)

> **注釈**
>
> 音声データを直接取得する機能は、[音声データ取得機能](functions_audio_sink.html) を参照してください。

## 利用方法

### 接続と送受信設定

以下は基本的な送受信設定の例です。例では既に初期化済みの `Sora` インスタンス (`sora`) を利用しています。

```csharp
Sora sora; // 初期化済みの Sora インスタンス
var signalingUrl = "wss://example.com/signaling"; // シグナリング URL
var channelId = "sora"; // チャンネル ID
var unityAudioInput = false; // true なら Unity 内で生成した音声を送信
var unityAudioOutput = false; // true なら再生を Unity 側で処理
var disableDevice = false; // true なら NoAudioDevice を有効化
var recordingDevice = ""; // 空文字ならデフォルト録音デバイス
var playoutDevice = ""; // 空文字ならデフォルト再生デバイス

var config = new Sora.Config()
{
    SignalingUrl = signalingUrl,
    ChannelId = channelId,
    Role = Sora.Role.Sendrecv,
    Audio = true, // 音声送信を有効化
    NoAudioDevice = disableDevice, // 録音デバイスを利用しない場合は true
    UnityAudioInput = unityAudioInput, // Unity 生成音声を送信する場合に true
    UnityAudioOutput = unityAudioOutput, // Unity 側で再生する場合に true
    AudioRecordingDevice = recordingDevice, // 利用する録音デバイス
    AudioPlayoutDevice = playoutDevice, // 利用する再生デバイス
};

sora.Connect(config);
```

### 利用可能なオーディオデバイスの列挙

`Sora.GetAudioRecordingDevices()` と `Sora.GetAudioPlayoutDevices()` を使うと利用可能なデバイスを取得できます。取得結果をログに出力する例です。

```csharp
void DumpDeviceInfo(string label, Sora.DeviceInfo[] devices)
{
    if (devices == null || devices.Length == 0)
    {
        // デバイスが見つからない場合の処理
        Debug.LogWarning($"{label}: device not found");
        return;
    }

    foreach (var device in devices)
    {
        // デバイス情報をログに出力
        Debug.Log($"{label}: DeviceName={device.DeviceName}, UniqueName={device.UniqueName}");
    }
}

void Start()
{
    DumpDeviceInfo("audio recording devices", Sora.GetAudioRecordingDevices());
    DumpDeviceInfo("audio playout devices", Sora.GetAudioPlayoutDevices());
}
```

### 音声コーデックとビットレートの設定

音質に影響する主要な設定について説明します。

#### コーデックの指定

`Sora.Config.AudioCodecType` を使用して利用する音声コーデックを指定できます。省略した場合は Sora サーバーのデフォルト値が使用されます (現状 `OPUS` のみ)。

```csharp
var config = new Sora.Config
{
    SignalingUrl = signalingUrl,
    ChannelId = channelId,
    AudioCodecType = Sora.AudioCodecType.OPUS, // コーデックを指定
};

sora.Connect(config);
```

#### ビットレートの設定

`Sora.Config.AudioBitRate` で送信ビットレート (kbps) を指定できます。省略した場合は Sora サーバーのデフォルト値が使用されます。

```csharp
var config = new Sora.Config
{
    SignalingUrl = signalingUrl,
    ChannelId = channelId,
    AudioBitRate = 64, // 音声のビットレート (kbps) を指定
};

sora.Connect(config);
```

### Unity 音声入力を送信する場合

Unity で生成した音声を送信する場合は `UnityAudioInput` を `true` にし、`Sora.ProcessAudio()` にフレームデータを渡します。

以下は `AudioRenderer` を利用して 1 フレーム分のサンプルを送る例です。

```csharp
void Start()
{
    StartCoroutine(RenderAudio());
}

IEnumerator RenderAudio()
{
    // Unity 内で音を鳴らしておくとキャプチャ状況を確認しやすい
    audioSourceInput.Play();
    // オーディオレンダラーを開始
    AudioRenderer.Start();

    while (true)
    {
        // Sora インスタンスが存在し、Unity 音声入力が有効な場合のみ処理する
        if (sora == null || !unityAudioInput) continue;
        // 1 フレーム分のサンプル数を取得する
        var samples = AudioRenderer.GetSampleCountForCaptureFrame();
        // ステレオモードでない場合はスキップ
        if (AudioSettings.speakerMode != AudioSpeakerMode.Stereo) continue;

        // ステレオ (2 チャンネル) 分のバッファを確保
        using (var buf = new Unity.Collections.NativeArray<float>(samples * 2, Unity.Collections.Allocator.Temp))
        {
            // オーディオデータをレンダリング
            AudioRenderer.Render(buf);
            // Sora 経由で音声データを送信
            sora.ProcessAudio(buf.ToArray(), 0, samples);
        }
    }
}
```

### ソフトミュートとハードミュート

音声ミュートにはデバイスを維持するソフトミュートと、デバイス自体を利用しないハードミュートの 2 種類があります。

ソフトミュートは `Sora.AudioEnabled` を切り替えて行います。この場合マイクデバイスは解放されません。

```csharp
public void ToggleAudio()
{
    if (sora == null) return;
    sora.AudioEnabled = !sora.AudioEnabled;
}
```

ハードミュートは接続時に `Sora.Config.NoAudioDevice` を `true` に設定します。送信中に切り替えることはできないため、設定を変える場合は再接続が必要です。

```csharp
var config = new Sora.Config
{
    SignalingUrl = signalingUrl,
    ChannelId = channelId,
    NoAudioDevice = true, // 物理マイクデバイスを利用しない
};

sora.Connect(config);
```

> **警告**
>
> `UnityAudioInput` が `true` の場合、`NoAudioDevice` を `true` にしても Unity からの音声入力は継続します。

### Unity 内で受信音声を再生する場合

`Config.UnityAudioOutput` を `true` にすると、受信音声が `Sora.OnHandleAudio` でコールバックされます。以下はキューを使って `AudioClip` に流し込む例です。

```csharp
// 受信した音声データを保持するキュー
Queue<short[]> audioBuffer = new Queue<short[]>();
// キューに格納されているサンプル数の合計
int audioBufferSamples = 0;
// 現在読み取り中のチャンク内の位置
int audioBufferPosition = 0;

void SetupAudioOutput()
{
    // 音声データ受信時のコールバックを設定
    sora.OnHandleAudio = (buf, samples, channels) =>
    {
        lock (audioBuffer)
        {
            // 受信したバッファをキューに追加
            audioBuffer.Enqueue(buf);
            // サンプル数を加算
            audioBufferSamples += samples;
        }
    };

    // 複数の受信者がいる場合は、重複にならないよう "Remote_{connectionId}" などを使用してください
    // 48000Hz Stereo のデータのみ受け取ることができます
    var clip = AudioClip.Create("Remote", 480000, 1, 48000, true, data =>
    {
        lock (audioBuffer)
        {
            // バッファが空、またはデータ不足の場合は無音を返す
            if (audioBuffer.Count == 0 || audioBufferSamples < data.Length)
            {
                Array.Fill(data, 0.0f);
                return;
            }

            // キューの先頭チャンクを取得
            var chunk = audioBuffer.Peek();
            // 要求されたデータ長分のサンプルを取り出す
            for (int i = 0; i < data.Length; ++i)
            {
                // 現在のチャンクを読み終えた場合、次のチャンクへ移動
                while (audioBufferPosition >= chunk.Length)
                {
                    audioBuffer.Dequeue();
                    chunk = audioBuffer.Peek();
                    audioBufferPosition = 0;
                }
                // short 型 (±32768) から float 型 (±1.0) に変換
                data[i] = chunk[audioBufferPosition] / 32768.0f;
                ++audioBufferPosition;
            }
            // 処理したサンプル数を減算
            audioBufferSamples -= data.Length;
        }
    });

    // AudioClip を AudioSource にセットして再生開始
    audioSourceOutput.clip = clip;
    audioSourceOutput.Play();
}
```

### ハンズフリー制御 (`Sora.IAudioOutputHelper`)

`Sora.AudioOutputHelperFactory.Create()` で `IAudioOutputHelper` を生成すると、ハンズフリー切り替えなどの再生経路制御が可能になります。詳細は [ハンズフリー](functions_iaudiooutputhelper.html) も参照してください。

```csharp
Sora.IAudioOutputHelper audioOutputHelper;

void InitAudioOutputHelper()
{
    // ルート変更時に呼ばれるコールバックを指定して生成
    audioOutputHelper = Sora.AudioOutputHelperFactory.Create(OnChangeRoute);
}

void OnChangeRoute()
{
    if (audioOutputHelper == null) return;

    // ルート変更を検知して処理を行う
    Debug.Log("音声ルートが変更されました: " +
              (audioOutputHelper.IsHandsfree() ? "ハンズフリー ON" : "ハンズフリー OFF"));
}

public void OnClickHandsfree()
{
    if (audioOutputHelper == null) return;
    audioOutputHelper.SetHandsfree(!audioOutputHelper.IsHandsfree());
}
```

<!-- mikan:page doc="functions_audio_sink" -->

# 音声データ取得機能

Sora Unity SDK では音声トラックから非圧縮の音声データを取得する仕組みを提供しています。

音声トラックを表す `AudioTrack` に `IAudioTrackSink` を関連付けると、音声データを音声トラックごとにコールバックで受け取ることができます。

ここでは、音声データ取得機能と利用方法について説明します。基本的な音声送受信については [音声の送信と受信](functions_audio.html) を参照してください。

## 音声データの形式

コールバックで取得できる音声データは非圧縮の `16 bit PCM (Pulse Code Modulation)` 形式です。

`IAudioTrackSink` インターフェースは以下のように定義されています。

```csharp
public interface IAudioTrackSink
{
    void OnData(short[] data, int bitsPerSample, int sampleRate,
                int numberOfChannels, int numberOfFrames,
                long? absoluteCaptureTimestampMs);
}
```

`OnData()` コールバックのパラメータ:

- `data`: PCM 形式の音声データ (short 配列)
- `bitsPerSample`: 1 サンプル当たりのビット数 (libwebrtc では常に 16)
- `sampleRate`: サンプルレート (単位: Hz)
- `numberOfChannels`: 音声データのチャンネル数 (モノラルなら 1、ステレオなら 2)
- `numberOfFrames`: data に含まれるフレーム数
- `absoluteCaptureTimestampMs`: キャプチャ時刻 (ミリ秒)

## 送信音声データを取得する

`Sora.SenderAudioTrackSink` に `IAudioTrackSink` を実装したクラスを設定すると、送信中の音声データを取得できます。

```csharp
class AudioDataSink : Sora.IAudioTrackSink
{
    public void OnData(short[] data, int bitsPerSample, int sampleRate,
                       int numberOfChannels, int numberOfFrames,
                       long? absoluteCaptureTimestampMs)
    {
        // PCM 音声データを処理
        Debug.Log($"送信音声データ: sampleRate={sampleRate}, channels={numberOfChannels}, frames={numberOfFrames}");
    }
}

void Start()
{
    sora.SenderAudioTrackSink = new AudioDataSink();
}
```

## 受信音声データを取得する

`Sora.OnMediaStreamTrack` コールバックで受信した `AudioTrack` に `IAudioTrackSink` を追加すると、各トラックの音声データを個別に取得できます。

### AudioTrack の識別方法

`IAudioTrackSink.OnData()` で受け取る音声データがどのトラックのものか判断するには、`OnMediaStreamTrack` コールバックで渡される `AudioTrack` や `connectionId` を使用してください。

`connectionId` は Sora サーバーが払い出すコネクション ID です。

### AudioTrackSink と AudioTrack の関連付けについて

- `IAudioTrackSink` と `AudioTrack` の関連付けは **1:1** を前提に設計されています
- 1 つの `IAudioTrackSink` を複数の `AudioTrack` に同時に関連付ける 1:N の利用は想定していません
- 一方で、1 本の `AudioTrack` に対して複数の `IAudioTrackSink` を関連付けることは可能で、各シンクは独立して同一のトラックから音声データを受け取ります

### 実装例

以下は受信音声トラックごとに音声データを取得する例です。

```csharp
class AudioTrackSink : Sora.IAudioTrackSink
{
    public void OnData(short[] data, int bitsPerSample, int sampleRate,
                       int numberOfChannels, int numberOfFrames,
                       long? absoluteCaptureTimestampMs)
    {
        // PCM 音声データを処理
        Debug.Log($"受信音声データ: sampleRate={sampleRate}, channels={numberOfChannels}, frames={numberOfFrames}");
    }
}

Dictionary<string, AudioTrackSink> audioSinks = new Dictionary<string, AudioTrackSink>();

void Start()
{
    sora.OnMediaStreamTrack = (transceiver, track, connectionId) =>
    {
        if (track.Kind == Sora.MediaStreamTrack.AudioKind)
        {
            var audioTrack = track as Sora.AudioTrack;
            var sink = new AudioTrackSink();
            audioTrack.AddSink(sora, sink);
            audioSinks[connectionId] = sink;
        }
    };

    sora.OnRemoveMediaStreamTrack = (receiver, track, connectionId) =>
    {
        if (track.Kind == Sora.MediaStreamTrack.AudioKind && audioSinks.ContainsKey(connectionId))
        {
            var audioTrack = track as Sora.AudioTrack;
            audioTrack.RemoveSink(sora, audioSinks[connectionId]);
            audioSinks.Remove(connectionId);
        }
    };
}
```

<!-- mikan:page doc="functions_video" -->

# 映像の送信と受信

Sora Unity SDK で映像を送信・受信する際に必要となる設定や API について説明します。

デバイスカメラ・Unity カメラの切り替え、ミュート操作、受信映像の描画までを確認できるようになっています。

## 映像送信と受信の提供機能について

Sora Unity SDK では以下を提供しています。

- デバイスカメラを映像送信に利用する
- Unity カメラを映像送信に利用する
- 任意の `Texture` を映像送信に利用する
- 映像送信を一時停止する (ソフトミュート)
- カメラデバイスを利用しない (ハードミュート)
- 利用可能なカメラデバイス一覧を取得する
- 受信した映像を任意のテクスチャに描画する
- 映像コーデックの指定をする
- ハードウェアアクセラレーションの利用を指定する

### プラットフォームと制限

- `Sora.OnCapturerFrame` は Android では利用できません
- iOS や macOS ではカメラアクセス権限が無い場合、デバイス列挙や接続処理が失敗するため権限を付与したうえで利用してください
- Unity カメラ送信や任意のテクスチャを送信する場合は `RenderTextureFormat.BGRA32` が必要となるため、プロジェクト設定で BGRA32 を有効にしてください

## 映像関連の API リファレンス

### Sora.Config

`Sora.Config` クラスは Sora インスタンスの接続設定を定義します。映像送信に関する主なプロパティは以下の通りです。

- `Video`: 映像トラックの送信を有効にするかどうか。`false` にすると映像送信を停止します
- `NoVideoDevice`: 物理カメラデバイスを利用しない場合に `true` を設定します
- `VideoBitRate`: 映像送信のビットレート (kbps)。省略時は接続する Sora のデフォルト値になります
- `CameraConfig`: 使用するカメラソースをまとめた `Sora.CameraConfig` のインスタンス
- `VideoCodecType`: 利用する映像コーデックを指定します。省略時は Sora のデフォルト値になります
- `VideoCodecImplementation`: 利用する映像エンコーダー / デコーダーを指定します。省略時は Internal (libwebrtc 標準) になります
- `VideoVp9Params`: VP9 コーデックのパラメーターを JSON 文字列で指定します。空文字や不正な値の場合は `INVALID-MESSAGE` エラーになります。
- `VideoAv1Params`: AV1 コーデックのパラメーターを JSON 文字列で指定します。空文字や不正な値の場合は `INVALID-MESSAGE` エラーになります。
- `VideoH264Params`: H.264 コーデックのパラメーターを JSON 文字列で指定します。空文字や不正な値の場合は `INVALID-MESSAGE` エラーになります。

### Sora.CameraConfig

`Sora.CameraConfig` クラスはカメラソースを定義します。プロパティは以下の通りです。

- `CapturerType`: カメラの種類を指定します (`DeviceCamera` / `UnityCamera` / `Texture` のいずれかでデフォルトは `DeviceCamera`)
- `UnityCamera`: Unity カメラを送信する場合に指定します
- `UnityCameraRenderTargetDepthBuffer`: Unity カメラのレンダーターゲットに確保する深度バッファビット数を指定します (デフォルトは `16`)
- `VideoCapturerDevice`: 利用する物理カメラの `DeviceName` もしくは `UniqueName` を指定します(空文字の場合はデフォルトデバイスを利用します)
- `VideoWidth`: 映像の幅を指定します(デフォルトは `640`)
- `VideoHeight`: 映像の高さを指定します(デフォルトは `480`)
- `VideoFps`: 映像のフレームレートを指定します(デフォルトは `30`)
- `Texture`: `RenderTexture` を送信する場合に指定します

#### Sora.CameraConfig のヘルパーメソッド

`Sora.CameraConfig` には設定生成を簡単にするヘルパーメソッドが用意されています。

各プロパティを個別に設定する代わりに、これらのメソッドを使うことで適切な設定のインスタンスを簡単に作成できます。

物理カメラを使用する場合:

`Sora.CameraConfig.FromDeviceCamera(string videoCapturerDevice, int videoWidth, int videoHeight, int videoFps)`

端末の内蔵カメラ、外付け Web カメラなどの物理カメラを送信ソースとして設定します。

- `videoCapturerDevice`: `Sora.GetVideoCapturerDevices()` で取得したデバイスの `DeviceName` または `UniqueName` を指定
- `videoWidth`, `videoHeight`: 送信する映像の解像度（例：1280 x 720）
- `videoFps`: 送信するフレームレート（例：30 fps）

Unity カメラを使用する場合:

`Sora.CameraConfig.FromUnityCamera(UnityEngine.Camera unityCamera, int unityCameraRenderTargetDepthBuffer, int videoWidth, int videoHeight, int videoFps)`

Unityシーン内のカメラが映している内容を送信ソースとして設定します。ゲーム画面やCG映像を配信したい場合に使用します。

- `unityCamera`: 送信したい Unity の Camera コンポーネント（例： `Camera.main` ）
- `unityCameraRenderTargetDepthBuffer`: RenderTexture 深度バッファビット数（通常は16または24）
- `videoWidth`, `videoHeight`: 送信する映像の解像度
- `videoFps`: 送信するフレームレート

Texture を使用する場合:

`Sora.CameraConfig.FromTexture(UnityEngine.Texture texture, int videoFps)`

Unity で生成・管理している任意の `Texture` を送信ソースとして指定します。

- `texture`: 送信したい `Texture` （ `RenderTexture` 推奨）
- `videoFps`: 送信するフレームレート

ヘルパーメソッドを利用すると `CapturerType` に応じた必要な設定を利用することができます。

### Sora クラスの映像関連 API

- `Sora.Connect(Sora.Config config)`: 指定した設定で接続します
- `Sora.VideoEnabled`: ソフトミュートのためのトグルプロパティ
- `Sora.SwitchCamera(Sora.CameraConfig cameraConfig)`: 接続中に送信カメラを切り替えます。`NoVideoDevice` の設定に依存せず呼び出します
- `Sora.OnRender()`: Unity カメラを利用する場合に `WaitForEndOfFrame` 後に呼び出してフレームを送信します
- `Sora.OnCapturerFrame`: キャプチャ直後のフレームを受け取るコールバック。別スレッドで実行されます
- `Sora.GetVideoCapturerDevices()`: 利用可能なカメラデバイス一覧を `Sora.DeviceInfo[]` で取得します (列挙に失敗した場合は `null` が返ります)
- `Sora.OnAddTrack` / `Sora.OnRemoveTrack`: 受信映像トラックの追加・削除時に通知されます
- `Sora.GetVideoTrackFromVideoSinkId(uint videoSinkId)`: `videoSinkId` から対応する `VideoTrack` を取得します。指定した `videoSinkId` に対応する `VideoTrack` が見つからない場合は例外をスローします
- `Sora.VideoTrack`: 映像トラックを表します。 `Sora.GetVideoTrackFromVideoSinkId()` や `Sora.OnMediaStreamTrack` で取得できます- `VideoTrack.GetVideoSinkId(Sora sora)`: この `VideoTrack` に対応する `videoSinkId` を取得します
- `Sora.RenderTrackToTexture(uint videoSinkId, Texture texture)`: `videoSinkId` で受信した映像を `texture` にレンダリングします。送信中の場合、自身の `videoSinkId` を指定すれば送信映像もレンダリングできます
- `Sora.DispatchEvents()`: メインスレッドでイベントを処理するために `Update()` などから呼び出します

## 利用方法

### 接続と送信設定

以下は基本的な送信設定の例です。例では既に初期化済みの `Sora` インスタンス (`sora`) を利用しています。

```csharp
// Inspector などで取得した設定値をもとに送信設定を組み立てる例
Sora sora; // 初期化済みの Sora インスタンス
var signalingUrl = "wss://example.com/signaling"; // シグナリング URL
var channelId = "sora"; // チャンネル ID
var selectedDevice = "camera_unique_name"; // 利用するデバイスカメラ名
Camera capturedCamera = Camera.main; // Unity カメラ送信時に利用するカメラ
var renderTargetDepth = 16; // RenderTexture の深度バッファビット数
int videoWidth = 1280; // 映像の幅
int videoHeight = 720; // 映像の高さ
int videoFps = 30; // 映像のフレームレート
int videoBitRate = 1500; // 映像のビットレート (kbps)
var useUnityCamera = false; // true なら Unity カメラを送信
var disableDevice = false; // true なら NoVideoDevice を有効化

var config = new Sora.Config
{
    SignalingUrl = signalingUrl,
    ChannelId = channelId,
    Role = Sora.Role.Sendrecv,
    Video = true, // 映像送信を有効化
    NoVideoDevice = disableDevice, // 物理カメラデバイスを利用しない場合は true
    VideoBitRate = videoBitRate, // 送信ビットレート (kbps)
};

// 物理カメラか Unity カメラかを判定してカメラソースを設定
// 使用するカメラに応じて、ヘルパーメソッドで CameraConfig を生成します
// useUnityCamera が true かつ capturedCamera が null でない場合は Unity カメラを使用します
// それ以外の場合、物理カメラデバイスを使用 (Web カメラなどの実カメラを送信)します
config.CameraConfig = useUnityCamera && capturedCamera != null
    ? Sora.CameraConfig.FromUnityCamera(capturedCamera, renderTargetDepth, videoWidth, videoHeight, videoFps)
    : Sora.CameraConfig.FromDeviceCamera(selectedDevice, videoWidth, videoHeight, videoFps);

sora.Connect(config);
```

### 利用可能なカメラデバイスの列挙

`Sora.GetVideoCapturerDevices()` を使うと利用可能なカメラデバイスを取得できます。

戻り値は `Sora.DeviceInfo[]` で、列挙が失敗した場合は `null` が返ります。

取得したデバイス名、UniqueName を使って `Sora.CameraConfig.VideoCapturerDevice` に設定できます。

ここでは取得結果をログに出力する例を示します。

```csharp
void DumpDeviceInfo(string label, Sora.DeviceInfo[] devices)
{
    if (devices == null || devices.Length == 0)
    {
        // デバイスが見つからない場合の処理
        Debug.LogWarning($"{label}: device not found");
        return;
    }

    foreach (var device in devices)
    {
        // DeviceName と UniqueName をログに出力
        Debug.Log($"{label}: DeviceName={device.DeviceName}, UniqueName={device.UniqueName}");
    }
}

void Start()
{
    // 例として起動時にデバイス一覧を出力
    DumpDeviceInfo("video capturer devices", Sora.GetVideoCapturerDevices());
}
```

### 映像コーデックとビットレートの設定

映像品質に影響する主要な設定について説明します。

#### コーデックの指定

`Sora.Config.VideoCodecType` を使用して利用する映像コーデックを指定できます。省略した場合は Sora サーバーのデフォルト値が使用されます。

利用可能なコーデック:

- `Sora.VideoCodecType.VP9`
- `Sora.VideoCodecType.VP8`
- `Sora.VideoCodecType.H264`
- `Sora.VideoCodecType.AV1`
- `Sora.VideoCodecType.H265`

コーデックを利用する前に、クライアントがそのエンコーダ／デコーダを利用可能か `Sora.GetVideoCodecCapability()` で確認してください。

`Encoder / Decoder` が `true` でないコーデックを指定すると、接続処理や切断処理でクラッシュする恐れがあります。

#### コーデックパラメーターの指定

各コーデックには詳細なパラメーターを設定できます。

##### VP9 のパラメーター

`Sora.Config.VideoVp9Params` で VP9 コーデックのプロファイル ID を JSON 文字列として指定できます。

```csharp
// SoraSample.cs を参考にした VP9 のパラメーターを設定するサンプルコード
// enableVideoVp9Params が true の場合に VP9 パラメーターを設定します

// VP9 パラメーターを設定する場合有効にする
public bool enableVideoVp9Params = false;
// VP9 パラメーターを設定 0, 1, 2, 3 が利用可能
public int videoVp9ParamsProfileId;

// VP9 パラメーターを設定する場合は JSON 文字列を設定する
string videoVp9ParamsJson = "";
if (enableVideoVp9Params)
{
    var vp9Params = new VideoVp9Params()
    {
        profile_id = videoVp9ParamsProfileId
    };
    videoVp9ParamsJson = JsonUtility.ToJson(vp9Params);
}

var config = new Sora.Config
{
    SignalingUrl = signalingUrl,
    ChannelId = channelId,
    VideoCodecType = Sora.VideoCodecType.VP9,
    VideoVp9Params = videoVp9ParamsJson,
};
```

##### AV1 のパラメーター

`Sora.Config.VideoAv1Params` で AV1 コーデックのプロファイルを JSON 文字列として指定できます。

```csharp
// SoraSample.cs を参考にした AV1 のパラメーターを設定するサンプルコード
// enableVideoAv1Params が true の場合に AV1 パラメーターを設定します

// AV1 パラメーターを設定する場合有効にする
public bool enableVideoAv1Params = false;
// AV1 パラメーターを設定 0, 1, 2 が利用可能
public int videoAv1ParamsProfile;

// AV1 パラメーターを設定する場合は JSON 文字列を設定する
string videoAv1ParamsJson = "";
if (enableVideoAv1Params)
{
    var av1Params = new VideoAv1Params()
    {
        profile = videoAv1ParamsProfile
    };
    videoAv1ParamsJson = JsonUtility.ToJson(av1Params);
}

var config = new Sora.Config
{
    SignalingUrl = signalingUrl,
    ChannelId = channelId,
    VideoCodecType = Sora.VideoCodecType.AV1,
    VideoAv1Params = videoAv1ParamsJson,
};
```

##### H.264 のパラメーター

`Sora.Config.VideoH264Params` で H.264 コーデックのプロファイルレベル ID を JSON 文字列として指定できます。

```csharp
// SoraSample.cs を参考にした H.264 のパラメーターを設定するサンプルコード
// enableVideoH264Params が true の場合に H.264 パラメーターを設定します

// H.264 パラメーターを設定する場合有効にする
public bool enableVideoH264Params = false;
// H.264 パラメーターを設定
// 例: "42e01f" はレベル 3.1
public string videoH264ParamsProfileLevelId = "";

// H.264 パラメーターを設定する場合は JSON 文字列を設定する
string videoH264ParamsJson = "";
if (enableVideoH264Params)
{
    var h264Params = new VideoH264Params()
    {
        profile_level_id = videoH264ParamsProfileLevelId
    };
    videoH264ParamsJson = JsonUtility.ToJson(h264Params);
}

var config = new Sora.Config
{
    SignalingUrl = signalingUrl,
    ChannelId = channelId,
    VideoCodecType = Sora.VideoCodecType.H264,
    VideoH264Params = videoH264ParamsJson,
};
```

#### ビットレートの設定

`Sora.Config.VideoBitRate` で送信ビットレート（kbps）を指定できます。省略した場合は Sora サーバーのデフォルト値が使用されます。

```csharp
var config = new Sora.Config
{
    SignalingUrl = signalingUrl,
    ChannelId = channelId,
    VideoCodecType = Sora.VideoCodecType.H264, // コーデックを指定
    VideoBitRate = 1500, // ビットレート(kbps)を指定
};

sora.Connect(config);
```

`VideoCodecImplementation` を使用してエンコーダー/デコーダーの実装を指定することも可能です。

詳細は [エンコーダー / デコーダーの指定](functions_hardware_acceleration.html) を参照してください。

### Unity カメラを送信する場合

Unity カメラを映像送信に利用する場合の設定と実装方法を説明します。

#### 設定方法

Unity カメラを使用する場合は `CameraConfig` で `CapturerType.UnityCamera` を指定し、送信したいカメラを設定します。

```csharp
var config = new Sora.Config
{
    SignalingUrl = signalingUrl,
    ChannelId = channelId,
    CameraConfig = new Sora.CameraConfig()
    {
        CapturerType = Sora.CapturerType.UnityCamera,
        UnityCamera = capturedCamera, // 送信したいCamera
        VideoFps = 30,
        VideoWidth = 1280,
        VideoHeight = 720,
    },
};
```

または、ヘルパーメソッドを使用することもできます：

```csharp
config.CameraConfig = Sora.CameraConfig.FromUnityCamera(capturedCamera, 16, 1280, 720, 30);
```

#### フレーム送信の実装

Unity カメラを送信する際は `WaitForEndOfFrame` の最後で `Sora.OnRender()` を呼び出します。

この処理はコルーチンとして実装し、`Start()` などで開始してください。

```csharp
void Start()
{
    StartCoroutine(Render());
}

IEnumerator Render()
{
    while (true)
    {
        yield return new WaitForEndOfFrame(); // Unity の描画完了を待機
        if (sora != null)
        {
            // OnRender() は必ず WaitForEndOfFrame の後に呼び出すこと
            sora.OnRender(); // Unity カメラの映像フレームを Sora に転送
        }
    }
}
```

### Texture を送信する場合

`CapturerType.Texture` を使うと、任意の `Texture` を映像トラックとして送信できます。ポストプロセス済みのゲーム画面やコンピュートシェーダーの結果などを配信したい場合に有効です。

> **注釈**
>
> `Texture2D` なども指定できますが、ピクセルを書き換えるたびに Unity が内部テクスチャを作り直し、以前に取得した `GetNativeTexturePtr()` が無効になります。
> Sora に渡したポインタが切れてしまうため、動的に更新する場合は `RenderTexture` を Sora に渡し、`Graphics.Blit(Texture2D, RenderTexture)` などで内容を反映させる運用を推奨します。

#### 設定例

```csharp
// 生成した RenderTexture を Sora に送信し、かつ画面に表示するサンプル
// 事前に RenderTexture を用意していない場合でも自動で生成します

Sora sora;
// RenderTexture を送る(Inspector で割り当て可。未設定なら生成)
public RenderTexture captureTargetTexture;
// captureTargetTexture の内容を画面表示する Texture
public Texture2D stagingTexture;

InitSora();

GetVideoSize(videoSize, out var videoWidth, out var videoHeight);

// RenderTexture 未割り当てなら生成
if (captureTargetTexture == null)
{
    captureTargetTexture = new RenderTexture(videoWidth, videoHeight, 16, RenderTextureFormat.BGRA32);
    captureTargetTexture.Create();
}
else if (!captureTargetTexture.IsCreated())
{
    captureTargetTexture.Create();
}

// stagingTexture もサイズを揃える
if (stagingTexture == null ||
    stagingTexture.width != captureTargetTexture.width ||
    stagingTexture.height != captureTargetTexture.height)
{
    stagingTexture = new Texture2D(captureTargetTexture.width, captureTargetTexture.height, TextureFormat.BGRA32, false);
}

// stagingTexture を更新して RenderTexture に反映(内容を書き換えた直後に呼ぶ)
stagingTexture.Apply(false, false);
Graphics.Blit(stagingTexture, captureTargetTexture);

// RenderTexture を送る設定
var cameraConfig = Sora.CameraConfig.FromTexture(captureTargetTexture, videoFps);

var config = new Sora.Config()
{
    SignalingUrl = signalingUrl,
    ChannelId = channelId,
    CameraConfig = cameraConfig,
};
sora.Connect(config);

// 毎フレーム更新したい場合は Update() で
void Update()
{
    if (stagingTexture != null && captureTargetTexture != null)
    {
        stagingTexture.Apply(false, false);
        Graphics.Blit(stagingTexture, captureTargetTexture);
    }
}
```

### カメラの切り替え

接続中にデバイスカメラとUnityカメラを切り替える場合は `SwitchCamera()` を使用します。

```csharp
// クラスのフィールドとして定義
Sora sora;
public Camera capturedCamera;
public string videoCapturerDevice = "";

public void SwitchToUnityCamera()
{
    if (sora == null) return;
    sora.SwitchCamera(Sora.CameraConfig.FromUnityCamera(capturedCamera, 16, 1280, 720, 30));
}

public void SwitchToDeviceCamera()
{
    if (sora == null) return;
    sora.SwitchCamera(Sora.CameraConfig.FromDeviceCamera(videoCapturerDevice, 1280, 720, 30));
}
```

### ソフトミュートとハードミュート

ミュートにはデバイスを維持するソフトミュートと、デバイス自体を利用しないハードミュートの 2 種類があります。

ソフトミュートは `Sora.VideoEnabled` を切り替えて行います。この場合カメラデバイスは解放されません。

```csharp
public void ToggleVideo()
{
    if (sora == null) return;
    sora.VideoEnabled = !sora.VideoEnabled;
}
```

カメラデバイスを利用しないハードミュートは接続時に `Sora.Config.NoVideoDevice` を `true` に設定することで行います。

> **警告**
>
> 送信中ハードウェアミュートに切り替えることはできず、再接続をする必要があります。

`Sora.SwitchCamera()` を呼び出すとカメラを取得しに行くため、ハードミュート中は呼び出さないでください。

意図せずカメラを取得してミュートが解除されることがあります。

```csharp
var config = new Sora.Config
{
    SignalingUrl = signalingUrl,
    ChannelId = channelId,
    NoVideoDevice = true, // 物理カメラデバイスを利用しない
};

sora.Connect(config);
```

### 映像受信の処理

受信した映像トラックは `OnAddTrack` / `OnRemoveTrack` で管理し、`RenderTrackToTexture` で描画します。

`connectionId` が空文字の場合は自身の映像です。

この例は SoraUnitySdkExamples の SoraSample.cs にもありますのでそちらも参考にしてください。

```csharp
// 受信映像トラックを管理するためのDictionary
Dictionary<string, GameObject> tracks = new Dictionary<string, GameObject>();

// 映像トラックが追加された時のコールバック
sora.OnAddTrack = (videoSinkId, connectionId) =>
{
    // UI要素を生成(baseContentはプリファブとして事前に用意)
    // Hierarchy に Canvas を作成して RawImage を対象にすると簡単です
    var obj = Instantiate(baseContent);
    obj.name = $"track {videoSinkId}";
    obj.transform.SetParent(scrollViewContent.transform);
    obj.SetActive(true);

    // 映像を描画するためのテクスチャを生成
    var image = obj.GetComponent<UnityEngine.UI.RawImage>();
    image.texture = new Texture2D(320, 240, TextureFormat.RGBA32, false);

    // トラック管理用のDictionaryに追加
    tracks[videoSinkId] = obj;
};

// 映像トラックが削除された時のコールバック
sora.OnRemoveTrack = (videoSinkId, connectionId) =>
{
    if (!tracks.TryGetValue(videoSinkId, out var obj)) return;

    // テクスチャとGameObjectを適切に破棄
    var image = obj.GetComponent<UnityEngine.UI.RawImage>();
    Destroy(image.texture);
    Destroy(obj);
    tracks.Remove(videoSinkId);
};

void Update()
{
    if (sora == null) return;

    // 受信イベントをメインスレッドで処理(必須)
    sora.DispatchEvents();

    // 各トラックの映像をテクスチャに描画
    foreach (var pair in tracks)
    {
        var image = pair.Value.GetComponent<UnityEngine.UI.RawImage>();
        // 受信映像をテクスチャに描画(毎フレーム呼び出す)
        sora.RenderTrackToTexture(pair.Key, image.texture);
    }
}
```

<!-- mikan:page doc="functions_simulcast" -->

# サイマルキャスト機能

Sora Unity SDK のサイマルキャスト機能について説明します。

サイマルキャスト機能は、配信時に 1 つの RTCPeerConnection から複数の画質の映像を配信する機能です。

サイマルキャストの詳細については Sora の [サイマルキャスト機能](https://sora-doc.shiguredo.jp/SIMULCAST) をご確認ください。

## サイマルキャストの有効化

サイマルキャスト機能を有効にするには、`Sora.Config.Simulcast` プロパティを `true` に設定します。

```csharp
// Simulcast を有効化する例
// Inspector で設定可能にする
public bool simulcast = false;
// config に Simulcast プロパティを追加し、 true に設定
var config = new Sora.Config
{
    SignalingUrl = signalingUrl,
    ChannelId = channelId,
    Role = Role,
    CameraConfig = new Sora.CameraConfig()
    {
        CapturerType = captureUnityCamera && capturedCamera != null ? Sora.CapturerType.UnityCamera : Sora.CapturerType.DeviceCamera,
        UnityCamera = capturedCamera,
        VideoFps = videoFps,
        // 3 つの画質を配信するために解像度を 1080p に設定
        VideoWidth = 1920,
        VideoHeight = 1080,
        VideoCapturerDevice = videoCapturerDevice,
    },
    // 3 つの画質を配信するために H264 でビットレートを 5000 kbps に設定
    VideoCodecType = Sora.VideoCodecType.H264,
    VideoBitRate = 5000,
    // Simulcast を有効化
    Simulcast = true,
};

sora.Connect(config);
```

## 受信する映像の画質の指定 (SimulcastRid)

> **注釈**
>
> 2027 年 12 月リリース予定の Sora で廃止予定のため、Sora Unity SDK 2026.1.0 以降は非推奨となります。代わりに SimulcastRequestRid を使用してください。

シグナリング時に受信する映像の画質 (rid) を指定することができます。

この機能は Sendrecv / Recvonly でのみ利用可能です。

シグナリング時にサイマルキャストの rid を指定するには、`Sora.Config.SimulcastRid` を指定します。

指定可能な rid は R0, R1, R2 の 3 種類です。

```csharp
// Simulcast rid を指定する例
// Inspector で設定可能にする
// enable フラグを用意して指定するか未指定かを切り替え可能にする
public bool enableSimulcastRid = false;
// 指定する rid を用意する(R0, R1, R2 のいずれか)
public Sora.SimulcastRidType simulcastRid = Sora.SimulcastRidType.R0;

// config に SimulcastRid プロパティを追加し、 rid の配列を設定します
var config = new Sora.Config
{
    SignalingUrl = signalingUrl,
    ChannelId = channelId,
    // sendrecv / recvonly でのみ利用可能
    Role = Sora.Role.Sendrecv,
    CameraConfig = new Sora.CameraConfig()
    {
        CapturerType = captureUnityCamera && capturedCamera != null ? Sora.CapturerType.UnityCamera : Sora.CapturerType.DeviceCamera,
        UnityCamera = capturedCamera,
        VideoFps = videoFps,
        // 3 つの画質を配信するために解像度を 1080p に設定
        VideoWidth = 1920,
        VideoHeight = 1080,
        VideoCapturerDevice = videoCapturerDevice,
    },
    // 3 つの画質を配信するために H264 でビットレートを 5000 kbps に設定
    VideoCodecType = Sora.VideoCodecType.H264,
    VideoBitRate = 5000,
    // Simulcast を有効化
    Simulcast = true,
};
// rid を指定する場合のみプロパティを追加
if (enableSimulcastRid)
{
    config.SimulcastRid = simulcastRid;
}
sora.Connect(config);
```

## 受信する映像の画質の指定 (SimulcastRequestRid)

> **注釈**
>
> Sora 2025.2.0 以降で利用可能です

シグナリング時に受信する映像の画質 (rid) を指定することができます。

この機能は Sendrecv / Recvonly でのみ利用可能です。

シグナリング時にサイマルキャストリクエストの rid を指定するには、`Sora.Config.SimulcastRequestRid` プロパティに rid を指定します。

指定可能な rid は none, R0, R1, R2 の 4 種類です。

```csharp
// Simulcast Request rid を指定する例
// Inspector で設定可能にする
// enable フラグを用意して指定するか未指定かを切り替え可能にする
public bool enableSimulcastRequestRid = false;
// 指定する rid を用意する(none, R0, R1, R2 のいずれか)
public Sora.SimulcastRequestRidType simulcastRequestRid = Sora.SimulcastRequestRidType.R0;

// config に SimulcastRequestRid プロパティを追加し、rid の配列を設定します
var config = new Sora.Config
{
    SignalingUrl = signalingUrl,
    ChannelId = channelId,
    // sendrecv / recvonly でのみ利用可能
    Role = Sora.Role.Sendrecv,
    CameraConfig = new Sora.CameraConfig()
    {
        CapturerType = captureUnityCamera && capturedCamera != null ? Sora.CapturerType.UnityCamera : Sora.CapturerType.DeviceCamera,
        UnityCamera = capturedCamera,
        VideoFps = videoFps,
        // 3 つの画質を配信するために解像度を 1080p に設定
        VideoWidth = 1920,
        VideoHeight = 1080,
        VideoCapturerDevice = videoCapturerDevice,
    },
    // 3 つの画質を配信するために H264 でビットレートを 5000 kbps に設定
    VideoCodecType = Sora.VideoCodecType.H264,
    VideoBitRate = 5000,
    // Simulcast を有効化
    Simulcast = true,
};
// rid を指定する場合のみプロパティを追加
if (enableSimulcastRequestRid)
{
    config.SimulcastRequestRid = simulcastRequestRid;
}
sora.Connect(config);
```

<!-- mikan:page doc="functions_getstats" -->

# 統計情報

Sora Unity SDK の統計情報機能について説明します。

この機能を利用することで、接続状況や通信品質を把握することができます。

## 統計情報の取得機能について

統計情報の取得機能は、`Sora.GetStats` メソッドを利用して取得することができます。

このメソッドは内部で WebRTC の RTCStatsReport を利用し、統計データを取得します。

## 利用方法

統計情報の取得は一定間隔に行うことを推奨します。

ここではコルーチンを使用して 10 秒間隔で統計情報を取得し Debug.Log に出力する方法を示します。

```csharp
// Soraインスタンス
private Sora sora;
// 接続状態
// 接続状態を見て統計情報の取得を制御する
private State state;

private enum State
{
    Init,
    Started,
    Disconnecting,
}

IEnumerator GetStats()
{
    while (true)
    {
        // 10秒間隔で取得
        yield return new WaitForSeconds(10);

        // 接続中の場合のみ取得
        if (state != State.Started)
        {
            continue;
        }

        sora.GetStats((stats) =>
        {
            // 注意: このコールバックは Unity メインスレッドとは別のスレッドで実行される
            Debug.LogFormat("GetStats: {0}", stats);
        });
    }
}
```

Start() メソッドでコルーチンを開始します。

```csharp
void Start()
{
    StartCoroutine(GetStats());
}
```

<!-- mikan:page doc="functions_iaudiooutputhelper" -->

# ハンズフリー

iOS と Android デバイスでのみ `IAudioOutputHelper` を利用することでハンズフリーができます。

ハンズフリーではヘッドセットの接続有無によって以下のように挙動が変わります。

- ヘッドセットが接続されていない場合は通話用スピーカーと通常のスピーカーが切り替わります
- ヘッドセットが接続されている場合は、ヘッドセットのスピーカーとマイクから端末の通常のスピーカーとマイクへ切り替わります
- マイクなしイヤホン接続時の動作は考慮されておらず、イヤホンによりマイクが利用できなくなることがあります

## ハンズフリーの挙動について

ハンズフリーの挙動は実行するプラットフォームによって以下のような違いがあります。

### Android の Bluetooth ヘッドセット接続時に音声通話スピーカーから音が出るケースがある

- Android は ハンズフリーの状態から Bluetooth ヘッドセットに切り替えを行う際に一度音声通話スピーカーから音が出たあとに Bluetooth ヘッドセットに切り替わります- Bluetooth ヘッドセット接続までにタイムラグがあるため、切り替わるまでの時間に音声通話スピーカーから音が出ます
- iOS では Bluetooth ヘッドセット接続時に音声通話スピーカーから音が出ることはありません

### ハンズフリー機能を有効にしてから切断し、再接続した場合の動作差異

- iOS ではハンズフリー機能を有効にしてから切断し、再接続した場合にはハンズフリー機能が有効の状態となります。
- Android ではハンズフリー機能を有効にしてから切断し、再接続した場合に、切断前の有効状態を維持せずにハンズフリーは無効の状態に戻ります- Android でハンズフリー機能有効の状態で開始した際に Android API が正常に動作せずハンズフリー無効の状態に切り替えられなくなる事象があったため、ハンズフリーは必ず無効の状態から開始する対応としましたAndroid でハンズフリーの設定を維持する場合はアプリ側で設定を保持し、再接続後に切断前の状態を再設定する必要があります

## 利用方法

ハンズフリーの利用方法は以下の通りです。

ここでは例として、UI ボタンのクリックイベントを利用してハンズフリーの ON/OFF を切り替えています。

```csharp
// IAudioOutputHelper のインスタンスを取得する
Sora.IAudioOutputHelper audioOutputHelper;

void Start()
{
    // アプリケーションの初期処理で AudioOutputHelper のインスタンスを作成する
    // 引数には Action を設定する。一例としてここではルート変更時にログ出力を行う
    audioOutputHelper = Sora.AudioOutputHelperFactory.Create(() => { Debug.Log("OnChangeRoute"); });
}

void OnApplicationQuit()
{
    DisposeSora();

    // audioOutputHelper のインスタンスが存在しない場合は処理を抜ける
    if (audioOutputHelper == null)
    {
        return;
    }

    // アプリケーション終了時に IAudioOutputHelper のインスタンスを破棄する
    audioOutputHelper.Dispose();
}

/*
ハンズフリーの ON/OFF を切り替える。
例として UI ボタンのクリックイベント用に OnClickSetHandsfree() を作成する。
*/
public void OnClickSetHandsfree()
{
    // Sora がいない場合は何もしない
    if (sora == null)
    {
        return;
    }

    // audioOutputHelper のインスタンスが存在しない場合は処理を抜ける
    if (audioOutputHelper == null)
    {
        return;
    }

    // 現在のハンズフリーの状態を取得する
    bool isHandsfree = audioOutputHelper.IsHandsfree();
    // ハンズフリーの状態を反転させる
    audioOutputHelper.SetHandsfree(!isHandsfree);
}
```

## ハンズフリー利用時の注意点

ハンズフリーは音声の送受信利用を前提としています。

そのため、Sendonly, Recvonly や NoAudioDevice といった設定ではハンズフリーは利用できません。

上記の補足として iOS の音声デバイスの仕様を以下に記載します。

Sora Unity SDK 内の iOS の実装では音声デバイスを利用しない場合、 AVAudioSession の カテゴリを PlayAndRecord にせず、デフォルトのまま利用します。

Sora Unity SDK のハンズフリーは Sora C++ SDK で実装されています。

その中で iOS のハンズフリー実装は `overrideOutputAudioPort(_:)` を使用して実現しており、このメソッドは PlayAndRecord 以外のカテゴリでは利用できません。

参考：[overrideOutputAudioPort(_:)](https://developer.apple.com/documentation/avfaudio/avaudiosession/1616443-overrideoutputaudioport)

<!-- mikan:page doc="functions_messaging" -->

# リアルタイムメッセージング機能

Sora Unity SDK のリアルタイムメッセージング機能について説明します。

この機能を利用することで、チャネル参加者に対してリアルタイムにメッセージを送受信することができます。

## リアルタイムメッセージング機能について

リアルタイムメッセージング機能を利用するためには、`data_channel_signaling` を有効にする必要があります。

細かな設定方法については [Sora ドキュメント](https://sora-doc.shiguredo.jp/MESSAGING) を参照してください。

## Sora Unity SDK の実装内容

Sora Unity SDK では、リアルタイムメッセージング機能を利用するための実装を以下のように提供しています。

```csharp
// データチャネルの設定を保持するクラス
public class DataChannel
{
    // 必須設定項目
    public string Label = ""; // チャネルのラベル
    public Direction Direction = Sora.Direction.Sendrecv; // チャネルの送受信方向

    // 以下はオプション設定
    public bool? Ordered; // メッセージの順序保証
    public int? MaxPacketLifeTime; // パケットの最大寿命 (ms 単位)
    public int? MaxRetransmits; // 最大再送回数
    public string? Protocol; // チャネルで使用するプロトコル名
    public bool? Compress; // データの圧縮を有効化するか
    public List<string>? Header; // ヘッダー情報
}

// データチャネルの設定を保持するリスト
public List<DataChannel> DataChannels = new List<DataChannel>();

// config.DataChannels の設定を内部のデータチャネル構造に変換して追加
foreach (var m in config.DataChannels)
{
    // データチャネルの方向を文字列形式に変換
    var direction =
        m.Direction == Direction.Sendonly ? "sendonly" :
        m.Direction == Direction.Recvonly ? "recvonly" : "sendrecv";

    // 内部のデータチャネル設定オブジェクトを生成
    var c = new SoraConf.Internal.DataChannel()
    {
        label = m.Label, // ラベルを設定
        direction = direction, // 送受信方向を設定
    };

    // オプション項目を設定 (null でない場合のみ)
    if (m.Ordered != null)
    {
        c.SetOrdered(m.Ordered.Value); // 順序保証を設定
    }
    if (m.MaxPacketLifeTime != null)
    {
        c.SetMaxPacketLifeTime(m.MaxPacketLifeTime.Value); // 最大寿命を設定
    }
    if (m.MaxRetransmits != null)
    {
        c.SetMaxRetransmits(m.MaxRetransmits.Value); // 最大再送回数を設定
    }
    if (m.Protocol != null)
    {
        c.SetProtocol(m.Protocol); // プロトコル名を設定
    }
    if (m.Compress != null)
    {
        c.SetCompress(m.Compress.Value); // 圧縮の有効/無効を設定
    }
    if (m.Header != null)
    {
        // ヘッダー情報を設定 (リストを内部形式に変換)
        c.SetHeader(new SoraConf.Internal.DataChannel.Header { content = m.Header });
    }

    // 内部データチャネルリストに追加
    cc.data_channels.Add(c);
}

// メッセージの受信
public Action<string, byte[]> OnMessage
{
    set
    {
        if (onMessageHandle.IsAllocated)
        {
            onMessageHandle.Free();
        }

        onMessageHandle = GCHandle.Alloc(value);
        sora_set_on_message(p, MessageCallback, GCHandle.ToIntPtr(onMessageHandle));
    }
}
```

## 利用方法

リアルタイムメッセージング機能を利用するためには、以下の条件を満たす必要があります。

- Sora の設定でリアルタイムメッセージング機能が利用可能になっていること
- `data_channel_signaling` が有効になっていること
- `data_channels` の設定が行われていること
- `#` から始まる `label` が設定されていること
- `direction` が設定されていること

以下に Sora Unity SDK Samples でのリアルタイムメッセージング機能の利用方法を示します。

設定は Inspector で実施することを想定したものです。

また、メッセージの送信はゲーム画面上の UI から行うことを想定しています。

ご利用になる用途に合わせて適宜変更してください。

```csharp
// データチャネルの設定をするクラス
[System.Serializable]
public class DataChannel
{
    // 必須設定項目
    public string label = ""; // データチャネルのラベル
    public Sora.Direction direction = Sora.Direction.Sendrecv; // チャネルの送受信方向

    // 以下は各オプション項目を有効にするためのフラグと設定値
    public bool enableOrdered; // 順序保証を有効化するか
    public bool ordered; // メッセージの順序保証設定
    public bool enableMaxPacketLifeTime; // パケット寿命設定を有効化するか
    public int maxPacketLifeTime; // パケットの最大寿命
    public bool enableMaxRetransmits; // 最大再送回数設定を有効化するか
    public int maxRetransmits; // 最大再送回数
    public bool enableProtocol; // プロトコル設定を有効化するか
    public string protocol; // 使用するプロトコル名
    public bool enableCompress; // 圧縮設定を有効化するか
    public bool compress; // 圧縮の有効/無効設定
    public bool enableHeader; // ヘッダー設定を有効化するか
    public string[] header; // ヘッダー情報 (文字列の配列)
}
[Header("リアルタイムメッセージングの設定")]
public DataChannel[] dataChannels;
string[] fixedDataChannelLabels;
```

Sora に接続する際に設定を行う部分の例を以下に示します。

```csharp
// Sora インスタンスの宣言
Sora sora;
// Sora.Config インスタンスの生成
var config = new Sora.Config();

// dataChannels が設定されている場合、処理を開始
if (dataChannels != null)
{
    foreach (var m in dataChannels)
    {
        // 新しい Sora.DataChannel インスタンスを生成
        var c = new Sora.DataChannel();
        c.Label = m.label; // ラベルを設定
        c.Direction = m.direction; // 送受信方向を設定

        // 各オプション項目の設定 (有効フラグを確認)
        if (m.enableOrdered)
        {
            c.Ordered = m.ordered; // 順序保証を設定
        }
        if (m.enableMaxPacketLifeTime)
        {
            c.MaxPacketLifeTime = m.maxPacketLifeTime; // 最大寿命を設定
        }
        if (m.enableMaxRetransmits)
        {
            c.MaxRetransmits = m.maxRetransmits; // 最大再送回数を設定
        }
        if (m.enableProtocol)
        {
            c.Protocol = m.protocol; // プロトコル名を設定
        }
        if (m.enableCompress)
        {
            c.Compress = m.compress; // 圧縮設定を有効/無効化
        }
        if (m.enableHeader)
        {
            // ヘッダー情報を文字列配列からリストに変換して設定
            c.Header = m.header.ToList();
        }

        // 設定済みのデータチャネルを config に追加
        config.DataChannels.Add(c);
    }

    // 設定したデータチャネルのラベルを配列に抽出
    fixedDataChannelLabels = config.DataChannels.Select(x => x.Label).ToArray();
}
```

メッセージの送信は以下のように行います。

```csharp
// Sora インスタンスの宣言
Sora sora;

public void OnClickSend()
{
    if (fixedDataChannelLabels == null || sora == null)
    {
        return;
    }
    // リアルタイムメッセージングを使って全てのラベルに適当なデータを送る
    // ここでは "aaa" という文字列を送信している
    foreach (var label in fixedDataChannelLabels)
    {
        string message = "aaa";
        sora.SendMessage(label, System.Text.Encoding.UTF8.GetBytes(message));
    }
}
```

メッセージの受信は以下のように行います。

```csharp
// Sora インスタンスの宣言
Sora sora;

sora.OnMessage = (label, data) =>
{
    // 受信したメッセージのラベルとデータをログ出力
    // dataはバイト配列として受信されるため、UTF8文字列に変換して表示
    Debug.LogFormat("OnMessage: label={0} data={1}", label, System.Text.Encoding.UTF8.GetString(data));
};
```

<!-- mikan:page doc="functions_forwarding_filters" -->

# 転送フィルター

Sora Unity SDK の転送フィルター機能について説明します。

この機能を利用することで、音声や映像のフィルターをすることができます。

## Sora 2024.2.0 以降の Sora での利用について

Sora 2024.2.0 からルールだけでなくフィルターそのものを複数設定できるようになりました。

これまでの `ForwardingFilter` は非推奨になり、新たに `ForwardingFilters` が追加されました。

今後は `ForwardingFilters` を使用して転送フィルターを設定してください。

以下は `ForwardingFilters` を前提とした説明を記載しています。

## 転送フィルターについて

転送フィルターは `ForwardingFilters` クラスを使用して設定することができます。

このクラスは `ForwardingFilter` のリストになっており、複数の転送フィルターを設定が可能になっています。

転送フィルターの仕様の詳細については [Sora ドキュメントの転送フィルター機能](https://sora-doc.shiguredo.jp/FORWARDING_FILTER) を参照してください。

また、複数の転送フィルターの仕様については [Sora ドキュメントのマルチ転送フィルター機能](https://sora-doc.shiguredo.jp/MULTI_FORWARDING_FILTER) を参照してください。

Sora.cs で `ForwardingFilters` と `ForwardingFilter` クラスは以下のように定義されています。

```csharp
// 転送フィルターの設定を保持するクラス
public class ForwardingFilter
{
    public string? Action;
    public string? Name;
    public int? Priority;
    public class Rule
    {
        public string Field;
        public string Operator;
        public List<string> Values = new List<string>();
    }
    public List<List<Rule>> Rules = new List<List<Rule>>();
    public string? Version;
    public string? Metadata;
}
public class Config
{
    // ForwardingFilter 設定
    public ForwardingFilter ForwardingFilter;
    // ForwardingFilters 設定
    public List<ForwardingFilter> ForwardingFilters;
}
```

## 利用方法

転送フィルターの利用方法の例を以下に示します。

```csharp
var config = new Sora.Config();
// ForwardingFilters プロパティにフィルタリストを設定
config.ForwardingFilters = new List<Sora.ForwardingFilter>
{
    // フィルタ1: 特定の client-id (carol) を持つデータを許可
    new Sora.ForwardingFilter
    {
        // 許可アクション
        Action = Sora.ActionAllow,
        // フィルタの名前
        Name = "client-id-carol-allow",
        // 優先度
        Priority = 0,
        // フィルタのルール
        Rules = new List<List<Sora.ForwardingFilter.Rule>>
        {
            new List<Sora.ForwardingFilter.Rule>
            {
                new Sora.ForwardingFilter.Rule
                {
                    // 許可対象の client-id リスト
                    Field = Sora.FieldClientId,
                    Operator = Sora.OperatorIsIn,
                    Values = new List<string> { "carol" }
                }
            }
        },
        // フィルタのバージョン
        Version = "a",
        // メタデータ(JSON形式)
        Metadata = "{\"spam\":\"egg\"}"
    },
    // フィルタ2: audio と video データをフィルタ
    new Sora.ForwardingFilter
    {
        // Action / Name / Priority は未指定の場合はデフォルト値が設定される
        // フィルタのルール
        Rules = new List<List<Sora.ForwardingFilter.Rule>>
        {
            new List<Sora.ForwardingFilter.Rule>
            {
                new Sora.ForwardingFilter.Rule
                {
                    Field = Sora.FieldKind,
                    Operator = Sora.OperatorIsIn,
                    Values = new List<string> { "audio", "video" }
                }
            },
        },
    }
};
```

<!-- mikan:page doc="functions_ca_cert" -->

# 証明書の指定

Sora Unity SDK で CA 証明書、クライアント証明書、クライアントシークレットキーを指定する方法を説明します。

この機能を利用することで、Unity SDK を利用しているときに Sora に接続する証明書を指定することができます。

## 証明書について

Sora Unity SDK は libwebrtc の証明書チェック機能と、ハードコードで持っている証明書を使用して認証をしています。

独自の証明書を使用したい場合、PEM 形式の CA 証明書、クライアント証明書、クライアントシークレットキーを指定することで利用が可能です。

## Sora Unity SDK の実装内容

Sora Unity SDK では、証明書の指定を利用するための実装を以下のように提供しています。

```csharp
public class Config
{
    // クライアント証明書の文字列
    public string? ClientCert;
    // クライアント証明書の秘密鍵の文字列
    public string? ClientKey;
    // ルート証明書の文字列
    public string? CACert;
}
```

## 利用方法

以下に Sora Unity SDK Samples での利用方法を示します。

設定は Inspector で実施することを想定したものです。

ファイルをロードではなく、ファイル内容を直接入力する設定になっています。

ご利用になる用途に合わせて適宜変更してください。

### Inspector での設定例

以下に Inspector での設定例を示します。
ファイルの内容を貼り付けてください。

```text
-----BEGIN CERTIFICATE-----
MIIFaz (省略)
-----END CERTIFICATE-----
```

証明書関連設定の定義

```csharp
// ここでは証明書を Inspector に貼り付ける実装にする
// 有効にするフラグを用意してあるので、証明書を使わない場合は false にする
public bool useClientCert = false;
private string clientCert = @"";
public bool useClientKey = false;
private string clientKey = @"";
public bool useCACert = false;
private string caCert = @"";
```

Sora に接続する際に設定を行う部分の例を以下に示します。

```csharp
// Sora インスタンスの宣言
Sora sora;
// Sora.Config インスタンスの生成
var config = new Sora.Config();

// 有効フラグを確認して、証明書を設定
if (useClientCert)
{
    config.ClientCert = clientCert;
}
if (useClientKey)
{
    config.ClientKey = clientKey;
}
if (useCACert)
{
    config.CACert = caCert;
}
```

<!-- mikan:page doc="functions_degradation_preference" -->

# DegradationPreference

Sora Unity SDK で利用できる `DegradationPreference` 設定について説明します。

この設定を利用すると、帯域幅が不足した際に映像の劣化をどのように行うかを指定できます。

例えばプレゼンテーションのような動きのない映像では、 `MaintainResolution` を指定して解像度を優先することで、文字の読みやすさを保つことができます。

## 概要

`DegradationPreference` は映像配信中にネットワーク帯域が不足した場合の調整方針を制御します。

Sora Unity SDK では `Sora.Config.DegradationPreference` を設定することで、Sora へ希望する劣化方針を伝えることができます。

## 指定できる値

Sora Unity SDK が提供する `Sora.DegradationPreference` 列挙体は、以下の 4 種類です。

これらは Sora.cs で enum 型として定義されています。

- `Disabled`: 劣化方針を指定しません
- `MaintainFramerate`: フレームレートを優先的に維持し、解像度を下げます
- `MaintainResolution`: 解像度を優先的に維持し、フレームレートを下げます
- `Balanced`: フレームレートと解像度の両方をバランスよく調整します

## 利用方法

`Sora.Config.DegradationPreference` に列挙値を代入し、 `Sora.Connect(config)` を呼び出してください。

値を指定しない場合は未指定として扱われ libwebrtc デフォルトの挙動として MAINTAIN_FRAMERATE で動作します。

### 基本的な利用方法

最もシンプルな利用方法は接続時に `Sora.Config` に直接設定する方法です。

```csharp
var config = new Sora.Config()
{
    // その他の設定は省略
    // ここでは Balanced を指定しています
    DegradationPreference = Sora.DegradationPreference.Balanced
};
sora.Connect(config);
```

### Inspector で選択可能にする例

Sora Unity SDK Samples への実装を考慮した例を以下に示します。

ここでは enableDegradationPreference フラグを用意し、これが true の場合にのみ `DegradationPreference` を設定します。

また、Inspector で `DegradationPreference` を選択できるようにしています。

```csharp
// DegradationPreference を有効化するフラグ
// ここでは値なしを選択できるようにするために用意します
public bool enableDegradationPreference = false;
// Inspector で選択可能にしておき、デフォルトは Balanced にします
public Sora.DegradationPreference degradationPreference = Sora.DegradationPreference.Balanced;

// Soraインスタンスの宣言
Sora sora;

// Sora Unity SDK Samples の実装通り、ボタン押下で接続開始します
public void OnClickStart()
{
    InitSora();
    // Sora.Config インスタンスの生成
    var config = new Sora.Config()
    {
        // 省略
    };
    // enableDegradationPreference が true の場合のみ DegradationPreference を設定します
    if (enableDegradationPreference)
    {
        // Inspector で設定した値を利用します
        config.DegradationPreference = degradationPreference;
    }
    sora.Connect(config);
}
```

<!-- mikan:page doc="functions_hardware_acceleration" -->

# エンコーダー / デコーダーの指定

ここでは Sora Unity SDK におけるビデオエンコーダー / デコーダーの指定方法と、
ハードウェアアクセラレーションを優先的に利用する手順を説明します。

Sora Unity SDK では、利用環境に合わせてエンコーダーとデコーダーを指定することができます。
また、ハードウェアアクセラレーションを優先的に設定する機能も用意しています。

この機能を利用することで、ハードウェアアクセラレーションを利用したエンコードやデコードを行うことができます。
ハードウェアアクセラレーションを利用することで、CPU の負荷を軽減し、より高品質な映像を提供することができます。
また、H.264 や H.265 などのコーデックを利用することができます。

## 指定可能なエンコーダーおよびデコーダー

### Internal

ソフトウェアエンコーダーおよびデコーダーを利用します。

また、libwebrtc で提供されているエンコーダーおよびデコーダーを利用します。

この中には macOS と iOS の場合、Apple の VideoToolbox を利用したハードウェアエンコーダーおよびデコーダーも含まれています。

また、Android の場合、Android の MediaCodec を利用したハードウェアエンコーダーおよびデコーダーも含まれています。

それ以外のプラットフォームでは、ソフトウェアエンコーダーおよびデコーダーを利用します。

### Intel VPL

Intel VPL は Intel 組込 GPU や Intel Arc で利用できるハードウェアアクセラレーターです。

Linux と Windows で利用でき、対応コーデックは VP9 / AV1 / H.264 / H.265 です。

### AMD AMF

> **注意**
>
> AMD AMF はドライバーが不安定なため、現在非推奨です。

AMD AMF は AMD 組込 GPU や AMD のビデオカードで利用できるハードウェアアクセラレーターです。

Linux と Windows で利用でき、対応コーデックは VP9 / AV1 / H.264 / H.265 です。

AV1 デコーダーは Windows x86_64 でのみ利用できます。

### NVIDIA Video Codec

NVIDIA Video Codec は NVIDIA のビデオカードで利用できるハードウェアアクセラレーターです。

Linux と Windows で利用できます。対応コーデックは VP8 / VP9 / AV1 / H.264 / H.265 です。

VP8 と VP9 はデコーダーのみ利用できます。

## エンコーダーデコーダーの指定に関連するクラスと関数

### Sora.VideoCodecImplementation

`Sora.VideoCodecImplementation` は、利用するエンコーダーおよびデコーダーの実装を指定するための列挙型です。
以下の値が指定可能です。

- `Internal` : ソフトウェアまたは libwebrtc で提供されているエンコーダーおよびデコーダーを利用します
- `IntelVPL` : Intel VPL を利用します
- `NvidiaVideoCodec` : NVIDIA Video Codec を利用します
- `AmdAmf` : AMD AMF を利用します

### Sora.VideoCodecPreference

`Sora.VideoCodecPreference` は、利用するエンコーダーおよびデコーダーの指定を行うためのクラスです。
このクラスを使用することで、特定のハードウェアアクセラレーションを利用する設定を行うことができます。
設定は、コーデックごとに指定することが可能です。また、エンコーダーおよびデコーダー個別に指定することもできます。

### Sora.GetVideoCodecCapability()

`Sora.GetVideoCodecCapability()` は、現在の環境で利用可能なエンコーダーおよびデコーダーの対応状況を取得するための関数です。
この関数を使用して、利用可能なコーデックやハードウェアアクセラレーションの情報を取得できます。

取得された情報は `Sora.VideoCodecPreference.CreateFromImplementation()` や `GetHardwareAcceleratorPreference()` の入力として使用します。

### Sora.VideoCodecPreference.CreateFromImplementation()

`Sora.VideoCodecPreference.CreateFromImplementation()` は、指定されたエンコーダーおよびデコーダーの実装に基づいて、指定された Sora.VideoCodecImplementation のみを利用する Sora.VideoCodecPreference を作成します。

### Sora.VideoCodecPreference.GetHardwareAcceleratorPreference()

`Sora.VideoCodecPreference.GetHardwareAcceleratorPreference()` は、取得した対応状況に基づき、ハードウェアアクセラレーションを優先する設定を生成するためのメソッドです。
このメソッドを使用することで、ハードウェアエンコーダーが利用可能な場合に自動的に優先設定を適用できます。利用不可能な場合はソフトウェアエンコーダー (Internal) の設定を試みます。

## 利用方法

エンコーダーとデコーダーの利用方法は 3 種類あります。

1. エンコーダーとデコーダーを指定する
2. 利用可能なハードウェアアクセラレーションを自動優先する
3. エンコーダー / デコーダーを個別に (異なる実装で) 指定する
4. エンコーダーとデコーダーを指定する

---

```csharp
// Sora インスタンスの宣言
Sora sora;
// Sora.Config インスタンスの生成
var config = new Sora.Config();

// Inspector で選択可能にしておき、デフォルトは Internal
public Sora.VideoCodecImplementation videoCodecImplementation = Sora.VideoCodecImplementation.Internal;

// ボタン押下で接続開始する例
public void OnClickStart()
{
    // 1. 利用可能なエンコーダーとデコーダーの一覧を取得
    var capability = Sora.GetVideoCodecCapability(new Sora.VideoCodecCapabilityConfig());
    var availableEngines = capability.Engines.Where(e => e.Name == videoCodecImplementation);

    // 2. 指定したエンコーダーとデコーダーが利用可能か確認
    if (!availableEngines.Any())
    {
        Debug.LogError($"指定された実装 {videoCodecImplementation} が利用できません。接続を中止します。");
        return;
    }
    // 3. Preference を生成
    var preference = Sora.VideoCodecPreference.CreateFromImplementation(capability, videoCodecImplementation);

    // 4. Config を構築して接続開始
    var config = new Sora.Config
    {
        VideoCodecPreference = preference,
    };
}
```

### 2. 利用可能なハードウェアアクセラレーションを自動優先する

こちらは Sora Unity SDK Samples にも含まれておりますので、そちらも参考にしてみてください。

[Sora Unity SDK サンプル集](https://github.com/shiguredo/sora-unity-sdk/tree/master/SoraUnitySdkExamples)

```csharp
// Sora インスタンスの宣言
Sora sora;
// Sora.Config インスタンスの生成
var config = new Sora.Config();

// ボタン押下で接続開始する例
public void OnClickStart()
{
    // ハードウェアエンコーダーが使える場合は自動で優先 (利用不可なら自動的に Internal 等へフォールバック)

    // 1. 対応状況を取得
    var capability = Sora.GetVideoCodecCapability(new Sora.VideoCodecCapabilityConfig());

    // 2. ハードウェア優先の Preference を生成
    var preference = Sora.VideoCodecPreference.GetHardwareAcceleratorPreference(capability);

    // 3. Config に設定 (利用可能な HW が無い場合は Internal が選択される)
    var config = new Sora.Config
    {
        VideoCodecPreference = preference,
    };
}
```

### 3. エンコーダー / デコーダーを個別 (異なる実装) に指定する

> **注意**
>
> AMD AMF はドライバーが不安定なため、現在非推奨です。

エンコーダーとデコーダーを異なるハードウェアアクセラレーターで個別に指定することができます。
ここでは、H.264 のエンコードを NVIDIA Video Codec、デコードを AMD AMF で行う例を示します。

```csharp
// Sora インスタンスの宣言
Sora sora;
// Sora.Config インスタンスの生成
var config = new Sora.Config();

// ボタン押下で接続開始する例
public void OnClickStart()
{
    var capability = Sora.GetVideoCodecCapability(new Sora.VideoCodecCapabilityConfig());

    // H.264: エンコードを NVIDIA, デコードを AMD AMF に分離
    // Parameters はコーデック固有パラメーター(JSON)。空の場合 "{}" を渡す。
    var preference = new Sora.VideoCodecPreference
    {
        Codecs = new Sora.VideoCodecPreference.Codec[]
        {
            new Sora.VideoCodecPreference.Codec
            {
                Type = Sora.VideoCodecType.H264,
                Encoder = Sora.VideoCodecImplementation.NvidiaVideoCodec,
                Decoder = Sora.VideoCodecImplementation.AmdAmf,
                Parameters = "{}",
            }
        }
    };

    // 指定したエンコーダーとデコーダーが利用可能かチェックする
    var availableEngines = capability.Engines.Where(e =>
        e.Name == Sora.VideoCodecImplementation.NvidiaVideoCodec ||
        e.Name == Sora.VideoCodecImplementation.AmdAmf);

    if (!availableEngines.Any())
    {
        Debug.LogError("[VideoCodec] 指定したエンコーダーとデコーダーが利用できません。接続を中止します。");
        return;
    }

    // config に設定
    var config = new Sora.Config()
    {
        VideoCodecPreference = preference,
    };
}
```

<!-- mikan:page doc="functions_rpc" -->

# RPC 機能

Sora Unity SDK の RPC 機能について説明します。

> **注意**
>
> この機能は実験的機能のため、正式版では仕様が変更される可能性があります

## RPC 機能について

RPC 機能は DataChannel 経由で Sora の一部 HTTP API を利用するための機能です。 JSON-RPC 2.0 プロトコルの仕様に準拠しています。

この機能は Sora 2025.2 以降で、かつ DataChannel 経由のシグナリングが有効な場合に利用可能です。
Sora の RPC 機能の詳細は [Sora ドキュメントの RPC 機能](https://sora-doc.shiguredo.jp/RPC) をご確認ください。

### 利用時の注意事項

- label が `rpc` のメッセージは `Sora.OnMessage` には届きません
- RPC レスポンス受信とタイムアウト判定は `Sora.DispatchEvents()` の呼び出しで処理されます- `DispatchEvents()` を定期的に呼び出さない場合、コールバックは呼ばれず、タイムアウトも返りません
- 切断時、およびアプリ終了に伴う `Dispose()` 実行時、未完了の RPC リクエストは破棄されます
- `paramsJson` は JSON 文字列をそのまま埋め込むため、JSON を渡してください

## Sora Unity SDK の実装内容

Sora Unity SDK では RPC の送信とレスポンス受信を以下の API で提供しています。

- `void RequestRpcNotification(string method, string paramsJson)`: JSON-RPC 2.0 Notification を送信
- `void RequestRpc(string method, string paramsJson, Action<RpcResult> onResult, long timeoutMillis)`: JSON-RPC 2.0 Request を送信（タイムアウトをミリ秒で指定)

### RequestRpcNotification のパラメータ

- `method`: 呼び出すメソッド名 (例: `"2025.2.0/RequestSimulcastRid"`)
- `paramsJson`: メソッドのパラメータを表す JSON 文字列。オブジェクト形式 (例: `{"key":"value"}`) または配列形式 (例: `[1,2,3]`) で指定します。パラメータがない場合は `"{}"` を指定してください

> **注釈**
>
> JSON-RPC 2.0 Notification として送信されます。この場合 Sora はレスポンスを返しません。

### RequestRpc のパラメータ

- `method`: 呼び出すメソッド名 (例: `"2025.2.0/RequestSimulcastRid"`)
- `paramsJson`: メソッドのパラメータを表す JSON 文字列。オブジェクト形式 (例: `{"key":"value"}`) または配列形式 (例: `[1,2,3]`) で指定します。パラメータがない場合は `"{}"` を指定してください
- `onResult`: `Sora.RpcResult` 型のレスポンス用のコールバック
- `timeoutMillis`: Sora レスポンスのタイムアウト時間（ミリ秒）。 `0` より大きな値を指定してください- `Sora.DefaultRpcTimeoutMillis` で指定すると 5,000 ms となります

> **注釈**
>
> SDK は内部でリクエスト ID を自動採番し、レスポンスと紐付けます。アプリケーション側で ID を指定することはできません。

#### RpcResult のメンバー

- `ResultKind`: RPC リクエスト結果です。 `Response` / `Timeout` のいずれかが入ります
- `Method`: RPC リクエストしたメソッドです。リクエスト時に指定したメソッドと同じものが入ります
- `ParamsJson`: RPC リクエストパラメータの JSON 文字列です。リクエスト時に指定した JSON 文字列と同じものが入ります
- `ResponseJson`: RPC レスポンスの JSON 文字列です。データ内容のパースは SDK の利用者側の責務となります

> **重要**
>
> `ResultKind.Response` は Sora からの RPC レスポンスを受信することができたことのみを表し、リクエスト内容の成功 / 失敗を表しません。
> ResponseJson の内容（result / error）を利用者側で判定してください

## 利用方法

### シグナリング設定

Sora Unity SDK Examples の `SoraSample.cs` では、Inspector で `dataChannel signaling` を設定し、
`Sora.Config` に反映しています。

以下のように DataChannel 経由のシグナリングを有効にする設定を行います。

```csharp
var config = new Sora.Config()
{
    EnableDataChannelSignaling = true,
    DataChannelSignaling = true,
};
```

### RPC リクエストの送信とレスポンス受信

ここでは UI のボタンから RPC リクエストを送信し、レスポンスを受信する例を示します。

レスポンスデータはコールバックで受け取るため、レスポンスデータを処理するコールバックハンドラを `Sora.RpcResult` 型で用意します。
また受信したレスポンスデータは JSON 形式の文字列です。パース処理は独自に実装する必要があります。

> **重要**
>
> Sora.RequestRpc に渡される onResult コールバックは DispatchEvents() で処理されるため、
> Update() で定期的に DispatchEvents() が呼ばれている必要があります。

```csharp
// SoraSample.cs からの抜粋した RPC 機能を使用するための設定パラメータと送信/受信メソッドの例です。
// [Header]`` 属性が付与されたフィールドで、各 RPC メソッドのパラメータを Inspector から設定できます。

// 送信する RPC メッセージの種類
public enum RpcMessageType
{
    None,
    RequestSimulcastRid,
    RequestSpotlightRid,
    ResetSpotlightRid,
    PutSignalingNotifyMetadata,
    PutSignalingNotifyMetadataItem,
}

[Header("RPC メッセージの設定")]
// Inspector で送信したい RPC メッセージの種類を選択します
public RpcMessageType rpcMessageType = RpcMessageType.None;
// RPC リクエストの timeoutMillis（ミリ秒）。空欄の場合は SDK のデフォルト値を利用します
public string rpcTimeoutMillis = "";

[Header("RequestSimulcastRid の設定")]
public string sendRequestSimulcastRid = "r0";
public string sendRequestSimulcastRidSenderConnectionId = "";

[Header("RequestSpotlightRid の設定")]
public string sendRequestSpotlightFocusRid = "r1";
public string sendRequestSpotlightUnfocusRid = "none";
public string sendRequestSpotlightRidConnectionId = "";

[Header("ResetSpotlightRid の設定")]
public string sendResetSpotlightRidConnectionId = "";

[Header("PutSignalingNotifyMetadata の設定")]
public string sendPutSignalingNotifyMetadataJson = "{\"key\":\"value\"}";
public bool sendPutSignalingNotifyMetadataPush = false;

[Header("PutSignalingNotifyMetadataItem の設定")]
public string sendPutSignalingNotifyMetadataItemKey = "status";
public string sendPutSignalingNotifyMetadataItemValue = "\"active\"";
public bool sendPutSignalingNotifyMetadataItemPush = false;

// ボタンを押したときに呼び出される RPC 送信メソッド例
// RpcMessageType enum で送信する RPC メッセージの種類を選択します。
public void OnClickSendRpc()
{
    if (sora == null)
    {
        return;
    }

    // Inspector で選択された RPC メッセージの種類に応じて処理を分岐する
    switch (rpcMessageType)
    {
        case RpcMessageType.None:
            Debug.Log("RPC メッセージの種類が選択されていません");
            break;
        case RpcMessageType.RequestSimulcastRid:
            SendRequestSimulcastRid();
            break;
        case RpcMessageType.RequestSpotlightRid:
            SendRequestSpotlightRid();
            break;
        case RpcMessageType.ResetSpotlightRid:
            SendResetSpotlightRid();
            break;
        case RpcMessageType.PutSignalingNotifyMetadata:
            SendPutSignalingNotifyMetadata();
            break;
        case RpcMessageType.PutSignalingNotifyMetadataItem:
            SendPutSignalingNotifyMetadataItem();
            break;
    }
}

// レスポンスをコールバックで受け取るハンドラです
// sora.RequestRpc の引数に指定します
void HandleRpcResult(Sora.RpcResult result) {
    switch (result.ResultKind) {
        // レスポンスを受信できた場合です
        // レスポンスの内容が成功かエラーか判定するにはさらにレスポンスデータをパースする必要があります
        case Sora.RpcResultKind.Response:
        {
            var responseJson = result.ResponseJson;
            Debug.LogFormat("RPC response: method={0}, response={1}", result.Method, responseJson);

            // JSON-RPC 2.0 の result / error 判定例
            // 実際には JSON パーサーを使用してください
            if (responseJson != null && responseJson.Contains("\"result\""))
            {
                Debug.Log("RPC result が返りました");
            }
            else if (responseJson != null && responseJson.Contains("\"error\""))
            {
                Debug.LogError("RPC error が返りました");
            }
            break;
        }
        // リクエストがタイムアウトになった場合です
        case Sora.RpcResultKind.Timeout:
            Debug.LogErrorFormat("RPC timeout: method={0}", result.Method);
            break;
    }
}

// Sora.RequestRpc メソッドを利用して RPC リクエストします
void RequestRpcInternal(string method, string paramsJson)
{
    if (sora == null)
    {
        return;
    }

    // タイムアウト時間無指定であれば Sora.DefaultRpcTimeoutMillis を指定します
    if (string.IsNullOrWhiteSpace(rpcTimeoutMillis))
    {
        sora.RequestRpc(method, paramsJson, HandleRpcResult, Sora.DefaultRpcTimeoutMillis);
        return;
    }

    // タイムアウト時間は long 型のためパースします
    var timeoutMillisText = rpcTimeoutMillis.Trim();
    if (!long.TryParse(timeoutMillisText, out var timeoutMillis))
    {
        Debug.LogErrorFormat("RPC timeoutMillis の形式が不正です: timeoutMillis={0}", rpcTimeoutMillis);
        return;
    }
    if (timeoutMillis <= 0)
    {
        Debug.LogErrorFormat("RPC timeoutMillis は 1 以上を指定してください: timeoutMillis={0}", timeoutMillis);
        return;
    }

    sora.RequestRpc(method, paramsJson, HandleRpcResult, timeoutMillis);
}

// 各 RPC メソッド ( SendRequestSimulcastRid、SendRequestSpotlightRid など) は、
// Inspector で選択されたメッセージタイプに応じて OnClickSendRpc() から呼び出されます。
// 実際の RPC リクエストは sora.RequestRpc() メソッドを使用して送信されます。

void SendRequestSimulcastRid()
{
    Debug.LogFormat("SendRequestSimulcastRid: rid={0}, sender_connection_id={1}", sendRequestSimulcastRid, sendRequestSimulcastRidSenderConnectionId);
    string paramsJson;
    if (string.IsNullOrEmpty(sendRequestSimulcastRidSenderConnectionId))
    {
        paramsJson = $"{{\"rid\":\"{sendRequestSimulcastRid}\"}}";
    }
    else
    {
        paramsJson = $"{{\"sender_connection_id\":\"{sendRequestSimulcastRidSenderConnectionId}\",\"rid\":\"{sendRequestSimulcastRid}\"}}";
    }
    RequestRpcInternal("2025.2.0/RequestSimulcastRid", paramsJson);
}

void SendRequestSpotlightRid()
{
    Debug.LogFormat("SendRequestSpotlightRid: focus={0}, unfocus={1}, send_connection_id={2}", sendRequestSpotlightFocusRid, sendRequestSpotlightUnfocusRid, sendRequestSpotlightRidConnectionId);
    string paramsJson;
    if (string.IsNullOrEmpty(sendRequestSpotlightRidConnectionId))
    {
        paramsJson = $"{{\"spotlight_focus_rid\":\"{sendRequestSpotlightFocusRid}\",\"spotlight_unfocus_rid\":\"{sendRequestSpotlightUnfocusRid}\"}}";
    }
    else
    {
        paramsJson = $"{{\"send_connection_id\":\"{sendRequestSpotlightRidConnectionId}\",\"spotlight_focus_rid\":\"{sendRequestSpotlightFocusRid}\",\"spotlight_unfocus_rid\":\"{sendRequestSpotlightUnfocusRid}\"}}";
    }
    RequestRpcInternal("2025.2.0/RequestSpotlightRid", paramsJson);
}

void SendResetSpotlightRid()
{
    Debug.LogFormat("SendResetSpotlightRid: send_connection_id={0}", sendResetSpotlightRidConnectionId);
    string paramsJson;
    if (string.IsNullOrEmpty(sendResetSpotlightRidConnectionId))
    {
        paramsJson = "{}";
    }
    else
    {
        paramsJson = $"{{\"send_connection_id\":\"{sendResetSpotlightRidConnectionId}\"}}";
    }
    RequestRpcInternal("2025.2.0/ResetSpotlightRid", paramsJson);
}

void SendPutSignalingNotifyMetadata()
{
    Debug.LogFormat("SendPutSignalingNotifyMetadata: {0}", sendPutSignalingNotifyMetadataJson);
    string paramsJson = sendPutSignalingNotifyMetadataPush
        ? $"{{\"push\":true,\"metadata\":{sendPutSignalingNotifyMetadataJson}}}"
        : $"{{\"metadata\":{sendPutSignalingNotifyMetadataJson}}}";
    RequestRpcInternal("2025.2.0/PutSignalingNotifyMetadata", paramsJson);
}

void SendPutSignalingNotifyMetadataItem()
{
    Debug.LogFormat("SendPutSignalingNotifyMetadataItem: key={0}, value={1}", sendPutSignalingNotifyMetadataItemKey, sendPutSignalingNotifyMetadataItemValue);
    string paramsJson = sendPutSignalingNotifyMetadataItemPush
        ? $"{{\"push\":true,\"key\":\"{sendPutSignalingNotifyMetadataItemKey}\",\"value\":{sendPutSignalingNotifyMetadataItemValue}}}"
        : $"{{\"key\":\"{sendPutSignalingNotifyMetadataItemKey}\",\"value\":{sendPutSignalingNotifyMetadataItemValue}}}";
    RequestRpcInternal("2025.2.0/PutSignalingNotifyMetadataItem", paramsJson);
}

// コールバック発火のため DispatchEvents の定期的な呼び出しが必要です
void Update()
{
    if (sora != null)
    {
        sora.DispatchEvents();
    }
}
```

<!-- mikan:page doc="samples_tutorial" -->

# サンプル集を使った接続確認

## 概要

このチュートリアルでは Sora Unity SDK のサンプル集を使って接続確認をするところまでを説明します。

[Sora Unity SDK サンプル集](https://github.com/shiguredo/sora-unity-sdk/tree/master/SoraUnitySdkExamples)

## チュートリアルの注意点

- このチュートリアルは Windows 10 でのみ動作確認をしています。
- このチュートリアルは Unity Editor 上での動作確認を前提としています。
- このチュートリアルは Python3 がインストールされていることを前提としています。

## 接続先の用意

接続確認を行うために接続先を用意します。
接続先は時雨堂が開発、販売している WebRTC SFU Sora を利用します。

検証目的であれば [Sora Labo](https://sora-labo.shiguredo.jp/) を利用することで、 Sora を無料で試すことができます。

GitHub アカウントを用意して [Sora Labo のドキュメント](https://github.com/shiguredo/sora-labo-doc) を読んだ後  にサインアップしてください。

## Sora Unity SDK サンプル集の取得

[Sora Unity SDK](https://github.com/shiguredo/sora-unity-sdk/) を clone してください。

安定版の master ブランチを使います。

```bash
$ git clone -b master https://github.com/shiguredo/sora-unity-sdk.git
```

> **注釈**
>
> Apple Vision Pro (visionOS) を利用する場合は `apple-vision-pro` タグが付与されたブランチを使用してください。

```bash
$ git clone -b 2026.1.0-apple-vision-pro.0 https://github.com/shiguredo/sora-unity-sdk.git
```

## Sora Unity SDK のインストール

clone が完了したら、作成されたディレクトリに移動後、 `python3 run.py install` を実行して Sora Unity SDK をインストールします。
Sora Unity SDK のインストール方法は以下の通りです。

```bash
$ cd sora-unity-sdk
$ python3 run.py install

# Ubuntu 以外のプラットフォーム、Ubuntu 24.04 を使用する場合は以下のコマンドを実行してください。
$ rm -rf SoraUnitySdkExamples/Assets/Plugins/SoraUnitySdk/ubuntu-22.04
# Ubuntu 22.04 を使用する場合は以下のコマンドを実行してください。
$ rm -rf SoraUnitySdkExamples/Assets/Plugins/SoraUnitySdk/ubuntu-24.04
```

> **注釈**
>
> Ubuntu 以外のプラットフォームでビルドを行う場合も、Ubuntu 22.04 と Ubuntu 24.04 いずれかのディレクトリを削除してください。
> ビルド時に同一ファイル名のバイナリが複数存在するとビルドエラーになります。

### Unity Editor で Sora Unity SDK サンプル集を開く

Sora Unity SDK のインストールが完了したら、 Unity Editor でサンプル集を開きます。

Unity Editor は [Sora Unity SDK 概要](overview.html) の対応 Unity バージョンを推奨しています。

Unity Editor でサンプル集を開くとこのようになっています。

![image](https://i.gyazo.com/3cebd97452cab92e4ab6b7ae31898206.png)

## 接続確認をする

ここでは Sora Labo を使って接続確認をします。

### シーンを開く

Sora Unity SDK サンプル集では接続サンプルとして以下のシーンが用意されています。

- multi_sendrecv
- multi_sendonly
- multi_recvonly

ここでは multi_sendrecv を使用します。

### 接続設定

サンプル集のシーンは Script オブジェクトで設定を行います。

![image](https://i.gyazo.com/d48fa446ae1e23856f1043e483f96f65.png)

Sora Labo で取得したシグナリング URLs 、チャネル ID 、アクセストークンを設定します。

![image](https://i.gyazo.com/b5ef947c329e1831927bf53a6d691b5e.png)

### 接続する

Sora Labo の Devtools と映像の送受信を行います。

事前に送受信確認のために Sora Labo の Devtools でマルチストリーム送受信を開いておき fakeMedia で接続しておきます。

Unity Editor の Play ボタンを押下してください。

Game Tab が開き以下のような画面になりますので開始ボタンを押下します。

![image](https://i.gyazo.com/6a0254bbdca453599c3f086cc0f5fcaf.png)

無事送受信が開始されると以下のような画面になります。

![image](https://i.gyazo.com/b28ca35c08b483a3c0101811fac9f82b.png)

以上で接続確認は完了です。

## 各プラットフォーム向けの設定

このチュートリアルで使用したサンプル集では各プラットフォーム向けの設定が行われています。

ご自身のプロジェクトで Sora Unity SDK を利用する場合は各プラットフォーム向けに設定をする必要があります。

それぞれのドキュメントを参照してください。

### Windows のビルド

Sora Unity SDK のインストール完了後に使うことができます。

Target Platform を Windows に指定してビルドしてください。

### macOS のビルド

[macOS で使ってみる](use_macos.html) をお読みください。

### iOS のビルド

[iOS で使ってみる](use_ios.html) をお読みください。

### Android のビルド

[Android で使ってみる](use_android.html) をお読みください。

### Linux のビルド

libva-drm2 パッケージの apt によるインストール、 Sora Unity SDK のインストール完了後に使うことができます。

Target Platform を Linux に指定してビルドしてください。

### visionOS のビルド

[visionOS で使ってみる](use_visionos.html) をお読みください。

## 次のステップ

Sora Unity SDK のサンプル集ではいろいろな機能を試せるようになっています。

それぞれの機能を試せるよう次項からサンプル集を使用した機能の試し方について説明します。

<!-- mikan:page doc="samples_connect_settings" -->

# 接続の設定

## 概要

ここでは Sora Unity SDK のサンプル集を使って接続設定について説明します。

[Sora Unity SDK サンプル集](https://github.com/shiguredo/sora-unity-sdk/tree/master/SoraUnitySdkExamples)

## Signaling URL と Signaling URL Candidate

接続する Sora の URL を設定します。 Signaling URL と Signaling URL Candidate は必須項目です。どちらか一方は必ず設定してください。

Sora Unity SDK Sample はクラスター環境でも利用できるよう Signaling URL を複数設定できるようになっています。

Signaling URL と Signaling URL Candidate で別の項目ですが、同じように機能します。複数指定したい場合は Signaling URL Candidate で接続先を追加してください。

![image](https://i.gyazo.com/d14f7e516b7780e235ff5b5c70c23858.png)

## Insecure

Insecure を有効にすると SSL/TLS の証明書の検証を行わなくなります。

## Channel ID

Sora に接続する Channel ID を設定します。必須項目になりますので必ず設定してください。

## Client ID

クライアント ID を設定します。

## Bundle ID

バンドル ID を設定します。

## DataChannel シグナリングの設定

DataChannel シグナリングを有効にするかどうかを設定します。

DataChannel シグナリングを有効にすると、 DataChannel を利用したシグナリングを行うことができます。

**Data Channel Signaling**: DataChannel シグナリングを有効にするかどうかを設定します
**Data Channel Signaling Timeout**: DataChannel シグナリングのタイムアウトを設定します
**Ignore Disconnect Websocket**: WebSocket の切断を無視するかどうかを設定します
**Disconnect Wait Timeout**: 切断時のタイムアウトを設定します

![image](https://i.gyazo.com/0c36e5597a90ad5e8a870bb15ce74707.png)

### DataChannel シグナリングを無効にしたい場合

現在の Inspector の設定では DataChannel シグナリングを無効にすることができません。 DataChannel シグナリングを無効にしたい場合は、以下のように設定してください。

SoraSample.cs の config に以下のように設定します。

```csharp
// EnableDataChannelSignaling = dataChannelSignaling,
EnableDataChannelSignaling = true,
DataChannelSignaling = dataChannelSignaling,
```

## HTTP Proxy の設定

Proxy を設定します。

Proxy を設定することで、 Sora への接続時に Proxy を経由して接続することができます。

**ProxyUrl**: Proxy の URL とポート番号を指定します (例 : )
**ProxyUsername**: Proxy の認証に利用するユーザーを指定します
**ProxyPassword**: Proxy の認証に利用するパスワードを指定します

![image](https://i.gyazo.com/32061109684d207ea5220f1e8c8772cf.png)

<!-- mikan:page doc="samples_video_audio_settings" -->

# 映像と音声の設定

## 概要

このドキュメントでは、Sora Unity SDK サンプル集を使用した映像および音声の設定手順を解説します。設定例を通じて、各種パラメーターの使い方を順番に説明します。

[Sora Unity SDK サンプル集](https://github.com/shiguredo/sora-unity-sdk/tree/master/SoraUnitySdkExamples)

### このドキュメントで確認できること

- 映像デバイスと音声デバイスの指定方法
- 映像の設定- Unity Camera を使ったゲームキャプチャの方法
  - 映像コーデックの指定方法
  - 映像コーデックパラメーターの指定方法
  - 映像ビットレート・フレームレートの指定方法
- 音声の設定- 音声デバイスの指定方法
  - Unity Audio Input を使った音声キャプチャの方法
  - 音声コーデックの指定方法
- 映像や音声を送らない方法
- 音声ストリーミング機能の言語コードを指定する

## 映像デバイスと音声デバイスの指定方法

サンプル集では映像デバイスと音声デバイスを指定することができます。

デバイスを指定しない場合、実行環境がもつデフォルトのカメラとマイクを使用します。

指定する場合は `DeviceName` または `UniqueName` を指定します。

Unity Editor で実行する場合、Editor の Play ボタンを押すとデバイス一覧が Console に表示されます。

![image](https://i.gyazo.com/d48d51950fba81035bd144b3b9fc8559.png)

映像デバイスと音声デバイスの `DeviceName` と `UniqueName` がわかれば以下の設定に追記することでデバイスを指定できます。

### Video Capturer Device を指定する

Console に表示されたデバイス名を Video Capturer Device に設定します。

`------------ video capturer devices --------------` 以下から指定する `DeviceName` または `UniqueName` を探します。

### Audio Recording Device を指定する

Console に表示されたデバイス名を Audio Recording Device に設定します。

`------------ audio recording devices --------------` 以下から指定する `DeviceName` または `UniqueName` を探します。

### Audio Playout Device を指定する

Console に表示されたデバイス名を Audio Playout Device に設定します。

`------------ audio playout devices --------------` 以下から指定する `DeviceName` または `UniqueName` を探します。

## 映像の設定

### Unity Camera を使ったゲームキャプチャの方法

サンプル集では Capture Unity Camera を選択することで Scene 内の Camera を使ってゲームをキャプチャすることができます。

デフォルトで設定されているのは Scene 上の Camera ですが、他の Camera を設定することもできます。

![image](https://i.gyazo.com/fcc87d236a1cdbdceded52ce0670e451.png)

### 映像コーデックの指定方法

Video Codec Type を指定することで映像コーデックを指定することができます。

映像コーデックは SDK で定義しているものを指定する必要があります。

VP8 / VP9 / H264 / H265 / AV1 が指定できます。

> **注意**
>
> AMD AMF はドライバーが不安定なため、現在非推奨です。

> **警告**
>
> Windows と Ubuntu 22.04 / 24.04 で H.265 を利用するには、 Intel VPL、AMD AMF、NVIDIA Video Codec のいずれかが必要です。

![image](https://i.gyazo.com/e5340ab530dc37cda2498771a4d8ef9f.png)

### 映像コーデックパラメーターを指定する

サンプル集では映像コーデックパラメーターを指定することができます。

映像コーデックパラメーターは VP9 / AV1 / H.264 で指定できます。

![image](https://i.gyazo.com/f7228c84fb310a44c8e68f8c81e8bf9a.png)

#### VP9 の映像コーデックパラメーター

- Enable Video Vp 9 Params を ON にします
- Video Vp 9 Params Profile Id を 0-3 の値に設定します

#### AV1 の映像コーデックパラメーター

- Enable Video Av 1 Params を ON にします
- Video Av 1 Params Profile を 0-2 の値に設定します

#### H.264 の映像コーデックパラメーター

- Enable Video H264 Params を ON にします
- Video H264 Params Profile Level Id を設定します (例：42e01f)

### 映像ビットレートを指定する

映像ビットレートを指定するには Video Bitrate を設定します。

0 の場合 Sora のデフォルト設定が利用されます。

![image](https://i.gyazo.com/663526d8066cda930345cea61f959625.png)

### 映像フレームレートを指定する

映像フレームレートを指定するには Video Fps を設定します。

デフォルトでは 30fps です。

![image](https://i.gyazo.com/0e97646d76093e82a353f8c5d6bb2e64.png)

## 音声の設定

### Unity Audio Input を使った音声キャプチャの方法

サンプル集では Unity Audio Input を選択することで Scene 内の AudioSourceInput を使ってゲーム内の音声を送信することができます。

デフォルトで設定されているのは AudioSourceInput ゲームオブジェクトの Audio Source に設定されている音声ですが、他の音声を設定することもできます。

![image](https://i.gyazo.com/6ff5ba997832da258d4f208b5903402c.png)

### 音声コーデックを指定する

Audio Codec Type で音声コーデックを指定することができます。

利用できるコーデックは OPUS です。

![image](https://i.gyazo.com/4b5784adf51e92332fd1e2686fc6dbb7.png)

## 映像や音声を送らない方法

サンプル集では 映像や音声を送らないようにするパラメーターとして以下を用意しています。

- Video
- No Video Device
- Audio
- No Audio Device

Video や Audio を OFF にすることでデバイスを掴んだ状態で映像や音声を送らないようにすることができます。

この状態ではセルフビューには映像や音声が表示されます。

No Video Device や No Audio Device を ON にすることでデバイスを掴まない状態で映像や音声を送らないようにすることができます。

この状態ではセルフビューには映像や音声が表示されません。

![image](https://i.gyazo.com/f4dee1a305b9095010e4f1ba043fa5a4.png)

## 音声ストリーミング機能の言語コードを指定する

音声ストリーミング機能で使用する言語コードを Audio Streaming Language Code に指定することができます。

音声ストリーミングの詳細は [Sora のドキュメント](https://sora-doc.shiguredo.jp/AUDIO_STREAMING) を参照してください。

![image](https://i.gyazo.com/b057626f9a52608f89ac732856373e2a.png)

<!-- mikan:page doc="samples_metadata" -->

# メタデータ

## 概要

ここでは Sora Unity SDK のサンプル集を使ってメタデータの設定について説明します。

[Sora Unity SDK サンプル集](https://github.com/shiguredo/sora-unity-sdk/tree/master/SoraUnitySdkExamples)

## メタデータの設定

Sora Unity SDK のサンプル集ではいくつかのメタデータの設定を行っています。

### Signaling Notify Metadata

Sora に接続した時や切断したときに送るシグナリング通知に含まれるメタデータを設定できます。

シグナリング通知メタデータの詳細は Sora のドキュメントの [シグナリング通知メタデータ](https://sora-doc.shiguredo.jp/SIGNALING_NOTIFY_METADATA) を参照してください。

![image](https://i.gyazo.com/d463c5de266f28b83c8375d10699d1d0.png)

### Access Token

Sora Labo に接続するためのアクセストークンを設定します。

![image](https://i.gyazo.com/e7c5b65a4df3164560124608153512ce.png)

### それ以外のメタデータ

Inspector で設定可能なメタデータは上記の2つだけですが、SoraSample.cs を編集することでそれ以外のメタデータを設定することができます。

アクセストークンを設定している箇所で `Metadata` クラスを定義しているので、ここに追加したいメタデータを定義してください。

```csharp
[Serializable]
class Metadata
{
    // ここに追加したいメタデータを定義する
    public string access_token;
}

// アクセストークンがない場合はこの条件ではメタデータを設定しないため条件を変更する必要がある
// accessToken がある場合はメタデータを設定する
string metadata = "";
if (accessToken.Length != 0)
{
    var md = new Metadata()
    {
        access_token = accessToken
    };
    metadata = JsonUtility.ToJson(md);
}
```

<!-- mikan:page doc="samples_simulcast" -->

# サイマルキャスト機能

## 概要

このチュートリアルでは Sora Unity SDK のサンプル集を使ってサイマルキャスト機能の説明をします。

[Sora Unity SDK サンプル集](https://github.com/shiguredo/sora-unity-sdk/tree/master/SoraUnitySdkExamples)

## サイマルキャストの注意点

サイマルキャストは解像度にあったビットレートを指定する必要があります。

詳細は [Sora ドキュメント](https://sora-doc.shiguredo.jp/SIMULCAST) を参照してください。

## サイマルキャスト設定

### サイマルキャストを有効にする

サイマルキャストを利用するには Inspector で `Simulcast` を有効にします。

![image](https://i.gyazo.com/741327386bca746ce313e9f663d58e36.png)

### コーデックを指定する

サイマルキャストは VP9 、 VP8 、H.264 、 AV1 、 H.265 のコーデックを指定することができます。

コーデックは Inspector の Video Codec Type で指定します。

![image](https://i.gyazo.com/a9a444a90fe92ba3465000bbc6154177.png)

### 解像度とビットレートを指定する

サイマルキャストは最大で 3 本のストリームを出力します。

ストリームの本数は解像度とビットレートによって決まるため解像度にあったビットレートを指定する必要があります。

解像度とビットレートの対応表は [Sora ドキュメント](https://sora-doc.shiguredo.jp/SIMULCAST) を参照してください。

ビットレートは Inspector の Video Bit Rate で指定します。

ここでは例として HD サイズの場合のビットレートである 3000 を指定します。

![image](https://i.gyazo.com/f2dbcb9fb04e9da5b9bf079374abb8fb.png)

## その他の設定

サイマルキャストにはその他にも設定があります。

### Simulcast Rid

> **注釈**
>
> Sora Unity SDK 2026.1.0 以降は非推奨となり、2027 年 12 月リリース予定の Sora では利用できなくなります。代わりに Simulcast Request Rid を使用してください。

サイマルキャストで配信されている映像を受信する際のエンコードの初期値を指定することができます。

利用するには Inspector の Enable Simulcast Rid を有効にし、その下の Simulcast Rid Type を指定します。

![image](https://i.gyazo.com/8421213cf0872fe30c3bba2d75c4c97b.png)

### Simulcast Request Rid

サイマルキャストで配信されている映像を受信する際のエンコードの初期値を指定することができます。

利用するには Inspector の Enable Simulcast Request Rid を有効にし、その下の Simulcast Request Rid Type を指定します。

![image](https://i.gyazo.com/6c9590297eccebea172762f1dd4726ff.png)

<!-- mikan:page doc="samples_spotlight" -->

# スポットライト機能

## 概要

ここでは Sora Unity SDK のサンプル集を使ってスポットライト機能を説明します。

[Sora Unity SDK サンプル集](https://github.com/shiguredo/sora-unity-sdk/tree/master/SoraUnitySdkExamples)

## 注意

スポットライト機能はサイマルキャスト機能を活用した機能です。

そのため解像度にあったビットレートを指定する必要があります。

詳細は [Sora ドキュメント](https://sora-doc.shiguredo.jp/SIMULCAST) を参照してください。

## スポットライト設定

スポットライトはサイマルキャストと同時に利用することができます。

サイマルキャストの設定は [サイマルキャスト機能](samples_simulcast.html) を参照してください。

### スポットライトを有効にする

スポットライトを有効にするには Inspector で `Spotlight` を有効にします。

![image](https://i.gyazo.com/c69329cb7b83f4a51fe170a393a30501.png)

### コーデックを指定する

スポットライトは VP8 / VP9 / H.264 / AV1 のコーデックで利用することができます。

コーデックは Inspector の Video Codec Type で指定します。

![image](https://i.gyazo.com/a9a444a90fe92ba3465000bbc6154177.png)

### スポットライトのフォーカス数を指定する

フォーカスするスポットライトの数を指定します。

![image](https://i.gyazo.com/18ebdd3366846e1dbf45c7fa5d7f7b04.png)

## その他の設定

スポットライトにはその他にも設定があります。

### Spotlight Focus Rid

サイマルキャストと組み合わせて使用しているときに利用できます。

フォーカスするスポットライトの RID を指定します。

- Spotlight Focus Rid を ON にします
- Spotlight Focus Rid Type を指定します

![image](https://i.gyazo.com/9bd7644d1f7918bd8d172e0022c3d5e3.png)

### Spotlight Unfocus Rid

サイマルキャストと組み合わせて使用しているときに利用できます。

アンフォーカスした時のスポットライトの RID を指定します。

- Spotlight Unfocus Rid を ON にします
- Spotlight Unfocus Rid を指定します

![image](https://i.gyazo.com/233a179fc695abaa76b8052901d21513.png)

<!-- mikan:page doc="samples_data_channels" -->

# リアルタイムメッセージング機能

## 概要

ここでは Sora Unity SDK のサンプル集を使ってリアルタイムメッセージング機能について説明します。

[Sora Unity SDK サンプル集](https://github.com/shiguredo/sora-unity-sdk/tree/master/SoraUnitySdkExamples)

## リアルタイムメッセージング機能の注意点

リアルタイムメッセージングを使用する場合は Data Channel Signaling が有効になっている必要があります。

リアルタイムメッセージングの詳細については [Sora のドキュメント](https://sora-doc.shiguredo.jp/MESSAGING) を参照してください。

## リアルタイムメッセージング設定

リアルタイムメッセージングはラベルを指定することで利用することができます。

![image](https://i.gyazo.com/5c1a791dc70d911679d20624fc5a8308.png)

### Data Channels

設定したいメッセージの数を指定します。

### Element

DataChannels で指定した数だけ生成されます。それぞれのラベルを指定します。

### Label

メッセージのラベルを指定します。先頭に `#` が付いている必要があります。

### Direction

メッセージを送受信、または送信するか受信するかを指定します。

sendrecv は送受信、sendonly は送信のみ、recvonly は受信のみになります。

### Ordered

Ordered を有効にするとメッセージが順番に届くようになります。

Ordered を有効にするには以下の設定が必要です。

- Enable Ordered を有効にする
- Ordered を有効にする

### Max Packet Life Time

最大再送時間を指定することができます。デフォルトは未指定で無制限です。

Max Packet Life Time を有効にするには以下の設定が必要です。

- Enable Max Packet Life Time を有効にする
- Max Packet Life Time を有効にする

### Max Retransmits

最大再送回数を指定することができます。デフォルトは未指定で無制限です。

Max Retransmits を有効にするには以下の設定が必要です。

- Enable Max Retransmits を有効にする
- Max Retransmits で再送回数を指定する

### Protocol

現在指定する必要はありません。

### Compress

Compress を有効にするとメッセージが圧縮されます。

Compress を有効にするには以下の設定が必要です。

- Enable Compress を有効にする
- Compress を有効にする

### Header

Header を有効にして、Inspector で以下の設定をすることで Sora がメッセージにヘッダーを付与します。

- `{"type": "sender_connection_id"}` を設定する

## メッセージの送信

Sora Unity SDK サンプル集ではメッセージの送信は ゲーム画面の送信ボタンを押下することで送信できます。

メッセージの内容は `aaa` を送信するようになっています。

SoraSample.cs の以下に示す部分を変更することで送信するメッセージを変更することができます。

```csharp
public void OnClickSend()
{
    if (fixedDataChannelLabels == null || sora == null)
    {
        return;
    }
    // リアルタイムメッセージングを使って全てのラベルに適当なデータを送る
    foreach (var label in fixedDataChannelLabels)
    {
        string message = "aaa";
        sora.SendMessage(label, System.Text.Encoding.UTF8.GetBytes(message));
    }
}
```

<!-- mikan:page doc="samples_forwarding_filters" -->

# 転送フィルター機能

## 概要

ここでは Sora Unity SDK のサンプル集を使って転送フィルターの設定を試す方法を説明します。

[Sora Unity SDK サンプル集](https://github.com/shiguredo/sora-unity-sdk/tree/master/SoraUnitySdkExamples)

## 転送フィルターの注意点

- Inspector で転送フィルターを設定する場合 Unity 2022 LTS 以前のバージョンでは表示に問題があります。

## 転送フィルター

転送フィルターは Sora がクライアントへ転送する音声や映像のパケットをフィルターする機能です。

転送フィルターを設定することで特定の映像や音声を受信しなくなります。

詳細は [Sora のドキュメント](https://sora-doc.shiguredo.jp/FORWARDING_FILTER) をご確認ください。

## マルチ転送フィルターの設定方法

マルチ転送フィルター機能は、転送フィルターに名前 (name) と優先度 (priority) を指定することで、 1 チャネルや 1 コネクションに複数の転送フィルターを設定できる機能です。

転送フィルターよりも複雑な条件でフィルターを設定できます。

詳細は [Sora のドキュメント](https://sora-doc.shiguredo.jp/MULTI_FORWARDING_FILTER) をご確認ください。

## 転送フィルターの設定方法

Inspector の ForwardingFilters の設定を変更することで転送フィルターを設定できます。

ForwardingFilters はリストなので、1 件だけ設定すれば単独の転送フィルターと同じ挙動になります。

1 チャネル、1 コネクションに対して複数の転送フィルターを設定したい場合は name や priority を設定します。

それぞれに Action などの設定を行うことができます。

![image](https://i.gyazo.com/c07c4dd44626bd5f44a89a7c542fa03a.png)

以下に設定方法を記載します。

### Action

EnableAction を有効にすることで action 項目を有効にできます。

Forwarding Filter Action を指定することで allow と block のどちらかを設定できます。

![image](https://i.gyazo.com/de2123337129929ba5c31bda81d099dc.png)

### Name

EnableName を有効にすることで name 項目を有効にできます。

Forwarding Filter Name を指定することでフィルターに名前を設定できます。

![image](https://i.gyazo.com/cdc7cb7340ac1c13016855a7a52d65f2.png)

### Priority

EnablePriority を有効にすることで priority 項目を有効にできます。

Forwarding Filter Priority を指定することでフィルターの優先度を設定できます。

![image](https://i.gyazo.com/500ce287d9d3f5b3ec030f86597dc5c0.png)

### Rule Lists

### Data

Data の数を増やすことで一つの転送フィルターにかける条件を増やすことができます。

Data には Field / Op / Values があり、そこに条件を設定します。

![image](https://i.gyazo.com/c59d1feb4aaf6c7483f0f48f4342ea4b.png)

### Field

Field には以下の値を設定できます。

- connection_id : フィルターをかける connection_id を指定します。
- client_id : フィルターをかける client_id を指定します。
- kind : フィルターをかける kind を指定します。 音声や映像を指定できます。

### Op

Op には以下の値を設定できます。

- is_in : 指定した値が Values に含まれている場合にフィルターをかけます。
- is_not_in : 指定した値が Values に含まれていない場合にフィルターをかけます。

### Values

Values には文字列を設定します。複数設定することができます。例： audio, video

kind の場合には audio または video を設定します。

### Forwarding Filter Version

Enable Forwarding Filter Version を設定することで version 項目を有効にできます。

Forwarding Filter Version を指定することで転送フィルターのバージョンを設定できます。

![image](https://i.gyazo.com/13a272a300d9732fff0c1687b766292f.png)

### Forwarding Filter Metadata

Enable Forwarding Filter Metadata を設定することで metadata 項目を有効にできます。

Forwarding Filter Metadata を指定することで metadata を設定できます。

![image](https://i.gyazo.com/feadbbefcd2e2b67a87518d50ead35d3.png)

<!-- mikan:page doc="use_h264" -->

# H.264 を利用する

Sora Unity SDK ではソフトウェアでの H.264 エンコード/デコードの利用はできません。
これは H.264 のソフトウェアエンコーダー/デコーダーを含んで配布した場合はライセンス費用が発生することから、
無効にしているためです。

ハードウェアで H.264 エンコーダー/デコーダーが使える場合は、利用するエンコーダー/デコーダーを指定することで利用することができます。
詳細は [エンコーダー / デコーダーの指定](functions_hardware_acceleration.html) を参照してください。

> **注意**
>
> AMD AMF はドライバーが不安定なため、現在非推奨です。

- Windows 版では以下のいずれかのハードウェアアクセラレーターがインストールされていれば、H.264 エンコーダー/デコーダーを利用できます。- [NVIDIA Video Codec SDK](https://developer.nvidia.com/video-codec-sdk)
  - [Intel VPL](https://github.com/intel/libvpl)
  - [AMD AMF](https://github.com/GPUOpen-LibrariesAndSDKs/AMF)
- macOS, iOS 版では [VideoToolbox](https://developer.apple.com/documentation/videotoolbox) を利用します。
- Android 版では [MediaCodec](https://developer.android.com/reference/android/media/MediaCodec) で H.264 が利用可能であれば利用します。
- Linux 版では以下のいずれかのハードウェアアクセラレーターがインストールされていれば、H.264 エンコーダー/デコーダーを利用できます。- [NVIDIA Video Codec SDK](https://developer.nvidia.com/video-codec-sdk)
  - [Intel VPL](https://github.com/intel/libvpl)
  - [AMD AMF](https://github.com/GPUOpen-LibrariesAndSDKs/AMF)

## H.264 が利用可能かどうかを調べる

`Sora.GetVideoCodecCapability()` 関数を呼び出すことで、利用可能なハードウェアエンコーダー/デコーダーの情報を取得できます。
詳細は [エンコーダー / デコーダーの指定](functions_hardware_acceleration.html) を参照してください。

<!-- mikan:page doc="set_video_size" -->

# 解像度の変更方法

## 概要

解像度の変更には「送信する映像のサイズ」、「受信するテクスチャのサイズ」、「 Unity の表示上のサイズ」の3つを変える必要があります。  
ここでの変更方法は [Sora Unity SDK サンプル集](https://github.com/shiguredo/sora-unity-sdk/tree/master/SoraUnitySdkExamples) を参考例として記載しています。

## 変更対象

- SoraSample.cs
- RawImage ( multi_sendonly シーンのみ)

## 変更方法

### 送信する映像のサイズの変更

#### SoraSample.cs

`VideoWidth` と `VideoHeight` パラメーターを追加してください。

![image](https://i.gyazo.com/36bad2d5d625a7e63107a9a2a5db7984.png)

### 受信するテクスチャのサイズの変更

#### SoraSample.cs

テクスチャを生成するパラメーターを変更してください。  
参考： [UnityDocument:Texture2D.Texture2D](https://docs.unity3d.com/jp/460/ScriptReference/Texture2D-ctor.html)

- multi_sendrecv / multi_sendonly の場合![image](https://i.gyazo.com/50d3e2699d008e59d2649733aae6b7ea.png)

### Unity の表示上のサイズの変更

#### RawImage ( multi_sendonly シーンのみ)

Hierarchy から RawImage を選択し、Inspector から `Width` と `Height` の値を変更してください。  
`Width` と `Height` を変更すると設定した値によっては「開始」と「終了」ボタンが隠れてしまうため、  
Hierarchy から 「ButtonStart」 と 「ButtonEnd」 を選択して少し上に動かしてください。

![image](https://i.gyazo.com/9ba94ab0b13edc2d4d4bf0d529e3ed14.png)

参考: `Width` と `Height` を変更すると Game ビューでは以下のように変化します。

![image](https://i.gyazo.com/791329a7ea7d5524cb781027ef918446.png)

#### multi_sendrecv シーンを変更したい場合

multi_sendrecv シーンは動的に必要なイメージ数が変わるため、あらかじめ設定する RawImage はありません。   
その場合は Hierarchy の Canvas / BaseTrack の変更と Canvas / Scroll View のサイズ変更をしてください。

![image](https://i.gyazo.com/e025bc6392b4424e1b25d0b6f95b2589.png)

### 変更結果

Unity での表示。

![image](https://i.gyazo.com/1b5cbd74888c36e3923ec99910db5955.png)

Unity から送信した映像の表示設定した 1280x720 になっています。

![image](https://i.gyazo.com/3e7b05d4a2467dcd211b95660a764910.png)

<!-- mikan:page doc="use" -->

# プロジェクトにインストールする

## 概要

ここでは Sora Unity SDK をプロジェクトにインストールして利用する方法を説明します。

インストール前に Sora Unity SDK の動作を確認したい場合は Sora Unity SDK のサンプル集を試してみてください。

[Sora Unity SDK サンプル集](https://github.com/shiguredo/sora-unity-sdk/tree/master/SoraUnitySdkExamples)

サンプル集の使い方についてはチュートリアルの [サンプル集を使った接続確認](samples_tutorial.html) をお読みください。

> **警告**
>
> Apple Vision Pro で動作を確認したい場合は [visionOS で使ってみる](use_visionos.html) をお読みください。

## Sora Unity SDK のインストール

Sora Unity SDK を導入したいご自身のプロジェクトにインストールしてみます。

 から最新の `SoraUnitySdk.zip` をダウンロードして展開し、Sora Unity SDK を利用したいプロジェクトに以下のようにコピーして下さい。

- `SoraUnitySdk/Plugins/SoraUnitySdk` を `Assets/Plugins/SoraUnitySdk` にコピーしてください- Ubuntu を利用している場合は `ubuntu-22.04` または `ubuntu-24.04` がありますので利用していないバージョンを `Assets/Plugins/SoraUnitySdk` から削除してください。
  - また、Ubuntu 以外の環境では同一ファイルエラーでビルドに失敗するため `ubuntu-22.04` または `ubuntu-24.04` を削除してください。
- `SoraUnitySdk/SoraUnitySdk` を `Assets/SoraUnitySdk` にコピーしてください。
- `SoraUnitySdk/StreamingAssets` を `Assets/StreamingAssets` にコピーしてください。

## 接続先の用意

接続先は時雨堂が開発、販売している WebRTC SFU Sora を利用します。

検証目的であれば [Sora Labo](https://sora-labo.shiguredo.jp/) を利用することで、 Sora を無料で試すことができます。

GitHub アカウントを用意して [Sora Labo のドキュメント](https://github.com/shiguredo/sora-labo-doc) を読んだ後  にサインアップしてください。

## 使ってみる

### Windows で Sora Unity SDK を使ってみる

Sora Unity SDK のインストール完了後に使うことができます。

### macOS で Sora Unity SDK を使ってみる

Sora Unity SDK のインストール完了後 [macOS で使ってみる](use_macos.html) をお読みください。

### iOS で Sora Unity SDK を使ってみる

Sora Unity SDK のインストール完了後 [iOS で使ってみる](use_ios.html) をお読みください。

### Android で Sora Unity SDK を使ってみる

Sora Unity SDK のインストール完了後 [Android で使ってみる](use_android.html) をお読みください。

### Linux で Sora Unity SDK を使ってみる

Sora Unity SDK のインストール完了後 [Linux (Ubuntu) で使ってみる](use_linux.html) をお読みください。

## FAQ

[FAQ](faq.html) をお読みください。

<!-- mikan:page doc="use_macos" -->

# macOS で使ってみる

## 動作環境

- macOS 13.3 arm64 以上が必要です
- arm64 の Mac が必要です

## macOS で使うために必要な設定

### macOS Plugin の設定

#### SoraUnitySdk.bundle

- インスペクタ -> Platform Settings -> CPU を Any CPU に設定してください。

![image](https://i.gyazo.com/9b0956b68ac846a5f9b878e78927e38f.png)

### Player Settings の設定

#### カメラ使用時の設定

カメラを使用する場合は以下の設定をする必要があります。

Player Settings -> Other Settings -> Camera Usage Description にカメラ利用のためのコメント(内容は任意)を設定してください。カメラを利用しない recvonly や Capture Unity Camera の場合は不要です。

![image](https://i.gyazo.com/5caf1a7aa3a5b5fdc9bf54665d294028.png)

#### マイク使用時の設定

マイクを使用する場合は以下の設定をする必要があります。

Player Settings -> Other Settings -> Microphone Usage Description にマイク利用のためのコメント(内容は任意)を設定して下さい。マイクを利用しない recvonly や Unity Audio Input の場合は不要です。

![image](https://i.gyazo.com/0302833be236aac6237034f4ca9c90fe.png)

<!-- mikan:page doc="use_android" -->

# Android で使ってみる

## 動作環境

- Android 7 以上が必要です
- arm64-v8a の端末が必要です

## Android で使うために必要な設定

### Android Plugin の設定変更をします

libSoraUnitySdk.so インスペクタの Platform settings -> Android の設定で CPU を ARM64 に変更して下さい。

![image](https://i.gyazo.com/f7dbf0ebbd1b1567517b4fcd34ff1c97.png)

### Graphics APIs を設定します

#### Vulkan を使用したい場合

Player Settings -> Other Settings の Graphics APIs で Vulkan を先頭にして下さい。

![image](https://i.gyazo.com/bdd46d716499e312f3361b756e90b53c.png)

#### OpenGLES を使用したい場合

Player Settings -> Other Settings の Graphics APIs で OpenGLES3 を先頭にして下さい。

![image](https://i.gyazo.com/a3fe926948f72079cb663075c7968288.png)

### Minimum API Level で Android 7.0 'Nougat' ( API level 24 ) 以上を設定します

Player Settings -> Other Settings -> Minimum API Level で Android 7.0 'Nougat' ( API level 24 ) 以上を選択してください。

![image](https://i.gyazo.com/f14a796b9c2a1661cbb4ad39734b5cc5.png)

### Target Architectures で ARM64 を設定します

Player Settings -> Other Settings -> Target Architectures で ARM64 にチェックをして下さい。

![image](https://i.gyazo.com/de434b5dfff683dd3f9c306b9e9844bc.png)

## そのほかの利用に関する注意点

- Development Build では接続できていたがリリースビルドで接続できない。- インターネット接続のパーミッションが付与されていない可能性があります。`Project Settings - Player - Android タブ - Other Settings - Configuration - Internet Access` の設定を`Require` に設定されているかご確認ください。![image](https://i.gyazo.com/264d2afe1c1fec007a673f80665cf86e.png)
- Sora Unity SDK が要求する Gradle バージョンと Unity のデフォルトバージョンの組み合わせによりアプリ起動時に即クラッシュする可能性や、Android ビルドが Gradle のバージョンによってできない可能性があります。- Unity のバージョンを最新にアップデートする- Unity が使用する Gradle のバージョンについては [Unity Editor の公式ドキュメント](https://docs.unity3d.com/ja/2023.2/Manual/android-gradle-overview.html) を参照してください。
  - Unity で利用する Gradle のバージョンを変更する

<!-- mikan:page doc="use_ios" -->

# iOS で使ってみる

## 動作環境

- iOS 13 以上が必要です
- 64bit の iPhone が必要です

## iOS で使うために必要な設定

### iOS Plugin の設定

#### libwebrtc.a

- インスペクタ -> Select Platform for plugin -> Any Platform のチェックを外し、 Include Platforms で iOS だけが チェックされるように設定してください。

![image](https://i.gyazo.com/7628eee5c7976abbc20eed5e9835b130.png)

#### libSoraUnitySdk.a

- インスペクタ -> Select Platform for plugin -> Any Platform のチェックを外し、 Include Platforms で iOS だけが チェックされるように設定してください。
- Platform settings の OpenGLES の項目にチェックが入っていない場合、チェックを入れてください。

![image](https://i.gyazo.com/fc03999de53503d484f640e419701793.jpg)

#### libboost_json.a

- インスペクタ -> Select Platform for plugin -> Any Platform のチェックを外し、 Include Platforms で iOS だけが チェックされるように設定してください。

![image](https://i.gyazo.com/db3ddc8c4624d83cd2a0ed4cc65c4fbd.png)

#### libsora.a

- 特に変更は必要ありません。想定している設定内容は以下の画像の通りです。

![image](https://i.gyazo.com/d4de6b900211ed2fb528e3d245abc216.png)

### Player Settings の設定

#### Target Minimum iOS Version

Player Settings -> Other Settings -> Target Minimum iOS Version で 12.0 以上を設定してください。

![image](https://i.gyazo.com/dfa0a38c8e5c78347a3030fb9603bd4e.png)

#### カメラ使用時の設定

カメラを使用する場合は以下の設定をする必要があります。

Player Settings -> Other Settings -> Camera Usage Description にカメラ利用のためのコメント(内容は任意)を設定してください。カメラを利用しない recvonly や Capture Unity Camera の場合は不要です。

![image](https://i.gyazo.com/ea332824fbcf5377734c6d399d1c77e2.png)

#### マイク使用時の設定

マイクを使用する場合は以下の設定をする必要があります。

Player Settings -> Other Settings -> Microphone Usage Description にマイク利用のためのコメント(内容は任意)を設定して下さい。マイクを利用しない recvonly や Unity Audio Input の場合は不要です。

![image](https://i.gyazo.com/aa73f00db149a853234939659eff999a.png)

<!-- mikan:page doc="use_visionos" -->

# visionOS で使ってみる

> **警告**
>
> Apple Vision Pro (visionOS) 対応はお試し版です。最低限の動作確認のみ行っており、正常に動作しない可能性があります。

> **警告**
>
> 現時点では音声の送受信と映像の受信のみ対応しています。映像の送信は未対応です。

## 動作環境

- visionOS 2.0 以降
- Apple Vision Pro 実機が必要です

## 制限事項

- 映像の送信は未対応です- 映像の受信は可能です
- 音声の送受信は可能です

## visionOS で使うために必要な設定

Apple Vision Pro 対応版のリリースは通常版とは別に `apple-vision-pro` タグが付与されたバージョンで提供されます。

 から `apple-vision-pro` タグが付与されたバージョンの `SoraUnitySdk.zip` をダウンロードしてください。

### インストール

ダウンロードした `SoraUnitySdk.zip` を展開し、Sora Unity SDK を利用したいプロジェクトに以下のようにコピーしてください。

- `SoraUnitySdk/Plugins/SoraUnitySdk` を `Assets/Plugins/SoraUnitySdk` にコピーしてください
- `SoraUnitySdk/SoraUnitySdk` を `Assets/SoraUnitySdk` にコピーしてください
- `SoraUnitySdk/StreamingAssets` を `Assets/StreamingAssets` にコピーしてください

### visionOS Plugin の設定

#### libwebrtc.a

- インスペクタ -> Select Platform for plugin -> Any Platform のチェックを外し、 Include Platforms で visionOS だけがチェックされるように設定してください。

![image](https://i.gyazo.com/34e01e7a48cc0eb62a7181879dcaadad.png)

#### libSoraUnitySdk.a

- インスペクタ -> Select Platform for plugin -> Any Platform のチェックを外し、 Include Platforms で visionOS だけがチェックされるように設定してください。

![image](https://i.gyazo.com/fe4b7600becf136b2327232b684498d7.png)

#### libboost_json.a

- インスペクタ -> Select Platform for plugin -> Any Platform のチェックを外し、 Include Platforms で visionOS だけがチェックされるように設定してください。

![image](https://i.gyazo.com/259a4fc6190c11b5e3b1423d699ae1e2.png)

#### libboost_filesystem.a

- インスペクタ -> Select Platform for plugin -> Any Platform のチェックを外し、 Include Platforms で visionOS だけがチェックされるように設定してください。

![image](https://i.gyazo.com/488011035e8a68ae2e1bbd5e3bde3fe9.png)

#### libsora.a

- 特に変更は必要ありません。

### Player Settings の設定

#### Target SDK の設定

Player Settings -> Other Settings -> Target SDK で Device SDK を設定してください。

#### マイク使用時の設定

マイクを使用する場合は以下の設定をする必要があります。

Player Settings -> Other Settings -> Microphone Usage Description にマイク利用のためのコメント(内容は任意)を設定してください。マイクを利用しない場合は不要です。

![image](https://i.gyazo.com/3ef2f8cb66d8627c0b88764cb429c0bd.png)

### ビルド設定

Build Settings で Platform を `visionOS` に設定してビルドしてください。

![image](https://i.gyazo.com/473a6c33feb9dfe9b7dae7e187dc2dd0.png)

### Xcode プロジェクトの設定

ビルドによって生成された Xcode プロジェクトは `Unity-VisionOS.xcodeproj` となります。

<!-- mikan:page doc="use_linux" -->

# Linux (Ubuntu) で使ってみる

## 動作環境

- Unity Editor の対応する Ubuntu バージョンを前提とします
- Sora Unity SDK では Ubuntu 22.04 / 24.04 が必要です

## Linux で使うために必要な設定

Linux で使うためには、共通の設定と NVIDIA か IntelVPL または AMD-AMF いずれかの GPU で利用するかによって設定が異なります。
ここでは共通の設定と GPU ごとに必要な設定、Plugins の配置について説明します。

### 共通の設定

Sora Unity SDK の利用には、以下のライブラリが必要です。

```shell
sudo apt-get install libdrm2 libva2 libva-drm2
```

### IntelVPL GPU を利用する場合

Ubuntu24.04 と Ubuntu22.04 でのセットアップ手順を記載します。

#### Intel VPL を Ubuntu 24.04 でセットアップする

```shell
sudo apt update
sudo apt -y install wget gpg

# Intel の GPG キーをインストールする
wget -qO - https://repositories.intel.com/gpu/intel-graphics.key | sudo gpg --dearmor --output /usr/share/keyrings/intel-graphics.gpg
# Intel のリポジトリを追加する
echo "deb [arch=amd64,i386 signed-by=/usr/share/keyrings/intel-graphics.gpg] https://repositories.intel.com/gpu/ubuntu noble client" | sudo tee /etc/apt/sources.list.d/intel-gpu-noble.list

sudo apt update
# Intel VPL に必要なライブラリをインストールする
sudo apt -y install intel-media-va-driver-non-free libmfx1 libmfx-gen1 libvpl2 libvpl-tools libva-glx2 va-driver-all vainfo

# sudo で vainfo が実行できるか確認する
sudo vainfo --display drm --device /dev/dri/renderD128

# udev のルールを追加する
sudo -s
echo 'KERNEL=="render*" GROUP="render", MODE="0666"' > /etc/udev/rules.d/99-vpl.rules
# 再起動する
sudo reboot

# vainfo が sudo なしで実行できるか確認する
vainfo --display drm --device /dev/dri/renderD128
```

#### Intel VPL を Ubuntu 22.04 でセットアップする

```shell
sudo apt update
sudo apt -y install wget gpg

# Intel の GPG キーをインストールする
wget -qO - https://repositories.intel.com/gpu/intel-graphics.key | sudo gpg --dearmor --output /usr/share/keyrings/intel-graphics.gpg
# Intel のリポジトリを追加する
echo "deb [arch=amd64,i386 signed-by=/usr/share/keyrings/intel-graphics.gpg] https://repositories.intel.com/gpu/ubuntu jammy client" | sudo tee /etc/apt/sources.list.d/intel-gpu-jammy.list

sudo apt update
# Intel VPL に必要なライブラリをインストールする
sudo apt -y install intel-media-va-driver-non-free libmfx1 libmfx-gen1 libvpl2 libvpl-tools libva-glx2 va-driver-all vainfo

# sudo で vainfo が実行できるか確認する
sudo vainfo --display drm --device /dev/dri/renderD128

# udev のルールを追加する
sudo -s
echo 'KERNEL=="render*" GROUP="render", MODE="0666"' > /etc/udev/rules.d/99-vpl.rules
# 再起動する
sudo reboot

# vainfo が sudo なしで実行できるか確認する
vainfo --display drm --device /dev/dri/renderD128
```

#### ドライバーインストール確認

```shell
lspci -k | grep -EA3 'VGA|3D|Display'
```

#### 参考リンク

[Ubuntu 24.04 LTS のインストール手順](https://dgpu-docs.intel.com/driver/client/overview.html#installing-client-gpus-on-ubuntu-desktop-24-04-lts)

[Ubuntu 24.10 のインストール手順](https://dgpu-docs.intel.com/driver/client/overview.html#installing-client-gpus-on-ubuntu-desktop-24-10)

### AMD AMF GPU を利用する場合

> **注意**
>
> AMD AMF はドライバーが不安定なため、現在非推奨です。

インストールにあたり、セキュアブートは切っておく必要があります。

AMD のグラフィックドライバーインストール手順を参考に、以下のコマンドで AMD のグラフィックドライバーをインストールしてください。

インストールするバージョンは [AMD のウェブサイト](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/install/quick-start.html) を参考に最新版を利用するようにしてください。

ここでは Ubuntu 24.04 の AMD グラフィックドライバーのインストール手順を説明します。

```shell
wget https://repo.radeon.com/amdgpu-install/6.4.3/ubuntu/noble/amdgpu-install_6.4.60403-1_all.deb
sudo apt install ./amdgpu-install_6.4.60403-1_all.deb
sudo apt update
sudo apt install "linux-headers-$(uname -r)" "linux-modules-extra-$(uname -r)"
sudo apt install amdgpu-dkms
sudo amdgpu-install --usecase=graphics,amf --vulkan=pro --no-32 -y --accept-eula

sudo usermod -aG render $USER
sudo usermod -aG video $USER

# シェルに入り直すか以下のコマンドで反映させる
newgrp render
newgrp video
```

全て手順を終えたら、再起動してください。

`vainfo` を実行することでドライバーが正しくインストールされているか確認できます。

```shell
$ sudo apt install vainfo
$ vainfo
libva info: VA-API version 1.20.0
libva info: Trying to open /usr/lib/x86_64-linux-gnu/dri/radeonsi_drv_video.so
libva info: Found init function __vaDriverInit_1_16
libva info: va_openDriver() returns 0
vainfo: VA-API version: 1.20 (libva 2.12.0)
vainfo: Driver version: Mesa Gallium driver 25.0.0-devel for AMD Radeon Graphics (radeonsi, phoenix, LLVM 19.1.5, DRM 3.63, 6.8.0-71-generic)
vainfo: Supported profile and entrypoints
    VAProfileH264ConstrainedBaseline:      VAEntrypointVLD
    VAProfileH264ConstrainedBaseline:      VAEntrypointEncSlice
    VAProfileH264Main               :      VAEntrypointVLD
    VAProfileH264Main               :      VAEntrypointEncSlice
    VAProfileH264High               :      VAEntrypointVLD
    VAProfileH264High               :      VAEntrypointEncSlice
    VAProfileHEVCMain               :      VAEntrypointVLD
    VAProfileHEVCMain               :      VAEntrypointEncSlice
    VAProfileHEVCMain10             :      VAEntrypointVLD
    VAProfileHEVCMain10             :      VAEntrypointEncSlice
    VAProfileJPEGBaseline           :      VAEntrypointVLD
    VAProfileVP9Profile0            :      VAEntrypointVLD
    VAProfileVP9Profile2            :      VAEntrypointVLD
    VAProfileAV1Profile0            :      VAEntrypointVLD
    VAProfileAV1Profile0            :      VAEntrypointEncSlice
    VAProfileNone                   :      VAEntrypointVideoProc
```

[参考 : AMD のグラフィックドライバーインストール手順](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/install/quick-start.html#amdgpu-driver-installation)

### NVIDIA GPU を利用する場合

Ubuntu のドライバーリストを確認します

```shell
sudo ubuntu-drivers list
```

NVIDIA のドライバーをインストールします。

```shell
sudo ubuntu-drivers install
```

以下のコマンドで NVIDIA GPU が利用できるか確認できます。

```shell
nvidia-smi
```

### Plugins の配置

Plugins/SoraUnitySdk/linux/x86_64 に以下のファイルを配置してください。

#### libSoraUnitySdk.so

- インスペクタ -> Platform Settings -> CPU を Any CPU に設定してください。

![image](https://i.gyazo.com/71329583ad3922f753f834416dbeb5e4.png)

<!-- mikan:page doc="build_windows" -->

# Windows 10 x86_64 向けにビルドする

**ビルドに関する質問は受け付けていません**

> **警告**
>
> 自前ビルドは推奨していません。提供されているバイナリを利用してください。

## 事前準備

以下の環境を準備します。

- Windows 10 22H2 x86_64 以降

以下のツールをインストールしてください。

- [Visual Studio 2019 | Visual Studio](https://visualstudio.microsoft.com/ja/vs/)- C++ をビルドするためのコンポーネントを入れてください
  - 動作確認は Visual Studio 2019 Community で行っています
- Python 3.10.6 以降

## Unity プラグインのビルド

PowerShell を起動し、プロジェクトのルートディレクトリで `python3 run.py build windows_x86_64` を実行してください。

```console
$ python3 run.py build windows_x86_64
```

うまくいくと `_build\windows_x86_64\release\sora_unity_sdk\Release\SoraUnitySdk.dll` が生成されます。

## インストール

`_build\windows_x86_64\release\sora_unity_sdk\Release\SoraUnitySdk.dll` と `Sora\` を自身のプロジェクトにコピーしてください。

<!-- mikan:page doc="build_macos" -->

# macOS x86_64 向けにビルドする

**ビルドに関する質問は受け付けていません**

> **警告**
>
> 自前ビルドは推奨していません。提供されているバイナリを利用してください。

## 事前準備

以下の環境を準備します。

- macOS 13.4.1 arm64 以降

以下のツールをインストールしてください。

- Xcode 14.3.1 以降
- Python 3.10.6 以降

## Unity プラグインのビルド

コマンドラインで `python3 run.py build macos_arm64` を実行してください。

```console
$ python3 run.py build macos_arm64
```

ビルドに成功すると `_build/macos_arm64/release/sora_unity_sdk/SoraUnitySdk.bundle` が生成されます。

## インストール

`_build/macos_arm64/release/sora_unity_sdk/SoraUnitySdk.bundle` と `Sora/` を任意のプロジェクトの Assets にコピーしてください。

<!-- mikan:page doc="build_linux" -->

# Linux x86_64 向けにビルドする

**ビルドに関する質問は受け付けていません**

> **警告**
>
> 自前ビルドは推奨していません。提供されているバイナリを利用してください。

## 事前準備

以下の環境を準備します。

- Ubuntu 22.04 x86_64 以降

以下のツールをインストールしてください。

- libdrm-dev libva-dev libgl-dev パッケージ
- Python 3.10.6 以降

## Unity プラグインのビルド

コマンドラインで `python3 run.py build ubuntu-22.04_x86_64` を実行してください。

```console
$ python3 run.py build ubuntu-22.04_x86_64
```

ビルドに成功すると `_build/ubuntu-22.04_x86_64/release/sora_unity_sdk/libSoraUnitySdk.so` が生成されます。

## インストール

`_build/ubuntu-22.04_x86_64/release/sora_unity_sdk/libSoraUnitySdk.so` と `Sora/` を任意のプロジェクトの Assets にコピーしてください。

<!-- mikan:page doc="build_android" -->

# Android 向けにビルドする

**ビルドに関する質問は受け付けていません**

> **警告**
>
> 自前ビルドは推奨していません。提供されているバイナリを利用してください。

## 事前準備

以下の環境を準備します。

- Ubuntu 22.04 x86_64 以降

以下のツールをインストールしてください。

- libdrm-dev libva-dev libgl-dev パッケージ
- Python 3.10.6 以降

## Unity プラグインのビルド

コマンドラインで `python3 run.py build android` を実行してください。

```console
$ python3 run.py build android
```

ビルドに成功すると `_build/android/release/sora_unity_sdk/libSoraUnitySdk.so` が生成されます。

## インストール

`_build/android/release/sora_unity_sdk/libSoraUnitySdk.so` と `Sora/` を任意のプロジェクトの Assets にコピーしてください。

<!-- mikan:page doc="build_ios" -->

# iOS 向けにビルドする

**ビルドに関する質問は受け付けていません**

> **警告**
>
> 自前ビルドは推奨していません。提供されているバイナリを利用してください。

## 事前準備

以下の環境を準備します。

- macOS 13.4.1 arm64 以降

以下のツールをインストールしてください。

- Xcode 14.3.1 以降
- Python 3.10.6 以降

## Unity プラグインのビルド

コマンドラインで `python3 run.py build ios` を実行してください。

```console
$ python3 run.py build ios
```

ビルドに成功すると `_build/ios/release/sora_unity_sdk/libSoraUnitySdk.a` が生成されます。

## インストール

`_build/ios/release/sora_unity_sdk/libSoraUnitySdk.a` と `Sora/` を任意のプロジェクトの Assets にコピーしてください。

<!-- mikan:page doc="build_visionos" -->

# visionOS 向けにビルドする

**ビルドに関する質問は受け付けていません**

> **警告**
>
> 自前ビルドは推奨していません。提供されているバイナリを利用してください。

> **警告**
>
> Apple Vision Pro (visionOS) 対応はお試し版です。

## 事前準備

以下の環境を準備します。

- macOS 26 arm64 以降

以下のツールをインストールしてください。

- Xcode 26 以降
- Python 3.10.6 以降

利用したい Apple Vision Pro のリリースブランチをチェックアウトしてください。

例: `git checkout 2026.1.0-apple-vision-pro.0`

## Unity プラグインのビルド

コマンドラインで `python3 run.py build visionos` を実行してください。

```console
$ python3 run.py build visionos
```

ビルドに成功すると `_build/visionos/release/sora_unity_sdk/libSoraUnitySdk.a` が生成されます。

## インストール

`_build/visionos/release/sora_unity_sdk/libSoraUnitySdk.a` と `Sora/` を任意のプロジェクトの Assets にコピーしてください。

<!-- mikan:page doc="2025_1_to_2025_2" -->

# 2025.1.x から 2025.2.x への移行

2025.1.x から 2025.2.x への移行についての注意点をまとめています。

変更内容の詳細については [リリースノート](release.html) を参照してください。

## エンコーダー・デコーダー指定方法の変更

2025.1.x までは、ハードウェアアクセラレーターを優先して利用していましたが、
2025.2.x からは、libwebrtc が利用するエンコーダー・デコーダー以外のハードウェアアクセラレーターを利用する場合は明示的に指定を行う必要があります。

これまで通りエンコーダー・デコーダーにハードウェアアクセラレーターを優先して利用したい場合は、
以下のように、変更することで利用することができます。

ハードウェアアクセラレーターの優先順位は以下の通りです。

> > **注意**
> >
> > AMD AMF はドライバーが不安定なため、現在非推奨です。

- Intel VPL
- AMD AMF
- NVIDIA Video Codec
- Internal (未指定時に自動で使用される、libwebrtc が利用するエンコーダー・デコーダー)

```csharp
// ハードウェアエンコーダーが使える場合は優先して使う

// 1. ビデオエンコーダーの対応状況を取得する
var capability = Sora.GetVideoCodecCapability(new Sora.VideoCodecCapabilityConfig());

// 2. 取得した対応状況から、ハードウェアエンコードを優先するための設定を取得する
var preference = Sora.VideoCodecPreference.GetHardwareAcceleratorPreference(capability);

// 3. config に優先設定を適用することで、ハードウェアエンコーダーが利用できる環境ではソフトウェアエンコードより優先して使用される
config.VideoCodecPreference = preference;
```

### エンコーダー・デコーダーの指定方法の変更に伴い、以下の変更が行われました。

#### `Sora.Config.UseHardwareEncoder` の削除

`Sora.Config.UseHardwareEncoder` は削除されました。

今後は `Sora.Config.VideoCodecPreference` を使用してください。

これまでのような `true/false` のフラグではなく、利用するエンコーダー・デコーダーの実装を明示的に指定できるようになりました。

以下のように、利用可能なハードウェアエンコーダー／デコーダーを優先する設定が可能です。

詳細は [エンコーダーデコーダーの指定](functions_hardware_acceleration.html) を参照してください。

#### `Sora.IsH264Supported()` 関数の削除

`Sora.IsH264Supported()` 関数が削除されました。  
この関数は、H.264 のハードウェアエンコード・ハードウェアデコードが利用可能かどうかを true/false で返していました。  
今後は `Sora.GetVideoCodecCapability()` を使用し、対応しているエンコーダー・デコーダーの情報を確認してください。

以下のようにして、現在の環境で利用可能な実装と対応コーデックの一覧をログに出力できます。

```csharp
var capability = Sora.GetVideoCodecCapability(new Sora.VideoCodecCapabilityConfig());
foreach (var engine in capability.Engines)
{
    Debug.Log($"Implementation: {engine.Name}");
    foreach (var codec in engine.Codecs)
    {
        Debug.Log($"  Codec: {codec.Type}, Encoder: {codec.Encoder}, Decoder: {codec.Decoder}");
    }
}
```

## Ubuntu 20.04 のサポート終了

Ubuntu 20.04 のサポートが終了しました。
引き続き Ubuntu を利用する場合は Ubuntu22.04 または Ubuntu 24.04 への移行をお願いします。

Ubuntu 22.04 または Ubuntu 24.04 のインストール方法は [プロジェクトにインストールする](use.html) を参照してください。

## 音声コーデックと映像コーデックのデフォルト値変更

Sora.Config.VideoCodecType と Sora.Config.AudioCodecType のデフォルト値が変更されました。
2025.2.x からは Nullable 型になり、デフォルトは null (未指定)になります。

未指定の場合、以下の Sora のデフォルトのコーデックが使用されます。これは以前のデフォルト値と同じ値なので利用されるコーデックに変更はありません。

- 音声コーデック: OPUS
- 映像コーデック: VP9

<!-- mikan:page doc="2024_1_to_2024_2" -->

# 2024.1.x から 2024.2.x への移行

2024.2.0 にて `AudioOutputHelper` の利用方法が変更されました。
ハンズフリー機能を利用している場合は、以下の手順で移行してください。

## 修正内容

- `Sora.AudioOutputHelper` は `Sora.IAudioOutputHelper` に変更されました。- `Sora.IAudioOutputHelper` は `Sora.AudioOutputHelperFactory.Create` メソッドを使用して生成されます。このメソッドはスピーカーの変更を検知するための Action 型の引数を取ります。

## 移行方法

Sora.AudioOutputHelper の生成ロジックの変更を行います。

1. `Sora.AudioOutputHelper` を `IAudioOutputHelper` に変更します。
2. `Sora.IAudioOutputHelper` のインスタンスを生成する箇所を、 `AudioOutputHelperFactory.Create` を利用するよう変更します。

以下のサンプルコードを元に対応を行ってください。

### 移行前 (2024.1.0)

```csharp
// AudioOutputHelper のインスタンスを取得する
Sora.AudioOutputHelper audioOutputHelper;

void Start()
{
    // アプリケーションの初期処理で AudioOutputHelper のインスタンスを生成する
    // 引数には Action を設定する。一例としてここではログ出力を行う
    audioOutputHelper = new Sora.AudioOutputHelper(() => { Debug.Log("OnChangeRoute"); });
}
```

### 移行後 (2024.2.0)

```csharp
// IAudioOutputHelper のインスタンスを取得する
// インスタンス名を IAudioOutputHelper に変更する
Sora.IAudioOutputHelper audioOutputHelper;

void Start()
{
    // アプリケーションの初期処理で IAudioOutputHelper のインスタンスを生成する
    // 引数には Action を設定する。一例としてここではログ出力を行う
    // Sora.AudioOutputHelperFactory.Create を使用してインスタンスを生成する
    audioOutputHelper = Sora.AudioOutputHelperFactory.Create(() => { Debug.Log("OnChangeRoute"); });
}
```

<!-- mikan:page doc="2023_3_to_2023_4" -->

# 2023.3.x から 2023.4.x への移行

2023.4.0 にて `Sora.Config` 中にあるカメラに関する以下のフィールドを `Sora.CameraConfig` に移動しました。
以下の項目を利用している場合は、 `Sora.CameraConfig` に移行してください。

- CapturerType
- UnityCamera
- UnityCameraRenderTargetDepthBuffer
- VideoCapturerDevice
- VideoWidth
- VideoHeight
- VideoFps

## 修正内容

- `Sora.Config` に `Sora.CameraConfig` を追加しました。 `Sora.CameraConfig` はカメラに関する以下の設定を保持するクラスです。- CapturerType
  - UnityCamera
  - UnityCameraRenderTargetDepthBuffer
  - VideoCapturerDevice
  - VideoWidth
  - VideoHeight
  - VideoFps
- `Sora.Config` から以下の項目を削除しました。- CapturerType
  - UnityCamera
  - UnityCameraRenderTargetDepthBuffer
  - VideoCapturerDevice
  - VideoWidth
  - VideoHeight
  - VideoFps

## 移行方法

以下の通り、カメラに関する設定を `Sora.CameraConfig` に移行してください。

### デバイスカメラの例

- 移行前 (2023.3.0)

移行前のデバイスカメラに関する設定は Sora.Config のフィールドとして定義されており、以下のように設定していました。
例として可能な限り多くの項目を設定していますが利用している項目のみの移行で問題ありません。

```csharp
config = new Config() {
  SignalingUrl = "wss://sora.example.com/signaling",
  ChannelId = "sora",
  // Sora.Config フィールドにあったデバイスカメラに関する設定
  CapturerType = Sora.CapturerType.DeviceCamera,
  VideoCapturerDevice = "camera",
  VideoWidth = 640,
  VideoHeight = 480,
  VideoFps = 30,
};
```

- 移行後 (2023.4.0)

移行後のデバイスカメラに関する設定は新たに作られた Sora.CameraConfig 内のフィールドになりました。

```csharp
config = new Config() {
  SignalingUrl = "wss://sora.example.com/signaling",
  ChannelId = "sora",
  // Sora.CameraConfig で移行前と同じデバイスカメラ設定を指定します。
  CameraConfig = new CameraConfig() {
    CapturerType = Sora.CapturerType.DeviceCamera,
    VideoCapturerDevice = "camera",
    VideoWidth = 640,
    VideoHeight = 480,
    VideoFps = 30,
  },
};
```

### Unity Camera の例

- 移行前 (2023.3.0)

移行前の Unity カメラに関する設定は Sora.Config のフィールドとして定義されており、以下のように設定していました。
例として可能な限り多くの項目を設定していますが利用している項目のみの移行で問題ありません。

```csharp
config = new Config() {
  SignalingUrl = "wss://sora.example.com/signaling",
  ChannelId = "sora",
  // Sora.Config フィールドにあった Unity カメラに関する設定
  CapturerType = Sora.CapturerType.UnityCamera,
  UnityCamera = someUnityCapturedCamera,
  UnityCameraRenderTargetDepthBuffer = 16,
  VideoWidth = 640,
  VideoHeight = 480,
  VideoFps = 30,
};
```

- 移行後 (2023.4.0)

移行後の Unity カメラに関する設定は新たに作られた Sora.CameraConfig 内のフィールドになりました。

```csharp
config = new Config() {
  SignalingUrl = "wss://sora.example.com/signaling",
  ChannelId = "sora",
  // Sora.CameraConfig で移行前と同じ Unity カメラ設定を指定します。
  CameraConfig = new CameraConfig() {
    CapturerType = Sora.CapturerType.UnityCamera,
    UnityCamera = someUnityCapturedCamera,
    UnityCameraRenderTargetDepthBuffer = 16,
    VideoWidth = 640,
    VideoHeight = 480,
    VideoFps = 30,
  },
};
```

## 移行の経緯

カメラ切り替え機能を追加に伴い `Sora` に `Sora.SwitchCamera(CameraConfig)` を追加しました。
引数の簡略化のために `Sora.CameraConfig` に設定をまとめました。