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, pins=(pin0, pin1))

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.

``pins`` specifies which pins the speaker is connected to.

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`` or you can use the sound sources provided by modules like ``synth``.

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 kHz, 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

from microbit import display, sleep, button_a

import audio

import math

def repeated_frame(frame, count):

for i in range(count):

yield frame

def show_wave(name, frame, duration=1500):

display.scroll(name + " wave", wait=False,delay=100)

audio.play(repeated_frame(frame, duration),wait=False)

for i in range(75):

sleep(100)

if button_a.is_pressed():

display.clear()

audio.stop()

break

frame = audio.AudioFrame()

for i in range(len(frame)):

frame[i] = int(math.sin(math.pi*i/16)*124+0.5)

show_wave("Sine", frame)

triangle = audio.AudioFrame()

QUARTER = len(triangle)//4

for i in range(QUARTER):

triangle[i] = i*15

triangle[i+QUARTER] = 120-i*15

triangle[i+QUARTER*2] = -i*15

triangle[i+QUARTER*3] = i*15-120

show_wave("Triangle", triangle)

square = audio.AudioFrame()

HALF = len(square)//2

for i in range(HALF):

square[i] = -120

square[i+HALF] = 120

show_wave("Square", square)

sleep(1000)

for i in range(len(frame)):

frame[i] = 124-i*8

show_wave("Sawtooth", frame)

del frame

frames = [ None ] * 32

for i in range(32):

frames[i] = frame = audio.AudioFrame()

for j in range(len(triangle)):

frame[j] = (triangle[j]*(32-i) + square[j]*i)>>5

def repeated_frames(frames, count):

for frame in frames:

for i in range(count):

yield frame

display.scroll("Ascending wave", wait=False)

audio.play(repeated_frames(frames, 60))

QDEF(MP_QSTR_audio, (const byte*)"\x53\x05" "audio")

QDEF(MP_QSTR_AudioFrame, (const byte*)"\xae\x0a" "AudioFrame")

QDEF(MP_QSTR_source, (const byte*)"\xb8\x06" "source")

#ifndef __MICROPY_INCLUDED_MICROBIT_AUDIO_H__

#define __MICROPY_INCLUDED_MICROBIT_AUDIO_H__

#include "nrf.h"

#include "py/obj.h"

#include "py/runtime.h"

void audio_start(void);

void audio_stop(void);

mp_obj_t audio_init(void);

void audio_play_source(mp_obj_t src, bool wait);

void audio_set_pins(mp_obj_t pin0_obj, mp_obj_t pin1_obj);

#define LOG_AUDIO_CHUNK_SIZE 5

#define AUDIO_CHUNK_SIZE (1<<LOG_AUDIO_CHUNK_SIZE)

#define AUDIO_BUFFER_SIZE (AUDIO_CHUNK_SIZE*2)

#define AUDIO_CALLBACK_ID 0

typedef struct _microbit_audio_frame_obj_t {

mp_obj_base_t base;

int8_t data[AUDIO_CHUNK_SIZE];

} microbit_audio_frame_obj_t;

extern const mp_obj_type_t microbit_audio_frame_type;

microbit_audio_frame_obj_t *new_microbit_audio_frame(void);

#endif // __MICROPY_INCLUDED_MICROBIT_AUDIO_H__

extern const struct _mp_obj_module_t audio_module;

{ MP_OBJ_NEW_QSTR(MP_QSTR_audio), (mp_obj_t)&audio_module }, \

void *audio_buffer; \

void *audio_source;

Q(audio)

Q(play)

Q(AudioFrame)

Q(pins)

Q(source)