Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

feat(mobile): add hold-to-talk voice input behind a mode flag

tony1d493aa1f2da
diff --git a/mobile/lib/phone/settings_page.dart b/mobile/lib/phone/settings_page.dart
index 3a171d139..594280306 100644
--- a/mobile/lib/phone/settings_page.dart
+++ b/mobile/lib/phone/settings_page.dart
@@ -52,6 +52,19 @@ import 'voice_language_store.dart';
///
/// What a phone adds instead is the account and the machine links, which the desktop keeps in its
/// rail footer — on a phone there is no rail, so this is the only way to reach either.
+
+/// Whether the Terminal section offers the voice language.
+///
+/// Off: the mic transcribes in whatever [voiceLanguageStore] already holds, and there is no longer
+/// anywhere in the app to change it by hand.
+///
+/// ⚠️ **That is the whole of the setting, so turning this back on is the only way back to it.**
+/// The mic's long-press used to open the same picker, and hold-to-talk took that gesture for
+/// recording (see `voice_mic_mode.dart`) — so with this off, the stored language is whatever it was
+/// last set to, or the default for a phone that never set one. [_VoiceLanguageRow] and
+/// [showVoiceLanguagePicker] are both still here and still work; nothing but this flag was changed.
+const bool _showVoiceLanguage = false;
+
class SettingsPage extends StatelessWidget {
const SettingsPage({super.key, required this.notifier, this.large = true});
@@ -124,7 +137,11 @@ class _Body extends StatelessWidget {
const SettingsCaption('Terminal'),
SettingsGroup(
children: [
- _VoiceLanguageRow(),
+ // ⚠️ Voice language is hidden, not removed — flip [_showVoiceLanguage]
+ // to bring the row back. [_VoiceLanguageRow] and the picker behind it
+ // are untouched and still work; this is the only thing that was
+ // drawing them.
+ if (_showVoiceLanguage) _VoiceLanguageRow(),
_FontRow(),
_SizeRow(),
_TerminalThemeRow(),
diff --git a/mobile/lib/phone/terminal_foot_bar.dart b/mobile/lib/phone/terminal_foot_bar.dart
index fdb684443..2c31f0372 100644
--- a/mobile/lib/phone/terminal_foot_bar.dart
+++ b/mobile/lib/phone/terminal_foot_bar.dart
@@ -12,6 +12,7 @@ import 'voice_input_controller.dart';
import 'voice_language_store.dart';
import 'voice_mic_action.dart';
import 'voice_mic_button.dart';
+import 'voice_mic_mode.dart';
/// The foot of a terminal page, one row: which computer the agent runs on,
/// whether it is still answering, and the mic.
@@ -25,7 +26,7 @@ import 'voice_mic_button.dart';
/// ⚠️ **One fixed height, whatever it says.** This row's top edge is the
/// terminal's bottom edge: a row that grew for a two-line notice, or that lost
/// its mic while a pane attached, would resize the remote shell under it.
-class TerminalFootBar extends StatelessWidget {
+class TerminalFootBar extends StatefulWidget {
const TerminalFootBar({
super.key,
required this.name,
@@ -48,10 +49,27 @@ class TerminalFootBar extends StatelessWidget {
static const double height = VoiceMicButton.extent + 4;
+ @override
+ State<TerminalFootBar> createState() => _TerminalFootBarState();
+}
+
+class _TerminalFootBarState extends State<TerminalFootBar> {
+ /// Whether a hold in progress has been dragged off the mic, so letting go
+ /// would cancel. Held here rather than read from the controller because it is
+ /// a fact about the FINGER, which no amount of voice state can answer.
+ ///
+ /// [VoiceMicMode.tapToToggle] leaves it false forever — that mode has no hold
+ /// to slide out of.
+ bool _slippedOff = false;
+
+ String get name => widget.name;
+ PhoneSummary? get status => widget.status;
+ VoiceInputController get voice => widget.voice;
+
@override
Widget build(BuildContext context) {
AppTheme.watch(context);
- final session = this.session;
+ final session = widget.session;
// Nothing to say — the machine has not loaded, the header is carrying the
// state, and there is no pane to talk to. Draw no row rather than an empty
// one holding its height open under the terminal.
@@ -59,7 +77,7 @@ class TerminalFootBar extends StatelessWidget {
return const SizedBox.shrink();
}
return SizedBox(
- height: height,
+ height: TerminalFootBar.height,
child: Padding(
padding: const EdgeInsets.only(left: 20, right: 8),
child: ListenableBuilder(
@@ -70,12 +88,19 @@ class TerminalFootBar extends StatelessWidget {
child: AnimatedSwitcher(
duration: const Duration(milliseconds: 180),
layoutBuilder: _alignStart,
- child: _voiceLine(voice) ?? _machineLine(),
+ child: _voiceLine(voice, _slippedOff) ?? _machineLine(),
),
),
if (session != null) ...[
- if ((!voice.isIdle && !voice.isSending) || voice.notice != null)
+ if (_showsDismiss) ...[
_DismissButton(onTap: voice.clear),
+ // ⚠️ **Clearance, not styling.** The mic's hit area overflows
+ // its slot by [VoiceMicButton.touchOverhang] on each side, and
+ // it is painted after this button — so without a gap at least
+ // that wide its overhang lies on top of the `×`, and a press
+ // aimed at Cancel starts a recording instead.
+ const SizedBox(width: VoiceMicButton.touchOverhang),
+ ],
_mic(context, session),
],
],
@@ -85,6 +110,35 @@ class TerminalFootBar extends StatelessWidget {
);
}
+ /// Whether the `×` beside the mic is drawn.
+ ///
+ /// ⚠️ **Never while a take is being recorded in hold-to-talk, and that is a
+ /// layout bug rather than a preference.** This `×` appears to the LEFT of the
+ /// mic, so drawing it shifts the mic sideways — and in hold mode the thumb is
+ /// pressed on the mic at exactly that moment. The button would slide out from
+ /// under the finger mid-sentence, the finger would land outside its new
+ /// bounds, and the take would read as "slid off to cancel" and be thrown away
+ /// on release.
+ ///
+ /// It is not needed there either: releasing off the button is the cancel, and
+ /// the recording cannot outlast the thumb. What remains is what the gesture
+ /// cannot reach — words held from a failed send, and notices — which is also
+ /// the only state hold mode leaves standing after the finger is up.
+ bool get _showsDismiss {
+ if (voice.notice != null) return true;
+ if (voice.isSending) return false;
+ if (micHoldsToTalk) {
+ return switch (voice.status) {
+ VoiceInputStatus.starting ||
+ VoiceInputStatus.listening ||
+ VoiceInputStatus.transcribing => false,
+ VoiceInputStatus.idle ||
+ VoiceInputStatus.unavailable => voice.transcript.isNotEmpty,
+ };
+ }
+ return !voice.isIdle;
+ }
+
Widget _machineLine() =>
_MachineLine(key: const ValueKey('machine'), name: name, status: status);
@@ -93,7 +147,18 @@ class TerminalFootBar extends StatelessWidget {
return VoiceMicButton(
face: action.face,
onPressed: action.onPressed,
- onLongPress: () => unawaited(showVoiceLanguagePicker(context)),
+ // ⚠️ No language shortcut in hold-to-talk: press-and-hold is what records
+ // there, and a picker opening out of a held mic would fire in the middle
+ // of every sentence. Settings ▸ Voice language is the way to it.
+ onLongPress: micHoldsToTalk
+ ? null
+ : () => unawaited(showVoiceLanguagePicker(context)),
+ onHoldStart: action.onHoldStart,
+ onHoldFinish: action.onHoldFinish,
+ onSlipChanged: (off) {
+ if (!mounted || off == _slippedOff) return;
+ setState(() => _slippedOff = off);
+ },
);
}
}
@@ -101,9 +166,14 @@ class TerminalFootBar extends StatelessWidget {
/// What the row's left half says instead of the machine while voice is in use —
/// a notice first, since it is the one thing here that asks to be read. Null
/// with the mic at rest.
-Widget? _voiceLine(VoiceInputController voice) {
+Widget? _voiceLine(VoiceInputController voice, bool slippedOff) {
final notice = voice.notice;
- final label = notice ?? voiceActivityLabel(voice);
+ // ⚠️ The slip outranks the notice and the activity alike. A thumb held off
+ // the button is one release away from throwing the take away, and that is the
+ // only thing on this row worth the space at that moment.
+ final label = slippedOff
+ ? 'Release to cancel'
+ : notice ?? voiceActivityLabel(voice);
if (label == null) return null;
return Text(
label,
@@ -114,7 +184,11 @@ Widget? _voiceLine(VoiceInputController voice) {
fontSize: 12,
height: 1.3,
fontWeight: FontWeight.w500,
- color: notice != null ? AppPalette.warn : AppPalette.accent,
+ // The warning colour for both things that are about to go wrong or go
+ // away, matching the mic's own fill while it is under a slipped thumb.
+ color: (slippedOff || notice != null)
+ ? AppPalette.warn
+ : AppPalette.accent,
),
);
}
@@ -185,11 +259,17 @@ class _DismissButton extends StatelessWidget {
key: const ValueKey('voice-cancel'),
behavior: HitTestBehavior.opaque,
onTap: onTap,
+ // ⚠️ **44, not [VoiceMicButton.extent], and the two parted company when
+ // the mic grew.** The mic's hit area now spills well past its own slot to
+ // give a held thumb room; this sits immediately to its left, so a target
+ // that grew alongside it would put the two in the same place and a press
+ // meant for the mic would land on Cancel. 44 is iOS's minimum and as much
+ // as this button needs — it is tapped deliberately, never held.
child: SizedBox.square(
- dimension: VoiceMicButton.extent,
+ dimension: 44,
child: Icon(
LucideIcons.x300,
- size: 16,
+ size: 17,
color: AppPalette.textSecondary,
),
),
diff --git a/mobile/lib/phone/voice_input_controller.dart b/mobile/lib/phone/voice_input_controller.dart
index cd63503b0..e46baf0e1 100644
--- a/mobile/lib/phone/voice_input_controller.dart
+++ b/mobile/lib/phone/voice_input_controller.dart
@@ -58,6 +58,16 @@ class VoiceInputController extends ChangeNotifier {
/// 25 MB; five minutes of 16 kHz mono is under 10.
static const maxTake = Duration(minutes: 5);
+ /// Under this, a take is a slip of the thumb rather than a sentence.
+ ///
+ /// ⚠️ **Push-to-talk needs this and tap-to-toggle never did.** Two taps are
+ /// hard to do inside a third of a second; a press and release is the easiest
+ /// thing in the world, and every accidental brush of the button used to go all
+ /// the way to the backend and come back empty — reported as "Didn't catch
+ /// that", which blames the speaking rather than the length. Caught here it is
+ /// silent: nothing was said, so nothing is announced.
+ static const minTake = Duration(milliseconds: 350);
+
final VoiceTranscriber transcriber;
final VoiceRecorder _recorder;
@@ -138,6 +148,63 @@ class VoiceInputController extends ChangeNotifier {
if (_status == VoiceInputStatus.listening) await _transcribeTake();
}
+ /// A push-to-talk hold has begun. Pairs with [finishHold].
+ ///
+ /// ⚠️ **Exists because a hold cannot be expressed as start-then-stop, and
+ /// trying broke hold-to-talk outright.** [startListening] takes two awaits to
+ /// reach [VoiceInputStatus.listening] — the permission check, then the
+ /// microphone actually opening, which is hundreds of milliseconds of hardware
+ /// on a real phone. A release landing inside that window found the status on
+ /// `starting` and abandoned the take, while the `startListening` still in
+ /// flight went on to open the microphone and set `listening` — a recording
+ /// nobody was holding and nothing would stop, whose audio then joined the NEXT
+ /// take. What came back was the tail of one sentence glued to the head of
+ /// another, which transcribes to nothing and reads as "Didn't catch that".
+ ///
+ /// So the hold is a fact of its own, held here, and the release is applied to
+ /// whatever state the start has reached by then — including a start that has
+ /// not finished yet, which [_holdReleased] makes it check for itself.
+ Future<void> startHold(Future<bool> Function(String text) deliver) async {
+ _holdReleased = false;
+ await startListening();
+ // Let go while the microphone was still opening: the take that just became
+ // live has no thumb on it, so it is ended and sent from here — the release
+ // could not do it itself, because at that moment there was no take to end.
+ if (_holdReleased && _status == VoiceInputStatus.listening) {
+ _holdReleased = false;
+ await submit(deliver);
+ }
+ }
+
+ /// A push-to-talk hold has ended, and what was said should be sent.
+ ///
+ /// Returns at once when the microphone is still opening — [startHold] is
+ /// mid-flight and owns the take, and this call has already recorded that the
+ /// thumb is up, which is what makes it finish and send as soon as there is
+ /// something to send.
+ Future<void> finishHold(Future<bool> Function(String text) deliver) async {
+ _holdReleased = true;
+ if (_status == VoiceInputStatus.starting) return;
+ _holdReleased = false;
+ await submit(deliver);
+ }
+
+ /// Drops a push-to-talk take without sending it — the thumb slid off the
+ /// button.
+ ///
+ /// ⚠️ Clears the flag as well, and that is not tidying: leaving it set would
+ /// let a [startHold] still in flight reach its own send branch and deliver the
+ /// very take this just threw away. [clear] bumps the take counter, so the
+ /// recording itself is already abandoned; this closes the other half.
+ void cancelHold() {
+ _holdReleased = false;
+ clear();
+ }
+
+ /// Whether the thumb has come up while a hold's [startListening] is still on
+ /// its way to `listening`. See [startHold].
+ bool _holdReleased = false;
+
/// Sends everything heard, and empties the transcript once it is sent — kept
/// when delivery fails, so nothing said has to be said twice.
///
@@ -203,6 +270,13 @@ class VoiceInputController extends ChangeNotifier {
: 'take: ${recording.length.inMilliseconds}ms '
'${recording.wav.length}B peak=${recording.peak}',
);
+ // Too short to be speech — a brushed button. Silent on purpose: there is
+ // no failure to report, and a notice would be the app talking back about
+ // something the person did not mean to do.
+ if (recording != null && recording.length < minTake) {
+ _setStatus(VoiceInputStatus.idle);
+ return false;
+ }
if (recording == null || recording.peak < silencePeak) {
_setStatus(VoiceInputStatus.idle, notice: VoiceNotice.noSound);
return false;
diff --git a/mobile/lib/phone/voice_mic_action.dart b/mobile/lib/phone/voice_mic_action.dart
index 57dacf436..0ce7b13f1 100644
--- a/mobile/lib/phone/voice_mic_action.dart
+++ b/mobile/lib/phone/voice_mic_action.dart
@@ -6,52 +6,187 @@ import 'package:harness_mobile/terminal/terminal_session.dart';
import 'voice_input_controller.dart';
import 'voice_mic_button.dart';
+import 'voice_mic_mode.dart';
-typedef VoiceMicAction = ({VoiceMicFace face, VoidCallback? onPressed});
+typedef VoiceMicAction = ({
+ VoiceMicFace face,
+ VoidCallback? onPressed,
+ VoidCallback? onHoldStart,
+ void Function({required bool cancelled})? onHoldFinish,
+});
/// What the mic shows and does for the voice input's state right now.
///
-/// ⚠️ Tapping while the microphone is still OPENING calls it off rather than
-/// sending: there is no take yet, and a send of nothing would leave the
-/// recording to start behind the person's back.
+/// Which set of callbacks comes back is decided by [voiceMicMode]: the tap mode
+/// fills `onPressed` and the hold mode fills the two hold callbacks. The face is
+/// worked out the same way for both — it describes the STATE, and only the
+/// button knows which gesture reaches it.
VoiceMicAction voiceMicAction(
VoiceInputController voice,
TerminalSession session,
-) {
+) => micHoldsToTalk ? _holdAction(voice, session) : _tapAction(voice, session);
+
+/// Tap to start, tap again to send — [VoiceMicMode.tapToToggle].
+///
+/// ⚠️ Tapping while the microphone is still OPENING calls it off rather than
+/// sending: there is no take yet, and a send of nothing would leave the
+/// recording to start behind the person's back.
+VoiceMicAction _tapAction(VoiceInputController voice, TerminalSession session) {
void send() => unawaited(voice.submit(session.sendComposerText));
final canSend = session.acceptsInput;
- if (voice.isSending) return (face: VoiceMicFace.busy, onPressed: null);
+ if (voice.isSending) return _face(VoiceMicFace.busy);
return switch (voice.status) {
- VoiceInputStatus.transcribing => (face: VoiceMicFace.busy, onPressed: null),
- VoiceInputStatus.starting => (
- face: VoiceMicFace.starting,
+ VoiceInputStatus.transcribing => _face(VoiceMicFace.busy),
+ VoiceInputStatus.starting => _face(
+ VoiceMicFace.starting,
onPressed: () => unawaited(voice.stopListening()),
),
- VoiceInputStatus.listening => (
- face: VoiceMicFace.listening,
+ VoiceInputStatus.listening => _face(
+ VoiceMicFace.listening,
onPressed: send,
),
- _ when voice.transcript.isNotEmpty => (
- face: VoiceMicFace.retry,
+ _ when voice.transcript.isNotEmpty => _face(
+ VoiceMicFace.retry,
onPressed: canSend ? send : null,
),
- VoiceInputStatus.unavailable => (
- face: VoiceMicFace.off,
+ VoiceInputStatus.unavailable => _face(
+ VoiceMicFace.off,
onPressed: () => unawaited(voice.startListening()),
),
- VoiceInputStatus.idle => (
- face: VoiceMicFace.talk,
+ VoiceInputStatus.idle => _face(
+ VoiceMicFace.talk,
onPressed: canSend ? () => unawaited(voice.startListening()) : null,
),
};
}
+/// Hold to talk, release to send — [VoiceMicMode.holdToTalk].
+///
+/// The whole cycle is one gesture, so there is no state the person can be left
+/// stranded in and nothing to press a second time. Two things follow from that,
+/// and both differ from the tap mode:
+///
+/// - **A release always ends the take**, including one that arrives while the
+/// microphone is still opening. The pair that makes that safe is
+/// [VoiceInputController.startHold] and [VoiceInputController.finishHold] —
+/// a start and a release that know about each other, rather than two calls
+/// racing over a status neither of them owns.
+/// - **Words held from a failed send are sent by holding again.** The tap mode
+/// shows an arrow for that; here the retry rides along with the next take,
+/// because `submit` sends the whole transcript and a take that transcribes to
+/// nothing still carries what was held.
+VoiceMicAction _holdAction(
+ VoiceInputController voice,
+ TerminalSession session,
+) {
+ if (voice.isSending) return _face(VoiceMicFace.busy);
+ if (voice.status == VoiceInputStatus.transcribing) {
+ return _face(VoiceMicFace.busy);
+ }
+ // Recording, or the microphone opening: the thumb is down either way, and
+ // what happens next is decided by how it comes up.
+ if (voice.status == VoiceInputStatus.starting ||
+ voice.status == VoiceInputStatus.listening) {
+ return _face(
+ voice.status == VoiceInputStatus.starting
+ ? VoiceMicFace.starting
+ : VoiceMicFace.listening,
+ onPressed: _live,
+ onHoldFinish: _release(voice, session),
+ );
+ }
+ final canSend = session.acceptsInput;
+ // Refused microphone included: holding asks for it again, the same recovery
+ // the tap mode offers, reached with the gesture this mode uses for everything.
+ // Its release goes through [_release] like every other, which is what makes a
+ // permission granted on that very prompt turn into a take that gets sent —
+ // the person is already talking by then. A refusal that stands sends nothing,
+ // because the transcript is empty and `submit` says nothing about that.
+ final refused = voice.status == VoiceInputStatus.unavailable;
+ final live = refused || canSend;
+ return _face(
+ // ⚠️ `retry` rather than `talk` when words are held, even though holding
+ // does the same thing either way: the arrow is the only thing on this row
+ // that says the last send did not land and the words are still here.
+ refused
+ ? VoiceMicFace.off
+ : voice.transcript.isNotEmpty
+ ? VoiceMicFace.retry
+ : VoiceMicFace.talk,
+ onPressed: live ? _live : null,
+ onHoldStart: live
+ ? () => unawaited(voice.startHold(session.sendComposerText))
+ : null,
+ onHoldFinish: live ? _release(voice, session) : null,
+ );
+}
+
+/// The thumb came up: the one way a hold ever ends.
+///
+/// Sliding off throws the take away, and anything held from a failed send with
+/// it — somebody who slid off to cancel means this message, not just this breath
+/// of it. Otherwise the controller sends what was said.
+///
+/// ⚠️ **[VoiceInputController.finishHold] rather than `submit`, because the
+/// release can land before there is anything to submit.** Opening the microphone
+/// takes two awaits and real hardware time, and a release inside that window
+/// used to abandon the take while the start still in flight went on to open the
+/// microphone anyway — a recording with no thumb on it, which nothing stopped
+/// and whose audio joined the next take. `finishHold` hands that case back to
+/// the start, which finishes and sends the moment it has a take to finish.
+void Function({required bool cancelled}) _release(
+ VoiceInputController voice,
+ TerminalSession session,
+) => ({required bool cancelled}) {
+ if (cancelled) {
+ voice.cancelHold();
+ return;
+ }
+ unawaited(voice.finishHold(session.sendComposerText));
+};
+
+/// Marks the button live in hold mode without giving it anything to do on tap.
+///
+/// `onPressed` is what [VoiceMicButton] reads to decide whether it is enabled at
+/// all — dimmed and deaf when null — and in hold mode the work is on the hold
+/// callbacks instead. A no-op keeps the one meaning the flag has in common
+/// across both modes.
+void _live() {}
+
+VoiceMicAction _face(
+ VoiceMicFace face, {
+ VoidCallback? onPressed,
+ VoidCallback? onHoldStart,
+ void Function({required bool cancelled})? onHoldFinish,
+}) => (
+ face: face,
+ onPressed: onPressed,
+ onHoldStart: onHoldStart,
+ onHoldFinish: onHoldFinish,
+);
+
/// What the mic is doing, in a word or two — null with it at rest.
+///
+/// In hold-to-talk the listening line says what the RELEASE will do instead of
+/// naming the state: the thumb is already down and holding, so "Listening…" is
+/// the one thing the person can see for themselves, and what happens when they
+/// let go is the thing they cannot.
String? voiceActivityLabel(VoiceInputController voice) {
if (voice.isSending) return 'Sending…';
return switch (voice.status) {
- VoiceInputStatus.starting => 'Starting…',
- VoiceInputStatus.listening => 'Listening…',
+ // ⚠️ "Wait" rather than "Starting…" in hold mode, and it is the difference
+ // between working and not. Opening the microphone is real hardware time, and
+ // somebody holding a button starts talking the instant they press it — so
+ // the first word lands before anything is recording and the take comes back
+ // as half a sentence that transcribes to nothing. The line has to ASK them
+ // to wait, and the buzz when [VoiceInputStatus.listening] arrives is what
+ // tells them to go.
+ VoiceInputStatus.starting =>
+ micHoldsToTalk ? 'Opening the mic — wait for the buzz' : 'Starting…',
+ VoiceInputStatus.listening =>
+ micHoldsToTalk
+ ? 'Listening… release to send, slide off to cancel'
+ : 'Listening…',
VoiceInputStatus.transcribing => 'Transcribing…',
VoiceInputStatus.idle || VoiceInputStatus.unavailable => null,
};
diff --git a/mobile/lib/phone/voice_mic_button.dart b/mobile/lib/phone/voice_mic_button.dart
index 4b0f2aca4..f1bd58e1e 100644
--- a/mobile/lib/phone/voice_mic_button.dart
+++ b/mobile/lib/phone/voice_mic_button.dart
@@ -5,6 +5,8 @@ import 'package:lucide_icons_flutter/lucide_icons.dart';
import 'package:harness_mobile/shared/theme/app_theme.dart';
import 'package:harness_mobile/shared/widgets/pulse.dart';
+import 'voice_mic_mode.dart';
+
/// What the mic says it will do when tapped.
enum VoiceMicFace {
/// At rest: tap to talk.
@@ -24,91 +26,311 @@ enum VoiceMicFace {
/// The microphone was refused: tap to ask again.
off,
+
+ /// Recording with the thumb dragged off the button — letting go now throws
+ /// the take away. [VoiceMicMode.holdToTalk] only.
+ ///
+ /// Its own face rather than a flag on [listening] because it is the opposite
+ /// promise: the ring stops breathing, the fill goes to the warning colour and
+ /// the glyph becomes a `×`. What is about to happen has to be readable at a
+ /// glance, by someone whose thumb is covering the button.
+ cancelling,
}
/// The one voice control on a terminal page — a small round button at the foot
/// of the page, beside the machine it is talking to.
///
-/// Talk and send are the same tap, walkie-talkie style: tap to start, tap again
-/// to finish the sentence and send it. The face changes to say which tap is
-/// next — a mic, then an arrow.
+/// Two ways to work it, chosen by [voiceMicMode] and nothing else:
+///
+/// - [VoiceMicMode.tapToToggle] — tap to start, tap again to finish the
+/// sentence and send it. The face says which tap is next: a mic, then an
+/// arrow. Long-press is the language shortcut.
+/// - [VoiceMicMode.holdToTalk] — the recording lasts exactly as long as the
+/// thumb is down, and letting go sends. Sliding off the button first throws
+/// the take away, and the face turns to a `×` to say so. No long-press:
+/// that gesture is what records.
///
/// ⚠️ **The swell is painted, never laid out.** The breathing ring scales past
/// the button's box with [Clip.none] rather than growing it: this button's row
/// sits under the terminal, and a row whose height moved with the animation
/// would resize the remote shell every frame.
-class VoiceMicButton extends StatelessWidget {
+class VoiceMicButton extends StatefulWidget {
const VoiceMicButton({
super.key,
required this.face,
required this.onPressed,
this.onLongPress,
+ this.onHoldStart,
+ this.onHoldFinish,
+ this.onSlipChanged,
});
final VoiceMicFace face;
/// Null draws the button dimmed and dead.
+ ///
+ /// In [VoiceMicMode.holdToTalk] this still decides whether the button is live
+ /// — a terminal that is not taking input must not record — but it is the hold
+ /// callbacks below that do the work.
final VoidCallback? onPressed;
/// The language picker — a shortcut to the Settings row, for someone who
- /// talks in two languages.
+ /// talks in two languages. Null in [VoiceMicMode.holdToTalk], whose press and
+ /// hold belong to the recording.
final VoidCallback? onLongPress;
- /// The tap target: iOS's 44pt minimum, around a smaller mark.
- static const double extent = 44;
- static const double _core = 32;
+ /// The thumb went down: start recording. [VoiceMicMode.holdToTalk] only.
+ final VoidCallback? onHoldStart;
+
+ /// The thumb came up. `cancelled` is true when it was dragged off the button
+ /// first, which throws the take away instead of sending it.
+ final void Function({required bool cancelled})? onHoldFinish;
+
+ /// The thumb crossed in or out of the button mid-hold, so the row beside it
+ /// can say what letting go will now do.
+ ///
+ /// The button's own face already turns to a `×`, but the thumb is ON the
+ /// button and covering most of it — the words to the left are what somebody
+ /// can actually read at that moment.
+ final ValueChanged<bool>? onSlipChanged;
+
+ /// The space this button takes in the row, and with it the row's height.
+ ///
+ /// ⚠️ **Raising this makes the terminal shorter, so it is not the knob to
+ /// reach for when the target feels small.** `TerminalFootBar.height` is
+ /// derived from it, and that row's top edge is the terminal's bottom edge —
+ /// every point added here is a point taken off the remote shell, which is then
+ /// resized. [touchExtent] is the one that grew instead: it widens what the
+ /// finger can hit without costing the terminal anything.
+ static const double extent = 52;
+
+ /// What the finger may actually land on.
+ ///
+ /// ⚠️ **Deliberately LARGER than [extent], and drawn outside the row's
+ /// bounds.** Hold-to-talk asks for a press held through a whole sentence, so
+ /// the target has to forgive a thumb that shifts while somebody talks — but
+ /// the row cannot grow to hold a bigger one without shortening the terminal.
+ /// An [OverflowBox] resolves the two: the hit area reaches up over the
+ /// terminal's last line and down towards the home indicator, neither of which
+ /// has anything tappable to collide with, while the row keeps its height.
+ static const double touchExtent = 76;
+
+ /// How far the hit area spills past its slot on each side.
+ ///
+ /// What anything placed beside this button has to clear: the overhang is
+ /// painted over its neighbour and would swallow the neighbour's presses. See
+ /// the gap before the mic in `terminal_foot_bar.dart`.
+ static const double touchOverhang = (touchExtent - extent) / 2;
+
+ /// The visible circle.
+ static const double _core = 40;
+
+ /// How far past [touchExtent] the thumb may stray and still count as "on" the
+ /// button.
+ ///
+ /// ⚠️ Generous on purpose — a thumb resting on the circle covers most of it,
+ /// and the finger's reported point wanders by several points while somebody
+ /// talks. Cancelling is meant to be a deliberate move away, not something a
+ /// steady hand trips over mid-sentence.
+ static const double _slipMargin = 32;
+
+ @override
+ State<VoiceMicButton> createState() => _VoiceMicButtonState();
+}
+
+class _VoiceMicButtonState extends State<VoiceMicButton> {
+ /// Whether the thumb is currently outside the button, with a hold in
+ /// progress. Drives the [VoiceMicFace.cancelling] face.
+ bool _slippedOff = false;
+
+ bool get _live => widget.onPressed != null;
- bool get _lit => switch (face) {
+ /// What to draw: the face given, unless a hold has been dragged off the
+ /// button, which only this widget knows about.
+ VoiceMicFace get _face => _slippedOff && widget.face == VoiceMicFace.listening
+ ? VoiceMicFace.cancelling
+ : widget.face;
+
+ bool get _lit => switch (_face) {
VoiceMicFace.starting ||
VoiceMicFace.listening ||
+ VoiceMicFace.cancelling ||
VoiceMicFace.retry => true,
VoiceMicFace.talk || VoiceMicFace.busy || VoiceMicFace.off => false,
};
- String get _semanticLabel => switch (face) {
- VoiceMicFace.talk => 'Talk to the agent',
+ String get _semanticLabel => switch (_face) {
+ VoiceMicFace.talk =>
+ micHoldsToTalk ? 'Hold to talk to the agent' : 'Talk to the agent',
VoiceMicFace.starting => 'Cancel',
- VoiceMicFace.listening => 'Send what was said',
+ VoiceMicFace.listening =>
+ micHoldsToTalk ? 'Release to send' : 'Send what was said',
+ VoiceMicFace.cancelling => 'Release to cancel',
VoiceMicFace.busy => 'Working',
VoiceMicFace.retry => 'Send again',
VoiceMicFace.off => 'Voice input is off',
};
+ /// Whether [point], in the hit area's own coordinates, still counts as on the
+ /// button.
+ ///
+ /// Measured against [VoiceMicButton.touchExtent] — the box the [Listener]
+ /// actually covers — rather than the row slot, because that is the box the
+ /// pointer's `localPosition` is reported in.
+ bool _within(Offset point) {
+ const extent = VoiceMicButton.touchExtent;
+ const margin = VoiceMicButton._slipMargin;
+ return point.dx >= -margin &&
+ point.dy >= -margin &&
+ point.dx <= extent + margin &&
+ point.dy <= extent + margin;
+ }
+
+ void _onPointerDown(PointerDownEvent event) {
+ if (!_live) return;
+ _setSlipped(false);
+ HapticFeedback.lightImpact();
+ widget.onHoldStart?.call();
+ }
+
+ void _onPointerMove(PointerMoveEvent event) {
+ if (!_live || widget.onHoldFinish == null) return;
+ final off = !_within(event.localPosition);
+ if (off == _slippedOff) return;
+ // Felt as well as seen: the thumb is over the button, so the change of
+ // meaning has to reach the hand that cannot see it.
+ HapticFeedback.selectionClick();
+ _setSlipped(off);
+ }
+
+ void _onPointerUp(PointerUpEvent event) {
+ if (widget.onHoldFinish == null) return;
+ final cancelled = _slippedOff;
+ _setSlipped(false);
+ widget.onHoldFinish!(cancelled: cancelled);
+ }
+
+ /// The gesture was taken over by something else — a scroll that won the
+ /// arena, the app going away. Treated as a cancel: a take nobody ended
+ /// deliberately must not be sent.
+ void _onPointerCancel(PointerCancelEvent event) {
+ if (widget.onHoldFinish == null) return;
+ _setSlipped(false);
+ widget.onHoldFinish!(cancelled: true);
+ }
+
+ /// ⚠️ Tells the row BEFORE rebuilding itself. The listener sits in an ancestor
+ /// that rebuilds this button, so calling it inside `setState` would report the
+ /// change from the middle of a build.
+ void _setSlipped(bool value) {
+ if (value == _slippedOff) return;
+ _slippedOff = value;
+ widget.onSlipChanged?.call(value);
+ if (mounted) setState(() {});
+ }
+
+ /// ⚠️ **The buzz that says "the microphone is open — talk now", and
+ /// hold-to-talk does not work without it.** Opening the microphone is real
+ /// hardware time, and a thumb that has just pressed a button is a thumb whose
+ /// owner has already started the sentence: those first words land before
+ /// anything is recording, and what reaches the backend is half a sentence that
+ /// transcribes to nothing. The row asks them to wait; this is what releases
+ /// them, felt rather than read, because their thumb is over the button and
+ /// their eyes are not necessarily on the screen.
+ ///
+ /// Only on the way IN to listening, and only while holding — the tap mode's
+ /// own press already told them the take had begun.
+ @override
+ void didUpdateWidget(VoiceMicButton old) {
+ super.didUpdateWidget(old);
+ if (!micHoldsToTalk) return;
+ if (old.face != VoiceMicFace.listening &&
+ widget.face == VoiceMicFace.listening) {
+ HapticFeedback.mediumImpact();
+ }
+ }
+
@override
Widget build(BuildContext context) {
AppTheme.watch(context);
- final live = onPressed != null;
return Semantics(
button: true,
- enabled: live,
+ enabled: _live,
label: _semanticLabel,
- onLongPressHint: onLongPress == null ? null : 'Choose language',
- child: GestureDetector(
+ onLongPressHint: widget.onLongPress == null ? null : 'Choose language',
+ // ⚠️ **The slot is [VoiceMicButton.extent]; the hit area inside it is the
+ // larger [VoiceMicButton.touchExtent], spilling out on every side.** The
+ // [OverflowBox] is what allows a child bigger than its parent without the
+ // parent growing — so the row, and the terminal above it, keep their
+ // heights while the finger gets a target half again as wide.
+ //
+ // `Clip.none` on the stack matters for the same reason: the ring already
+ // paints past the core, and clipping to the slot would cut both it and
+ // the overflowing hit area back to nothing.
+ child: SizedBox.square(
+ dimension: VoiceMicButton.extent,
+ child: OverflowBox(
+ maxWidth: VoiceMicButton.touchExtent,
+ maxHeight: VoiceMicButton.touchExtent,
+ child: _gestures(
+ child: SizedBox.square(
+ dimension: VoiceMicButton.touchExtent,
+ child: AnimatedOpacity(
+ duration: const Duration(milliseconds: 160),
+ opacity: _live ? 1 : 0.4,
+ child: Stack(
+ alignment: Alignment.center,
+ clipBehavior: Clip.none,
+ children: [
+ // ⚠️ Not while cancelling: the ring means "listening, carry
+ // on talking", and leaving it breathing under a `×` would
+ // say both things at once.
+ if (_face == VoiceMicFace.listening) const _Ring(),
+ _Core(face: _face, lit: _lit),
+ ],
+ ),
+ ),
+ ),
+ ),
+ ),
+ ),
+ );
+ }
+
+ /// ⚠️ **A [Listener], not a [GestureDetector], and the difference is what
+ /// makes hold-to-talk work at all.** A gesture detector's long-press only
+ /// fires after the press delay, and reports a drag off the button as the
+ /// press being cancelled — so recording would start a beat late and end the
+ /// moment the thumb wandered. Raw pointer events start the take on the frame
+ /// the finger lands and keep reporting while it moves, which is what lets the
+ /// button tell "still talking" from "slid off to cancel".
+ ///
+ /// The tap mode keeps its [GestureDetector]: there is nothing to track
+ /// between the two taps, and it comes with the tap-cancel semantics that mode
+ /// wants.
+ Widget _gestures({required Widget child}) {
+ if (!micHoldsToTalk) {
+ return GestureDetector(
key: const ValueKey('voice-mic'),
behavior: HitTestBehavior.opaque,
- onTap: live
+ onTap: _live
? () {
HapticFeedback.lightImpact();
- onPressed!();
+ widget.onPressed!();
}
: null,
- onLongPress: onLongPress,
- child: SizedBox.square(
- dimension: extent,
- child: AnimatedOpacity(
- duration: const Duration(milliseconds: 160),
- opacity: live ? 1 : 0.4,
- child: Stack(
- alignment: Alignment.center,
- clipBehavior: Clip.none,
- children: [
- if (face == VoiceMicFace.listening) const _Ring(),
- _Core(face: face, lit: _lit),
- ],
- ),
- ),
- ),
- ),
+ onLongPress: widget.onLongPress,
+ child: child,
+ );
+ }
+ return Listener(
+ key: const ValueKey('voice-mic'),
+ behavior: HitTestBehavior.opaque,
+ onPointerDown: _onPointerDown,
+ onPointerMove: _onPointerMove,
+ onPointerUp: _onPointerUp,
+ onPointerCancel: _onPointerCancel,
+ child: child,
);
}
}
@@ -119,6 +341,12 @@ class _Core extends StatelessWidget {
final VoiceMicFace face;
final bool lit;
+ /// The fill's hue. Cancelling takes the warning colour: the button is about
+ /// to throw away what was just said, and that is not something the accent —
+ /// which everywhere else in the app means "go" — should be saying.
+ Color get _tint =>
+ face == VoiceMicFace.cancelling ? AppPalette.warn : AppPalette.accent;
+
@override
Widget build(BuildContext context) => AnimatedContainer(
duration: const Duration(milliseconds: 220),
@@ -131,10 +359,7 @@ class _Core extends StatelessWidget {
? LinearGradient(
begin: Alignment.topLeft,
end: Alignment.bottomRight,
- colors: [
- Color.lerp(AppPalette.accent, Colors.white, 0.18)!,
- AppPalette.accent,
- ],
+ colors: [Color.lerp(_tint, Colors.white, 0.18)!, _tint],
)
: null,
color: lit ? null : AppGlass.surfaceFill,
@@ -142,12 +367,7 @@ class _Core extends StatelessWidget {
color: lit ? Colors.white.withValues(alpha: 0.28) : AppGlass.lift,
),
boxShadow: lit
- ? [
- BoxShadow(
- color: AppPalette.accent.withValues(alpha: 0.4),
- blurRadius: 12,
- ),
- ]
+ ? [BoxShadow(color: _tint.withValues(alpha: 0.4), blurRadius: 12)]
: null,
),
child: Center(
@@ -169,22 +389,29 @@ class _Glyph extends StatelessWidget {
Widget build(BuildContext context) {
if (face == VoiceMicFace.busy) {
return SizedBox.square(
- dimension: 14,
+ dimension: 18,
child: CircularProgressIndicator(
- strokeWidth: 1.8,
+ strokeWidth: 2.2,
color: AppPalette.accent,
),
);
}
return Icon(
switch (face) {
- VoiceMicFace.listening || VoiceMicFace.retry => LucideIcons.arrowUp300,
+ // ⚠️ In hold-to-talk the arrow would be a lie: nothing is sent by
+ // pressing this, it is sent by letting go. The mic stays up for the
+ // whole take and the thumb never leaves it, so there is no second press
+ // for an arrow to describe.
+ VoiceMicFace.listening =>
+ micHoldsToTalk ? LucideIcons.mic300 : LucideIcons.arrowUp300,
+ VoiceMicFace.retry => LucideIcons.arrowUp300,
+ VoiceMicFace.cancelling => LucideIcons.x300,
VoiceMicFace.off => LucideIcons.micOff300,
VoiceMicFace.talk ||
VoiceMicFace.starting ||
VoiceMicFace.busy => LucideIcons.mic300,
},
- size: 16,
+ size: 21,
color: lit
? Colors.white
: face == VoiceMicFace.off
diff --git a/mobile/lib/phone/voice_mic_mode.dart b/mobile/lib/phone/voice_mic_mode.dart
new file mode 100644
index 000000000..b952f7eb7
--- /dev/null
+++ b/mobile/lib/phone/voice_mic_mode.dart
@@ -0,0 +1,37 @@
+/// How the mic is worked: tap it twice, or hold it down.
+///
+/// Two shapes for the same act, kept side by side behind [voiceMicMode] so the
+/// choice can be changed back without rebuilding anything around it. Every
+/// difference between them is decided from this enum — the gesture the button
+/// listens for, the faces it can show, and what a release does — and nothing
+/// else in the app branches on it.
+enum VoiceMicMode {
+ /// Tap to start, tap again to send. Walkie-talkie: the button holds the
+ /// recording open with nothing held down, so a long sentence costs no thumb.
+ ///
+ /// Long-press stays the language shortcut here, because nothing else wants it.
+ tapToToggle,
+
+ /// Hold to talk, release to send. Push-to-talk: the recording lives exactly as
+ /// long as the thumb is down, and letting go sends what was said.
+ ///
+ /// Sliding off the button before letting go throws the take away instead —
+ /// the gesture every phone messenger uses, and the only way out of a take
+ /// begun by accident.
+ ///
+ /// ⚠️ The language shortcut is GONE in this mode: the gesture it used is the
+ /// gesture that now records. Settings ▸ Voice language is the way to it.
+ holdToTalk,
+}
+
+/// Which of the two the app is built with.
+///
+/// ⚠️ **A compile-time constant on purpose, not a setting.** This is here to
+/// make the second shape easy to try, not to ask the person which one they
+/// want — a preference would mean a Settings row, a stored value, and two
+/// behaviours live at once in a button whose whole job is to be unambiguous
+/// under the thumb. Change this line, rebuild, and the app is the other app.
+const VoiceMicMode voiceMicMode = VoiceMicMode.holdToTalk;
+
+/// Whether the mic records only while held down.
+bool get micHoldsToTalk => voiceMicMode == VoiceMicMode.holdToTalk;