From 458e5a176ad7af19f1607235c652ff96be03a972 Mon Sep 17 00:00:00 2001
From: Carlos Pereira Atencio <carlos@microbit.org>
Date: Mon, 15 May 2023 11:07:25 +0100
Subject: [PATCH 1/7] docs: Add initial proposal for recording & playback API.

---
 docs/audio.rst      |  71 ++++++++++++++++++++++++--
 docs/microphone.rst | 118 +++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 180 insertions(+), 9 deletions(-)

diff --git a/docs/audio.rst b/docs/audio.rst
index c607101b4..5ed607891 100644
--- a/docs/audio.rst
+++ b/docs/audio.rst
@@ -12,18 +12,25 @@ a speaker to pin 0 and GND on the edge connector to hear the sounds.
 The ``audio`` module can be imported as ``import audio`` or accessed via
 the ``microbit`` module as ``microbit.audio``.
 
-There are three different kinds of audio sources that can be played using the
+There are four different kinds of audio sources that can be played using the
 :py:meth:`audio.play` function:
 
 1. `Built in sounds <#built-in-sounds-v2>`_ (**V2**),
    e.g. ``audio.play(Sound.HAPPY)``
+
 2. `Sound Effects <#sound-effects-v2>`_ (**V2**), a way to create custom sounds
    by configuring its parameters::
 
     my_effect = audio.SoundEffect(freq_start=400, freq_end=2500, duration=500)
     audio.play(my_effect)
 
-3. `Audio Frames <#audioframe>`_, an iterable (like a list or a generator)
+3. `AudioBuffer <#audiobuffer>`_ (**V2**), a generic buffer for audio that can
+   be used to record sound from the micro:bit V2 built-in microphone::
+
+    my_audio_buffer = microphone.record()
+    audio.play(my_audio_buffer)
+
+4. `Audio Frames <#audioframe>`_, an iterable (like a list or a generator)
    of Audio Frames, which are lists of 32 samples with values from 0 to 255::
 
     square_wave = audio.AudioFrame()
@@ -40,13 +47,16 @@ Functions
 
     Play the audio source to completion.
 
-    :param source: There are three types of data that can be used as a source:
+    :param source: There are four types of data that can be used as a source:
 
         - ``Sound``: The ``microbit`` module contains a list of
           built-in sounds, e.g. ``audio.play(Sound.TWINKLE)``. A full list can
           be found in the `Built in sounds <#built-in-sounds-v2>`_ section.
         - ``SoundEffect``: A sound effect, or an iterable of sound effects,
           created via the :py:meth:`audio.SoundEffect` class
+        - ``AudioBuffer``: An audio buffer, or an iterable of audio buffers,
+          created via the :py:meth:`audio.AudioBuffer` class or
+          :doc:`microphone.record() <microphone>` function
         - ``AudioFrame``: An iterable of ``AudioFrame`` instances as described
           in the `AudioFrame Technical Details <#id2>`_ section
 
@@ -215,6 +225,61 @@ Sound Effects Example
 .. include:: ../examples/soundeffects.py
     :code: python
 
+
+Audio Buffer **V2**
+===================
+
+.. py:class::
+    AudioBuffer(duration=3000, rate=11000)
+
+    Create a buffer to contain audio data and its sampling rate.
+
+    The sampling rate is configured via constructor or instance attribute,
+    and is used by the ``microphone.record_into()`` and
+    ``audio.play()`` functions to configure the recording and playback rates.
+
+    For audio recording, reducing the number of samples recorded per second
+    will reduce the size of the data buffer, but also reduce the sound quality.
+    And increasing the sampling rate increases the buffer size and sound
+    quality.
+
+    For audio playback, reducing the sampling rate compared with the recording
+    rate, will slow down the audio. And increasing the playback rate
+    will speed it up.
+
+    The size of the buffer will be determined by the samples per second
+    and the ``duration`` configured when creating a new instance.
+
+    :param duration: Indicates in milliseconds, how much sound data the buffer
+        can contained at the configured ``data_rate``.
+    :param rate: Sampling rate of for the data in the buffer. This value is
+        used for recording and playback, and can be edited as an attribute.
+
+    .. py:function:: copy()
+
+        :returns: A copy of the Audio Buffer.
+
+    .. py:attribute:: rate
+
+        The sampling rate for the data inside the buffer.
+        TODO: Indicate range of valid values here.
+
+Audio Buffer Example
+--------------------
+
+::
+
+    my_buffer = audio.AudioBuffer(duration=5000)
+    microphone.record_into(my_buffer)
+    audio.play(my_buffer)
+
+    # A smaller buffer can be generated with the same duration by using
+    # a lower sampling rate
+    smaller_buffer = audio.AudioBuffer(duration=5000, rate=5500)
+    microphone.record_into(my_buffer)
+    audio.play(my_buffer)
+
+
 AudioFrame
 ==========
 
diff --git a/docs/microphone.rst b/docs/microphone.rst
index 88a847031..fe654886a 100644
--- a/docs/microphone.rst
+++ b/docs/microphone.rst
@@ -4,9 +4,9 @@ Microphone **V2**
 .. py:module:: microbit.microphone
 
 This object lets you access the built-in microphone available on the
-micro:bit **V2**. It can be used to respond to sound. The microphone input
-is located on the front of the board alongside a microphone activity LED,
-which is lit when the microphone is in use.
+micro:bit **V2**. It can be used to record and respond to sound.
+The microphone input is located on the front of the board alongside a
+microphone activity LED, which is lit when the microphone is in use.
 
 .. image:: microphone.png
     :width: 300px
@@ -28,6 +28,25 @@ accessible via variables in ``microbit.SoundEvent``:
 - ``microbit.SoundEvent.LOUD``: Represents the transition of sound events,
   from ``quiet`` to ``loud`` like clapping or shouting.
 
+Recording
+=========
+
+TODO:
+* Describe the feature.
+* Indicate how the sampling rate relates to recording quality.
+* Indicate how changing the sampling rate on the fly affects playback speed.
+* What happens if the user changes the sampling rate while recording?
+
+::
+
+    from microbit import *
+
+    while True:
+        if button_a.is_pressed():
+            my_recording = microphone.record(duration=5000)
+            audio.play(my_recording)
+        sleep(200)
+
 Functions
 =========
 
@@ -91,11 +110,60 @@ Functions
 
     :return: A representation of the sound pressure level in the range 0 to 255.
 
+.. py:function:: record(duration=3000, rate=11000, wait=True)
+
+    Record sound for the amount of time indicated by ``duration`` at the
+    sampling rate indicated by ``rate``.
+
+    The amount of memory consumed is directly related to the length of the
+    recording and the sampling rate. The higher these values, the more memory
+    it will use.
+
+    A lower sampling rate will reduce memory consumption and sound quality.
+
+    If there isn't enough memory available a ``MemoryError`` will be raised.
+
+    :param duration: How much time to record in milliseconds.
+    :param rate: Number of samples to capture per second.
+    :param wait: When set to ``True`` it blocks until the recording is
+        done, if it is set to ``False`` it will run in the background.
+    :returns: An ``AudioBuffer``, configured at the provided ``duration``
+        and ``rate``, with the sound data.
+
+.. py:function:: record_into(buffer, rate=11000, wait=True)
+
+    Record sound into an existing ``AudioBuffer``.
+
+    :param buffer: An ``AudioBuffer`` to record the microphone sound.
+    :param rate: Number of samples to capture per second.
+    :param wait: When set to ``True`` it blocks until the recording is
+        done, if it is set to ``False`` it will run in the background.
 
