Sora

public final class Sora : @unchecked Sendable

サーバーへのインターフェースです。 Sora オブジェクトを使用してサーバーへの接続を行います。

Show on GitHub

SDK の操作

  • SDK の終了処理を行います。 アプリケーションの終了と同時に SDK の使用を終了する場合、 この関数を呼ぶ必要はありません。

    Declaration

    Swift

    public static func finish()
    Show on GitHub

  • ログレベル。指定したレベルより高いログは出力されません。 デフォルトは info です。

    Declaration

    Swift

    public static var logLevel: LogLevel { get set }
    Show on GitHub

プロパティ

イベントの購読

  • Sora インスタンスのイベントを購読します。

    購読者ごとに独立した AsyncStream を返します。購読ごとに buffer / drop 方針 / 終端が 独立しており、1 つの購読を解除しても他の購読者へ影響しません。接続ごとのイベントは MediaChannel.subscribeEvents(bufferingPolicy:) で購読します。

    • 配送されるのは mediaChannelAdded / mediaChannelRemoved / audioRouteChanged と、 このインスタンスが開始した接続の connected / connectFailed / disconnected です。
    • イベントは配送順に届きます。通し番号の順序と一致しない場合はあります (同時に配送された イベントのみ)。
    • buffer は既定で SoraEvent.defaultBufferSize 件です。あふれた場合は最も古いイベントが 破棄されます。sequence で欠落を検出できます。
    • 購読を開始する前に配送されたイベントは届きません (buffer は購読ごとに作られます)。 接続前に開始しておけば、mediaChannelAdded と接続結果を取り逃しません。
    • payload はすべて値として確定しており、配送後も購読者が保持できます。
    • 購読の解除は、購読している Task の cancel、購読に使った AsyncStream への参照の解放、 または Sora インスタンスの解放です。
    • 購読している Task の loop の中から同期 API (mediaChannels などの getter、connect、 disconnect を含む) を呼べます。配送は排他区間の外で行うため deadlock しません。
    • 配送 executor はイベントの発生元によって異なります (libwebrtc の callback スレッド、 signaling の受信スレッド、DispatchQueue.global()、呼び出し元の executor など)。AsyncStream の再開後に実行される購読者のコードは、購読している Task の executor 上で動きます。 UI 更新は main actor / main queue へ束ねてください。

    • この API の追加によって、既存の handlers の callback 型・配送 executor・配送順序・ 発火回数は変わりません。

    Declaration

    Swift

    public func subscribeEvents(
  bufferingPolicy: AsyncStream<SoraEvent>.Continuation.BufferingPolicy = .bufferingNewest(
    SoraEvent.defaultBufferSize)
) -> AsyncStream<SoraEvent>

    Parameters

    bufferingPolicy

    購読者ごとの buffer と drop 方針

    Return Value

    このインスタンスのイベントを配送する stream

    Show on GitHub

インスタンスの生成と取得

  • シングルトンインスタンス

    Declaration

    Swift

    public static let shared: Sora
    Show on GitHub

  • 初期化します。 大抵の用途ではシングルトンインスタンスで問題なく、 インスタンスを生成する必要はないでしょう。 メディアチャネルのリストをグループに分けたい、 または複数のイベントハンドラを使いたいなどの場合に インスタンスを生成してください。

    Declaration

    Swift

    public init()
    Show on GitHub

接続

  • サーバーに接続します。

    呼び出し元のスレッドは保証されない (接続に成功した場合、設定エラーで終端した場合、接続に 失敗した場合のいずれも、接続を開始したスレッドとは異なるスレッドから呼ばれ得る)。 UI 更新や共有状態の変更は main queue / main actor へ束ねること。

    Swift 6 言語モードで @MainActor の文脈から接続する場合は、クロージャに @Sendable を 付けるか nonisolated な関数へ処理を分離して隔離を外す。MediaChannel は Sendable では ないため、main actor へ渡す場合は nonisolated(unsafe) let で運び、 Task { @MainActor in ... } で main actor 上へ移す。

    Declaration

    Swift

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

    Parameters

    configuration

    クライアントの設定
    webRTCConfiguration

    WebRTC の設定
    handler

    接続試行後に呼ばれるクロージャー。
    mediaChannel

    (接続成功時のみ) メディアチャネル
    error

    (接続失敗時のみ) エラー

    Return Value

    接続試行中の状態

    Show on GitHub

音声ユニットの操作

  • 音声ユニットの手動による初期化の可否。 false をセットした場合、音声トラックの生成時に音声ユニットが自動的に初期化されます。 (音声ユニットを使用するには audioEnabled に true をセットして初期化する必要があります) true をセットした場合、音声ユニットは自動的に初期化されません。 デフォルトは false です。

    Declaration

    Swift

    public var usesManualAudio: Bool { get set }
    Show on GitHub

  • 音声ユニットの使用の可否。 このプロパティは usesManualAudio が true の場合のみ有効です。 デフォルトは false です。

    true をセットした場合、音声ユニットは必要に応じて初期化されます。 false をセットした場合、すでに音声ユニットが初期化済みで起動されていれば、 音声ユニットを停止します。

    このプロパティを使用すると、音声ユニットの初期化によって AVPlayer などによる再生中の音声が中断されてしまうことを防げます。

    Declaration

    Swift

    public var audioEnabled: Bool { get set }
    Show on GitHub

  • AVAudioSession の設定を変更する際に使います。 WebRTC で使用中のスレッドをロックします。 このメソッドは次のプロパティとメソッドの使用時に使ってください。

    • category
    • categoryOptions
    • mode
    • secondaryAudioShouldBeSilencedHint
    • currentRoute
    • maximumInputNumberOfChannels
    • maximumOutputNumberOfChannels
    • inputGain
    • inputGainSettable
    • inputAvailable
    • inputDataSources
    • inputDataSource
    • outputDataSources
    • outputDataSource
    • sampleRate
    • preferredSampleRate
    • inputNumberOfChannels
    • outputNumberOfChannels
    • outputVolume
    • inputLatency
    • outputLatency
    • ioBufferDuration
    • preferredIOBufferDuration
    • setCategory(_:withOptions:)
    • setMode(_:)
    • setInputGain(_:)
    • setPreferredSampleRate(_:)
    • setPreferredIOBufferDuration(_:)
    • setPreferredInputNumberOfChannels(_:)
    • setPreferredOutputNumberOfChannels(_:)
    • overrideOutputAudioPort(_:)
    • setPreferredInput(_:)
    • setInputDataSource(_:)

    • setOutputDataSource(_:)

    Declaration

    Swift

    public func configureAudioSession(block: () -> Void)

    Parameters

    block

    ロック中に実行されるクロージャー
    Show on GitHub

  • 音声モードを変更します。 このメソッドは 接続完了後 に実行してください。

    Declaration

    Swift

    public func setAudioMode(
  _ mode: AudioMode,
  options: AVAudioSession.CategoryOptions = [
    .allowBluetooth, .allowBluetoothA2DP, .allowAirPlay,
  ]
) -> Result<Void, Error>

    Parameters

    mode

    音声モード

    Return Value

    変更の成否

    Show on GitHub

libwebrtc のログ出力

  • libwebrtc のログレベルを指定します。 ログは RTCSetMinDebugLogLevel() でも指定可能ですが、 RTCSetMinDebugLogLevel() ではログの時刻が表示されません。 本メソッドでログレベルを指定すると、時刻を含むログを出力します。

    Declaration

    Swift

    public static func setWebRTCLogLevel(_ severity: RTCLoggingSeverity)
    Show on GitHub