OpenParable
Skip to content
← Back to skills

Tts Error Reporting

Development
tts-error-reporting

Tts Error Reporting is an Agent Skill for development published in the Project-N-E-K-O/N.E.K.O repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Convention for reporting errors from multiprocessing TTS workers to the main process frontend. Use this skill when modifying, adding, or debugging TTS workers in tts_client.py to ensure connection errors, quotas, and API limits correctly display Toast notifications to the user rather than failing silently.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Project-N-E-K-O/N.E.K.O/blob/HEAD/.agent/skills/tts-error-reporting/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/tts-error-reporting, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

TTS Error Reporting Protocol

To ensure users are properly notified when a TTS service encounters an error (such as quota exhaustion, API issues, or connection failures), TTS workers running in separate processes must propagate errors back to the main process (core.py).

Core Rule: Use response_queue.put(("__error__", error_msg))

When a TTS worker (e.g. step_realtime_tts_worker, qwen_realtime_tts_worker, etc.) catches an error, it MUST NOT only log the error using logger.error(). It MUST ALSO send the error message back to the main process through its response_queue using the explicit tuple format ("__error__", error_msg).

This ensures that core.py's tts_response_handler can intercept the error and translate it into a frontend WebSocket message (type: 'status'), triggering a user-friendly Toast notification (e.g., "💥 免费TTS限额已耗尽").

Example Implementation

# Bad Pattern (Fails silently for user)
except Exception as e:
    logger.error(f"TTS Worker Error: {e}")
    # Worker dies or hangs, user stuck on "Preparing..."

# Good Pattern (Structured JSON error for i18n frontend toasts)
import json
except Exception as e:
    logger.error(f"TTS Worker Error: {e}")
    # Map to specific error codes known to i18n
    error_payload = json.dumps({"code": "API_QUOTA_TIME", "details": str(e)})
    response_queue.put(("__error__", error_payload))

# Acceptable Fallback (Fallback 1008 error if code unknown)
except Exception as e:
    logger.error(f"TTS Worker Error: {e}")
    error_payload = json.dumps({"code": "API_1008_FALLBACK", "msg": str(e)})
    response_queue.put(("__error__", error_payload))

WebSocket Stream Callbacks Example

import json
def on_error(self, message: str): 
    logger.error(f"TTS Error: {message}")
    error_payload = json.dumps({"code": "API_1008_FALLBACK", "msg": message})
    self.response_queue.put(("__error__", error_payload))

Checklist for Adding a New TTS Worker

Whenever you add a new TTS API worker in tts_client.py:

  1. Ensure the worker signature accepts a response_queue.
  2. Locate all network initialization blocks, try/except loops, and on_error WebSocket callbacks.
  3. In every local exception block where the worker might fail or drop the connection, add response_queue.put(("__error__", error_message_string)).
  4. Ensure string encoding handles JSON cleanly if propagating raw API errors.