VideoHardMuteSerialQueue のコメント追加

Author: t-miya

Sora/MediaChannel.swift

@@ -234,7 +234,7 @@ public final class MediaChannel {
   private let manager: Sora
 
   // 映像ハードミュートの同時呼び出しを防ぐためのキューです
-  // 同時に呼び出された場合はエラーになります
+  // 同時に呼び出された場合は `SoraError.mediaChannelError` となります
   private let videoHardMuteSerialQueue = VideoHardMuteSerialQueue()
 
   // MARK: - インスタンスの生成
@@ -645,27 +645,28 @@ public final class MediaChannel {
   }
 
   /// MediaChannel の接続中にマイクをハードミュート有効化/無効化します
-  /// 前提条件として、
-  /// - 接続時設定で音声が有効になっている
-  /// - 接続時設定でロールが sendonly または sendrecv である
   ///
   /// - Parameter mute: `true` で有効化、`false` で無効化
   /// - Returns: 成功した場合は `nil`、失敗した場合は `Error` を返します
   /// - Throws: エラー時は `SoraError.mediaChannelError` がスローされます
   public func setAudioHardMute(_ mute: Bool) -> Error? {
+    // 接続中か
     guard state == .connected else {
       return SoraError.mediaChannelError(
         reason: "MediaChannel is not connected (state: \(state))")
     }
 
+    // 接続設定で音声が有効になっているか
     guard configuration.audioEnabled else {
       return SoraError.mediaChannelError(reason: "audioEnabled is false")
     }
 
+    // 接続設定で配信側ロールになっているか
     guard configuration.isSender else {
       return SoraError.mediaChannelError(reason: "role is not sender")
     }
 
+    // 音声ハードミュートを切り替えます
     if !NativePeerChannelFactory.default.audioDeviceModuleWrapper.setAudioHardMute(mute) {
       return SoraError.mediaChannelError(
         reason: "AudioDeviceModuleWrapper::setAudioHardMute failed")
@@ -675,127 +676,122 @@ public final class MediaChannel {
   }
 
   /// MediaChannel の接続中にマイクをソフトミュート有効化 / 無効化します
-  /// 前提条件として、
-  /// - 接続時設定で音声が有効になっている
-  /// - 接続時設定でロールが sendonly または sendrecv である
-  /// - 配信ストリームが存在するかつローカル音声トラックが存在する
   ///
   /// - Parameter mute: `true` で有効化、`false` で無効化
   /// - Returns: 成功した場合は `nil`、失敗した場合は `Error` を返します
   /// - Throws: エラー時は `SoraError.mediaChannelError` がスローされます
   public func setAudioSoftMute(_ mute: Bool) -> Error? {
+    // 接続中か
     guard state == .connected else {
       return SoraError.mediaChannelError(
         reason: "MediaChannel is not connected (state: \(state))")
     }
 
+    // 接続設定で音声が有効になっているか
     guard configuration.audioEnabled else {
       return SoraError.mediaChannelError(reason: "audioEnabled 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.hasAudioTrack else {
       return SoraError.mediaChannelError(reason: "senderStream has no AudioTrack")
     }
 
+    // ローカル音声トラックの有効/無効を切り替えます
     senderStream.audioEnabled = !mute
     Logger.debug(type: .mediaChannel, message: "setAudioSoftMute mute=\(mute)")
     return nil
   }
 
   /// MediaChannel の接続中に映像をソフトミュート有効化 / 無効化します
-  /// 前提条件として、
-  /// - 接続時設定で映像が有効になっている
-  /// - 接続時設定でロールが sendonly または sendrecv である
-  /// - 配信ストリームが存在するかつローカル映像トラックが存在する
   ///
   /// - Parameter mute: `true` で有効化、`false` で無効化
   /// - Returns: 成功した場合は `nil`、失敗した場合は `Error` を返します
   /// - Throws: エラー時は `SoraError.mediaChannelError` がスローされます
   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` の場合のみ有効です。
   /// 内部でシリアルキューにより、操作を排他実行します。
-  /// 同時に呼び出された場合はエラーになります。
+  /// 同時に呼び出された場合はキュー側で `SoraError.mediaChannelError` がスローされます
   ///
-  /// 前提条件として、
-  /// - 接続時設定で映像が有効になっている
-  /// - 接続時設定でロールが sendonly または sendrecv である
-  /// - 配信ストリームが存在するかつローカル映像トラックが存在する
-  ///
-  /// 映像ハードミュートは、黒塗りフレーム状態で停止させるため映像ソフトミュート用処理を併用します。
-  /// そのため、以下の処理を内部で実行します。
-  ///
-  /// - `mute == true`: 映像ソフトミュートを有効化してから、カメラ入力を停止します
-  /// - `mute == false`: カメラ入力を再開してから、映像ソフトミュートを無効化します。
-  ///    ハードミュート前のソフトミュートの状態に関わらず無効化します
+  /// 映像ハードミュートは、黒塗りフレーム状態で停止させるため映像ソフトミュート用処理を併用します
   ///
   /// - Parameter mute: `true` で有効化、`false` で無効化
   /// - Throws: エラー時は `SoraError.mediaChannelError` がスローされます
   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
     }

Sora/MediaStream.swift

@@ -48,23 +48,23 @@ public protocol MediaStream: AnyObject {
   // MARK: - 映像と音声の可否
 
   /// 映像の可否。
-  /// ``false`` をセットすると、サーバーへの映像の送受信を停止します。
-  /// ``true`` をセットすると送受信を再開します。
+  /// `false` をセットすると、サーバーへの映像の送受信を停止します。
+  /// `true` をセットすると送受信を再開します。
   var videoEnabled: Bool { get set }
 
   /// 音声の可否。
-  /// ``false`` をセットすると、サーバーへの音声の送受信を停止します。
-  /// ``true`` をセットすると送受信を再開します。
+  /// `false` をセットすると、サーバーへの音声の送受信を停止します。
+  /// `true` をセットすると送受信を再開します。
   ///
   /// サーバーへの送受信を停止しても、マイクはミュートされませんので注意してください。
   var audioEnabled: Bool { get set }
 
-  /// 映像トラックを保持している場合は ``true`` を返します。
+  /// 映像トラックを保持している場合は `true` を返します。
   ///
   /// SDK 内部で利用する判定用のプロパティです。
   var hasVideoTrack: Bool { get }
 
-  /// 音声トラックを保持している場合は ``true`` を返します。
+  /// 音声トラックを保持している場合は `true` を返します。
   ///
   /// SDK 内部で利用する判定用のプロパティです。
   var hasAudioTrack: Bool { get }

Sora/VideoMute.swift

@@ -1,26 +1,38 @@
 import Foundation
 
 // 映像ハードミュートの同時呼び出しを防ぐためのシリアルキュークラスです
-// 同時に呼び出された場合はエラーになります
+// MediaChannel.setVideoHardMute(_:) 内での使用を想定しています
+//
+// 既に処理が実行中または CameraVideoCapturer が無効な場合は `SoraError.mediaChannelError` がスローされます
 final class VideoHardMuteSerialQueue {
   private let queue = DispatchQueue(label: "jp.shiguredo.sora.video.hardmute")
 
+  // 同時実行を防ぐための処理実行中フラグ
   private var isProcessing = false
   private var capturer: CameraVideoCapturer?
 
+  // queue 上で同時実行を防ぐ排他処理を行い、
+  // libwebrtc のカメラ用キュー（SoraDispatcher）でカメラ操作を行います
   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
+        // CameraVideoCapturer.current は stop 実行時に nil になるため
+        // restart 用にキャプチャラーを退避します
+        let storedCapturer = capturer
 
+        // キューの完了処理です。処理中フラグの無効化と continuation を完了します
+        // 状態更新を同一キューで直列化するため queue.async で実行します
+        // continuation.resume も同一キュー上で呼ぶようにしています
         func finish(_ error: Error?, update: ((VideoHardMuteSerialQueue) -> Void)? = nil) {
           queue.async { [self] in
             update?(self)
@@ -33,37 +45,49 @@ final class VideoHardMuteSerialQueue {
           }
         }
 
+        // libwebrtc のカメラ用キューでカメラ操作を非同期実行します
         SoraDispatcher.async(on: .camera) {
           if mute {
+            // ミュート有効化
+            // 起動中のカメラがあれば停止します
             guard let current = CameraVideoCapturer.current else {
-              if cachedCapturer != nil {
+              // 前回のハードミュートでキャプチャラーを退避している場合は冪等として成功扱いにします
+              if storedCapturer != nil {
                 finish(nil)
               } else {
+                // カメラが起動しておらず再開用キャプチャラーも無い場合は失敗にします
                 finish(SoraError.mediaChannelError(reason: "CameraVideoCapturer is unavailable"))
               }
               return
             }
 
+            // CameraVideoCapturer.stop() により映像キャプチャを停止します
+            // CameraVideoCapturer.stop() は実行結果を Error? コールバックで返します
             current.stop { error in
               finish(error) { serialQueue in
+                // キャプチャラーは再開用として退避します
                 serialQueue.capturer = current
               }
             }
             return
           }
 
+          // 既にカメラが起動中であれば何もしません
           if CameraVideoCapturer.current != nil {
             finish(nil)
             return
           }
 
-          guard let cachedCapturer else {
+          // 退避済みのキャプチャラーの存在チェック
+          guard let storedCapturer else {
             finish(SoraError.mediaChannelError(reason: "CameraVideoCapturer is unavailable"))
             return
           }
 
-          cachedCapturer.stream = senderStream
-          cachedCapturer.restart { error in
+          // マルチストリームの場合、停止時と現在の送信ストリームが異なることがあるので再設定します
+          storedCapturer.stream = senderStream
+          // CameraVideoCapturer.restart() により映像キャプチャを再開
+          storedCapturer.restart { error in
             finish(error)
           }
         }