-Example
-=======
+.. py:function:: is_recording()
 
-An example that runs through some of the functions of the microphone API::
+    :returns: ``True`` if the microphone is currently recording sound, or
+      ``False`` otherwise.
+
+.. py:function:: stop_recording()
+
+    Stops an a recording running in the background.
+
+.. py:function:: set_sensitivity(gain)
+
+    Configure the microphone sensitivity to one of these three levels:
+    ``microphone.SENSITIVITY_LOW``, ``microphone.SENSITIVITY_MEDIUM``,
+    ``microphone.SENSITIVITY_HIGH``.
+
+    These constants correspond to a number, and any values between these
+    constants are valid arguments
+
+    :param gain: Microphone gain.
+
+Examples
+========
+
+An example that runs through some of the functions of the microphone
+Sound Events API::
 
     # Basic test for microphone.  This test should update the display when
     # Button A is pressed and a loud or quiet sound *is* heard, printing the
@@ -143,3 +211,41 @@ An example that runs through some of the functions of the microphone API::
                     display.clear()
                 print(sound)
                 sleep(500)
+
+
+An example of recording and playback with a display animation::
+
+    from microbit import *
+
+    talk_open = Image(
+        "09090:"
+        "00000:"
+        "09990:"
+        "90009:"
+        "09990"
+    )
+    talk_closed = Image(
+        "09090:"
+        "00000:"
+        "00000:"
+        "99999:"
+        "00000"
+    )
+
+    my_recording = audio.AudioBuffer(duration=5000, rate=5500)
+
+    while True:
+        if button_a.is_pressed():
+            microphone.record_into(my_recording, rate=5500, wait=False)
+            display.show([talk_open, talk_closed], loop=True, wait=False, delay=150)
+            while button_a.is_pressed():
+                sleep(50)
+            display.show(mouth_open, loop=False) # workaround issue #150
+            display.clear()
+        if button_b.is_pressed():
+            audio.play(my_recording, wait=False)
+            while audio.is_playing():
+                x = accelerometer.get_x()
+                my_recording.rate = scale(x, (-1000, 1000), (2250, 11000))
+                sleep(50)
+        sleep(100)

From 1407c6b7cc2f1070aad9504de5bb9523c6e95c56 Mon Sep 17 00:00:00 2001
From: Carlos Pereira Atencio <carlos@microbit.org>
Date: Tue, 22 Aug 2023 15:48:39 +0100
Subject: [PATCH 2/7] docs: Update recording & playback based on review.

---
 docs/audio.rst      | 113 +++++++++++++-------------------------------
 docs/microphone.rst |  82 +++++++++++++++++++++++---------
 2 files changed, 93 insertions(+), 102 deletions(-)

diff --git a/docs/audio.rst b/docs/audio.rst
index 5ed607891..250c69898 100644
--- a/docs/audio.rst
+++ b/docs/audio.rst
@@ -12,7 +12,7 @@ a speaker to pin 0 and GND on the edge connector to hear the sounds.
 The ``audio`` module can be imported as ``import audio`` or accessed via
 the ``microbit`` module as ``microbit.audio``.
 
-There are four different kinds of audio sources that can be played using the
+There are three different kinds of audio sources that can be played using the
 :py:meth:`audio.play` function:
 
 1. `Built in sounds <#built-in-sounds-v2>`_ (**V2**),
@@ -24,14 +24,9 @@ There are four different kinds of audio sources that can be played using the
     my_effect = audio.SoundEffect(freq_start=400, freq_end=2500, duration=500)
     audio.play(my_effect)
 
-3. `AudioBuffer <#audiobuffer>`_ (**V2**), a generic buffer for audio that can
-   be used to record sound from the micro:bit V2 built-in microphone::
-
-    my_audio_buffer = microphone.record()
-    audio.play(my_audio_buffer)
-
-4. `Audio Frames <#audioframe>`_, an iterable (like a list or a generator)
-   of Audio Frames, which are lists of 32 samples with values from 0 to 255::
+3. `Audio Frames <#audioframe>`_, an instance or an iterable (like a list or
+   generator) of Audio Frames, which are lists of samples with values
+   from 0 to 255::
 
     square_wave = audio.AudioFrame()
     for i in range(16):
@@ -47,18 +42,16 @@ Functions
 
     Play the audio source to completion.
 
-    :param source: There are four types of data that can be used as a source:
+    :param source: There are three types of data that can be used as a source:
 
         - ``Sound``: The ``microbit`` module contains a list of
           built-in sounds, e.g. ``audio.play(Sound.TWINKLE)``. A full list can
           be found in the `Built in sounds <#built-in-sounds-v2>`_ section.
         - ``SoundEffect``: A sound effect, or an iterable of sound effects,
           created via the :py:meth:`audio.SoundEffect` class
-        - ``AudioBuffer``: An audio buffer, or an iterable of audio buffers,
-          created via the :py:meth:`audio.AudioBuffer` class or
-          :doc:`microphone.record() <microphone>` function
-        - ``AudioFrame``: An iterable of ``AudioFrame`` instances as described
-          in the `AudioFrame Technical Details <#id2>`_ section
+        - ``AudioFrame``: An instance or an iterable of ``AudioFrame``
+          instances as described in the
+          `AudioFrame Technical Details <#technical-details>`_ section
 
     :param wait: If ``wait`` is ``True``, this function will block until the
         source is exhausted.
@@ -79,6 +72,13 @@ Functions
 
     Stops all audio playback.
 
+.. py:function:: set_rate(sample_rate)
+
+    Changes the sampling rate of ``AudioFrame`` playback.
+    The default playback rate is 7812 samples per second.
+    Decreasing the playback sampling rate results in slowed down sound, and
+    increasing it speeds it up.
+
 
 Built-in sounds **V2**
 ======================
@@ -226,70 +226,16 @@ Sound Effects Example
     :code: python
 
 
-Audio Buffer **V2**
-===================
-
-.. py:class::
-    AudioBuffer(duration=3000, rate=11000)
-
-    Create a buffer to contain audio data and its sampling rate.
-
-    The sampling rate is configured via constructor or instance attribute,
-    and is used by the ``microphone.record_into()`` and
-    ``audio.play()`` functions to configure the recording and playback rates.
-
-    For audio recording, reducing the number of samples recorded per second
-    will reduce the size of the data buffer, but also reduce the sound quality.
-    And increasing the sampling rate increases the buffer size and sound
-    quality.
-
-    For audio playback, reducing the sampling rate compared with the recording
-    rate, will slow down the audio. And increasing the playback rate
-    will speed it up.
-
-    The size of the buffer will be determined by the samples per second
-    and the ``duration`` configured when creating a new instance.
-
-    :param duration: Indicates in milliseconds, how much sound data the buffer
-        can contained at the configured ``data_rate``.
-    :param rate: Sampling rate of for the data in the buffer. This value is
-        used for recording and playback, and can be edited as an attribute.
-
-    .. py:function:: copy()
-
-        :returns: A copy of the Audio Buffer.
-
-    .. py:attribute:: rate
-
-        The sampling rate for the data inside the buffer.
-        TODO: Indicate range of valid values here.
-
-Audio Buffer Example
---------------------
-
-::
-
-    my_buffer = audio.AudioBuffer(duration=5000)
-    microphone.record_into(my_buffer)
-    audio.play(my_buffer)
-
-    # A smaller buffer can be generated with the same duration by using
-    # a lower sampling rate
-    smaller_buffer = audio.AudioBuffer(duration=5000, rate=5500)
-    microphone.record_into(my_buffer)
-    audio.play(my_buffer)
-
-
 AudioFrame
 ==========
 
 .. py:class::
