1.4.0 (#42)

Author: BlindMaster24

docs/whats-new.rst

@@ -24,6 +24,18 @@ Fixed
 
 - Fixed documentation not being generated correctly.
 
+:version:`1.4.0` - 2025-04-28
+---------------------------------
+
+Added new capabilities for managing audio input devices and settings.
+
+Added
+~~~~~
+
+- Added the ability to list available sound devices and select the desired input device.
+- Added functions to get and set the microphone input gain level.
+- Added control to enable or disable voice transmission.
+
 :version:`1.3.1` - 2025-04-12
 ---------------------------------
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "teamtalk-py"
-version = "1.3.1"
+version = "1.4.0"
 description = "a simple but powerful pythonic library for making bots for the TeamTalk5 Conferencing System"
 readme = "README.md"
 requires-python = ">=3.11"

teamtalk/instance.py

@@ -255,42 +255,65 @@ def enable_voice_transmission(self, enabled: bool) -> bool:
         return success
 
     def get_input_volume(self) -> int:
-        """Gets the current input sound gain level (scaled 0-100).
+        """Gets the current input gain level (100=SDK default).
 
-        Reads the SDK gain and scales it via (sdk_gain / 20).
+        Retrieves the raw SDK gain and scales it so the SDK default gain level
+        (SOUND_GAIN_DEFAULT) corresponds to 100.
 
         Returns:
-            The volume level (0-100 scale, potentially higher).
+            int: The volume level where 100 is the SDK default gain. Values
+                 above 100 represent gain higher than the SDK default. Returns
+                 0 if the SDK call fails.
         """
         sdk_gain = sdk._GetSoundInputGainLevel(self._tt)
         if sdk_gain < 0:
             _log.warning(f"Could not get input gain for instance {self.server_info.host}, SDK returned {sdk_gain}")
             return 0
 
-        scaled_volume = round(sdk_gain / 20.0)
-        return max(0, scaled_volume)
+        sdk_default = float(sdk.SoundLevel.SOUND_GAIN_DEFAULT)
+        sdk_max = float(sdk.SoundLevel.SOUND_GAIN_MAX)
+
+        if sdk_default == 0:
+            scaled_volume = round((sdk_gain / sdk_max) * 100.0) if sdk_max != 0 else 0
+            max_possible_scaled = 100
+        else:
+            scaled_volume = round((sdk_gain / sdk_default) * 100.0)
+            max_possible_scaled = round((sdk_max / sdk_default) * 100.0)
+
+        return max(0, min(int(scaled_volume), int(max_possible_scaled)))
 
     def set_input_volume(self, volume: int) -> bool:
-        """Sets the input sound gain level using a 0-100 scale.
+        """Sets the input gain level (100=SDK default).
 
-        Uses a simple linear scale (volume * 20) where 50% maps to 1000 SDK gain.
+        Scales the input volume (where 100 is the SDK default gain) to the
+        SDK's raw gain range [0, 32000] and applies it, clamping the value.
 
         Args:
-            volume: The desired volume level (0-100 recommended).
+            volume (int): The desired volume level, where 100 corresponds to
+                          the SDK default gain.
 
         Returns:
-            True on success, False otherwise.
+            bool: True on success, False otherwise.
 
         Raises:
-            ValueError: If volume is less than 0.
+            ValueError: If volume is negative.
         """
         if volume < 0:
-            raise ValueError("Volume must be non-negative.")
+            raise ValueError("Volume cannot be negative.")
+
+        sdk_default = float(sdk.SoundLevel.SOUND_GAIN_DEFAULT)
+        sdk_max = float(sdk.SoundLevel.SOUND_GAIN_MAX)
+        sdk_min = float(sdk.SoundLevel.SOUND_GAIN_MIN)
+
+        if sdk_default == 0:
+            sdk_gain_float = (volume / 100.0) * sdk_max
+        else:
+            sdk_gain_float = (volume / 100.0) * sdk_default
 
-        sdk_gain = int(volume * 20.0)
-        sdk_gain = max(0, min(sdk_gain, 32000))
+        sdk_gain = int(round(sdk_gain_float))
+        sdk_gain = max(int(sdk_min), min(sdk_gain, int(sdk_max)))
 
-        _log.debug(f"Setting input volume for instance {self.server_info.host} to {volume}% (SDK level: {sdk_gain})")
+        _log.debug(f"Setting input volume for instance {self.server_info.host} to {volume} (SDK level: {sdk_gain})")
         success = sdk._SetSoundInputGainLevel(self._tt, sdk_gain)
         if not success:
             _log.error(f"Failed to set input volume for instance {self.server_info.host}")