Files
pipelines/app/lib/features/chat/speech/speech_engine.dart
T
alan 3164b7c8df Prefer natural voices for read aloud
Rank platform voice quality and select the most natural automatic voice while keeping explicit voice choices intact. Surface natural labels, hide novelty voices in the picker, and guide Apple users to download enhanced voices when needed.
2026-11-13 15:59:35 +00:00

133 lines
4.4 KiB
Dart

import 'package:flutter/foundation.dart';
/// One platform voice. [locale] is a BCP 47 tag such as `en-GB`.
@immutable
class SpeechVoice {
const SpeechVoice({
required this.name,
required this.locale,
this.qualityRank = 0,
this.networkRequired = false,
});
final String name;
final String locale;
/// A platform-independent quality score: 0 is unknown/compact and 3 is
/// premium, very high, or a browser's natural voice.
final int qualityRank;
final bool networkRequired;
/// The primary language subtag (`en` for `en-GB`), lower case.
String get language => locale.split(RegExp('[-_]')).first.toLowerCase();
bool get isNatural => qualityRank >= 2;
bool get isNovelty => _noveltyVoice.hasMatch(name);
/// Converts the maps returned by flutter_tts on Apple, Android, and web.
factory SpeechVoice.fromPlatform(Map<Object?, Object?> raw) {
final name = '${raw['name'] ?? ''}';
final locale = '${raw['locale'] ?? ''}';
final quality = '${raw['quality'] ?? ''}'.toLowerCase();
final identifier = '${raw['identifier'] ?? ''}'.toLowerCase();
final network = '${raw['network_required'] ?? ''}'.toLowerCase();
var rank = switch (quality) {
'3' => 3,
'2' => 2,
'1' || '0' => 1,
'premium' || 'very high' || 'very_high' => 3,
'enhanced' || 'high' => 2,
'default' ||
'normal' ||
'standard' ||
'low' ||
'very low' ||
'very_low' => 1,
_ => 0,
};
if (identifier.contains('premium') ||
name.toLowerCase().contains(RegExp(r'\b(natural|online|neural)\b')) ||
name.toLowerCase().contains('google ')) {
rank = 3;
} else if (identifier.contains('enhanced')) {
rank = 2;
} else if (identifier.contains('compact')) {
rank = 1;
}
return SpeechVoice(
name: name,
locale: locale,
qualityRank: rank,
networkRequired: network == '1' || network == 'true',
);
}
@override
bool operator ==(Object other) =>
other is SpeechVoice && other.name == name && other.locale == locale;
@override
int get hashCode => Object.hash(name, locale);
}
final _noveltyVoice = RegExp(
r'\b(bells|bubbles|zarvox|whisper|boing|cellos|good news|jester|organ|superstar|trinoids)\b',
caseSensitive: false,
);
/// Picks the best automatic voice without consulting platform APIs.
SpeechVoice? bestSpeechVoice(List<SpeechVoice> voices, String language) {
final matching = voices.where(
(voice) => voice.language == language.toLowerCase(),
);
if (matching.isEmpty) return null;
final ranked = [...matching]..sort(compareSpeechVoices);
return ranked.first;
}
int compareSpeechVoices(SpeechVoice a, SpeechVoice b) {
final quality = b.qualityRank.compareTo(a.qualityRank);
if (quality != 0) return quality;
final offline = a.networkRequired ? 1 : 0;
final offlineOther = b.networkRequired ? 1 : 0;
if (offline != offlineOther) return offline.compareTo(offlineOther);
if (a.isNovelty != b.isNovelty) return a.isNovelty ? 1 : -1;
final name = a.name.compareTo(b.name);
return name != 0 ? name : a.locale.compareTo(b.locale);
}
/// The platform text-to-speech service the [SpeechController] drives.
///
/// [setRate] takes a multiplier where 1.0 is the platform's normal speed; an
/// implementation maps it onto its own scale. [onProgress] reports the word
/// being spoken as offsets into [utterance], the text the platform is actually
/// speaking (after a resume that can be a suffix of the text passed to
/// [speak]). Platforms without word boundaries never call it.
abstract class SpeechEngine {
/// Whether this platform can speak at all; the UI hides read aloud if not.
bool get supported;
/// Whether this engine can offer the Apple voice-download guidance.
///
/// This is deliberately false by default: only Apple engines have the
/// matching System Settings destination.
bool get supportsVoiceDownloadHint => false;
VoidCallback? onStart;
VoidCallback? onPause;
VoidCallback? onResume;
VoidCallback? onCompletion;
VoidCallback? onCancel;
ValueChanged<String>? onError;
void Function(String utterance, int start, int end)? onProgress;
/// Speaks [text]. Called with the same text while paused, it resumes.
Future<void> speak(String text);
Future<void> pause();
Future<void> stop();
/// Selects [voice], or the platform default when null.
Future<void> setVoice(SpeechVoice? voice);
Future<void> setRate(double rate);
Future<List<SpeechVoice>> voices();
}