33
44.. py :module :: audio
55
6- sounds from a speaker attached to the Microbit.
7- In order to use the audio module you will need to provide a sound source .
6+ to play your own sounds. If you are using a micro:bit
7+ ** V2 **, `` audio `` is also part of the `` microbit `` module .
88
9- A sound source is an iterable (sequence, like list or tuple, or a generator) of
10- frames, each of 32 samples.
11- The ``audio `` modules plays samples at the rate of 7812.5 samples per second,
12- which means that it can reproduce frequencies up to 3.9kHz.
9+ By default sound output will be via the edge connector on pin 0 and the
10+ built-in speaker **V2 **. You can connect a wired headphones or a speaker to
11+ pin 0 and GND on the edge connector to hear the sounds.
1312
1413Functions
1514=========
1615
1716.. py :function :: play(source, wait = True , pin = pin0, return_pin = None )
17+ play(source, wait = True , pin = (pin_speaker, pin0), return_pin = None )
1818
1919
2020
21- ``source `` is an iterable, each element of which must be an ``AudioFrame ``.
21+ * **source **: ``Sound `` - The ``microbit `` module contains a list of
22+ built-in sounds that your can pass to ``audio.play() ``.
2223
23- If ``wait `` is ``True ``, this function will block until the source is exhausted.
24+ * **source **: ``AudioFrame `` - The source agrument can also be an iterable
25+ of ``AudioFrame `` elements as described below.
2426
25- ``pin `` specifies which pin the speaker is connected to.
27+ * **wait **: If ``wait `` is ``True ``, this function will block until the
28+ source is exhausted.
2629
27- ``return_pin `` specifies a differential pin to connect to the speaker
28- instead of ground.
30+ * **pin **: As with the music module, you can use the optional ``pin ``
31+ argument to specify the output pin can be used to override the
32+ default of ``microbit.pin0 ``. If you have the latest micro:bit **V2 **,
33+ you can use ``microbit.pin_speaker ``. The pin argument can also take a
34+ tuple of two pins, for example ``pin=(pin_speaker, pin0) `` which would
35+ output sound on the built-in speaker and pin 0.
36+
37+ * **return_pin **: specifies a differential edge connector pin to connect
38+ to an external speaker instead of ground. This is ignored for the **V2 **
39+ revision.
40+
41+ .. py :function :: is_playing()
42+
43+ True `` if audio is playing, otherwise return ``False ``.
44+
45+ .. py :function :: stop()
46+
47+
2948
3049Classes
3150=======
@@ -41,9 +60,25 @@ Classes
4160Using audio
4261===========
4362
44- You will need a sound source, as input to the ``play `` function. You can generate your own, like in
45- ``examples/waveforms.py ``.
63+ You will need a sound source, as input to the ``play `` function. You can use
64+ the built-in sounds **V2 ** from the ``microbit `` module, ``microbit.Sound ``, or
65+ generate your own, like in ``examples/waveforms.py ``.
4666
67+ Built-in sounds **V2 **
68+ ----------------------
69+
70+ The built-in sounds can be called using ``audio.play(Sound.NAME) ``.
71+
72+ * ``Sound.GIGGLE ``
73+ * ``Sound.HAPPY ``
74+ * ``Sound.HELLO ``
75+ * ``Sound.MYSTERIOUS ``
76+ * ``Sound.SAD ``
77+ * ``Sound.SLIDE ``
78+ * ``Sound.SOARING ``
79+ * ``Sound.SPRING ``
80+ * ``Sound.TWINKLE ``
81+ * ``Sound.YAWN ``
4782
4883Technical Details
4984=================
@@ -52,23 +87,24 @@ Technical Details
5287 You don't need to understand this section to use the ``audio `` module.
5388 It is just here in case you wanted to know how it works.
5489
55- The ``audio `` module consumes samples at 7812.5 Hz, and uses linear interpolation to
56- output a PWM signal at 32.5 kHz, which gives tolerable sound quality.
90+ The ``audio `` module consumes ``AudioFrame `` samples at 7812.5 Hz, and uses
91+ linear interpolation to output a PWM signal at 32.5 kHz, which gives tolerable
92+ sound quality.
5793
5894The function ``play `` fully copies all data from each ``AudioFrame `` before it
59- calls ``next() `` for the next frame, so a sound source can use the same `` AudioFrame ``
60- repeatedly.
95+ calls ``next() `` for the next frame, so a sound source can use the same
96+ `` AudioFrame `` repeatedly.
6197
62- The ``audio `` module has an internal 64 sample buffer from which it reads samples.
63- When reading reaches the start or the mid-point of the buffer, it triggers a callback to
64- fetch the next ``AudioFrame `` which is then copied into the buffer.
65- This means that a sound source has under 4ms to compute the next ``AudioFrame ``,
66- and for reliable operation needs to take less 2ms (which is 32000 cycles, so should be plenty).
98+ The ``audio `` module has an internal 64 sample buffer from which it reads
99+ samples. When reading reaches the start or the mid-point of the buffer, it
100+ triggers a callback to fetch the next ``AudioFrame `` which is then copied into
101+ the buffer. This means that a sound source has under 4ms to compute the next
102+ ``AudioFrame ``, and for reliable operation needs to take less 2ms (which is
103+ 32000 cycles, so should be plenty).
67104
68105
69106Example
70107=======
71108
72109.. include :: ../examples/waveforms.py
73110 :code: python
74-
0 commit comments