setVideoSoftMute / setVideoHardMute を追加

Author: t-miya

CHANGES.md

@@ -24,6 +24,16 @@
   - 送信ストリームの AudioTrack を取得し、MediaStream.audioEnabled を切り替える
   - AudioTrack の有無判定を行うため、 MediaStream に `hasAudioTrack` を追加する
   - @t-miya
+- [ADD] MediaChannel に `setVideoSoftMute(_:)` を追加する
+  - 映像ソフトミュート機能のシンタックスシュガー
+  - 送信ストリームの VideoTrack を取得し、MediaStream.videoEnabled を切り替える
+  - VideoTrack の有無判定を行うため、 MediaStream に `hasVideoTrack` を追加する
+  - @t-miya
+- [ADD] MediaChannel に `setVideoHardMute(_:)` を追加する
+  - 映像ハードミュート機能のシンタックスシュガー
+  - CameraVideoCapturer を停止 / 再開し、カメラ入力を停止 / 再開する
+  - 映像ハードミュート時は、映像ソフトミュートも併用する
+  - @t-miya
 - [ADD] 音声のハードミュート有効化/無効化機能を追加する
   - iOS 端末のマイクインジケーターを消灯させる
   - AudioDeviceModuleWrapper クラスを追加する

Sora/MediaChannel.swift

