use std::collections::HashMap;
use std::sync::{Arc, Mutex, OnceLock};
use std::sync::atomic::{AtomicU64, Ordering};
pub mod dictation;
pub use dictation::{Dictation, Replacement};
#[cfg(any(target_os = "macos", target_os = "ios"))]
mod apple;
#[cfg(all(target_os = "android", native_speech_android))]
mod android;
#[cfg(target_os = "windows")]
mod windows;
#[cfg(any(target_os = "macos", target_os = "ios"))]
use apple as backend;
#[cfg(all(target_os = "android", native_speech_android))]
use android as backend;
#[cfg(target_os = "windows")]
use windows as backend;
#[derive(Clone, Debug)]
pub struct NativeSpeechOptions {
pub locale: Option<String>,
pub prefer_on_device: bool,
}
impl Default for NativeSpeechOptions {
fn default() -> Self {
Self { locale: None, prefer_on_device: true }
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash)]
#[non_exhaustive]
pub enum SpeechErrorKind {
PermissionDenied,
Unavailable,
Language,
Audio,
Busy,
Other,
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct SpeechError {
kind: SpeechErrorKind,
message: String,
}
impl SpeechError {
pub fn new(kind: SpeechErrorKind, message: impl Into<String>) -> Self {
Self { kind, message: message.into() }
}
pub fn kind(&self) -> SpeechErrorKind {
self.kind
}
pub fn message(&self) -> &str {
&self.message
}
}
impl std::fmt::Display for SpeechError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(&self.message)
}
}
impl std::error::Error for SpeechError {}
#[derive(Clone, Debug, PartialEq)]
pub enum NativeSpeechEvent {
Started,
Transcript {
text: String,
is_final: bool,
},
AudioLevel(f32),
Stopped,
Error(SpeechError),
}
#[cfg(any(target_os = "macos", target_os = "ios", all(target_os = "android", native_speech_android)))]
#[allow(dead_code)] pub(crate) mod codes {
pub(crate) const STARTED: i32 = 0;
pub(crate) const PARTIAL: i32 = 1;
pub(crate) const FINAL: i32 = 2;
pub(crate) const LEVEL: i32 = 3;
pub(crate) const STOPPED: i32 = 4;
pub(crate) const ERROR: i32 = 5;
pub(crate) const ERROR_PERMISSION: i32 = 6;
pub(crate) const ERROR_UNAVAILABLE: i32 = 7;
pub(crate) const ERROR_LANGUAGE: i32 = 8;
pub(crate) const ERROR_AUDIO: i32 = 9;
}
#[cfg(any(target_os = "macos", target_os = "ios", all(target_os = "android", native_speech_android)))]
pub(crate) fn error_kind_from_code(code: i32) -> SpeechErrorKind {
match code {
codes::ERROR_PERMISSION => SpeechErrorKind::PermissionDenied,
codes::ERROR_UNAVAILABLE => SpeechErrorKind::Unavailable,
codes::ERROR_LANGUAGE => SpeechErrorKind::Language,
codes::ERROR_AUDIO => SpeechErrorKind::Audio,
_ => SpeechErrorKind::Other,
}
}
type Callback = Arc<dyn Fn(NativeSpeechEvent) + Send + Sync>;
static SESSIONS: OnceLock<Mutex<HashMap<u64, Callback>>> = OnceLock::new();
static NEXT_SESSION: AtomicU64 = AtomicU64::new(1);
fn sessions() -> &'static Mutex<HashMap<u64, Callback>> {
SESSIONS.get_or_init(|| Mutex::new(HashMap::new()))
}
pub struct NativeSpeechSession {
id: u64,
}
pub fn engine_name() -> &'static str {
backend::ENGINE
}
impl NativeSpeechSession {
pub fn is_supported() -> bool {
backend::is_supported()
}
pub fn start(
options: NativeSpeechOptions,
callback: impl Fn(NativeSpeechEvent) + Send + Sync + 'static,
) -> Result<Self, SpeechError> {
if !Self::is_supported() {
return Err(SpeechError::new(
SpeechErrorKind::Unavailable,
"Native speech recognition is not available on this platform.",
));
}
if options.locale.as_ref().is_some_and(|locale| locale.contains('\0')) {
return Err(SpeechError::new(
SpeechErrorKind::Language,
"The speech recognition language is invalid.",
));
}
let id = NEXT_SESSION.fetch_add(1, Ordering::Relaxed);
{
let mut sessions = sessions().lock().unwrap();
if !sessions.is_empty() {
return Err(SpeechError::new(
SpeechErrorKind::Busy,
"Another speech recording is already active.",
));
}
sessions.insert(id, Arc::new(callback));
}
if let Err(error) = backend::start(id, &options) {
sessions().lock().unwrap().remove(&id);
return Err(error);
}
Ok(Self { id })
}
pub fn stop(&self) {
backend::stop(self.id, false);
}
pub fn cancel(&self) {
sessions().lock().unwrap().remove(&self.id);
backend::stop(self.id, true);
}
}
impl Drop for NativeSpeechSession {
fn drop(&mut self) {
self.cancel();
}
}
pub fn cancel_all() {
let ids: Vec<_> = sessions().lock().unwrap().drain().map(|(id, _)| id).collect();
for id in ids {
backend::stop(id, true);
}
}
#[cfg(any(test, target_os = "macos", target_os = "ios", all(target_os = "android", native_speech_android), target_os = "windows"))]
pub(crate) fn emit(id: u64, event: NativeSpeechEvent) {
let callback = {
let mut sessions = sessions().lock().unwrap();
if matches!(event, NativeSpeechEvent::Stopped | NativeSpeechEvent::Error(_)) {
sessions.remove(&id)
} else {
sessions.get(&id).cloned()
}
};
if let Some(callback) = callback {
let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| callback(event)));
}
}
#[cfg(not(any(target_os = "macos", target_os = "ios", all(target_os = "android", native_speech_android), target_os = "windows")))]
mod backend {
use super::{NativeSpeechOptions, SpeechError, SpeechErrorKind};
pub(super) const ENGINE: &str = "none";
pub(super) fn is_supported() -> bool { false }
pub(super) fn start(_: u64, _: &NativeSpeechOptions) -> Result<(), SpeechError> {
Err(SpeechError::new(
SpeechErrorKind::Unavailable,
"Native speech recognition is not available on this platform.",
))
}
pub(super) fn stop(_: u64, _: bool) {}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn terminal_and_cancelled_sessions_discard_late_native_results() {
let received = Arc::new(Mutex::new(Vec::new()));
let output = received.clone();
sessions().lock().unwrap().insert(1001, Arc::new(move |event| {
output.lock().unwrap().push(event);
}));
emit(1001, NativeSpeechEvent::Transcript { text: "draft".into(), is_final: false });
emit(1001, NativeSpeechEvent::Stopped);
emit(1001, NativeSpeechEvent::Transcript { text: "stale".into(), is_final: true });
assert_eq!(*received.lock().unwrap(), vec![
NativeSpeechEvent::Transcript { text: "draft".into(), is_final: false },
NativeSpeechEvent::Stopped,
]);
let output = received.clone();
sessions().lock().unwrap().insert(1002, Arc::new(move |event| {
output.lock().unwrap().push(event);
}));
emit(1001, NativeSpeechEvent::Error(SpeechError::new(SpeechErrorKind::Other, "late failure")));
NativeSpeechSession { id: 1002 }.cancel();
emit(1002, NativeSpeechEvent::Started);
assert_eq!(received.lock().unwrap().len(), 2);
let sessions = sessions().lock().unwrap();
assert!(!sessions.contains_key(&1001));
assert!(!sessions.contains_key(&1002));
}
}