Speaker

Plays notes, tones, polyphonic tracks and PCM streams on the speaker. More...

Modules
	Note synthesis
	Synthesizes PCM from SpeakerNote sequences.

Enumerations
enum	SpeakerPriority { SpeakerPriorityApp = 0 , SpeakerPriorityNotification , SpeakerPriorityCritical }
	Playback priority; a higher priority preempts a lower one. More...
enum	SpeakerState { SpeakerStateIdle = 0 , SpeakerStatePlaying , SpeakerStateDraining }
	Playback state. More...
enum	SpeakerSourceType {   SpeakerSourceNone = 0 , SpeakerSourceNoteSeq , SpeakerSourceStream , SpeakerSourceTracks ,   SpeakerSourceTone }
	Kind of source being played. More...

Functions
void	speaker_service_init (void)
	Initialize the speaker service.
bool	speaker_service_play_note_seq (const SpeakerNote *notes, uint32_t num_notes, SpeakerPriority pri, uint8_t vol)
	Play a note sequence.
bool	speaker_service_play_tone (uint16_t freq_hz, uint16_t duration_ms, uint8_t waveform, uint8_t velocity, SpeakerPriority pri, uint8_t vol)
	Play a single tone at an exact frequency.
bool	speaker_service_play_volume_preview (uint8_t vol)
	Play a short tone at an absolute output volume.
bool	speaker_service_play_tracks (const SpeakerTrack *tracks, uint32_t num_tracks, SpeakerPriority pri, uint8_t vol)
	Play monophonic tracks in parallel, mixed together.
void	speaker_service_register_finish (PebbleTask task)
	Post a PEBBLE_SPEAKER_EVENT with the finish reason whenever playback ends.
bool	speaker_service_stream_open (SpeakerPriority pri, uint8_t vol, SpeakerPcmFormat fmt)
	Open a PCM stream for writing.
bool	speaker_service_stream_open_owned (SpeakerPriority pri, uint8_t vol, SpeakerPcmFormat fmt, PebbleTask owner)
	Open a PCM stream owned by a task.
bool	speaker_service_stream_open_realtime_owned (SpeakerPriority pri, uint8_t vol, SpeakerPcmFormat fmt, PebbleTask owner)
	Open an owned PCM stream for internal live audio.
uint32_t	speaker_service_stream_write_owned (PebbleTask owner, const void *data, uint32_t num_bytes)
	Write PCM data to the stream owned by a task.
void	speaker_service_stream_close_owned (PebbleTask owner)
	Close the stream owned by a task, draining its buffered data.
uint32_t	speaker_service_stream_write (const void *data, uint32_t num_bytes)
	Write PCM data to the active stream.
void	speaker_service_stream_close (void)
	Close the active stream.
void	speaker_service_stop (void)
	Stop any active playback immediately.
void	speaker_service_set_volume (uint8_t vol)
	Set the playback volume.
void	speaker_service_set_volume_owned (PebbleTask owner, uint8_t vol)
	Set the playback volume, only if the playback belongs to a task.
SpeakerState	speaker_service_get_state (void)
	Get the playback state.
void	speaker_service_stop_for_task (PebbleTask task)
	Stop any playback owned by a task and drop its finish events.
void	speaker_service_set_owner_task (PebbleTask task)
	Set the task that owns the current playback.
bool	speaker_service_is_muted (void)
	Check whether the speaker is muted.
void	speaker_service_handle_audio_prefs_changed (void)
	Notify that the audio preferences (mute or system volume cap) changed.

Detailed Description

Plays notes, tones, polyphonic tracks and PCM streams on the speaker.

One source plays at a time, mixed to 16 kHz mono and fed to the audio driver from KernelBG. Starting playback preempts the current source when the new priority is higher, or when the current source has finished and only its tail is draining; otherwise the request is rejected. Volumes are 0-100 and are scaled by the user's speaker volume preference; output is silent while the speaker is muted (always, or during Do Not Disturb if so configured). Without CONFIG_SPEAKER every call is a no-op that reports failure.

The note, sample and PCM types are shared with the app SDK.

static const SpeakerNote s_chime[] = {
  {.midi_note = 72, .waveform = SpeakerWaveformSine, .duration_ms = 150},
  {.midi_note = 0, .duration_ms = 50},
  {.midi_note = 79, .waveform = SpeakerWaveformSine, .duration_ms = 300},
};
 