@@ -233,6 +233,10 @@ public final class MediaChannel {
 
   private let manager: Sora
 
+  // 映像ハードミュートの同時呼び出しを防ぐためのキューです
+  // 同時に呼び出された場合はエラーになります
+  private let videoHardMuteSerialQueue = VideoHardMuteSerialQueue()
+
   // MARK: - インスタンスの生成
 
   /// 初期化します。
@@ -686,6 +690,87 @@ public final class MediaChannel {
     Logger.debug(type: .mediaChannel, message: "setAudioSoftMute mute=\(mute)")
     return nil
   }
+
+  /// MediaChannel の接続中に映像をソフトミュート有効化 / 無効化します
+  /// 接続時のロールが sendonly または sendrecv でないとエラーを返します
+  /// - Parameter mute: `true` で有効化、`false` で無効化
+  /// - Returns: 成功した場合は `nil`、失敗した場合は `Error` を返します
+  public func setVideoSoftMute(_ mute: Bool) -> Error? {
+    guard state == .connected else {
+      return SoraError.mediaChannelError(
+        reason: "MediaChannel is not connected (state: \(state))")
+    }
+
+    guard configuration.videoEnabled else {
+      return SoraError.mediaChannelError(reason: "videoEnabled is false")
+    }
+
+    guard configuration.isSender else {
+      return SoraError.mediaChannelError(reason: "role is not sender")
+    }
+
+    guard let senderStream else {
+      return SoraError.mediaChannelError(reason: "senderStream is unavailable")
+    }
+
+    guard senderStream.hasVideoTrack else {
+      return SoraError.mediaChannelError(reason: "senderStream has no VideoTrack")
+    }
+
+    senderStream.videoEnabled = !mute
+    Logger.debug(type: .mediaChannel, message: "setVideoSoftMute mute=\(mute)")
+    return nil
+  }
+
+  /// MediaChannel の接続中に映像をハードミュート有効化 / 無効化します
+  ///
+  /// ハードミュートは、カメラ入力を停止 / 再開します。
+  /// `Configuration.cameraSettings.isEnabled == true` の場合のみ有効です。
+  /// 内部でシリアルキューにより、操作を排他実行します。
+  /// 同時に呼び出された場合はエラーになります。
+  ///
+  /// 映像ハードミュートは、黒塗りフレーム状態で停止させるため映像ソフトミュート用処理を併用します。
+  /// そのため、以下の処理を内部で実行します。
+  ///
+  /// - `mute == true`: 映像ソフトミュートを有効化してから、カメラ入力を停止します
+  /// - `mute == false`: カメラ入力を再開してから、映像ソフトミュートを無効化します。
+  ///    ハードミュート前のソフトミュートの状態に関わらず無効化します
+  ///
+  /// - Parameter mute: `true` で有効化、`false` で無効化
+  public func setVideoHardMute(_ mute: Bool) async throws {
+    guard state == .connected else {
+      throw SoraError.mediaChannelError(reason: "MediaChannel is not connected (state: \(state))")
+    }
+
+    guard configuration.videoEnabled else {
+      throw SoraError.mediaChannelError(reason: "videoEnabled is false")
+    }
+
+    guard configuration.cameraSettings.isEnabled else {
+      throw SoraError.mediaChannelError(reason: "cameraSettings.isEnabled is false")
+    }
+
+    guard configuration.isSender else {
+      throw SoraError.mediaChannelError(reason: "role is not sender")
+    }
+
+    guard let senderStream else {
+      throw SoraError.mediaChannelError(reason: "senderStream is unavailable")
+    }
+
+    guard senderStream.hasVideoTrack else {
+      throw SoraError.mediaChannelError(reason: "senderStream has no VideoTrack")
+    }
+
+    if mute {
+      senderStream.videoEnabled = false
+      try await videoHardMuteSerialQueue.set(mute: true, senderStream: senderStream)
+    } else {
+      try await videoHardMuteSerialQueue.set(mute: false, senderStream: senderStream)
+      senderStream.videoEnabled = true
+    }
+    Logger.debug(type: .mediaChannel, message: "setVideoHardMute mute=\(mute)")
+  }
 }
 
 extension MediaChannel: CustomStringConvertible {

Sora/MediaStream.swift

@@ -59,6 +59,11 @@ public protocol MediaStream: AnyObject {
   /// サーバーへの送受信を停止しても、マイクはミュートされませんので注意してください。
   var audioEnabled: Bool { get set }
 
+  /// 映像トラックを保持している場合は ``true`` を返します。
+  ///
+  /// SDK 内部で利用する判定用のプロパティです。
+  var hasVideoTrack: Bool { get }
+
   /// 音声トラックを保持している場合は ``true`` を返します。
   ///
   /// SDK 内部で利用する判定用のプロパティです。
@@ -206,6 +211,10 @@ class BasicMediaStream: MediaStream {
     nativeAudioTrack != nil
   }
 
+  var hasVideoTrack: Bool {
+    nativeVideoTrack != nil
+  }
+
   var remoteAudioVolume: Double? {
     get {
       nativeAudioTrack?.source.volume
@@ -269,3 +278,8 @@ class BasicMediaStream: MediaStream {
     }
   }
 }
+
+public extension MediaStream {
+  var hasAudioTrack: Bool { false }
+  var hasVideoTrack: Bool { false }
+}

Sora/VideoMute.swift

@@ -0,0 +1,73 @@
+import Foundation
+
+// 映像ハードミュートの同時呼び出しを防ぐためのシリアルキュークラスです
+// 同時に呼び出された場合はエラーになります
+final class VideoHardMuteSerialQueue {
+  private let queue = DispatchQueue(label: "jp.shiguredo.sora.video.hardmute")
+
+  private var isProcessing = false
+  private var capturer: CameraVideoCapturer?
+
+  func set(mute: Bool, senderStream: MediaStream) async throws {
+    try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
+      queue.async { [self] in
+        guard !isProcessing else {
+          continuation.resume(
+            throwing: SoraError.mediaChannelError(
+              reason: "video hard mute operation is in progress"))
+          return
+        }
+
+        isProcessing = true
+        let cachedCapturer = capturer
+
+        func finish(_ error: Error?, update: ((VideoHardMuteSerialQueue) -> Void)? = nil) {
+          queue.async { [self] in
+            update?(self)
+            isProcessing = false
+            if let error {
+              continuation.resume(throwing: error)
+            } else {
+              continuation.resume(returning: ())
+            }
+          }
+        }
+
+        SoraDispatcher.async(on: .camera) {
+          if mute {
+            guard let current = CameraVideoCapturer.current else {
+              if cachedCapturer != nil {
+                finish(nil)
+              } else {
+                finish(SoraError.mediaChannelError(reason: "CameraVideoCapturer is unavailable"))
+              }
+              return
+            }
+
+            current.stop { error in
+              finish(error) { serialQueue in
+                serialQueue.capturer = current
+              }
+            }
+            return
+          }
+
+          if CameraVideoCapturer.current != nil {
+            finish(nil)
+            return
+          }
+
+          guard let cachedCapturer else {
+            finish(SoraError.mediaChannelError(reason: "CameraVideoCapturer is unavailable"))
+            return
+          }
+
+          cachedCapturer.stream = senderStream
+          cachedCapturer.restart { error in
+            finish(error)
+          }
+        }
+      }
+    }
+  }
+}