Voice

Dictation sessions: microphone capture, Speex encoding and transcription by the phone. More...

Modules
	Transcription
	Validation and traversal of serialized transcriptions received from the phone.
	Speex encoder
	Speex wideband (16 kHz) encoder used to stream dictation audio.

Macros
#define	VOICE_SESSION_ID_INVALID   AUDIO_ENDPOINT_SESSION_INVALID_ID
	Invalid session id, returned when a session cannot be started.

Typedefs
typedef AudioEndpointSessionId	VoiceSessionId
	Dictation session identifier, the audio endpoint transfer session id.

Enumerations
enum	VoiceStatus {   VoiceStatusSuccess , VoiceStatusTimeout , VoiceStatusErrorGeneric , VoiceStatusErrorConnectivity ,   VoiceStatusErrorDisabled , VoiceStatusRecognizerResponseError }
	Outcome reported in voice service events. More...

Functions
VoiceSessionId	voice_start_dictation (VoiceEndpointSessionType session_type)
	Start a dictation session.
void	voice_stop_dictation (VoiceSessionId session_id)
	Stop recording and wait for the transcription.
void	voice_cancel_dictation (VoiceSessionId session_id)
	Cancel a dictation session at any stage.
void	voice_init (void)
	Initialize the voice service.
void	voice_handle_session_setup_result (VoiceEndpointResult result, VoiceEndpointSessionType session_type, bool app_initiated)
	Handle a session setup result received by the voice endpoint.
void	voice_handle_dictation_result (VoiceEndpointResult result, AudioEndpointSessionId session_id, Transcription *transcription, bool app_initiated, Uuid *app_uuid)
	Handle a dictation result received by the voice endpoint.
void	voice_handle_nlp_result (VoiceEndpointResult result, AudioEndpointSessionId session_id, char *reminder, time_t timestamp)
	Handle an NLP (reminder) result received by the voice endpoint.
VoiceSessionId	sys_voice_start_dictation (VoiceEndpointSessionType session_type)
	Syscall wrapper of voice_start_dictation().
void	sys_voice_stop_dictation (VoiceSessionId session_id)
	Syscall wrapper of voice_stop_dictation().
void	sys_voice_cancel_dictation (VoiceSessionId session_id)
	Syscall wrapper of voice_cancel_dictation().
void	voice_kill_app_session (PebbleTask task)
	Cancel the session started by an app that is exiting.

Detailed Description

Dictation sessions: microphone capture, Speex encoding and transcription by the phone.

One session runs at a time. Starting a session sets it up with the phone over the voice and audio endpoints; once both are ready the microphone is started and Speex frames are streamed. Progress is reported with PEBBLE_VOICE_SERVICE_EVENT events: a VoiceEventTypeSessionSetup event when the session is set up or fails to, then a VoiceEventTypeSessionResult event with the transcribed text or an error.

static VoiceSessionId s_session;
 
void start(void) {
  s_session = voice_start_dictation(VoiceEndpointSessionTypeDictation);
}
 
// On PEBBLE_VOICE_SERVICE_EVENT:
void handle_voice_event(const PebbleVoiceServiceEvent *e) {
  if (e->type == VoiceEventTypeSessionSetup && e->status == VoiceStatusSuccess) {
    // Recording; call voice_stop_dictation(s_session) when the user is done.
  } else if (e->type == VoiceEventTypeSessionResult && e->status == VoiceStatusSuccess) {
    use_text(e->data->sentence);
  }
}

Macro Definition Documentation

VOICE_SESSION_ID_INVALID

#define VOICE_SESSION_ID_INVALID   AUDIO_ENDPOINT_SESSION_INVALID_ID

Invalid session id, returned when a session cannot be started.

Typedef Documentation

VoiceSessionId

typedef AudioEndpointSessionId VoiceSessionId

Dictation session identifier, the audio endpoint transfer session id.

Enumeration Type Documentation

VoiceStatus

enum VoiceStatus

Outcome reported in voice service events.

Enumerator
VoiceStatusSuccess	Session set up, or transcription received.
VoiceStatusTimeout	The phone did not answer in time.
VoiceStatusErrorGeneric	Unexpected or malformed response, or local failure.
VoiceStatusErrorConnectivity	The phone reports the recognition service is unavailable.
VoiceStatusErrorDisabled	Voice is disabled on the phone.
VoiceStatusRecognizerResponseError	The recognizer returned an invalid response.