-    AudioFrame
+    AudioFrame(size=32)
 
-    An ``AudioFrame`` object is a list of 32 samples each of which is an unsigned byte
-    (whole number between 0 and 255).
+    An ``AudioFrame`` object is a list of samples each of which is an unsigned
+    byte (whole number between 0 and 255).
 
-    It takes just over 4 ms to play a single frame.
+    :param size: How many samples to contain in this instance.
 
     .. py:function:: copyfrom(other)
 
@@ -305,13 +251,19 @@ Technical Details
     You don't need to understand this section to use the ``audio`` module.
     It is just here in case you wanted to know how it works.
 
-The ``audio`` module can consumes an iterable (sequence, like list or tuple, or
-generator) of ``AudioFrame`` instances, each 32 samples at 7812.5 Hz, and uses
-linear interpolation to output a PWM signal at 32.5 kHz, which gives tolerable
-sound quality.
+The ``audio.play()`` function can consume an instance or iterable
+(sequence, like list or tuple, or generator) of ``AudioFrame`` instances.
+Its default playback rate is 7812 Hz, and uses linear interpolation to output
+a PWM signal at 32.5 kHz.
 
-The function ``play`` fully copies all data from each ``AudioFrame`` before it
-calls ``next()`` for the next frame, so a sound source can use the same
+Each ``AudioFrame`` instance is 32 samples by default, but it can be
+configured to a different size via constructor.
+
+So, for example, playing 32 samples at 7812 Hz takes just over 4 milliseconds
+(1/7812.5 * 32 = 0.004096 = 4096 microseconds).
+
+The function ``play()`` fully copies all data from each ``AudioFrame`` before
+it calls ``next()`` for the next frame, so a sound source can use the same
 ``AudioFrame`` repeatedly.
 
 The ``audio`` module has an internal 64 sample buffer from which it reads
@@ -325,5 +277,8 @@ the buffer. This means that a sound source has under 4ms to compute the next
 AudioFrame Example
 ------------------
 
+Creating and populating ``AudioFrame`` iterables and generators with
+different sound waveforms:
+
 .. include:: ../examples/waveforms.py
     :code: python
diff --git a/docs/microphone.rst b/docs/microphone.rst
index fe654886a..706a531b9 100644
--- a/docs/microphone.rst
+++ b/docs/microphone.rst
@@ -31,20 +31,51 @@ accessible via variables in ``microbit.SoundEvent``:
 Recording
 =========
 
-TODO:
-* Describe the feature.
-* Indicate how the sampling rate relates to recording quality.
-* Indicate how changing the sampling rate on the fly affects playback speed.
-* What happens if the user changes the sampling rate while recording?
+The microphone can record audio into an :doc:`AudioFrame <audio>`, which can
+then be played with the ``audio.play()`` function.
 
-::
+Audio sampling is the process of converting sound into a digital format.
+To do this, the microphone takes samples of the sound waves at regular
+intervals. How many samples are recorded per second is known as the
+"sampling rate", so recording at a higher sampling rate increases the sound
+quality, but as more samples are saved, it also takes more memory.
+
+The microphone sampling rate can be configured during sound recording via
+the ``rate`` argument in the ``record()`` and ``record_into()`` functions.
+
+At the other side, the audio playback sampling rate indicates how many samples
+are played per second. So if audio is played back with a higher sampling rate
+than the rate used during recording, then the audio will sound speeded up.
+If the playback sampling rate is twice the recording rate, the sound will take
+half the time to be played to completion. Similarly, if the playback rate
+is halved, it will play half as many samples per second, and so it will
+take twice as long to play the same amount of samples.
+
+How do you think a voice recording will sound if the playback rate is
+increased or decreased? Let's try it out!::
 
     from microbit import *
 
+    RECORDING_SAMPLING_RATE = 11000
+
     while True:
+        if pin_logo.is_touched():
+            # Record and play back at the same rate
+            my_recording = microphone.record(duration=3000, rate=RECORDING_SAMPLING_RATE)
+            audio.play(my_recording)
+
         if button_a.is_pressed():
-            my_recording = microphone.record(duration=5000)
+            # Play back at half the sampling rate
+            my_recording = microphone.record(duration=3000, rate=RECORDING_SAMPLING_RATE)
+            audio.set_rate(RECORDING_SAMPLING_RATE / 2)
             audio.play(my_recording)
+
+        if button_b.is_pressed():
+            # Play back at twice the sampling rate
+            my_recording = microphone.record(duration=3000, rate=RECORDING_SAMPLING_RATE)
+            audio.set_rate(RECORDING_SAMPLING_RATE * 2)
+            audio.play(my_recording)
+
         sleep(200)
 
 Functions
@@ -110,7 +141,7 @@ Functions
 
     :return: A representation of the sound pressure level in the range 0 to 255.
 
-.. py:function:: record(duration=3000, rate=11000, wait=True)
+.. py:function:: record(duration=3000, rate=7812, wait=True)
 
     Record sound for the amount of time indicated by ``duration`` at the
     sampling rate indicated by ``rate``.
@@ -119,7 +150,8 @@ Functions
     recording and the sampling rate. The higher these values, the more memory
     it will use.
 
-    A lower sampling rate will reduce memory consumption and sound quality.
+    A lower sampling rate will reduce both memory consumption and sound
+    quality.
 
     If there isn't enough memory available a ``MemoryError`` will be raised.
 
@@ -127,14 +159,14 @@ Functions
     :param rate: Number of samples to capture per second.
     :param wait: When set to ``True`` it blocks until the recording is
         done, if it is set to ``False`` it will run in the background.
-    :returns: An ``AudioBuffer``, configured at the provided ``duration``
-        and ``rate``, with the sound data.
+    :returns: An ``AudioFrame`` with the sound samples.
 
-.. py:function:: record_into(buffer, rate=11000, wait=True)
+.. py:function:: record_into(buffer, rate=7812, wait=True)
 
-    Record sound into an existing ``AudioBuffer``.
+    Record sound into an existing ``AudioFrame`` until it is filled,
+    or the ``stop_recording()`` function is called.
 
-    :param buffer: An ``AudioBuffer`` to record the microphone sound.
+    :param buffer: An ``AudioFrame`` to record sound.
     :param rate: Number of samples to capture per second.
     :param wait: When set to ``True`` it blocks until the recording is
         done, if it is set to ``False`` it will run in the background.
@@ -155,7 +187,7 @@ Functions
     ``microphone.SENSITIVITY_HIGH``.
 
     These constants correspond to a number, and any values between these
-    constants are valid arguments
+    constants are valid arguments.
 
     :param gain: Microphone gain.
 
@@ -217,14 +249,14 @@ An example of recording and playback with a display animation::
 
     from microbit import *
 
