Repository navigation
fix(voice): name the cause when read aloud fails - #22545
Conversation
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Every item traces to the defect reported in #17511. Catching the client-fallback code keeps the behaviour the base already had, where What this change shipsInventory (7 items) — 7 justifiedIntent: A user whose Polly voice or engine isn't offered in their region learns that and knows to change Voice, Engine or Region. FIX.
[FIRST-PRINCIPLES-REVIEWED] f5b01c5 Description read[DESCRIPTION-READ] 6758b7b1a7e52df1922a3eb78b050819db502833e351999b4f91b7bd98b2b19c That sha256 names the PR description this verdict read. Recompute it with |
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing blocks: the one new notice appears in all four screenshots, and the blind reader understood it as the specific reason Read aloud failed. Notes
[UX-REVIEWED] f5b01c5 Description read[DESCRIPTION-READ] c1a03e1da1e977d35616f017c6d329d367f1bd68c61e469e8b1202869de67225 That sha256 names everything this verdict read: the PR description, plus the 7 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the narrow, single-cause classifier is proportionate, unknown codes still fall through to the generic notice, and the change reverts cleanly. Notes
[DESIGN-REVIEWED] f5b01c5 Description read[DESCRIPTION-READ] 272eecd2ccdbf58eeb06769c67d5d115ee4a6b3948261ce874ee8077febbd622 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
2f99189 to
3aa7587
Compare
|
Rebased: main moved 5c17469 -> dea18bc (feat(crew) #21748 edited the same i18n locale files); also ran black on test/test_voice_reply_pipeline.py and test/test_chat_voice.py, which Backend Lint flagged on the prior head. Diff is otherwise unchanged (our two voicePlaybackNotice keys preserved in every catalog); CI re-running. |
4487095 to
bb411b8
Compare
efd09d2 to
db42ea2
Compare
|
self-added: no
|
|
self-added: no
|
|
self-added: no
|
|
self-added: no
|
|
self-added: no
|
db42ea2 to
b27d68d
Compare
|
self-added: no
|
|
self-added: no
|
|
self-added: no
|
|
self-added: no
|
|
self-added: no
|
60b2624 to
877c8db
Compare
|
The |
877c8db to
8d463db
Compare
|
self-added: yes
|
|
The |
8d463db to
a6e1338
Compare
Read aloud showed one generic "Read aloud failed" notice for every failure, so the user could not tell which setting to change. #17680 fixed the Polly consent mismatch; the Polly engine/region rejection #17511 reports still fell through to the generic notice. An Amazon Polly request AWS rejected (an engine a region does not support) returned no audio for every sentence and ended in the generic notice. _synthesize_polly now raises voice_polly_rejected at the first rejection on the person-waiting path (streaming_voice_reply) instead of being retried once per sentence; the notice names the rejection and points at the engine/region settings. _classify_polly_failure matches only that one failure from the CLI stderr, because it is the only AWS failure whose fix is the action the notice names and the only one that repeats for every sentence. A credential/access error or a sentence-scoped SSML error keeps the None/skip-per-sentence path and the generic notice. The AWS message can echo the request text, so it stays in the gateway log and the notice text is fixed. Unattended callers keep the text fallback. The notice string is added to every locale catalog; unknown codes keep the generic sentence. Fixes #17511
a6e1338 to
f5b01c5
Compare
|
self-added: yes
|
iamwhatever
left a comment
There was a problem hiding this comment.
APPROVE, reviewed at f5b01c5.
The fix is narrow and fails safe. Only the engine/region-unsupported Polly rejection becomes voice_polly_rejected, and only on the dashboard path (voice_reply.py#L1133-L1151). The raised text is fixed, so no AWS stderr reaches the UI. Every other failure keeps the skip-per-sentence path. The client-speech fallback still works for the new code (voicePlayback.ts#L107). All AI lanes pass on this head, CI is green, and there are no change requests.
AI findings judged non-blocking
- UX (note): the notice says "Region" while the settings field reads "AWS Region (Amazon Polly)". This is a wording nit, and the field is still easy to find. en.manual.json#L1637
- Design (note 1): when the fallback is allowed, the webview speaks the reply and no notice is shown. This matches the existing
voice_unavailablebehaviour and is stated in the PR. chat_voice.py#L73 - Design (note 2): the classifier matches on stderr text. If AWS rewords the message, the result is the pre-PR generic notice, so nothing gets worse. voice_reply.py#L961-L989
Tests were read and CI results checked; nothing was run locally.
— crew-pr-reviewer (r141)
Problem / Motivation
Goal: Read aloud names the cause and the one action that fixes it when Amazon Polly rejects the chosen voice or engine in the selected region, instead of showing the generic failure sentence.
Read aloud showed one notice — "Read aloud failed. Check the Text-to-speech settings and try again." — for every way synthesis could fail. The cause was only in the gateway log, so the user could not tell which setting to change. #17680 fixed the Amazon Polly consent mismatch; the Polly engine/region rejection #17511 reports still fell through to the generic notice.
Why it matters
A user whose Polly voice or engine is not offered in their region hits the same generic notice every time and cannot tell that the fix is a different Voice, Engine, or Region — they end up guessing.
Not a goal
voice_unavailableand the desktop client speaks the reply with its own engine; a surface that cannot keeps the generic notice. (An earlier draft added a dedicated no-engine notice, butvoice_unavailableis also raised when a Polly or registered provider returns no audio, so a notice keyed on it would name the wrong remedy for those users. Dropped.)What changed (motivation → approach → change)
An Amazon Polly request AWS rejected returned no audio for every sentence and ended in the generic notice, because
_synthesize_pollyreturnedNoneand the sentence stream skipped on and failed the same way. On the dashboard path — the one with a person waiting — it now matches the one failure #17511 reports (_classify_polly_failure): the chosen voice or engine is not offered in the region, which AWS rejects identically for every sentence. That one raisesvoice_polly_rejectedat the first sentence, whose notice names the voice/engine/region fix. It is the only AWS failure turned into a raise, because it is the only one whose fix is the action the notice names and the only one that repeats for every sentence; a credential/access error or a sentence-scoped SSML error keeps the oldNone/skip path and the generic notice, which is the honest answer when "change the voice, engine or region" would not help. Unattended callers (Slack, Telegram) keep the text fallback. A manual Read aloud that allows the client-speech fallback still speaks the reply with the webview's own engine on this code, as it did onvoice_unavailable, because that engine does not depend on the AWS region.The change lands in
src/kiro_crew/voice_reply.py(the narrow engine/region classifier and the raisedvoice_polly_rejectedcode),src/kiro_crew/dashboard/chat_voice.pyandwebsite/src/hooks/websocket/voicePlayback.ts(the code joinsvoice_unavailableas a client-fallback code, so its payloads carryspeakable),website/src/lib/voiceFailure.ts(the code→notice mapping), thewebsite/src/i18nlocale catalogs (the one notice string in all 13 shipped catalogs plus the pseudolocale),docs(thevoice-streaming.mdmodule spec), and awebsite/captureharness for the screenshots. The code maps to its own localized notice; an unknown code still shows the generic sentence.Backwards compatibility
Compatible: the Polly path gains one new raised code,
voice_polly_rejected, consumed byvoiceFailureMessage()and the client-speech fallback, both updated in lockstep; any unmapped code falls through to the existing generic notice. The no-enginevoice_unavailablebehaviour and unattended callers'Nonereturn and text fallback are unchanged.Removes nothing: no path, record, key or public function is hidden, deleted or narrowed; the change adds the
voice_polly_rejectedcode and its notice.Tests
test_voice_reply_synthesis.py:_synthesize_pollyraisesvoice_polly_rejectedon the engine/region-unsupported stderr with fixed text (no AWS stderr) whenraise_refusal=True; a credential error and an unfamiliar failure both returnNone(skip-per-sentence); the unattended path returnsNone.test_voice_reply_pipeline.py:streaming_voice_replylets the rejection propagate and stops at the first sentence rather than retrying per sentence.test_chat_voice.py: the synthesize endpoint answers 502 withvoice_polly_rejected(consent granted, AWS rejects on engine/region), carrying the fixed notice text with no secrets and thespeakabletext for the client fallback.clientSpeechFallback.test.tsx: a fallback-allowed Read aloud that hitsvoice_polly_rejectedspeaks on the client and raises no notice.Proof: PROVEN test_polly_aws_rejection_reaches_the_client_with_its_code and the clientSpeechFallback voice_polly_rejected case fail with the chat_voice.py / voicePlayback.ts fallback hunks reverted (head f5b01c5)
VoicePlaybackNotice.test.tsx: the notice renders the Polly-rejection copy forvoice_polly_rejected(not the generic "Read aloud failed").Manual verification
Captured the real
VoicePlaybackNoticefor the generic failure (before) and the Polly rejection (after) in light and dark via an isolated Vite capture harness (capture/read-aloud-failure-notice.*), asserting the expected sentence is on screen before each shot.Screenshots / video
Before — the generic notice shown for every failure (light):
After — Amazon Polly does not offer the voice/engine in the region (dark):
Both causes (light + dark)
Related Issues
Fixes #17511
Pattern harvest
Rule candidate: review-prompt
Pattern: a user-facing failure notice keyed on an error code must have a distinct code per actionable cause, and the code must be raised ONLY for the causes whose remedy its sentence names — a notice keyed on a code that several unrelated causes share (here
voice_unavailable, raised for both a missing engine and a provider returning no audio) names the wrong remedy for the other causes.Checklist