From 102cd8cb099d0c540ab3a668cd5531bedfa6bbf3 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 | 42 +++++++++++++++++++++++++++++++----------- docs/microphone.rst | 35 +++++++++++++++-------------------- 2 files changed, 46 insertions(+), 31 deletions(-) diff --git a/docs/audio.rst b/docs/audio.rst index 250c69898..7e0cdb48a 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) @@ -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). diff --git a/docs/microphone.rst b/docs/microphone.rst index 1aadc33df..da91eeb15 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) @@ -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():