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.
This commit is contained in:
2026-11-13 15:59:35 +00:00
parent eeb07e5645
commit 3164b7c8df
10 changed files with 424 additions and 35 deletions
@@ -22,6 +22,12 @@ class FlutterTtsSpeechEngine extends SpeechEngine {
TargetPlatform.linux || TargetPlatform.fuchsia => false,
};
@override
bool get supportsVoiceDownloadHint =>
!kIsWeb &&
(defaultTargetPlatform == TargetPlatform.iOS ||
defaultTargetPlatform == TargetPlatform.macOS);
/// AVSpeechSynthesizer's normal rate is 0.5 on a 0..1 scale; Android's
/// TextToSpeech and the Web Speech API use 1.0 as normal.
bool get _appleScale =>
@@ -106,7 +112,7 @@ class FlutterTtsSpeechEngine extends SpeechEngine {
return [
for (final item in raw is List ? raw : const [])
if (item is Map && item['name'] != null && item['locale'] != null)
SpeechVoice(name: '${item['name']}', locale: '${item['locale']}'),
SpeechVoice.fromPlatform(item.cast<Object?, Object?>()),
];
}
}
@@ -90,7 +90,12 @@ class SpeechController extends ChangeNotifier with WidgetsBindingObserver {
_set(SpeechState.speaking);
return _guard(() async {
await engine.setRate(_rate);
await engine.setVoice(voice);
final selected = voice ??
bestSpeechVoice(
await engine.voices(),
WidgetsBinding.instance.platformDispatcher.locale.languageCode,
);
await engine.setVoice(selected);
await engine.speak(document.text);
});
}
@@ -3,13 +3,63 @@ 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});
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) =>
@@ -19,6 +69,32 @@ class SpeechVoice {
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
@@ -30,6 +106,12 @@ 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;
@@ -23,11 +23,13 @@ class SettingsReadAloudSection extends StatefulWidget {
class _SettingsReadAloudSectionState extends State<SettingsReadAloudSection> {
SpeechController get _speech => widget.controller ?? speechController;
late final Future<List<SpeechVoice>> _voices;
@override
void initState() {
super.initState();
unawaited(_speech.restore());
_voices = _speech.voices();
}
Future<void> _pickVoice() async {
@@ -65,12 +67,13 @@ class _SettingsReadAloudSectionState extends State<SettingsReadAloudSection> {
title: const Text('Voice'),
subtitle: Text(
voice == null
? 'System default'
? 'Automatic (most natural)'
: '${voice.name} · ${voice.locale}',
),
chevron: true,
onTap: () => unawaited(_pickVoice()),
),
_voiceDownloadHint(context),
SettingsGroupItem(
child: Column(
crossAxisAlignment: CrossAxisAlignment.stretch,
@@ -131,4 +134,38 @@ class _SettingsReadAloudSectionState extends State<SettingsReadAloudSection> {
);
},
);
Widget _voiceDownloadHint(BuildContext context) {
return FutureBuilder<List<SpeechVoice>>(
future: _voices,
builder: (context, snapshot) {
if (!snapshot.hasData ||
!needsSpeechVoiceHint(
snapshot.data!,
View.of(context).platformDispatcher.locale.languageCode,
supportsVoiceDownloadHint:
_speech.engine.supportsVoiceDownloadHint,
)) {
return const SizedBox.shrink();
}
const hint =
'For a more natural voice, download one in System Settings > '
'Accessibility > Spoken Content > System voice > Manage voices.';
return SettingsGroupItem(
key: const Key('settings-read-aloud-voice-hint'),
child: Tooltip(
message: hint,
child: Text(
hint,
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: Theme.of(context).textTheme.bodySmall?.copyWith(
color: Theme.of(context).colorScheme.onSurfaceVariant,
),
),
),
);
},
);
}
}
@@ -4,6 +4,17 @@ import 'package:flutter/material.dart';
import '../chat/speech/speech.dart';
bool needsSpeechVoiceHint(
List<SpeechVoice> voices,
String language, {
bool supportsVoiceDownloadHint = false,
}) {
if (!supportsVoiceDownloadHint) return false;
return voices
.where((voice) => voice.language == language.toLowerCase())
.every((voice) => !voice.isNatural);
}
/// The picker's answer: a voice, or null for the system default.
typedef SpeechVoiceChoice = ({SpeechVoice? voice});
@@ -22,7 +33,7 @@ Future<SpeechVoiceChoice?> showSpeechVoicePicker(
}
/// Voices grouped by language subtag, the [device] language first and the
/// rest by name; voices within a group by name.
/// rest by name; natural voices and offline voices come first within a group.
List<({String language, List<SpeechVoice> voices})> groupSpeechVoices(
List<SpeechVoice> voices,
String device,
@@ -41,11 +52,7 @@ List<({String language, List<SpeechVoice> voices})> groupSpeechVoices(
for (final language in languages)
(
language: language,
voices: groups[language]!
..sort((a, b) {
final name = a.name.compareTo(b.name);
return name != 0 ? name : a.locale.compareTo(b.locale);
}),
voices: groups[language]!..sort(compareSpeechVoices),
),
];
}
@@ -113,7 +120,10 @@ class _VoicePickerDialogState extends State<_VoicePickerDialog> {
contentPadding: const EdgeInsets.symmetric(vertical: 16),
// A list needs a definite width; keep it to a readable dialog measure.
content: ConstrainedBox(
constraints: const BoxConstraints(maxWidth: 560),
constraints: BoxConstraints(
maxWidth: 560,
maxHeight: MediaQuery.sizeOf(context).height * .6,
),
child: SizedBox(
width: double.maxFinite,
child: FutureBuilder<List<SpeechVoice>>(
@@ -122,6 +132,17 @@ class _VoicePickerDialogState extends State<_VoicePickerDialog> {
if (snapshot.connectionState != ConnectionState.done) {
return const Center(child: CircularProgressIndicator());
}
if (snapshot.hasError) {
return Padding(
padding: const EdgeInsets.all(24),
child: Text(
'Voices could not be loaded. You can cancel and try again.',
style: TextStyle(
color: Theme.of(context).colorScheme.onSurfaceVariant,
),
),
);
}
final voices = snapshot.data ?? const <SpeechVoice>[];
return _list(context, groupSpeechVoices(voices, device));
},
@@ -154,9 +175,12 @@ class _VoicePickerDialogState extends State<_VoicePickerDialog> {
Navigator.of(context).pop((voice: voice));
},
child: ListView(
shrinkWrap: true,
primary: false,
children: [
const RadioListTile<String>(value: '', title: Text('System default')),
const RadioListTile<String>(
value: '',
title: Text('Automatic (most natural)'),
),
if (groups.isEmpty)
Padding(
padding: const EdgeInsets.symmetric(horizontal: 24, vertical: 8),
@@ -181,7 +205,23 @@ class _VoicePickerDialogState extends State<_VoicePickerDialog> {
Expanded(
child: RadioListTile<String>(
value: _keyOf(voice),
title: Text(voice.name),
title: Row(
children: [
Flexible(child: Text(voice.name)),
if (voice.isNatural)
Padding(
padding: const EdgeInsetsDirectional.only(
start: 8,
),
child: Text(
'Natural',
style: theme.textTheme.labelSmall?.copyWith(
color: theme.colorScheme.primary,
),
),
),
],
),
subtitle: Text(voice.locale),
),
),
@@ -4,16 +4,26 @@ import 'package:pipelines_app/features/chat/speech/speech.dart';
/// A scripted [SpeechEngine]: it records calls and a test fires the platform's
/// events. [stop] reports a cancel like every real platform does.
class FakeSpeechEngine extends SpeechEngine {
FakeSpeechEngine({this.supported = true, this.available = const []});
FakeSpeechEngine({
this.supported = true,
this.available = const [],
this.voiceDownloadHint = false,
this.voiceFailure = false,
});
@override
final bool supported;
final List<SpeechVoice> available;
final bool voiceDownloadHint;
final bool voiceFailure;
final calls = <String>[];
final spoken = <String>[];
double? rate;
SpeechVoice? voice;
@override
bool get supportsVoiceDownloadHint => voiceDownloadHint;
@override
Future<void> speak(String text) async {
calls.add('speak');
@@ -36,7 +46,10 @@ class FakeSpeechEngine extends SpeechEngine {
Future<void> setVoice(SpeechVoice? voice) async => this.voice = voice;
@override
Future<List<SpeechVoice>> voices() async => available;
Future<List<SpeechVoice>> voices() async {
if (voiceFailure) throw StateError('voice inventory failed');
return available;
}
/// Reports [word] (its first occurrence at or after [from]) being spoken.
void speakWord(String word, {int from = 0}) {
@@ -165,4 +165,37 @@ void main() {
expect(speech.rate, defaultSpeechRate);
expect(store.saved, (rate: defaultSpeechRate, voice: null));
});
testWidgets('an explicitly selected voice does not require voice inventory', (
tester,
) async {
engine = FakeSpeechEngine(voiceFailure: true);
reader();
const voice = SpeechVoice(name: 'Daniel', locale: 'en-GB');
// The saved selection is passed directly to the engine, even if querying
// the platform voice inventory is unavailable.
await speech.setVoice(voice);
await speech.read('a', ['Hello']);
expect(engine.voice, voice);
expect(engine.spoken, ['Hello']);
});
testWidgets(
'automatic voice selects the most natural device-language voice',
(tester) async {
engine = FakeSpeechEngine(
available: const [
SpeechVoice(name: 'Compact', locale: 'en-US', qualityRank: 1),
SpeechVoice(name: 'Enhanced', locale: 'en-US', qualityRank: 2),
SpeechVoice(name: 'French Natural', locale: 'fr-FR', qualityRank: 3),
],
);
reader();
await speech.read('a', ['Hello']);
expect(engine.voice?.name, 'Enhanced');
expect(speech.voice, isNull);
},
);
}
@@ -0,0 +1,59 @@
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/chat/speech/speech.dart';
void main() {
test('parses Apple quality and identifier without changing identity', () {
final voice = SpeechVoice.fromPlatform({
'name': 'Samantha',
'locale': 'en-US',
'quality': 'premium',
'identifier': 'com.apple.voice.premium.en-US.Samantha',
});
expect(voice.qualityRank, 3);
expect(voice.isNatural, isTrue);
expect(voice, const SpeechVoice(name: 'Samantha', locale: 'en-US'));
});
test('parses Android quality and prefers offline on a quality tie', () {
final online = SpeechVoice.fromPlatform({
'name': 'English online',
'locale': 'en-US',
'quality': 'very high',
'network_required': '1',
});
final offline = SpeechVoice.fromPlatform({
'name': 'English local',
'locale': 'en-US',
'quality': 'very high',
'network_required': '0',
});
expect(bestSpeechVoice([online, offline], 'en'), offline);
});
test('recognises natural web voice names', () {
final voice = SpeechVoice.fromPlatform({
'name': 'Microsoft Aria Online (Natural)',
'locale': 'en-US',
});
expect(voice.qualityRank, 3);
expect(voice.isNatural, isTrue);
});
test('picker ranking buries compact novelty voices', () {
final natural = const SpeechVoice(
name: 'Samantha Enhanced',
locale: 'en-US',
qualityRank: 2,
);
final novelty = const SpeechVoice(
name: 'Zarvox',
locale: 'en-US',
qualityRank: 1,
);
expect(compareSpeechVoices(natural, novelty), lessThan(0));
});
}
@@ -7,7 +7,11 @@ import 'package:pipelines_app/features/settings/settings_voice_picker.dart';
import '../chat/speech/fake_speech_engine.dart';
const _daniel = SpeechVoice(name: 'Daniel', locale: 'en-GB');
const _samantha = SpeechVoice(name: 'Samantha', locale: 'en-US');
const _samantha = SpeechVoice(
name: 'Samantha Enhanced',
locale: 'en-US',
qualityRank: 2,
);
const _thomas = SpeechVoice(name: 'Thomas', locale: 'fr-FR');
const _anna = SpeechVoice(name: 'Anna', locale: 'de-DE');
@@ -21,9 +25,16 @@ late FakeSpeechEngine _engine;
/// A fresh reader over [store], as after an app reload, and its section.
Future<SpeechController> _open(
WidgetTester tester,
MemorySpeechPreferences store,
) async {
_engine = FakeSpeechEngine(available: [_samantha, _thomas, _anna, _daniel]);
MemorySpeechPreferences store, {
List<SpeechVoice>? available,
bool voiceDownloadHint = false,
bool voiceFailure = false,
}) async {
_engine = FakeSpeechEngine(
available: available ?? [_samantha, _thomas, _anna, _daniel],
voiceDownloadHint: voiceDownloadHint,
voiceFailure: voiceFailure,
);
final speech = SpeechController(engine: _engine, store: store);
addTearDown(speech.dispose);
await tester.pumpWidget(
@@ -47,10 +58,11 @@ void main() {
addTearDown(tester.platformDispatcher.clearLocaleTestValue);
final store = MemorySpeechPreferences();
await _open(tester, store);
expect(find.text('System default'), findsOneWidget);
expect(find.text('Automatic (most natural)'), findsOneWidget);
await tester.tap(_voiceRow);
await tester.pumpAndSettle();
expect(find.text('Natural'), findsOneWidget);
// Grouped by language, the device's language first.
final french = tester.getTopLeft(find.text('French')).dy;
final english = tester.getTopLeft(find.text('English')).dy;
@@ -59,7 +71,7 @@ void main() {
expect(english, lessThan(german));
expect(
tester.getTopLeft(find.text('Daniel')).dy,
lessThan(tester.getTopLeft(find.text('Samantha')).dy),
greaterThan(tester.getTopLeft(find.text('Samantha Enhanced')).dy),
);
await tester.tap(find.text('Daniel'));
@@ -108,7 +120,7 @@ void main() {
expect(speech.voice, isNull);
expect(speech.rate, defaultSpeechRate);
expect(store.saved, (rate: defaultSpeechRate, voice: null));
expect(find.text('System default'), findsOneWidget);
expect(find.text('Automatic (most natural)'), findsOneWidget);
expect(find.text('Speaking rate 1.0×'), findsOneWidget);
expect(tester.widget<TextButton>(_reset).onPressed, isNull);
});
@@ -130,7 +142,7 @@ void main() {
// Each voice in the picker has its own sample; it does not choose it.
await tester.tap(_voiceRow);
await tester.pumpAndSettle();
await tester.tap(find.byTooltip('Play sample of Samantha'));
await tester.tap(find.byTooltip('Play sample of Samantha Enhanced'));
await tester.pump();
expect(_engine.voice, _samantha);
expect(_engine.spoken, hasLength(2));
@@ -140,9 +152,72 @@ void main() {
expect(speech.state, SpeechState.idle, reason: 'closing stops the sample');
});
testWidgets(
'shows the Apple download hint only for a non-natural inventory',
(tester) async {
tester.platformDispatcher.localeTestValue = const Locale('en', 'US');
addTearDown(tester.platformDispatcher.clearLocaleTestValue);
final store = MemorySpeechPreferences();
await _open(
tester,
store,
available: const [
SpeechVoice(
name: 'Samantha Compact',
locale: 'en-US',
qualityRank: 1,
),
],
voiceDownloadHint: true,
);
expect(
find.textContaining('download one in System Settings'),
findsOneWidget,
);
final hint = tester.widget<Text>(
find.descendant(
of: find.byKey(const Key('settings-read-aloud-voice-hint')),
matching: find.byType(Text),
),
);
expect(hint.maxLines, 1);
expect(
tester
.getTopLeft(find.byKey(const Key('settings-read-aloud-voice-hint')))
.dy,
greaterThan(tester.getTopLeft(_voiceRow).dy),
);
expect(
tester.getTopLeft(find.text('Speaking rate 1.0×')).dy,
greaterThan(
tester
.getTopLeft(
find.byKey(const Key('settings-read-aloud-voice-hint')),
)
.dy,
),
);
},
);
testWidgets('failed voice inventory is safe and dismissible', (tester) async {
final speech = await _open(
tester,
MemorySpeechPreferences(),
voiceFailure: true,
);
await tester.tap(_voiceRow);
await tester.pumpAndSettle();
expect(find.textContaining('Voices could not be loaded'), findsOneWidget);
expect(find.text('This device offers no other voices.'), findsNothing);
await tester.tap(find.text('Cancel'));
await tester.pumpAndSettle();
expect(speech.state, SpeechState.idle);
});
test('voices group by language, device language first', () {
final groups = groupSpeechVoices([_samantha, _anna, _daniel], 'de');
expect(groups.map((group) => group.language), ['de', 'en']);
expect(groups.last.voices, [_daniel, _samantha]);
expect(groups.last.voices, [_samantha, _daniel]);
});
}
+49 -10
View File
@@ -9,15 +9,31 @@ import 'package:pipelines_app/features/chat/speech/speech.dart';
void installSpeechFixture(Map<String, String> params) {
if (params['speech'] != 'fake') return;
final step = int.tryParse(params['speechStep'] ?? '') ?? 600;
final hint = params['speechHint'] == '1';
final empty = params['speechEmpty'] == '1';
final failure = params['speechFailure'] == '1';
debugSpeechController = SpeechController(
engine: _ScriptedSpeechEngine(Duration(milliseconds: step)),
engine: _ScriptedSpeechEngine(
Duration(milliseconds: step),
appleHint: hint,
empty: empty,
failure: failure,
),
);
}
class _ScriptedSpeechEngine extends SpeechEngine {
_ScriptedSpeechEngine(this.step);
_ScriptedSpeechEngine(
this.step, {
this.appleHint = false,
this.empty = false,
this.failure = false,
});
final Duration step;
final bool appleHint;
final bool empty;
final bool failure;
Timer? _timer;
String _text = '';
List<Match> _words = const [];
@@ -27,6 +43,9 @@ class _ScriptedSpeechEngine extends SpeechEngine {
@override
bool get supported => true;
@override
bool get supportsVoiceDownloadHint => appleHint;
@override
Future<void> speak(String text) async {
if (_paused && text == _text) {
@@ -81,12 +100,32 @@ class _ScriptedSpeechEngine extends SpeechEngine {
Future<void> setVoice(SpeechVoice? voice) async {}
@override
Future<List<SpeechVoice>> voices() async => const [
SpeechVoice(name: 'Samantha', locale: 'en-US'),
SpeechVoice(name: 'Daniel', locale: 'en-GB'),
SpeechVoice(name: 'Karen', locale: 'en-AU'),
SpeechVoice(name: 'Thomas', locale: 'fr-FR'),
SpeechVoice(name: 'Anna', locale: 'de-DE'),
SpeechVoice(name: 'Kyoko', locale: 'ja-JP'),
];
Future<List<SpeechVoice>> voices() async {
if (failure) throw StateError('fixture voice inventory failed');
if (empty) return const [];
return [
const SpeechVoice(
name: 'Samantha Compact',
locale: 'en-US',
qualityRank: 1,
),
if (!appleHint)
const SpeechVoice(
name: 'Samantha Enhanced',
locale: 'en-US',
qualityRank: 2,
),
if (!appleHint)
const SpeechVoice(
name: 'Microsoft Aria Online (Natural)',
locale: 'en-US',
qualityRank: 3,
),
const SpeechVoice(name: 'Bells', locale: 'en-US', qualityRank: 1),
const SpeechVoice(name: 'Daniel', locale: 'en-GB', qualityRank: 1),
const SpeechVoice(name: 'Thomas', locale: 'fr-FR', qualityRank: 1),
const SpeechVoice(name: 'Anna', locale: 'de-DE', qualityRank: 1),
const SpeechVoice(name: 'Kyoko', locale: 'ja-JP', qualityRank: 1),
];
}
}