Configure.initialCameraEnabled を追加、接続時のカメラ初期化を遅延できるようにする

Author: t-miya

CHANGES.md

@@ -11,6 +11,9 @@
 
 ## develop
 
+- [UPDATE] VideoHardMuteActor での映像ハードミュート解除時にカメラキャプチャ未生成なら生成するようにする
+  - `Configuration.initialCameraEnabled` により接続時にカメラ初期化が行われていない場合の処理
+  - @t-miya
 - [UPDATE] libwebrtc m144.7559.2.1 に上げる
   - @t-miya
 - [UPDATE] Statistics, StatisticsEntry をドキュメント対象として公開する
@@ -19,6 +22,9 @@
 - [UPDATE] Configuration.simulcastRid を非推奨にする
   - 移行先は `Configuration.simulcastRequestRid`
   - @zztkm
+- [ADD] Configuration に接続確立時にカメラ初期化を行わない設定 `initialCameraEnabled` を追加する
+  - 接続時に映像ハードミュートを行うために利用する
+  - @t-miya
 - [ADD] MediaChannel に音声ソフトミュートを設定する `setAudioSoftMute(_:)` を追加する
   - 送信ストリームの AudioTrack を取得し、MediaStream.audioEnabled を切り替える
     - デジタルサイレンスパケットが送られる状態となり、マイクからの音声は送出されない

Sora/Configuration.swift

