From 513ddf88721fe686d910d8984d5e76d842ba2165 Mon Sep 17 00:00:00 2001 From: Carlos Pereira Atencio Date: Thu, 22 Feb 2024 17:28:47 +0000 Subject: [PATCH] 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():