From fc61a36d4a4c9d18b4a8b352b138d9ab89498964 Mon Sep 17 00:00:00 2001
From: Valere <bill.carson@valrsoft.com>
Date: Tue, 24 Mar 2026 18:25:09 +0100
Subject: [PATCH] review: improve comments

---
 src/controls.ts                           | 14 ++++++++------
 src/state/AndroidControlledAudioOutput.ts |  4 +++-
 2 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/src/controls.ts b/src/controls.ts
index 86de0ace..1ddb1704 100644
--- a/src/controls.ts
+++ b/src/controls.ts
@@ -40,26 +40,28 @@ export interface OutputDevice {
   id: string;
   name: string;
   /**
-   * Reverse engineered:
-   *  - on iOS always true if output is routed to speaker. In other case iOS on declare a `dummy` id device.
-   *    In that case then ElementCalls manually append a earpiece device with id `EARPIECE_CONFIG_ID` anb `{ type: "earpiece" }`
+   * `forEarpiece` in an iOS only flag, that will be set on the default speaker device.
+   * The default speaker device will be used for the earpiece mode by
+   * using a stereo pan and reducing the volume significantly. (in combination this is similar to a dedicated earpiece mode)
+   *  - on iOS this is true if output is routed to speaker.
+   *    In that case then ElementCalls manually appends an earpiece device with id `EARPIECE_CONFIG_ID` and `{ type: "earpiece" }`
    *  - on Android this is unused.
    */
   forEarpiece?: boolean;
   /**
-   * Reverse engineered:
+   * Is the device the OS earpiece audio configuration?
    * - on iOS always undefined
    * - on Android true for the `TYPE_BUILTIN_EARPIECE`
    */
   isEarpiece?: boolean;
   /**
-   * Reverse engineered:
+   *  Is the device the OS default speaker:
    * - on iOS always true if output is routed to speaker. In other case iOS on declare a `dummy` id device.
    * - on Android true for the `TYPE_BUILTIN_SPEAKER`
    */
   isSpeaker?: boolean;
   /**
-   * Reverse engineered:
+   * Is the device the OS default external headset (bluetooth):
    * - on iOS always undefined.
    * - on Android true for the `TYPE_BLUETOOTH_SCO`
    */
diff --git a/src/state/AndroidControlledAudioOutput.ts b/src/state/AndroidControlledAudioOutput.ts
index ce4974ff..65ce20a0 100644
--- a/src/state/AndroidControlledAudioOutput.ts
+++ b/src/state/AndroidControlledAudioOutput.ts
@@ -70,7 +70,9 @@ export class AndroidControlledAudioOutput implements MediaDevice<
     "[MediaDevices AndroidControlledAudioOutput]",
   );
 
-  // STATE stream: the current state of the controller, including the list of available devices and the selected device.
+  /**
+   * STATE stream: the current state of the controller, including the list of available devices and the selected device.
+   */
   private readonly controllerState$: Behavior<ControllerState>;
 
   /**