audio Namespace Reference

Sound effects, music and the status LED. More...

Classes
struct	Effect
	An effect: its steps, and its priority with flags. Write them with AUDIO_EFFECT(). More...
struct	Melody
	A melody: one line of notes, easy to write by hand. More...
struct	Step
	An effect step in three bytes. More...

Enumerations
enum	: uint8_t {   SOFT = 0x10 ,   GLIDE = 0x20 }
	Flags ORed into an effect's priority (0-15). More...
enum	MusicMode : uint8_t {   MUSIC_OFF ,   ARPEGGIO ,   LEAD }
	How music is rendered on the one pin. More...
enum	Led : uint8_t {   LED_OFF ,   LED_BLINK ,   LED_TRIPLE ,   LED_PARTY }
	Status LED (PB9) patterns, for wins. Timed in update() ticks. More...

Functions
void	begin (const Effect *effects, uint8_t count, bool on=true)
	Set up the speaker, the LED pin and the timer, with the game's effects.
void	setOn (bool on)
	Turn sound on or off.
bool	on ()
	Whether sound is on.
void	sfx (uint8_t id)
	Play an effect.
void	sfx (uint8_t id, uint8_t semitones)
	Play an effect raised in pitch: a combo that climbs.
template<class E >
void	sfx (E e)
	Play an effect named by the game's enum.
template<class E >
void	sfx (E e, uint8_t semitones)
	Play an effect named by the game's enum, raised in pitch.
void	blip (uint16_t hz, uint16_t ms, bool soft=false)
	One note made up on the spot (a typewriter, a click, a counter rolling).
void	note (uint16_t hz, uint16_t ms, uint8_t priority)
	One note at a priority, like an effect.
bool	playing ()
	Whether an effect is sounding.
void	setMusic (uint8_t mode)
	Choose how music is rendered.
void	music (const uint8_t *score, bool loop=true)
	Play a Playtune score under the effects.
void	melody (const Melody &m, bool loop=true)
	Play a melody under the effects (it replaces any score).
void	stopMusic ()
	Stop the music.
void	loopMusic (bool on)
	Whether the music repeats.
bool	musicPlaying ()
	Whether music is playing.
void	update ()
	Run the LED patterns: once per logic tick.
void	led (Led pattern)
	Start an LED pattern (replacing the one running).

Detailed Description

Sound effects, music and the status LED.

Enumeration Type Documentation

anonymous enum

anonymous enum : uint8_t

Flags ORed into an effect's priority (0-15).

Enumerator
SOFT	A narrow pulse: quieter than everything else (clocks, ticks).
GLIDE	Sweeps change pitch at a cycle's end instead of restarting it.

MusicMode

enum audio::MusicMode : uint8_t

How music is rendered on the one pin.

The music code is linked in only by a game that calls music() or melody().

Enumerator
MUSIC_OFF	No music (held where it is).
ARPEGGIO	A score's sounding voices take 6 ms turns (the default).
LEAD	The melody (channel 0) plays; the others fill only its real rests.

Led

enum audio::Led : uint8_t

Status LED (PB9) patterns, for wins. Timed in update() ticks.

Enumerator
LED_OFF	Off.
LED_BLINK	One blink (12 ticks).
LED_TRIPLE	Three blinks.
LED_PARTY	Fast blinking for about 4 seconds at 60 fps.

Function Documentation

begin()

void audio::begin	(	const Effect *	effects,
		uint8_t	count,
		bool	on = true
	)

Set up the speaker, the LED pin and the timer, with the game's effects.

Parameters

effects	The effects table, in the order of the game's enum (kept by pointer).
count	The number of effects.
on	Whether sound starts on (a saved option, for instance).

setOn()

void audio::setOn

(

bool

on

)

Turn sound on or off.

Parameters

on	false: silent, effects refused, music stopped in place (it carries on from there when sound comes back).

on()

bool audio::on

(

)

Whether sound is on.

Returns

true after begin() with sound on, until setOn(false).

sfx() [1/4]

void audio::sfx

(

uint8_t

id

)

Play an effect.

Parameters

id	An index into the effects table, or the game's enum.

Refused while an effect of higher priority sounds; cuts off any other effect.

sfx() [2/4]

void audio::sfx	(	uint8_t	id,
		uint8_t	semitones
	)

Play an effect raised in pitch: a combo that climbs.

Parameters

id	An index into the effects table.
semitones	How far to raise the whole effect, 0-12.

sfx() [3/4]

template<class E >

void audio::sfx ( E  e )

inline

Play an effect named by the game's enum.

Parameters

e	The enum value (its index into the effects table).

sfx() [4/4]

template<class E >

void audio::sfx ( E  e, uint8_t  semitones  )

inline

Play an effect named by the game's enum, raised in pitch.

Parameters

e	The enum value.
semitones	How far to raise it, 0-12.

blip()

void audio::blip	(	uint16_t	hz,
		uint16_t	ms,
		bool	soft = false
	)

One note made up on the spot (a typewriter, a click, a counter rolling).

It cuts off effects of priority 0 and 1, is refused over anything higher, and is itself priority 0. To never play over any effect: if (!audioplaying()) audio::blip(...).

Parameters

hz	Pitch in Hz.
ms	Length in milliseconds.
soft	true for the quieter narrow pulse (as SOFT).

note()

void audio::note	(	uint16_t	hz,
		uint16_t	ms,
		uint8_t	priority
	)

One note at a priority, like an effect.

Parameters

hz	Pitch in Hz.
ms	Length in milliseconds.
priority	0-15, as an effect's.

playing()

bool audio::playing

(

)

Whether an effect is sounding.

Returns

true while an effect, blip() or note() plays.

setMusic()

void audio::setMusic

(

uint8_t

mode

)

Choose how music is rendered.

Parameters

mode	A MusicMode; MUSIC_OFF holds the tune where it is.

music()

void audio::music	(	const uint8_t *	score,
		bool	loop = true
	)

Play a Playtune score under the effects.

Parameters

score	The score (from tools/make_music.py), or nullptr to stop.
loop	true (default): start again at the end.

melody()

void audio::melody	(	const Melody &	m,
		bool	loop = true
	)

Play a melody under the effects (it replaces any score).

Parameters

m	The melody (kept by reference: it must stay valid).
loop	true (default): start again at the end.

stopMusic()

void audio::stopMusic

(

)

Stop the music.

loopMusic()

void audio::loopMusic

(

bool

on

)

Whether the music repeats.

Parameters

on	false: the score stops at its end instead of repeating.

musicPlaying()

bool audio::musicPlaying

(

)

Whether music is playing.

Returns

true while a score or melody plays; false once it has ended, and while sound or music is off.

update()

void audio::update

(

)

Run the LED patterns: once per logic tick.

led()

void audio::led

(

Led

pattern

)

Start an LED pattern (replacing the one running).

Parameters

pattern

The pattern.