speaker_service_play_note_seq(s_chime, ARRAY_LENGTH(s_chime), SpeakerPriorityNotification, 80);

Streaming PCM:

if (speaker_service_stream_open(SpeakerPriorityApp, 100, SpeakerPcmFormat_16kHz_16bit)) {
  uint32_t written = speaker_service_stream_write(pcm, pcm_len);
  // Retry the remaining pcm_len - written bytes later: the queue is full.
  speaker_service_stream_close();
}

Enumeration Type Documentation

SpeakerPriority

enum SpeakerPriority

Playback priority; a higher priority preempts a lower one.

Enumerator
SpeakerPriorityApp	Sounds started by apps.
SpeakerPriorityNotification	Notification sounds.
SpeakerPriorityCritical	Sounds that must not be interrupted, e.g. alarms.

SpeakerSourceType

enum SpeakerSourceType

Kind of source being played.

Enumerator
SpeakerSourceNone	No source.
SpeakerSourceNoteSeq	Note sequence, see speaker_service_play_note_seq().
SpeakerSourceStream	PCM stream, see speaker_service_stream_open().
SpeakerSourceTracks	Polyphonic tracks, see speaker_service_play_tracks().
SpeakerSourceTone	Single tone, see speaker_service_play_tone().

SpeakerState

enum SpeakerState

Playback state.

Enumerator
SpeakerStateIdle	Nothing is playing.
SpeakerStatePlaying	A source is playing.
SpeakerStateDraining	The stream was closed; its remaining queued data is playing.

Function Documentation

speaker_service_get_state()

SpeakerState speaker_service_get_state

(

void

)

Get the playback state.

Returns

Current state.

speaker_service_handle_audio_prefs_changed()

void speaker_service_handle_audio_prefs_changed

(

void

)

Notify that the audio preferences (mute or system volume cap) changed.

The output volume of a playing source is re-applied immediately.

speaker_service_init()

void speaker_service_init

(

void

)

Initialize the speaker service.

Called once at boot.

speaker_service_is_muted()

bool speaker_service_is_muted

(

void

)

Check whether the speaker is muted.

Returns

true if always-on mute is set, or the Do Not Disturb mute is set while Do Not Disturb is active.

speaker_service_play_note_seq()

bool speaker_service_play_note_seq	(	const SpeakerNote *	notes,
		uint32_t	num_notes,
		SpeakerPriority	pri,
		uint8_t	vol
	)

Play a note sequence.

Parameters

notes	Notes to play, copied internally.
num_notes	Number of entries in notes.
pri	Priority.
vol	Volume, 0-100.

Returns

true if playback started; false on invalid arguments, allocation failure, or if blocked by a higher or equal priority source.

speaker_service_play_tone()

bool speaker_service_play_tone	(	uint16_t	freq_hz,
		uint16_t	duration_ms,
		uint8_t	waveform,
		uint8_t	velocity,
		SpeakerPriority	pri,
		uint8_t	vol
	)

Play a single tone at an exact frequency.

Parameters

freq_hz	Tone frequency in Hz, 0 for silence.
duration_ms	Tone duration in milliseconds, must be non-zero.
waveform	SpeakerWaveform value.
velocity	Amplitude scale 0-127, 0 for full amplitude.
pri	Priority.
vol	Volume, 0-100.

Returns

true if playback started; false on invalid arguments or if blocked by a higher or equal priority source.

speaker_service_play_tracks()

bool speaker_service_play_tracks	(	const SpeakerTrack *	tracks,
		uint32_t	num_tracks,
		SpeakerPriority	pri,
		uint8_t	vol
	)

Play monophonic tracks in parallel, mixed together.

Track notes, samples and sample data are copied into kernel memory.

Parameters

tracks	Tracks to play.
num_tracks	Number of tracks, at most SPEAKER_MAX_TRACKS.
pri	Priority.
vol	Volume, 0-100.

Returns

true if playback started; false on invalid arguments, exceeded limits (see SPEAKER_MAX_SAMPLE_BYTES_TOTAL), allocation failure, or if blocked by a higher or equal priority source.

speaker_service_play_volume_preview()

bool speaker_service_play_volume_preview

(

uint8_t

vol

)

