Skip to content

Commit

Permalink
docs: Update Recording & Playback based on the latest implementation.
Browse files Browse the repository at this point in the history
  • Loading branch information
microbit-carlos committed Mar 1, 2024
1 parent eef81c0 commit 102cd8c
Show file tree
Hide file tree
Showing 2 changed files with 46 additions and 31 deletions.
42 changes: 31 additions & 11 deletions docs/audio.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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**
======================
Expand Down Expand Up @@ -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)
Expand All @@ -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).
Expand Down
35 changes: 15 additions & 20 deletions docs/microphone.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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)
Expand Down Expand Up @@ -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
Expand All @@ -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)
Expand Down Expand Up @@ -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():
Expand Down

0 comments on commit 102cd8c

Please sign in to comment.