@@ -135,6 +135,13 @@ public struct Configuration {
   /// デフォルトは `true` です。
   public var audioEnabled: Bool = true
 
+  /// 接続確立時に端末カメラキャプチャを自動起動するかどうか。
+  ///
+  /// `cameraSettings.isEnabled` が `true` の場合でも、このフラグが `false` であれば
+  /// 接続時点ではカメラキャプチャを起動しません。
+  /// 後から `MediaChannel.setVideoHardMute(false)` などで必要に応じて開始できます。
+  public var initialCameraEnabled: Bool = true
+
   /// サイマルキャストの可否。 `true` であればサイマルキャストを有効にします。
   public var simulcastEnabled: Bool = false
 

Sora/MediaChannel.swift

@@ -754,10 +754,18 @@ public final class MediaChannel {
     if mute {
       // ソフトミュートによる黒塗りフレーム送出 -> ハードミュート有効化の順になるようにします
       senderStream.videoEnabled = false
-      try await Self.videoHardMuteActor.setMute(mute: true, senderStream: senderStream)
+      try await Self.videoHardMuteActor.setMute(
+        mute: true,
+        senderStream: senderStream,
+        cameraSettings: configuration.cameraSettings
+      )
     } else {
       // ハードミュート無効化 -> ソフトミュートによる黒塗りフレーム送出解除の順になるようにします
-      try await Self.videoHardMuteActor.setMute(mute: false, senderStream: senderStream)
+      try await Self.videoHardMuteActor.setMute(
+        mute: false,
+        senderStream: senderStream,
+        cameraSettings: configuration.cameraSettings
+      )
       senderStream.videoEnabled = true
     }
     Logger.debug(type: .mediaChannel, message: "setVideoHardMute mute=\(mute)")

Sora/PeerChannel.swift

@@ -482,7 +482,9 @@ class PeerChannel: NSObject, RTCPeerConnectionDelegate {
     }
 
     // カメラの初期化
-    if configuration.videoEnabled, configuration.cameraSettings.isEnabled {
+    if configuration.videoEnabled, configuration.cameraSettings.isEnabled,
+      configuration.initialCameraEnabled
+    {
       initializeCameraVideoCapture(stream: stream)
     }
 

Sora/VideoMute.swift

@@ -13,10 +13,11 @@ actor VideoHardMuteActor {
   /// - Parameters:
   ///  - mute: `true` で有効化、`false` で無効化
   ///  - senderStream: 送信ストリーム
+  ///  - cameraSettings: カメラ設定
   /// - Throws:
-  ///   - 既に処理実行中、またはカメラキャプチャラーが無効な場合は `SoraError.mediaChannelError`
+  ///   - 既に処理実行中の場合は `SoraError.mediaChannelError`
   ///   - カメラ操作の失敗時は `SoraError.cameraError`
-  func setMute(mute: Bool, senderStream: MediaStream) async throws {
+  func setMute(mute: Bool, senderStream: MediaStream, cameraSettings: CameraSettings) async throws {
     guard !isProcessing else {
       throw SoraError.mediaChannelError(reason: "video hard mute operation is in progress")
     }
@@ -26,9 +27,8 @@ actor VideoHardMuteActor {
     // ミュートを有効化します
     if mute {
       guard let currentCapturer = await currentCameraVideoCapturer() else {
-        // 既にハードミュート済み(再開用キャプチャラーを保持)なら、冪等として何もしません
-        if capturer != nil { return }
-        throw SoraError.mediaChannelError(reason: "CameraVideoCapturer is unavailable")
+        // キャプチャ未起動の場合は停止対象がないため、冪等として成功扱いにします
+        return
       }
       try await stopCameraVideoCapture(currentCapturer)
       // ミュート無効化する際にキャプチャラーを使用するため保持しておきます
@@ -40,11 +40,12 @@ actor VideoHardMuteActor {
     // 現在のキャプチャラーが取得できる場合は既に再開済みとして成功扱いにします
     let currentCapturer = await currentCameraVideoCapturer()
     if currentCapturer != nil { return }
-    // 前回停止時のキャプチャラーが保持できていない場合エラー
-    guard let stored = capturer else {
-      throw SoraError.mediaChannelError(reason: "CameraVideoCapturer is unavailable")
+    // 前回停止時のキャプチャラーが保持できていれば restart、なければ新規に start します
+    if let stored = capturer {
+      try await restartCameraVideoCapture(stored, senderStream: senderStream)
+      return
     }
-    try await restartCameraVideoCapture(stored, senderStream: senderStream)
+    try await startCameraVideoCapture(cameraSettings: cameraSettings, senderStream: senderStream)
   }
 
   // 現在のカメラキャプチャラーを取得します
@@ -95,4 +96,59 @@ actor VideoHardMuteActor {
       }
     }
   }
+
+  // カメラキャプチャを開始します
+  private func startCameraVideoCapture(
+    cameraSettings: CameraSettings,
+    senderStream: MediaStream
+  ) async throws {
+    // libwebrtc のカメラ用キュー（SoraDispatcher）を利用して実行します
+    try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
+      SoraDispatcher.async(on: .camera) {
+        // 接続時設定の position に対応した device を取得します
+        // 未指定 (.unspecified) 時はエラーとします
+        if cameraSettings.position == .unspecified {
+          continuation.resume(
+            throwing: SoraError.cameraError(
+              reason: "CameraSettings.position should not be .unspecified"
+            )
+          )
+          return
+        }
+
+        let device =
+          CameraVideoCapturer.device(for: cameraSettings.position)
+        guard let device else {
+          continuation.resume(throwing: SoraError.cameraError(reason: "camera device is not found"))
+          return
+        }
+
+        guard
+          // 接続時設定に基づいてカメラの解像度、フレームレートを指定します
+          let format = CameraVideoCapturer.format(
+            width: cameraSettings.resolution.width,
+            height: cameraSettings.resolution.height,
+            for: device,
+            frameRate: cameraSettings.frameRate),
+          let frameRate = CameraVideoCapturer.maxFrameRate(cameraSettings.frameRate, for: format)
+        else {
+          continuation.resume(
+            throwing: SoraError.cameraError(reason: "failed to resolve camera settings"))
+          return
+        }
+
+        // カメラキャプチャを開始します
+        // CameraVideoCapturer.start はコールバック形式です
+        let capturer = CameraVideoCapturer(device: device)
+        capturer.stream = senderStream
+        capturer.start(format: format, frameRate: frameRate) { error in
+          if let error {
+            continuation.resume(throwing: error)
+          } else {
+            continuation.resume(returning: ())
+          }
+        }
+      }
+    }
+  }
 }