Function Documentation

sys_voice_cancel_dictation()

void sys_voice_cancel_dictation

(

VoiceSessionId

session_id

)

Syscall wrapper of voice_cancel_dictation().

Parameters

session_id

Session returned by voice_start_dictation().

sys_voice_start_dictation()

VoiceSessionId sys_voice_start_dictation

(

VoiceEndpointSessionType

session_type

)

Syscall wrapper of voice_start_dictation().

Parameters

session_type

Type of session; out of range values are rejected.

Returns

Session id, or VOICE_SESSION_ID_INVALID.

sys_voice_stop_dictation()

void sys_voice_stop_dictation

(

VoiceSessionId

session_id

)

Syscall wrapper of voice_stop_dictation().

Parameters

session_id

Session returned by voice_start_dictation().

voice_cancel_dictation()

void voice_cancel_dictation

(

VoiceSessionId

session_id

)

Cancel a dictation session at any stage.

No further event is sent for the session. Ignored if session_id is not the current session.

Parameters

session_id

Session returned by voice_start_dictation().

voice_handle_dictation_result()

void voice_handle_dictation_result	(	VoiceEndpointResult	result,
		AudioEndpointSessionId	session_id,
		Transcription *	transcription,
		bool	app_initiated,
		Uuid *	app_uuid
	)

Handle a dictation result received by the voice endpoint.

Ends the session. On success, the words of the first sentence are joined into a string carried by the VoiceEventTypeSessionResult event; transcription is not referenced afterwards.

Parameters

result	Result code for the dictation session.
session_id	Audio transfer session the transcription was derived from.
transcription	Transcription, already checked with transcription_validate().
app_initiated	True if the session was initiated by an app.
app_uuid	UUID of the initiating app, compared with the expected one. Not retained.

voice_handle_nlp_result()

void voice_handle_nlp_result	(	VoiceEndpointResult	result,
		AudioEndpointSessionId	session_id,
		char *	reminder,
		time_t	timestamp
	)

Handle an NLP (reminder) result received by the voice endpoint.

Ends the session. On success, the VoiceEventTypeSessionResult event carries a copy of reminder and timestamp.

Parameters

result	Result code for the session.
session_id	Audio transfer session the result was derived from.
reminder	Reminder text, zero terminated.
timestamp	Reminder time.

voice_handle_session_setup_result()

void voice_handle_session_setup_result	(	VoiceEndpointResult	result,
		VoiceEndpointSessionType	session_type,
		bool	app_initiated
	)

Handle a session setup result received by the voice endpoint.

Parameters

result	Result code for the session setup.
session_type	Type of session.
app_initiated	True if the session was initiated by an app.

voice_init()

void voice_init

(

void

)

Initialize the voice service.

voice_kill_app_session()

void voice_kill_app_session

(

PebbleTask

task

)

Cancel the session started by an app that is exiting.

Parameters

task	Exiting task; only PebbleTask_App sessions are cancelled.

voice_start_dictation()

VoiceSessionId voice_start_dictation

(

VoiceEndpointSessionType

session_type

)

Start a dictation session.

Lazily initializes the Speex encoder, sets the session up with the phone and starts streaming audio once it is ready. Then a VoiceEventTypeSessionSetup event is sent with:

• VoiceStatusSuccess when recording has started;
• an error status when the phone refuses the session or recording cannot start;
• VoiceStatusTimeout when the phone does not answer within 8 s.

If the phone stops the recording itself, a VoiceEventTypeSessionResult event follows as described in voice_stop_dictation(). When called from a third-party app, the app UUID is sent to the phone and the session is cancelled if the app exits.

Parameters

session_type

Type of session (dictation or NLP).

Returns

Session id, or VOICE_SESSION_ID_INVALID if a session is already in progress or the encoder could not be initialized.

voice_stop_dictation()

void voice_stop_dictation

(

VoiceSessionId

session_id

)

Stop recording and wait for the transcription.

Stops the microphone and the audio transfer. A VoiceEventTypeSessionResult event is then sent with:

• VoiceStatusSuccess and the text when the phone returns the transcription;
• an error status when the phone reports an error;
• VoiceStatusTimeout when no result arrives within 15 s.

Called before recording has started, the session is cancelled instead. Ignored if session_id is not the current session.

Parameters

session_id

Session returned by voice_start_dictation().