1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
|
Audio
*******
.. py:module:: audio
This module allows you play sounds from a speaker attached to the Microbit.
In order to use the audio module you will need to provide a sound source.
A sound source is an iterable (sequence, like list or tuple, or a generator) of
frames, each of 32 samples.
The ``audio`` modules plays samples at the rate of 7812.5 samples per second,
which means that it can reproduce frequencies up to 3.9kHz.
Functions
=========
.. py:function:: play(source, wait=True, pin=pin0, return_pin=None)
Play the source to completion.
``source`` is an iterable, each element of which must be an ``AudioFrame``.
If ``wait`` is ``True``, this function will block until the source is exhausted.
``pin`` specifies which pin the speaker is connected to.
``return_pin`` specifies a differential pin to connect to the speaker
instead of ground.
Classes
=======
.. py:class::
AudioFrame
An ``AudioFrame`` object is a list of 32 samples each of which is a signed byte
(whole number between -128 and 127).
It takes just over 4 ms to play a single frame.
Using audio
===========
You will need a sound source, as input to the ``play`` function. You can generate your own, like in
``examples/waveforms.py``.
Technical Details
=================
.. note::
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 consumes samples at 7812.5 Hz, and uses linear interpolation to
output a PWM signal at 32.5 kHz, which gives tolerable sound quality.
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 samples.
When reading reaches the start or the mid-point of the buffer, it triggers a callback to
fetch the next ``AudioFrame`` which is then copied into the buffer.
This means that a sound source has under 4ms to compute the next ``AudioFrame``,
and for reliable operation needs to take less 2ms (which is 32000 cycles, so should be plenty).
Example
=======
.. include:: ../examples/waveforms.py
:code: python
|
