33
44.. py :module :: audio
55
6-
6+
7+
8+ By default sound output will be via the edge connector on pin 0 and the
9+ built-in speaker **V2 **. You can connect a wired headphones or a speaker to
10+ pin 0 and GND on the edge connector to hear the sounds.
711
812The ``audio `` module can be imported as ``import audio `` or accessed via
913the ``microbit `` module as ``microbit.audio ``.
1014
11- In order to use the audio module you will need to provide a sound source.
12-
13- A sound source is an iterable (sequence, like list or tuple, or a generator) of
14- frames, each of 32 samples.
15- The ``audio `` modules plays samples at the rate of 7812.5 samples per second,
16- which means that it can reproduce frequencies up to 3.9kHz.
17-
1815Functions
1916=========
2017
2118.. py :function :: play(source, wait = True , pin = pin0, return_pin = None )
19+ play(source, wait = True , pin = (pin_speaker, pin0), return_pin = None )
2220
2321
2422
25- :param source: An iterable sound source, each element of which must be
26- an ``AudioFrame ``.
23+ :param source: ``Sound ``: The ``microbit `` module contains a list of
24+ built-in sounds that your can pass to ``audio.play() ``.
25+
26+ ``AudioFrame ``: The source agrument can also be an iterable
27+ of ``AudioFrame `` elements as described below.
2728 :param wait: If ``wait `` is ``True ``, this function will block until the
2829 source is exhausted.
29- :param pin: Specifies which pin the speaker is connected to.
30- :param return_pin: Specifies a differential pin to connect to the speaker
31- instead of ground.
30+ :param 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+ :param return_pin: specifies a differential edge connector pin to connect
37+ to an external speaker instead of ground. This is ignored for the **V2 **
38+ revision.
39+
40+ .. py :function :: is_playing()
41+
42+ :returns: ``True `` if audio is playing, otherwise returns ``False ``.
43+
44+ .. py :function :: stop()
45+
46+
3247
3348Classes
3449=======
@@ -52,9 +67,25 @@ Classes
5267Using audio
5368===========
5469
55- You will need a sound source, as input to the ``play `` function. You can generate your own, like in
56- ``examples/waveforms.py ``.
70+ You will need a sound source, as input to the ``play `` function. You can use
71+ the built-in sounds **V2 ** from the ``microbit `` module, ``microbit.Sound ``, or
72+ generate your own, like in ``examples/waveforms.py ``.
73+
74+ Built-in sounds **V2 **
75+ ----------------------
5776
77+ The built-in sounds can be called using ``audio.play(Sound.NAME) ``.
78+
79+ * ``Sound.GIGGLE ``
80+ * ``Sound.HAPPY ``
81+ * ``Sound.HELLO ``
82+ * ``Sound.MYSTERIOUS ``
83+ * ``Sound.SAD ``
84+ * ``Sound.SLIDE ``
85+ * ``Sound.SOARING ``
86+ * ``Sound.SPRING ``
87+ * ``Sound.TWINKLE ``
88+ * ``Sound.YAWN ``
5889
5990Technical Details
6091=================
@@ -63,7 +94,8 @@ Technical Details
6394 You don't need to understand this section to use the ``audio `` module.
6495 It is just here in case you wanted to know how it works.
6596
66- The ``audio `` module consumes ``AudioFrame `` samples at 7812.5 Hz, and uses
97+ The ``audio `` module can consumes an iterable (sequence, like list or tuple, or
98+ generator) of ``AudioFrame `` instances, each 32 samples at 7812.5 Hz, and uses
6799linear interpolation to output a PWM signal at 32.5 kHz, which gives tolerable
68100sound quality.
69101
@@ -84,4 +116,3 @@ Example
84116
85117.. include :: ../examples/waveforms.py
86118 :code: python
87-
0 commit comments