add-tts-provider

name	add-tts-provider
description	Add a new TTS provider to @aituber-onair/voice and wire it through engine implementation, public voice option types, internal engine handlers, factory registration, tests, docs, examples, and optional versioning updates. Use when requests include adding a TTS engine, supporting a voice provider or speech service, adding <provider> TTS, or updating supported voice providers.

Add TTS Provider

Overview

Add a new TTS provider for @aituber-onair/voice while preserving the current public API shape and usage style.

Before adding any provider as first-class support, read docs/agent-model-provider-guidelines.md. A provider/model is not eligible for public support unless the exact speech endpoint, request body, response shape, and user configuration path are documented or live-verified.

Inputs

Collect missing inputs before editing:

• engine_type: public engine id string (example: acmeTts)
• engine_class_name: engine class name (example: AcmeTtsEngine)
• display_name: user-facing provider name (example: Acme TTS)
• provider_kind: local or cloud
• default_speaker: default speaker or voice id example
• requires_api_key: boolean
• supports_emotion: boolean
• option_fields: provider-specific public option fields to add under VoiceServiceOptions
• default_api_url: optional default endpoint for local or overridable services
• examples_scope: optional, one of docs-only, react-only, or all-examples; default react-only
• bump_version: boolean, default false; set true only when the user explicitly requests release/version work
• next_version: optional explicit target version

Procedure

1. Run preflight checks:
   • Read docs/agent-model-provider-guidelines.md and classify the candidate as recommended/default, supported/explicit, exported deprecated compatibility, or candidate-only.
   • Search for existing candidate notes or research notes: rg "<engine_type>|<provider>|candidate|research|notes" docs skills .claude. Treat any matches as non-authoritative until official docs or live API behavior re-confirm them.
   • rg "<engine_type>|<engine_class_name>" packages/voice
   • Inspect current provider patterns in:
     • packages/voice/CONTRIBUTING.md
     • packages/voice/src/services/VoiceService.ts
     • packages/voice/src/services/internal/engineHandlers/
     • packages/voice/src/engines/
   • If the provider already partially exists, switch to gap-fix mode.
2. Preserve public API rules:
   • Do not introduce a nested config format.
   • Follow the existing VoiceServiceOptions top-level naming style.
   • Keep VoiceEngineAdapter public usage unchanged.
   • Keep existing public engine exports and methods backward compatible.
   • If adding support for an OpenAI-compatible endpoint would change the behavior of the existing openai provider, add a new provider instead of mutating openai.
3. Add engine implementation:
   • Confirm the provider's official docs or live API behavior for the exact speech endpoint, request body, audio response format, and voice-list endpoint when applicable.
   • Do not add a first-class engine based only on a model/provider marketing page or a global model list.
   • If any hard gate in docs/agent-model-provider-guidelines.md fails, keep the provider as candidate-only and do not add engine/type/factory/example support.
   • Create packages/voice/src/engines/<engine_class_name>.ts.
   • Implement VoiceEngine.
   • Reuse shared helpers from packages/voice/src/engines/internal/ and packages/voice/src/utils/ for URL building, decoding, clamping, WAV creation, and fetch timeout behavior.
   • Prefer explicit setter methods only when the provider needs runtime overrides.
   • If the provider has a default endpoint, add a constant in packages/voice/src/constants/voiceEngine.ts.

References

• For touchpoints and naming patterns, read: skills/add-tts-provider/references/voice-provider-touchpoints.md

Verification Commands

Run commands from repository root:

npm -w @aituber-onair/voice run fmt
npm -w @aituber-onair/voice run lint
npm -w @aituber-onair/voice run test
npm -w @aituber-onair/voice run build
rg "<engine_type>|<engine_class_name>" packages/voice

Acceptance Criteria

• New provider has a concrete engine implementation.
• Official docs or live API behavior confirm the exact speech endpoint, request body, response shape, and user configuration path.
• VoiceEngineType includes the new engine id.
• VoiceServiceOptions supports the new provider without changing existing public usage patterns.
• An internal engine handler exists and is registered.
• VoiceEngineFactory.getEngine() supports the new provider.
• Adapter tests cover provider option application and updateOptions().
• English and Japanese README mention the provider.
• Examples are updated for the requested scope.
• Final notes include the model/provider decision record from docs/agent-model-provider-guidelines.md.
• Version and changelog are updated when bump_version is true.
• Package verification commands pass.