docs: Update Recording & Playback based on the latest implementation.

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)
 
@@ -257,7 +276,8 @@ Its default playback rate is 7812 Hz, and uses linear interpolation to output
 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).

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)
@@ -119,10 +117,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
@@ -133,10 +131,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)
@@ -242,11 +238,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():