shinshin86/add-tts-provider

Add TTS Provider

Overview

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

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 true
• next_version: optional explicit target version

Procedure

1. Run preflight checks:
   • rg "<engine_type>|<engine_class_name>" packages/voice
   • Inspect current provider patterns in:
     • 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:
   • Create packages/voice/src/engines/<engine_class_name>.ts.
   • Implement VoiceEngine.
   • 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.
4. Add public engine registration:
   • Update packages/voice/src/types/voiceEngine.ts.
   • Update packages/voice/src/engines/index.ts.
   • Ensure packages/voice/src/index.ts still exposes the engine via export * from './engines';.
5. Add public option types:
   • Add <engine_class_name without Engine>VoiceServiceOptions to packages/voice/src/services/VoiceService.ts.
   • Add update type alias for the provider.
   • Extend VoiceServiceOptions and VoiceServiceOptionsUpdate.
   • Follow existing field naming conventions such as <engine_type>ApiUrl, <engine_type>Speed, or provider-specific names.
   • For OpenAI-compatible providers, prefer explicit top-level fields such as <engine_type>ApiUrl, <engine_type>Model, and <engine_type>Speed instead of reusing openAi* fields.
6. Add internal handler wiring:
   • Create packages/voice/src/services/internal/engineHandlers/<engine_type>.ts.
   • Implement:
     • allowedUpdateKeys
     • applyOptions(engine, options)
     • mergeOptions(current, update)
   • Register it in packages/voice/src/services/internal/engineHandlers/index.ts.
   • Keep the logic explicit. Do not generate setter names dynamically.
7. Add factory registration:
   • Update packages/voice/src/engines/VoiceEngineFactory.ts.
8. Add tests:
   • Create packages/voice/tests/<engine_class_name>.test.ts.
   • Add adapter coverage in packages/voice/tests/VoiceEngineAdapter.test.ts.
   • If the provider changes public exports, update packages/voice/tests/index.test.ts.
   • Verify updateOptions() behavior for provider-specific fields.
9. Update docs:
   • packages/voice/README.md
   • packages/voice/README_ja.md
   • Add provider overview, sample options, and any constraints such as API key or local server requirements.
10. Update examples according to examples_scope:
    • For react-only, update packages/voice/examples/react-basic/src/App.tsx and the related example README if needed.
    • In the React example, update ENGINE_DEFAULTS, engine selector options, provider-specific controls, API key behavior, and custom API URL wiring.
    • If a provider accepts but does not require an API key, keep UI behavior explicit rather than inferring from needsApiKey alone.
    • For all-examples, also add or update Node/Bun/Deno examples and example READMEs.
    • Keep example usage aligned with the current public API style.
11. If bump_version is true, prepare release updates for @aituber-onair/voice:
    • Decide next version:
      • Use next_version if provided.
      • Otherwise use a minor bump for new provider support unless repository rules differ.
    • Update packages/voice/package.json.
    • Update packages/voice/CHANGELOG.md.
    • Update affected lockfiles when workspace metadata changes.
12. Verify:
    • Run package-level fmt, lint, test, and build.
    • If the React example changed, run its build too.
    • Grep for <engine_type> to confirm expected placements.
    • Confirm no public API usage pattern changed in README or examples.
    • If the provider has a local default endpoint, optionally try a simple curl smoke test against that endpoint when the local service is expected to be running.

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.
• 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.
• Version and changelog are updated when bump_version is true.
• Package verification commands pass.