tts-error-reporting_skill

Overview

This skill defines a convention for reporting errors from multiprocessing TTS workers back to the main process so frontend users receive Toast notifications instead of silent failures. It targets TTS workers in tts_client.py and prescribes a strict response_queue tuple format for error propagation. Use it to make connection errors, quota limits, and API faults visible and actionable in the UI.

How this skill works

TTS workers catch exceptions and send a structured error payload to the main process via response_queue.put(("__error__", error_msg)). core.py's tts_response_handler listens for that tuple, converts it into a WebSocket status message, and the frontend displays a localized Toast alert. Workers should embed JSON error objects (code + details) when possible so the frontend can map to i18n messages.

When to use it

• When adding a new TTS worker function in tts_client.js/python that runs in a separate process.
• When handling network errors, connection drops, or WebSocket on_error callbacks inside a worker.
• When an API returns quota, rate-limit, or auth errors that should show to the user.
• When debugging silent TTS hangs where the UI remains stuck on a ‘Preparing…’ state.
• When converting raw provider errors into standardized frontend-friendly messages.

Best practices

• Always accept a response_queue parameter in worker signatures and use it on all exception paths.
• Send a tuple exactly as ("__error__", error_payload_string) to ensure tts_response_handler recognizes it.
• Prefer JSON payloads with a code and details, e.g. {"code":"API_QUOTA_TIME","details":"..."}, for i18n mapping.
• Log the original exception locally, then also push a sanitized error string to the response queue.
• Provide a fallback code (e.g. API_1008_FALLBACK) if the error type cannot be mapped to a known code.

Example use cases

• Wrap WebSocket on_error callback to json.dumps({code:'API_1008_FALLBACK',msg:message}) and put to response_queue.
• Catch provider-specific quota exceptions and send {code:'API_QUOTA_TIME',details:err} so the UI shows a quota Toast.
• During initialization failures send an immediate __error__ message to avoid leaving the UI in a loading state.
• Add response_queue notifications in retry loops so final failures surface instead of silent worker death.