# Sora に接続する

## 概要

Sora への接続処理の概要について記載しています。

## 接続の手順

Sora への接続は次の手順で行います。

1. [Configuration](_static/api/docs/Structs/Configuration.html) を生成する。
2. [Sora](_static/api/docs/Classes/Sora.html) オブジェクトの [connect メソッド](https://sora-ios-sdk.shiguredo.jp/_static/api/docs/Classes/Sora#/s:4SoraAAC7connect13configuration19webRTCConfiguration7handlerAA14ConnectionTaskCAA13ConfigurationV_AA03WebE0VyAA12MediaChannelCSg_s5Error_pSgtctF) を呼ぶ。

```swift
    import Sora

    // シグナリング URL とチャネル ID を指定する
    let url = URL(string: "wss://sora.example.com/signaling")!
    let soraChannelId = "sora"
    let config = Configuration(url: url,
                                  channelId: soraChannelId,
                                  role: .recvonly)

    // 接続する
    Sora.shared.connect(configuration: config) { mediaChannel, error in
        // 接続に失敗するとエラーが渡される。
        // 接続に成功すると error は nil
        if let error = error {
            // 接続エラー時の処理
            ...
        }

        // 接続成功時の処理
        // 映像を描画するビューをストリームにセットする等
        ...
    }
}
```

[Configuration](_static/api/docs/Structs/Configuration.html) は Sora への接続情報などの設定を保持するオブジェクトです。
Sora のシグナリング URL 、チャネル ID 、ロールをセットします。

次に [Configuration](_static/api/docs/Structs/Configuration.html) を引数として [Sora](_static/api/docs/Classes/Sora.html) オブジェクトの [connect メソッド](https://sora-ios-sdk.shiguredo.jp/_static/api/docs/Classes/Sora#/s:4SoraAAC7connect13configuration19webRTCConfiguration7handlerAA14ConnectionTaskCAA13ConfigurationV_AA03WebE0VyAA12MediaChannelCSg_s5Error_pSgtctF) を呼びます。このとき [Sora](_static/api/docs/Classes/Sora.html) オブジェクトは `Sora.shared` プロパティでシングルトンを取得できます。
このメソッドは Sora への接続を行い、接続の成否に関わらず `handler:` に指定されたブロックを実行します。
接続が成功すると [MediaChannel](_static/api/docs/Classes/MediaChannel.html) がブロックの引数として渡されます。
[MediaChannel](_static/api/docs/Classes/MediaChannel.html) は接続後の操作を行うためのオブジェクトです。

[connect メソッド](https://sora-ios-sdk.shiguredo.jp/_static/api/docs/Classes/Sora#/s:4SoraAAC7connect13configuration19webRTCConfiguration7handlerAA14ConnectionTaskCAA13ConfigurationV_AA03WebE0VyAA12MediaChannelCSg_s5Error_pSgtctF) の型と引数は次の通りです。


```
func connect(configuration: Configuration,
             webRTCConfiguration: WebRTCConfiguration = WebRTCConfiguration(),
             handler: (_ mediaChannel: MediaChannel?, _ error: Error?) -> Void)
```

- `configuration`: 接続情報です。シグナリング URL とチャネル ID を指定します。
- `webRTCConfiguration`: WebRTC に関する設定です (省略可) 。
- `handler`: 接続試行後に実行するブロックです。ブロックの型は `(MediaChannel?, Error?) -> Void` です。ブロックの引数は次の通りです。- `mediaChannel`: 接続に成功するとメディアチャネルが渡されます。失敗時は `nil` です。
  - `error`: 接続に失敗するとエラーが渡されます。成功時は `nil` です。

[MediaChannel](_static/api/docs/Classes/MediaChannel.html) は映像データを扱うストリームを複数保持します。
映像はストリームを通じて Sora と送受信されます。

ストリームは送信か受信のいずれかを担当し、ロールによって扱う数が異なります。
シングルストリームにおいて、送信と受信のストリームはそれぞれ 1 つです。
つまり、シングルストリームでは 1 回の接続につき送信か受信かのいずれか一方しか行えません。
**1 台の端末で映像の送受信を行う場合は、送信と受信で 2 回の接続が必要です。**

接続後の映像の送受信については [映像を描画する](videoview.html#6bc6da) を参考にしてください

## DataChannel 経由のシグナリング

Sora と DataChannel を経由したシグナリング通信を行うための接続方法について記載します。
詳しい仕様は [Sora のドキュメント](https://sora-doc.shiguredo.jp/DATA_CHANNEL_SIGNALING) をご確認ください。

DataChannel 経由のシグナリングを有効にするには、 [Configuration](_static/api/docs/Structs/Configuration.html) の `dataChannelSignaling` プロパティに `true` をセットしてください。
WebSocket が閉じたときに Sora に接続が切断されたと判断して欲しくない場合は `ignoreDisconnectWebSocket` プロパティに `true` をセットしてください。

```swift
var config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

// DataChannel 経由のシグナリングを有効にする
config.dataChannelSignaling = true

// WebSocket が閉じたことを無視する
config.ignoreDisconnectWebSocket = true
```

### イベントハンドラ

DataChannel に関するイベントハンドラは [MediaChannelHandlers](_static/api/docs/Classes/MediaChannelHandlers.html) に用意しています。
主なイベントハンドラは以下の通りです。

```swift
/// シグナリングが DataChannel 経由に切り替わったタイミングで呼ばれるクロージャー
public var onDataChannel: ((MediaChannel) -> Void)?

/// DataChannel のメッセージ受信時に呼ばれるクロージャー
public var onDataChannelMessage: ((MediaChannel, String, Data) -> Void)?
```

## 音声コーデックの設定

Sora 接続時に送信する音声についてコーデックの指定ができます。

- 音声のコーデックは [Configuration](_static/api/docs/Structs/Configuration.html) の `audioCodec` に [AudioCodec](_static/api/docs/Enums/AudioCodec.html) を設定します。

```swift
var config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

// 音声コーデックを opus に設定する
config.audioCodec = .opus
```

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

Sora 接続時に送信する音声についてビットレートの指定ができます。

- 音声のビットレートは [Configuration](_static/api/docs/Structs/Configuration.html) の `audioBitRate` に設定します。

```swift
var config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

// 音声ビットレートを 32 kbps に設定する
config.audioBitRate = 32
```

## 映像コーデックの設定

Sora 接続時に送信する映像についてコーデックの指定ができます。

- 映像のコーデックは [Configuration](_static/api/docs/Structs/Configuration.html) の `videoCodec` に [VideoCodec](_static/api/docs/Enums/VideoCodec.html) を設定します。
- 利用できる映像コーデックは VP8 / VP9 / H.264 / H.265 / AV1 です。未指定の場合は Sora のデフォルト値が設定されます。

```swift
var config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

// 映像コーデックを VP8 に設定する
config.videoCodec = .vp8
```

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

Sora 接続時に送信する映像についてビットレートの指定ができます。

- 映像のビットレートは [Configuration](_static/api/docs/Structs/Configuration.html) の `videoBitRate` に設定します。

```swift
var config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

// ビデオビットレートを 3000 kbps に設定する
config.videoBitRate = 3000
```


## 映像コーデックパラメーターの設定

送信する映像コーデックの設定と合わせて、映像コーデックのパラメータを指定可能です。
この機能は `role` が `sendrecv` または `sendonly` の場合に利用できます。

指定できる値の内容については以下の Sora ドキュメントをご確認ください。

- [Sora ドキュメント - ビデオの VP9 設定指定](https://sora-doc.shiguredo.jp/SIGNALING#b7556a)
- [Sora ドキュメント - ビデオの AV1 設定指定](https://sora-doc.shiguredo.jp/SIGNALING#48f92d)
- [Sora ドキュメント - ビデオの H.264 設定指定](https://sora-doc.shiguredo.jp/SIGNALING#ffc4cb)

```swift
var config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

// 映像コーデックの設定は VP9 / AV1 / H.264 のいずれか 1 種類のみです
// 利用しない映像コーデックパラメーターは設定しないでください

// VP9 の場合は profile_id の設定が可能です
config.videoCodec = .vp9
config.videoVp9Params = ["profile_id": 0]

// AV1 の場合は profile の設定が可能です
// config.videoCodec = .av1
// config.videoAv1Params = ["profile": 0]

// H.264 の場合は profile_level_id の設定が可能です
// config.videoCodec = .h264
// config.videoH264Params = ["profile_level_id": "42e01f"]
```


## 転送フィルターの設定

転送フィルター機能は、Sora 側でクライアントへ転送する音声や映像のパケットをフィルターする機能です。
詳しくは [Sora ドキュメント](https://sora-doc.shiguredo.jp/API_FORWARDING_FILTER) をご確認ください。

この機能は `role` が `sendrecv` または `recvonly` の場合にのみ利用できます。

### フィルターを設定する

Sora 接続時に `Configuration.forwardingFilters` を設定します。

### 設定例

以下の例は、自分の接続に対して、次の条件で映像または音声の受信をブロックします。

- connection_id が "S8YEN0TSE13JDC2991NG4XZ150" の場合は音声と映像の受信をブロックする、または client_id が "screen-share" の場合は音声の受信をブロックする

```swift
var config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

let forwardingFilter = ForwardingFilter(
    action: .block,
    rules: [
        [
            ForwardingFilterRule(field: .connectionId,
                                 operator: .isIn,
                                 values: ["S8YEN0TSE13JDC2991NG4XZ150"]),
        ],
        [
            ForwardingFilterRule(field: .clientId,
                                 operator: .isIn,
                                 values: ["screen-share"]),
            ForwardingFilterRule(field: .kind,
                                 operator: .isIn,
                                 values: ["audio"]),
        ]
    ],
)

config.forwardingFilters = [forwardingFilter]
```


## プロキシ・サーバーの設定

プロキシ・サーバーを経由した通信を行う場合は、 [Configuration](_static/api/docs/Structs/Configuration.html) の `proxy` プロパティにプロキシ情報をセットしてください。

- HTTP プロキシに対応しています
- SOCKS プロキシも設定できますが、動作を確認していません
- HTTP の CONNECT メソッドは HTTPS ではなく HTTP で送信します
- Proxy-Authorization ヘッダーを利用した Basic 認証に対応しています
- iOS の Wi-Fi に設定されたプロキシの項目を参照しません

```swift
var config = Configuration(url: url,
                           channelId: channelId,
                           role: .sendrecv)

// proxy 情報の設定を行う
config.proxy = Proxy(host: "proxy.example.com",
                            port: 3128,
                            agent: nil,
                            username: "ham",
                            password: "egg")
```


## 複数のシグナリング URL を指定する

Sora iOS SDK では、 urlCandidates に複数のシグナリング URL を指定することができます。

Sora iOS SDK は全ての URL に対して接続を試行し、最初に成功した接続をシグナリングに使用します。
このため、１台でも正常なサーバーが残っていれば Sora への接続が成功します。
クラスター機能は複数の URL を指定しなくても利用できますが、冗長性を高めるために複数 URL の指定を推奨します。

```swift
let urlCandidates = [
    URL(string: "wss://sora1.example.com/signaling")!,
    URL(string: "wss://sora2.example.com/signaling")!,
    URL(string: "wss://sora3.example.com/signaling")!
]
var config = Configuration(urlCandidates: urlCandidates,
                           channelId: channelId,
                           role: .sendrecv)
```

- 実際にシグナリングに利用されている URL は `MediaChannel` クラスの `connectedUrl` フィールドから確認できます。


## クラスター機能利用時のシグナリングのリダイレクト

クラスター機能を有効にすると、 Sora から、 type: offer の代わりに type: redirect が送られてくることがあります。
この場合、Sora iOS SDK は Sora の接続を一度切断し、 type: redirect で指定された location に再接続します。


## CPU やネットワーク帯域等逼迫時における映像品質優先項目の設定

映像の配信中に、CPU やネットワーク帯域などの制約を受けて、指定された解像度やフレームレートを維持できないことがあります。
そのような場合に、優先する項目を設定することができます。

例えば、文章が中心のスライドを利用するプレゼンテーションなど、フレームレートより解像度を優先した映像の配信を行いたい場合に、解像度を優先するように設定できます。

設定は [Configuration](_static/api/docs/Structs/Configuration.html) の `webRTCConfiguration.degradationPreference` から行います。
`degradationPreference` には以下の値を設定できます。

- disabled ... 何もしない
- balanced ... バランスを取る
- maintainResolution ... 解像度の維持を優先する
- maintainFramerate ... フレームレートの維持を優先する (デフォルトの挙動です)

```Swift
let config = Configuration(url: url,
                                channelId: soraChannelId,
                                role: .sendonly)

// リソースが逼迫した場合は解像度の維持を優先する
config.webRTCConfiguration.degradationPreference = .maintainResolution
```