-    talk_open = Image(
+    mouth_open = Image(
         "09090:"
         "00000:"
         "09990:"
         "90009:"
         "09990"
     )
-    talk_closed = Image(
+    mouth_closed = Image(
         "09090:"
         "00000:"
         "00000:"
@@ -232,20 +264,24 @@ An example of recording and playback with a display animation::
         "00000"
     )
 
-    my_recording = audio.AudioBuffer(duration=5000, rate=5500)
+    RECORDING_RATE = 5500
+    RECORDING_SECONDS = 5
+    RECORDING_SIZE = RECORDING_RATE * RECORDING_SECONDS
+
+    my_recording = audio.AudioBuffer(size=RECORDING_SIZE)
 
     while True:
         if button_a.is_pressed():
-            microphone.record_into(my_recording, rate=5500, wait=False)
-            display.show([talk_open, talk_closed], loop=True, wait=False, delay=150)
-            while button_a.is_pressed():
+            microphone.record_into(my_recording, rate=RECORDING_RATE, wait=False)
+            display.show([mouth_open, mouth_closed], loop=True, wait=False, delay=150)
+            while button_a.is_pressed() and microphone.is_recording():
                 sleep(50)
-            display.show(mouth_open, loop=False) # workaround issue #150
+            microphone.stop_recording()
             display.clear()
         if button_b.is_pressed():
             audio.play(my_recording, wait=False)
             while audio.is_playing():
                 x = accelerometer.get_x()
-                my_recording.rate = scale(x, (-1000, 1000), (2250, 11000))
+                audio.set_rate(scale(x, (-1000, 1000), (2250, 11000)))
                 sleep(50)
         sleep(100)

From 996f0ae9fcf017580bb757c1adc169f51dd2823f Mon Sep 17 00:00:00 2001
From: Carlos Pereira Atencio <carlos@microbit.org>
Date: Thu, 22 Feb 2024 17:28:47 +0000
Subject: [PATCH 3/7] docs: Update Recording & Playback based on the latest
 implementation.

---
 docs/audio.rst      | 46 ++++++++++++++++++++++++++++++++-------------
 docs/microphone.rst | 35 +++++++++++++++-------------------
 2 files changed, 48 insertions(+), 33 deletions(-)

diff --git a/docs/audio.rst b/docs/audio.rst
index 250c69898..40811f717 100644
--- a/docs/audio.rst
+++ b/docs/audio.rst
@@ -72,13 +72,6 @@ Functions
 
     Stops all audio playback.
 
-.. py:function:: set_rate(sample_rate)
-
-    Changes the sampling rate of ``AudioFrame`` playback.
-    The default playback rate is 7812 samples per second.
-    Decreasing the playback sampling rate results in slowed down sound, and
-    increasing it speeds it up.
-
 
 Built-in sounds **V2**
 ======================
@@ -230,12 +223,38 @@ AudioFrame
 ==========
 
 .. py:class::
-    AudioFrame(size=32)
+    AudioFrame(duration=-1, rate=7812)
 
-    An ``AudioFrame`` object is a list of samples each of which is an unsigned
+    An ``AudioFrame`` object is a list of samples, each of which is an unsigned
     byte (whole number between 0 and 255).
 
-    :param size: How many samples to contain in this instance.
+    The number of samples in an AudioFrame will depend on the
+    ``rate`` (number of samples per second) and ``duration`` parameters.
+    The total number of samples will always be a round up multiple of 32.
+
+    On micro:bit V1 the constructor does not take any arguments,
+    and an AudioFrame instance is always 32 bytes.
+
+    :param duration: (**V2**) Indicates how many milliseconds of audio this
+        instance can store.
+    :param rate: (**V2**) The sampling rate at which data will be stored
+        via the microphone, or played via the ``audio.play()`` function.
+
+    .. py:function:: set_rate(sample_rate)
+
+        (**V2 only**) Configure the sampling rate associated with the data
+        in the ``AudioFrame`` instance.
+
+        For recording from the microphone, increasing the sampling rate
+        increases the sound quality, but reduces the length of audio it
+        can store.
+        During playback, increasing the sampling rate speeds up the sound
+        and decreasing it slows it down.
+
+    .. py:function:: get_rate()
+
+        (**V2 only**) Return the configured sampling rate for this
+        ``AudioFrame`` instance.
 
     .. py:function:: copyfrom(other)
 
@@ -252,12 +271,13 @@ Technical Details
     It is just here in case you wanted to know how it works.
 
 The ``audio.play()`` function can consume an instance or iterable
-(sequence, like list or tuple, or generator) of ``AudioFrame`` instances.
-Its default playback rate is 7812 Hz, and uses linear interpolation to output
+(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.
 
 Each ``AudioFrame`` instance is 32 samples by default, but it can be
-configured to a different size via constructor.
+configured to a different size via constructor and the
+``AudioFrame.set_rate()`` method.
 
 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/microphone.rst b/docs/microphone.rst
index 706a531b9..af1b5678f 100644
--- a/docs/microphone.rst
+++ b/docs/microphone.rst
@@ -36,12 +36,12 @@ then be played with the ``audio.play()`` function.
 
 Audio sampling is the process of converting sound into a digital format.
 To do this, the microphone takes samples of the sound waves at regular
-intervals. How many samples are recorded per second is known as the
+intervals. The number of samples recorded per second is known as the
 "sampling rate", so recording at a higher sampling rate increases the sound
-quality, but as more samples are saved, it also takes more memory.
+quality, but as more samples are saved, it also consumes more memory.
 
 The microphone sampling rate can be configured during sound recording via
-the ``rate`` argument in the ``record()`` and ``record_into()`` functions.
+the ``AudioFrame.rate()`` method functions.
 
 At the other side, the audio playback sampling rate indicates how many samples
 are played per second. So if audio is played back with a higher sampling rate
@@ -56,24 +56,22 @@ increased or decreased? Let's try it out!::
 
     from microbit import *
 
-    RECORDING_SAMPLING_RATE = 11000
-
     while True:
         if pin_logo.is_touched():
             # Record and play back at the same rate
-            my_recording = microphone.record(duration=3000, rate=RECORDING_SAMPLING_RATE)
+            my_recording = microphone.record(duration=3000)
             audio.play(my_recording)
 
         if button_a.is_pressed():
             # Play back at half the sampling rate
-            my_recording = microphone.record(duration=3000, rate=RECORDING_SAMPLING_RATE)
-            audio.set_rate(RECORDING_SAMPLING_RATE / 2)
+            my_recording = microphone.record(duration=3000)
+            my_recording.set_rate(my_recording.get_rate() // 2)
             audio.play(my_recording)
 
         if button_b.is_pressed():
             # Play back at twice the sampling rate
-            my_recording = microphone.record(duration=3000, rate=RECORDING_SAMPLING_RATE)
-            audio.set_rate(RECORDING_SAMPLING_RATE * 2)
+            my_recording = microphone.record(duration=3000)
+            my_recording.set_rate(my_recording.get_rate() * 2)
             audio.play(my_recording)
 
         sleep(200)
@@ -141,10 +139,10 @@ Functions
 
     :return: A representation of the sound pressure level in the range 0 to 255.
 
-.. py:function:: record(duration=3000, rate=7812, wait=True)
+.. py:function:: record(duration=3000, rate=7812)
 
-    Record sound for the amount of time indicated by ``duration`` at the
-    sampling rate indicated by ``rate``.
+    Record sound into an ``AudioFrame`` for the amount of time indicated by
+    ``duration`` at the sampling rate indicated by ``rate``.
 
     The amount of memory consumed is directly related to the length of the
     recording and the sampling rate. The higher these values, the more memory
@@ -155,10 +153,8 @@ Functions
 
     If there isn't enough memory available a ``MemoryError`` will be raised.
 
-    :param duration: How much time to record in milliseconds.
+    :param duration: How long to record in milliseconds.
     :param rate: Number of samples to capture per second.
-    :param wait: When set to ``True`` it blocks until the recording is
-        done, if it is set to ``False`` it will run in the background.
     :returns: An ``AudioFrame`` with the sound samples.
 
 .. py:function:: record_into(buffer, rate=7812, wait=True)
@@ -264,11 +260,10 @@ An example of recording and playback with a display animation::
         "00000"
     )
 
-    RECORDING_RATE = 5500
-    RECORDING_SECONDS = 5
-    RECORDING_SIZE = RECORDING_RATE * RECORDING_SECONDS
+    RECORDING_RATE = 3906
+    RECORDING_MS = 5000
 
-    my_recording = audio.AudioBuffer(size=RECORDING_SIZE)
+    my_recording = audio.AudioBuffer(duration=RECORDING_MS, rate=RECORDING_RATE)
 
     while True:
         if button_a.is_pressed():

From abbcfa12b38929a820b5079cbcf282b465eb84de Mon Sep 17 00:00:00 2001
From: Carlos Pereira Atencio <carlos@microbit.org>
Date: Fri, 12 Apr 2024 17:17:54 +0100
Subject: [PATCH 4/7] 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)
 

From bf291ece310fab537235a12077da94e673f45643 Mon Sep 17 00:00:00 2001
From: Carlos Pereira Atencio <carlos@microbit.org>
Date: Mon, 15 Jul 2024 18:38:01 +0100
Subject: [PATCH 5/7] docs: Update Recording & Playback to use AudioRecording &
 AudioTrack.

---
 docs/audio.rst                    | 199 ++++++++++++++++++++++++------
 docs/microbit_micropython_api.rst |   8 +-
 docs/microphone.rst               |  37 +++---
 3 files changed, 189 insertions(+), 55 deletions(-)

diff --git a/docs/audio.rst b/docs/audio.rst
index a15c32661..65da8e0b2 100644
--- a/docs/audio.rst
+++ b/docs/audio.rst
@@ -24,7 +24,22 @@ There are three different kinds of audio sources that can be played using the
     my_effect = audio.SoundEffect(freq_start=400, freq_end=2500, duration=500)
     audio.play(my_effect)
 
-3. `Audio Frames <#audioframe>`_, an instance or an iterable (like a list or
+3. `Audio Recordings <#audiorecording-audiotrack-v2>`_, an object that can
+   be used to record audio from the microphone::
+
+    recording = audio.AudioRecording(duration=4000)
+    microphone.record_into(recording)
+    audio.play(recording)
+
+4. `Audio Tracks <#audiorecording-audiotrack-v2>`_, a way to point to a portion
+   of the data in an ``AudioRecording`` or a ``bytearray`` and/or modify it::
+
+    recording = audio.AudioRecording(duration=4000)
+    microphone.record(recording)
+    track = AudioTrack(recording)[1000:3000]
+    audio.play(track)
+
+5. `Audio Frames <#audioframe>`_, an instance or an iterable (like a list or
    generator) of Audio Frames, which are lists of samples with values
    from 0 to 255::
 
@@ -49,6 +64,10 @@ Functions
           be found in the `Built in sounds <#built-in-sounds-v2>`_ section.
         - ``SoundEffect``: A sound effect, or an iterable of sound effects,
           created via the :py:meth:`audio.SoundEffect` class
+        - ``AudioRecording``: An instance of ``AudioRecording`` as described
+          in the `AudioRecording <#audiorecording-audiotrack-v2>`_ section
+        - ``AudioTrack``: An instance of ``AudioTrack`` as described in the
+          `AudioTrack <#audiorecording-audiotrack-v2>`_ section
         - ``AudioFrame``: An instance or an iterable of ``AudioFrame``
           instances as described in the
           `AudioFrame Technical Details <#technical-details>`_ section
@@ -226,47 +245,163 @@ Sound Effects Example
     :code: python
 
 
-AudioFrame
-==========
+AudioRecording & AudioTrack **V2**
+==================================
 
-.. py:class::
-    AudioFrame(duration=-1, rate=7812)
+There are two classes that can contain (or point to) audio data 
+and an associated sampling rate:
 
-    An ``AudioFrame`` object is a list of samples, each of which is an unsigned
-    byte (whole number between 0 and 255).
+- ``AudioRecording`` contains its own buffer, it's initialised with a size
+  defined in time, and it's the object type that ``microphone.record()``
+  returns.
+- ``AudioTrack`` does not hold its own buffer and instead points to a buffer
+  externally created. This buffer could be an ``AudioRecording``, or a basic
+  type like a ``bytearray``. It's similar to a
+  `memoryview <https://docs.micropython.org/en/v1.9.3/pyboard/reference/speed_python.html#arrays>`_
+  and it can be used to easily chop a portion of the audio data in the
+  ``AudioRecording`` or to modify its contents.
 
-    The number of samples in an AudioFrame will depend on the
-    ``rate`` (number of samples per second) and ``duration`` parameters.
-    The total number of samples will always be a round up multiple of 32.
+AudioRecording
+--------------
 
-    On micro:bit V1 the constructor does not take any arguments,
-    and an AudioFrame instance is always 32 bytes.
+.. py:class::
+    AudioRecording(duration, rate=7812)
+
+    The ``AudioRecording`` object contains audio data and the sampling rate
+    associated to it.
 
-    :param duration: (**V2**) Indicates how many milliseconds of audio this
+    The size of the internal buffer will depend on the ``rate``
+    (number of samples per second) and ``duration`` parameters.
+
+    :param duration: Indicates how many milliseconds of audio this
         instance can store.
-    :param rate: (**V2**) The sampling rate at which data will be stored
+    :param rate: The sampling rate at which data will be stored
         via the microphone, or played via the ``audio.play()`` function.
 
     .. py:function:: set_rate(sample_rate)
 
-        (**V2 only**) Configure the sampling rate associated with the data
-        in the ``AudioFrame`` instance.
+        Configure the sampling rate associated with the data in the
+        ``AudioRecording`` instance.
+
+        :param sample_rate: The sample rate to set.
+
+    .. py:function:: get_rate()
+
+        Return the configured sampling rate for this
+        ``AudioRecording`` instance.
+
+        :return: The configured sample rate.
+
+    .. py:function:: copy()
+
+        :returns: a copy of the ``AudioRecording``.
+
+    .. py:function:: track(start_ms=0, end_ms=-1)
+
+        Create an `AudioTrack <#audio.AudioTrack>`_ instance from a portion of
+        the data in this ``AudioRecording`` instance.
+
+        :param start_ms: Where to start of the track in milliseconds.
+        :param end_ms: The end of the track in milliseconds.
+            If the default value of ``-1`` is provided it will end the track
+            at the end of the AudioRecording.
+
+When an AudioRecording is used to record data from the microphone,
+increasing the sampling rate increases the sound quality,
+but it also increases the amount of memory used.
+
+During playback, increasing the sampling rate speeds up the sound
+and decreasing the sample rate slows it down.
+
+AudioTrack
+----------
+
+An ``AudioTrack`` can be created from an ``AudioRecording`` or ``bytearray``
+and individual bytes can be accessed and modified like elements in a list.
+
+This class is useful to modify the audio data in an ``AudioRecording`` or
+to create precisely sized audio data buffers for sending and receiving them
+via communication protocols like radio or serial.
+
+.. py:class::
+    AudioTrack(buffer, rate=7812)
+
+    The ``AudioTrack`` object points to the data provided by the input buffer,
+    which can be an ``AudioRecording``, or a buffer-like object like a
+    ``bytearray``.
+    It also contains its own sampling rate, so multiple ``AudioTrack``
+    instances pointing to the same buffer can have different rates and won't
+    affect the rate of the original buffer.
+
+    :param buffer: The buffer containing the audio data.
+    :param rate: The sampling rate at which data will be stored
+        via the microphone, or played via the ``audio.play()`` function.
 
-        For recording from the microphone, increasing the sampling rate
-        increases the sound quality, but reduces the length of audio it
-        can store.
-        During playback, increasing the sampling rate speeds up the sound
-        and decreasing it slows it down.
+    .. py:function:: set_rate(sample_rate)
+
+        Configure the sampling rate associated with the data in the
+        ``AudioTrack`` instance.
 
         :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 sampling rate for this
+        ``AudioTrack`` instance.
 
         :return: The configured sample rate.
 
+    .. py:function:: copyfrom(other)
+
+        Overwrite the data in this ``AudioTrack`` with the data from another
+        ``AudioTrack``, ``AudioRecording`` or buffer-like object like
+        a ``bytes`` or ``bytearray`` instance.
+
+        :param other: Buffer-like instance from which to copy the data.
+
+Example
+-------
+
+::
+
+    from microbit import *
+
+    # An AudioRecording holds the audio data
+    recording = audio.AudioRecording(duration=4000)
+
+    # AudioTracks point to a portion of the data in the AudioRecording
+    # We can obtain the an AudioTrack from the AudioRecording.track() method
+    first_half = recording.track(end_ms=2000)
+    # Or we can create an AudioTrack from an AudioRecording and slice it
+    full_track = audio.AudioTrack(recording)
+    second_half = full_track[full_track.length() // 2:]
+
+    while True:
+        if button_a.is_pressed():
+            # We can record directly inside the AudioRecording
+            microphone.record(recording)
+        if button_b.is_pressed():
+            audio.play(recording, wait=False)
+            # The rate can be changed while playing
+            first_half.set_rate(
+                scale(accelerometer.get_x(), from_=(-1000, 1000), to=(3_000, 30_000))
+            )
+        if pin_logo.is_touched():
+            # We can also play the AudioTrack pointing to the AudioRecording
+            audio.play(first_half)
+
+
+AudioFrame
+==========
+
+.. py:class::
+    AudioFrame
+
+    An ``AudioFrame`` object is a list of 32 samples each of which is an unsigned byte
+    (whole number between 0 and 255).
+
+    It takes just over 4 ms to play a single frame.
+
     .. py:function:: copyfrom(other)
 
         Overwrite the data in this ``AudioFrame`` with the data from another
@@ -281,21 +416,13 @@ Technical Details
     You don't need to understand this section to use the ``audio`` module.
     It is just here in case you wanted to know how it works.
 
-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 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 parameters.
-
-So, for example, playing 32 samples at 7812 Hz takes just over 4 milliseconds
+The ``audio`` module can consumes an iterable (sequence, like list or tuple, or
+generator) of ``AudioFrame`` instances, each 32 samples at 7812.5 Hz,
+which take just over 4 milliseconds to play each frame
 (1/7812.5 * 32 = 0.004096 = 4096 microseconds).
 
-The function ``play()`` fully copies all data from each ``AudioFrame`` before
-it calls ``next()`` for the next frame, so a sound source can use the same
+The function ``play`` fully copies all data from each ``AudioFrame`` before it
+calls ``next()`` for the next frame, so a sound source can use the same
 ``AudioFrame`` repeatedly.
 
 The ``audio`` module has an internal 64 sample buffer from which it reads
diff --git a/docs/microbit_micropython_api.rst b/docs/microbit_micropython_api.rst
index 179d69f22..c68fb3de6 100644
--- a/docs/microbit_micropython_api.rst
+++ b/docs/microbit_micropython_api.rst
@@ -108,10 +108,10 @@ 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)
+    # Record audio into a new `AudioRecording`
+    recording = record(duration, rate=7812)
+    # Record audio into an existing `AudioRecording`
+    record_into(recording, rate=7812)
     # Returns `True` if the microphone is currently recording audio
     is_recording()
     # Stop any active audio recording
diff --git a/docs/microphone.rst b/docs/microphone.rst
index d9fdbc637..cd5854f1e 100644
--- a/docs/microphone.rst
+++ b/docs/microphone.rst
@@ -31,8 +31,8 @@ accessible via variables in ``microbit.SoundEvent``:
 Recording
 =========
 
-The microphone can record audio into an :doc:`AudioFrame <audio>`, which can
-then be played with the ``audio.play()`` function.
+The microphone can record audio into an :doc:`AudioRecording <audio>`,
+which can then be played with the ``audio.play()`` function.
 
 Audio sampling is the process of converting sound into a digital format.
 To do this, the microphone takes samples of the sound waves at regular
@@ -41,15 +41,17 @@ intervals. The number of samples recorded per second is known as the
 quality, but as more samples are saved, it also consumes more memory.
 
 The microphone sampling rate can be configured during sound recording via
-the ``AudioFrame.rate()`` method functions.
+the :py:meth:`AudioRecording.set_rate()<audio.AudioRecording.set_rate>` or
+:py:meth:`AudioTrack.set_rate()<audio.AudioTrack.set_rate>` methods.
 
 At the other side, the audio playback sampling rate indicates how many samples
 are played per second. So if audio is played back with a higher sampling rate
 than the rate used during recording, then the audio will sound speeded up.
 If the playback sampling rate is twice the recording rate, the sound will take
 half the time to be played to completion. Similarly, if the playback rate
-is halved, it will play half as many samples per second, and so it will
-take twice as long to play the same amount of samples.
+is halved, it will play half as many samples per second, so it will
+take twice as long to play the same amount of samples, and it will sound
+slowed down.
 
 How do you think a voice recording will sound if the playback rate is
 increased or decreased? Let's try it out!::
@@ -141,7 +143,7 @@ Functions
 
 .. py:function:: record(duration, rate=7812)
 
-    Record sound into an ``AudioFrame`` for the amount of time indicated by
+    Record sound into an ``AudioRecording`` for the amount of time indicated by
     ``duration`` at the sampling rate indicated by ``rate``.
 
     The amount of memory consumed is directly related to the length of the
@@ -155,17 +157,22 @@ Functions
 
     :param duration: How long to record in milliseconds.
     :param rate: Number of samples to capture per second.
-    :returns: An ``AudioFrame`` with the sound samples.
+    :returns: An ``AudioRecording`` with the sound samples.
 
-.. py:function:: record_into(buffer, rate=7812, wait=True)
+.. py:function:: record_into(buffer, wait=True)
 
-    Record sound into an existing ``AudioFrame`` until it is filled,
-    or the ``stop_recording()`` function is called.
+    Record sound into an existing ``AudioRecording`` or ``AudioTrack``
+    until it is filled, or the ``stop_recording()`` function is called.
 
-    :param buffer: An ``AudioFrame`` to record sound.
-    :param rate: Number of samples to capture per second.
+    This function also returns an ``AudioTrack`` created from the provided
+    input buffer, which length matches the recording duration.
+    This is useful when recording with ``wait`` set to ``False``, and the
+    recording is stopped before the input buffer is filled.
+
+    :param buffer: ``AudioRecording`` or ``AudioTrack`` to record sound into.
     :param wait: When set to ``True`` it blocks until the recording is
         done, if it is set to ``False`` it will run in the background.
+    :returns: An ``AudioTrack`` which ends where the recording ended.
 
 .. py:function:: is_recording()
 
@@ -263,18 +270,18 @@ An example of recording and playback with a display animation::
     RECORDING_RATE = 3906
     RECORDING_MS = 5000
 
-    my_recording = audio.AudioBuffer(duration=RECORDING_MS, rate=RECORDING_RATE)
+    my_recording = audio.AudioRecording(duration=RECORDING_MS, rate=RECORDING_RATE)
 
     while True:
         if button_a.is_pressed():
-            microphone.record_into(my_recording, rate=RECORDING_RATE, wait=False)
+            clipped_recording = microphone.record_into(my_recording, wait=False)
             display.show([mouth_open, mouth_closed], loop=True, wait=False, delay=150)
             while button_a.is_pressed() and microphone.is_recording():
                 sleep(50)
             microphone.stop_recording()
             display.clear()
         if button_b.is_pressed():
-            audio.play(my_recording, wait=False)
+            audio.play(clipped_recording, wait=False)
             while audio.is_playing():
                 x = accelerometer.get_x()
                 audio.set_rate(scale(x, (-1000, 1000), (2250, 11000)))

From 4841b60bd7556e5a4c8451cd4bbf050df27e96e9 Mon Sep 17 00:00:00 2001
From: Carlos Pereira Atencio <carlos@microbit.org>
Date: Thu, 1 Aug 2024 18:21:52 +0100
Subject: [PATCH 6/7] docs: update Recording & Playback on review + tweaks to
 descriptions.

---
 docs/audio.rst                    | 97 +++++++++++++++++++++----------
 docs/microbit_micropython_api.rst |  4 +-
 docs/microphone.rst               |  2 +-
 3 files changed, 68 insertions(+), 35 deletions(-)

diff --git a/docs/audio.rst b/docs/audio.rst
index 65da8e0b2..63d93513e 100644
--- a/docs/audio.rst
+++ b/docs/audio.rst
@@ -248,30 +248,34 @@ Sound Effects Example
 AudioRecording & AudioTrack **V2**
 ==================================
 
-There are two classes that can contain (or point to) audio data 
-and an associated sampling rate:
-
-- ``AudioRecording`` contains its own buffer, it's initialised with a size
-  defined in time, and it's the object type that ``microphone.record()``
-  returns.
-- ``AudioTrack`` does not hold its own buffer and instead points to a buffer
-  externally created. This buffer could be an ``AudioRecording``, or a basic
-  type like a ``bytearray``. It's similar to a
+To record and play back audio, we need a way to store the audio data and
+the sampling rate that has been used to record it and play it back.
+
+Two new classes are introduced in micro:bit V2 for this purpose:
+
+- The ``AudioRecording`` class holds its own audio data and sampling rate.
+  It is initialised with a size defined in units of time, and it's the object
+  type that the ``microphone.record()`` function returns.
+- The ``AudioTrack`` class contains its sampling rate, but does not hold its
+  own data. It instead points to a buffer externally created,
+  like an ``AudioRecording``, or a basic type like a ``bytearray``.
+  It's similar to a
   `memoryview <https://docs.micropython.org/en/v1.9.3/pyboard/reference/speed_python.html#arrays>`_
-  and it can be used to easily chop a portion of the audio data in the
-  ``AudioRecording`` or to modify its contents.
+  and it can be used to easily modify the audio data or chop into portions
+  of different sizes.
 
 AudioRecording
 --------------
 
 .. py:class::
-    AudioRecording(duration, rate=7812)
+    AudioRecording(duration, rate=11_000)
 
     The ``AudioRecording`` object contains audio data and the sampling rate
     associated to it.
 
     The size of the internal buffer will depend on the ``rate``
     (number of samples per second) and ``duration`` parameters.
+    The larger these values are, the more memory that will be used.
 
     :param duration: Indicates how many milliseconds of audio this
         instance can store.
@@ -306,32 +310,36 @@ AudioRecording
             If the default value of ``-1`` is provided it will end the track
             at the end of the AudioRecording.
 
-When an AudioRecording is used to record data from the microphone,
-increasing the sampling rate increases the sound quality,
-but it also increases the amount of memory used.
+When an ``AudioRecording`` is used to record data from the microphone,
+a higher sampling rate produces better sound quality,
+but it also uses more memory.
 
 During playback, increasing the sampling rate speeds up the sound
 and decreasing the sample rate slows it down.
 
+The data inside an ``AudioRecording`` is not easy to modify, so the
+``AudioTrack`` class is provided to help access the audio data like a list.
+The method ``AudioRecording.track()`` can be used to create an ``AudioTrack``,
+and its arguments ``start_ms`` and ``end_ms`` can be used to slice portions
+of the data.
+
 AudioTrack
 ----------
 
-An ``AudioTrack`` can be created from an ``AudioRecording`` or ``bytearray``
-and individual bytes can be accessed and modified like elements in a list.
-
-This class is useful to modify the audio data in an ``AudioRecording`` or
-to create precisely sized audio data buffers for sending and receiving them
-via communication protocols like radio or serial.
-
 .. py:class::
-    AudioTrack(buffer, rate=7812)
+    AudioTrack(buffer, rate=None)
 
     The ``AudioTrack`` object points to the data provided by the input buffer,
-    which can be an ``AudioRecording``, or a buffer-like object like a
-    ``bytearray``.
-    It also contains its own sampling rate, so multiple ``AudioTrack``
-    instances pointing to the same buffer can have different rates and won't
-    affect the rate of the original buffer.
+    which can be an ``AudioRecording``, another ``AudioTrack``,
+    or a buffer-like object like a ``bytearray``.
+
+    When the input buffer has an associated rate (e.g. an ``AudioRecording``
+    or ``AudioTrack``), the rate is copied. If the buffer object does not have
+    a rate, the default value of 11_000 is used.
+
+    Changes to an ``AudioTrack`` rate won't affect the original source rate,
+    so multiple instances pointing to the same buffer can have different
+    rates and the original buffer rate would stay unmodified.
 
     :param buffer: The buffer containing the audio data.
     :param rate: The sampling rate at which data will be stored
@@ -346,19 +354,44 @@ via communication protocols like radio or serial.
 
     .. py:function:: get_rate()
 
-        Return the configured sampling rate for this
-        ``AudioTrack`` instance.
+        Return the configured sampling rate for this ``AudioTrack`` instance.
 
         :return: The configured sample rate.
 
     .. py:function:: copyfrom(other)
 
         Overwrite the data in this ``AudioTrack`` with the data from another
-        ``AudioTrack``, ``AudioRecording`` or buffer-like object like
-        a ``bytes`` or ``bytearray`` instance.
+        ``AudioTrack``, ``AudioRecording``, or buffer-like object like
+        a ``bytearray`` instance.
+
+        If the input buffer is smaller than the available space in this
+        instance, the rest of the data is left untouched.
+        If it is larger, it will stop copying once this instance is filled.
 
         :param other: Buffer-like instance from which to copy the data.
 
+An ``AudioTrack`` can be created from an ``AudioRecording``, another
+``AudioTrack``, or a ``bytearray`` and individual bytes can be accessed and
+modified like elements in a list::
+
+    my_track = AudioTrack(bytearray(100))
+    # Create a square wave
+    half_length = len(my_track) // 2
+    for i in range(half_length):
+        my_track[i] = 255
+    for i in range(half_length, len(my_track)):
+        my_track[i] = 0
+
+
+Or smaller AudioTracks can be created using slices, useful to send them
+via radio or serial::
+
+    recording = microphone.record(duration=2000)
+    track = AudioTrack(recording)
+    packet_size = 32
+    for i in range(0, len(track), packet_size):
+        radio.send_bytes(track[i:i+packet_size])
+
 Example
 -------
 
diff --git a/docs/microbit_micropython_api.rst b/docs/microbit_micropython_api.rst
index c68fb3de6..dece730dc 100644
--- a/docs/microbit_micropython_api.rst
+++ b/docs/microbit_micropython_api.rst
@@ -109,9 +109,9 @@ The Microphone is accessed via the `microphone` object::
     # Returns a representation of the sound pressure level in the range 0 to 255.
     sound_level()
     # Record audio into a new `AudioRecording`
-    recording = record(duration, rate=7812)
+    recording = record(duration, rate=11_000)
     # Record audio into an existing `AudioRecording`
-    record_into(recording, rate=7812)
+    record_into(recording, wait=True)
     # Returns `True` if the microphone is currently recording audio
     is_recording()
     # Stop any active audio recording
diff --git a/docs/microphone.rst b/docs/microphone.rst
index cd5854f1e..0355ffc6a 100644
--- a/docs/microphone.rst
+++ b/docs/microphone.rst
@@ -141,7 +141,7 @@ Functions
 
     :return: A representation of the sound pressure level in the range 0 to 255.
 
-.. py:function:: record(duration, rate=7812)
+.. py:function:: record(duration, rate=11000)
 
     Record sound into an ``AudioRecording`` for the amount of time indicated by
     ``duration`` at the sampling rate indicated by ``rate``.

From b129d161192a640b0d034e9071e3b94af6731601 Mon Sep 17 00:00:00 2001
From: Carlos Pereira Atencio <carlos@microbit.org>
Date: Mon, 16 Sep 2024 17:12:09 +0100
Subject: [PATCH 7/7] docs: Update the recording default rate from 11k to 7812.

---
 docs/audio.rst                    | 10 +++++++---
 docs/microbit_micropython_api.rst |  2 +-
 docs/microphone.rst               | 15 ++++++++-------
 3 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/docs/audio.rst b/docs/audio.rst
index 63d93513e..986235f93 100644
--- a/docs/audio.rst
+++ b/docs/audio.rst
@@ -12,7 +12,7 @@ a speaker to pin 0 and GND on the edge connector to hear the sounds.
 The ``audio`` module can be imported as ``import audio`` or accessed via
 the ``microbit`` module as ``microbit.audio``.
 
-There are three different kinds of audio sources that can be played using the
+There are five different kinds of audio sources that can be played using the
 :py:meth:`audio.play` function:
 
 1. `Built in sounds <#built-in-sounds-v2>`_ (**V2**),
@@ -268,7 +268,7 @@ AudioRecording
 --------------
 
 .. py:class::
-    AudioRecording(duration, rate=11_000)
+    AudioRecording(duration, rate=7812)
 
     The ``AudioRecording`` object contains audio data and the sampling rate
     associated to it.
@@ -305,6 +305,10 @@ AudioRecording
         Create an `AudioTrack <#audio.AudioTrack>`_ instance from a portion of
         the data in this ``AudioRecording`` instance.
 
+        Out-of-range values will be truncated to the recording limits.
+        If ``end_ms`` is lower than ``start_ms``, an empty track will be
+        created.
+
         :param start_ms: Where to start of the track in milliseconds.
         :param end_ms: The end of the track in milliseconds.
             If the default value of ``-1`` is provided it will end the track
@@ -335,7 +339,7 @@ AudioTrack
 
     When the input buffer has an associated rate (e.g. an ``AudioRecording``
     or ``AudioTrack``), the rate is copied. If the buffer object does not have
-    a rate, the default value of 11_000 is used.
+    a rate, the default value of 7812 is used.
 
     Changes to an ``AudioTrack`` rate won't affect the original source rate,
     so multiple instances pointing to the same buffer can have different
diff --git a/docs/microbit_micropython_api.rst b/docs/microbit_micropython_api.rst
index dece730dc..41cb187de 100644
--- a/docs/microbit_micropython_api.rst
+++ b/docs/microbit_micropython_api.rst
@@ -109,7 +109,7 @@ The Microphone is accessed via the `microphone` object::
     # Returns a representation of the sound pressure level in the range 0 to 255.
     sound_level()
     # Record audio into a new `AudioRecording`
-    recording = record(duration, rate=11_000)
+    recording = record(duration, rate=7812)
     # Record audio into an existing `AudioRecording`
     record_into(recording, wait=True)
     # Returns `True` if the microphone is currently recording audio
diff --git a/docs/microphone.rst b/docs/microphone.rst
index 0355ffc6a..3818407c1 100644
--- a/docs/microphone.rst
+++ b/docs/microphone.rst
@@ -141,7 +141,7 @@ Functions
 
     :return: A representation of the sound pressure level in the range 0 to 255.
 
-.. py:function:: record(duration, rate=11000)
+.. py:function:: record(duration, rate=7812)
 
     Record sound into an ``AudioRecording`` for the amount of time indicated by
     ``duration`` at the sampling rate indicated by ``rate``.
@@ -267,10 +267,8 @@ An example of recording and playback with a display animation::
         "00000"
     )
 
-    RECORDING_RATE = 3906
-    RECORDING_MS = 5000
-
-    my_recording = audio.AudioRecording(duration=RECORDING_MS, rate=RECORDING_RATE)
+    RECORDING_RATE = 7812   # The default sample rate
+    my_recording = audio.AudioRecording(duration=5000, rate=RECORDING_RATE)
 
     while True:
         if button_a.is_pressed():
@@ -283,7 +281,10 @@ An example of recording and playback with a display animation::
         if button_b.is_pressed():
             audio.play(clipped_recording, wait=False)
             while audio.is_playing():
-                x = accelerometer.get_x()
-                audio.set_rate(scale(x, (-1000, 1000), (2250, 11000)))
+                clipped_recording.set_rate(scale(
+                    accelerometer.get_x(),
+                    (-1000, 1000),
+                    (RECORDING_RATE // 2, RECORDING_RATE * 2)
+                ))
                 sleep(50)
         sleep(100)