From 616051149b902d527bfdbdac47a5ad7521433f7b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Pavel=20Lobodinsky=CC=81?= <pavel.lobo@gmail.com>
Date: Wed, 5 Jan 2022 20:53:09 +0100
Subject: [PATCH] pybricks.common.Speaker: Add volume setter.

---
 doc/main/hubs/primehub.rst |  2 ++
 src/pybricks/_common.py    | 14 ++++++++++++--
 src/pybricks/_common.pyi   |  4 ++++
 3 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/doc/main/hubs/primehub.rst b/doc/main/hubs/primehub.rst
index 39be2eb..b9de150 100644
--- a/doc/main/hubs/primehub.rst
+++ b/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
diff --git a/src/pybricks/_common.py b/src/pybricks/_common.py
index 2ef202d..6ad560c 100644
--- a/src/pybricks/_common.py
+++ b/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
diff --git a/src/pybricks/_common.pyi b/src/pybricks/_common.pyi
index 74dc8fc..d514c19 100644
--- a/src/pybricks/_common.pyi
+++ b/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: ...