pybricks.common.Speaker: Add volume setter.

doc/main/hubs/primehub.rst

@@ -73,6 +73,8 @@ Prime Hub / Inventor Hub
 
     .. rubric:: Using the speaker
 
+    .. automethod:: pybricks.hubs::PrimeHub.speaker.volume
+
     .. automethod:: pybricks.hubs::PrimeHub.speaker.beep
 
     .. automethod:: pybricks.hubs::PrimeHub.speaker.play_notes

src/pybricks/_common.py

@@ -373,13 +373,23 @@ class Motor(DCMotor):
 class Speaker:
     """Plays beeps and sounds using a speaker."""
 
+    def volume(self, volume=None):
+        """Gets or sets the speaker volume.
+
+        If no volume is given, this method returns the current volume.
+
+        Arguments:
+            volume (:ref:`percentage`):
+                Volume of the speaker in the 0-100 range.
+        """
+        pass
+
     def beep(self, frequency=500, duration=100):
         """Play a beep/tone.
 
         Arguments:
             frequency (:ref:`frequency`):
-                Frequency of the beep. Frequencies below 100
-                are treated as 100.
+                Frequency of the beep in the 64-24000 Hz range.
             duration (:ref:`time`):
                 Duration of the beep. If the duration is less
                 than 0, then the method returns immediately and the frequency

src/pybricks/_common.pyi

@@ -81,6 +81,10 @@ class Motor(DCMotor):
     def track_target(self, target_angle: int) -> None: ...
 
 class Speaker:
+    @overload
+    def volume(self) -> int: ...
+    @overload
+    def volume(self, volume: int) -> None: ...
     def beep(self, frequency: int = 500, duration: int = 100) -> None: ...
     def play_notes(self, notes: Iterable[str], tempo: int = 120) -> None: ...