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

import audio

def audio_generator(file, frame):

ln = -1

while ln:

ln = file.readinto(frame)

yield frame

def play_file(name, pin=None, return_pin=None):

#Do allocation here, as we can't do it in an interrupt.

frame = audio.AudioFrame()

with open(name) as file:

audio.play(audio_generator(file, frame), pin=pin, return_pin=return_pin)

import audio

def from_file(file, frame):

ln = -1

while ln:

ln = file.readinto(frame)

yield frame

def reverb_gen(src, buckets, reflect, fadeout):

bucket_count = len(buckets)

bucket = 0

for frame in src:

echo = buckets[bucket]

echo *= reflect

echo += frame

yield echo

buckets[bucket] = echo

bucket += 1

if bucket == bucket_count:

bucket = 0

while fadeout:

fadeout -= 1

echo = buckets[bucket]

echo *= reflect

yield echo

buckets[bucket] = echo

bucket += 1

if bucket == bucket_count:

bucket = 0

def reverb(src, delay, reflect):

#Do all allocation up front, so we don't need to do any in the generator.

bucket_count = delay>>2

buckets = [ None ] * bucket_count

for i in range(bucket_count):

buckets[i] = audio.AudioFrame()

vol = 1.0

fadeout = 0

while vol > 0.05:

fadeout += bucket_count

vol *= reflect

return reverb_gen(src, buckets, reflect, fadeout)

def play_file(name, delay=80, reflect=0.5):

#Do allocation here, as we can't do it in an interrupt.

frame = audio.AudioFrame()

with open(name) as file:

gen = from_file(file, frame)

r = reverb(gen, delay, reflect)

audio.play(r)

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+128.5)

show_wave("Sine", frame)

triangle = audio.AudioFrame()

QUARTER = len(triangle)//4

for i in range(QUARTER):

triangle[i] = i*15

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

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

triangle[i+QUARTER*3] = i*15+8

show_wave("Triangle", triangle)

square = audio.AudioFrame()

HALF = len(square)//2

for i in range(HALF):

square[i] = 8

square[i+HALF] = 248

show_wave("Square", square)

sleep(1000)

for i in range(len(frame)):

frame[i] = 252-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_get_analog_period_microseconds, (const byte*)"\x7a\x1e" "get_analog_period_microseconds")

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

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

QDEF(MP_QSTR_return_pin, (const byte*)"\x27\x0a" "return_pin")

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

QDEF(MP_QSTR_copyfrom, (const byte*)"\x56\x08" "copyfrom")

QDEF(MP_QSTR_is_playing, (const byte*)"\x04\x0a" "is_playing")

#ifndef __MICROPY_INCLUDED_LIB_PWM_H__

#define __MICROPY_INCLUDED_LIB_PWM_H__

void pwm_start(void);

void pwm_stop(void);

int32_t pwm_set_period_us(int32_t us);

int32_t pwm_get_period_us(void);

int pwm_set_duty_cycle(int32_t pin, int32_t value);

#endif // __MICROPY_INCLUDED_LIB_PWM_H__

mp_obj_t microbit_pin_write_digital(mp_obj_t self_in, mp_obj_t value_in);

mp_obj_t microbit_pin_read_digital(mp_obj_t self_in);

#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_play_source(mp_obj_t src, mp_obj_t pin1, mp_obj_t pin2, bool wait);

#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;

uint8_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 *pwm_next_event; \

void *audio_buffer; \

void *audio_source;

Q(get_analog_period_microseconds)

Q(audio)

Q(play)

Q(AudioFrame)

Q(pin)

Q(return_pin)

Q(source)

Q(copyfrom)

Q(is_playing)