docs: Add audio.sound_level() and tweak audio descriptions.

bbcmicrobit · Jul 18, 2024 · 7299d1f · 7299d1f
1 parent 5d4a54c
commit 7299d1f
Show file tree

Hide file tree

Showing 3 changed files with 28 additions and 6 deletions.
diff --git a/docs/audio.rst b/docs/audio.rst
@@ -72,6 +72,13 @@ Functions
 
     Stops all audio playback.
 
+.. py:function:: sound_level()
+
+    Get the sound pressure level produced by audio currently being played.
+
+    :return: A representation of the output sound pressure level in the
+        range 0 to 255.
+
 
 Built-in sounds **V2**
 ======================
@@ -251,11 +258,15 @@ AudioFrame
         During playback, increasing the sampling rate speeds up the sound
         and decreasing it slows it down.
 
+        :param sample_rate: The sample rate to set.
+
     .. py:function:: get_rate()
 
         (**V2 only**) Return the configured sampling rate for this
         ``AudioFrame`` instance.
 
+        :return: The configured sample rate.
+
     .. py:function:: copyfrom(other)
 
         Overwrite the data in this ``AudioFrame`` with the data from another
@@ -272,12 +283,13 @@ Technical Details
 
 The ``audio.play()`` function can consume an instance or iterable
 (sequence, like list or tuple, or generator) of ``AudioFrame`` instances,
-The ``AudioFrame`` default playback rate is 7812 Hz, and the output is a
-a PWM signal at 32.5 kHz.
+The ``AudioFrame`` default playback rate is 7812 Hz, and can be configured
+at any point with the ``AudioFrame.set_rate()`` method.
+The ``AudioFrame.set_rate()`` also works while the ``AudioFrame`` is being
+played, which will affect the playback speed.
 
 Each ``AudioFrame`` instance is 32 samples by default, but it can be
-configured to a different size via constructor and the
-``AudioFrame.set_rate()`` method.
+configured to a different size via constructor parameters.
 
 So, for example, playing 32 samples at 7812 Hz takes just over 4 milliseconds
 (1/7812.5 * 32 = 0.004096 = 4096 microseconds).

diff --git a/docs/microbit_micropython_api.rst b/docs/microbit_micropython_api.rst
@@ -108,6 +108,16 @@ The Microphone is accessed via the `microphone` object::
     set_threshold(128)
     # Returns a representation of the sound pressure level in the range 0 to 255.
     sound_level()
+    # Record audio into a new `AudioFrame`
+    record(duration, rate=7812)
+    # Record audio into an existing `AudioFrame`
+    record_into(buffer, rate=7812)
+    # Returns `True` if the microphone is currently recording audio
+    is_recording()
+    # Stop any active audio recording
+    stop()
+    # Set the microphone sensitivity (also referred as gain)
+    set_sensitivity(microphone.SENSITIVITY_MEDIUM)
 
 Pins
 ----

diff --git a/docs/microphone.rst b/docs/microphone.rst
@@ -139,7 +139,7 @@ Functions
 
     :return: A representation of the sound pressure level in the range 0 to 255.
 
-.. py:function:: record(duration=3000, rate=7812)
+.. py:function:: record(duration, rate=7812)
 
     Record sound into an ``AudioFrame`` for the amount of time indicated by
     ``duration`` at the sampling rate indicated by ``rate``.
@@ -174,7 +174,7 @@ Functions
 
 .. py:function:: stop_recording()
 
-    Stops an a recording running in the background.
+    Stops a recording running in the background.
 
 .. py:function:: set_sensitivity(gain)