From a0f69086c50255ca1380d23bb81cad53cf206a9b Mon Sep 17 00:00:00 2001 From: Carlos Pereira Atencio Date: Fri, 12 Apr 2024 17:17:54 +0100 Subject: [PATCH] docs: Add audio.sound_level() and tweak audio descriptions. --- docs/audio.rst | 20 ++++++++++++++++---- docs/microbit_micropython_api.rst | 10 ++++++++++ docs/microphone.rst | 4 ++-- 3 files changed, 28 insertions(+), 6 deletions(-) diff --git a/docs/audio.rst b/docs/audio.rst index 40811f717..a15c32661 100644 --- 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 index 19362fdac..179d69f22 100644 --- 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 index af1b5678f..d9fdbc637 100644 --- 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)