Play a short tone at an absolute output volume.

Bypasses the user's speaker volume preference, so settings UIs can preview a candidate volume before it is saved. Mute still applies. Plays at SpeakerPriorityApp.

Parameters

vol	Absolute output volume, 0-100.

Returns

true if playback started.

speaker_service_register_finish()

void speaker_service_register_finish

(

PebbleTask

task

)

Post a PEBBLE_SPEAKER_EVENT with the finish reason whenever playback ends.

Stays enabled until speaker_service_stop_for_task() is called for task.

Parameters

task	Task interested in the events.

speaker_service_set_owner_task()

void speaker_service_set_owner_task

(

PebbleTask

task

)

Set the task that owns the current playback.

Parameters

task	Owning task.

speaker_service_set_volume()

void speaker_service_set_volume

(

uint8_t

vol

)

Set the playback volume.

Parameters

vol	Volume, 0-100.

speaker_service_set_volume_owned()

void speaker_service_set_volume_owned	(	PebbleTask	owner,
		uint8_t	vol
	)

Set the playback volume, only if the playback belongs to a task.

Parameters

owner	Owning task, or PebbleTask_Unknown to apply unconditionally.
vol	Volume, 0-100.

speaker_service_stop()

void speaker_service_stop

(

void

)

Stop any active playback immediately.

speaker_service_stop_for_task()

void speaker_service_stop_for_task

(

PebbleTask

task

)

Stop any playback owned by a task and drop its finish events.

Called on app exit.

Parameters

task	Exiting task.

speaker_service_stream_close()

void speaker_service_stream_close

(

void

)

Close the active stream.

Remaining buffered data is drained.

speaker_service_stream_close_owned()

void speaker_service_stream_close_owned

(

PebbleTask

owner

)

Close the stream owned by a task, draining its buffered data.

Parameters

owner

Owning task, or PebbleTask_Unknown to close any stream.

speaker_service_stream_open()

bool speaker_service_stream_open	(	SpeakerPriority	pri,
		uint8_t	vol,
		SpeakerPcmFormat	fmt
	)

Open a PCM stream for writing.

Parameters

pri	Priority.
vol	Volume, 0-100.
fmt	PCM format of the data to be written.

Returns

true if the stream opened; false on allocation failure or if blocked by a higher or equal priority source.

speaker_service_stream_open_owned()

bool speaker_service_stream_open_owned	(	SpeakerPriority	pri,
		uint8_t	vol,
		SpeakerPcmFormat	fmt,
		PebbleTask	owner
	)

Open a PCM stream owned by a task.

Ownership is assigned atomically with the open, so the owner's later writes, closes and volume changes cannot affect a stream that has preempted it.

Parameters

pri	Priority.
vol	Volume, 0-100.
fmt	PCM format of the data to be written.
owner	Owning task.

Returns

true if the stream opened.

speaker_service_stream_open_realtime_owned()

bool speaker_service_stream_open_realtime_owned	(	SpeakerPriority	pri,
		uint8_t	vol,
		SpeakerPcmFormat	fmt,
		PebbleTask	owner
	)

Open an owned PCM stream for internal live audio.

Writes feed complete driver blocks directly on the producer task. Driver callbacks retry on backpressure instead of inserting silence into the PCM queue, and closing always drains.

Parameters

pri	Priority.
vol	Volume, 0-100.
fmt	PCM format of the data to be written.
owner	Owning task.

Returns

true if the stream opened.

speaker_service_stream_write()

uint32_t speaker_service_stream_write	(	const void *	data,
		uint32_t	num_bytes
	)

Write PCM data to the active stream.

Parameters

data	Source buffer.
num_bytes	Number of bytes to write; a trailing partial sample is dropped.

Returns

Number of bytes accepted, fewer than num_bytes when the queue is full.

speaker_service_stream_write_owned()

uint32_t speaker_service_stream_write_owned	(	PebbleTask	owner,
		const void *	data,
		uint32_t	num_bytes
	)

Write PCM data to the stream owned by a task.

Parameters

owner	Owning task, or PebbleTask_Unknown to write to any stream.
data	Source buffer.
num_bytes	Number of bytes to write; a trailing partial sample is dropped.

Returns

Number of bytes accepted, 0 if no stream is open or it belongs to another task.