Scope#
WS08-004 implements first-class voice consistency profile contracts for audio
voice workflows, including speaker embedding controls, pronunciation lexicon
controls, and style token controls with provider-capability-aware runtime
application.
Research and Existing Implementation Alignment#
Before implementation, existing ISIS patterns were reviewed in:
- Existing provider fields and API contracts:
libs/isis/ai-providers/src/types/tts.types.tslibs/isis/ai-providers/src/providers/tts/elevenlabs-provider.ts
- Existing voice profile and pronunciation system primitives:
libs/isis/audio-generation/src/voice/elevenlabs-client.tslibs/isis/ai-providers/src/providers/conversational-ai/pronunciation-dictionary
- Existing generation-api normalization/capability-guard patterns:
apps/isis/generation-api/src/workflows/executor.tsapps/isis/generation-api/src/schemas/job.schema.ts
These references were used to align new contracts with current ISIS naming and provider behavior (voice IDs, pronunciation dictionary locators, and consistency-related voice controls).
Deliverables#
- Typed API and SDK contracts
- Added
voiceConsistency/voice_consistencyrequest contracts across:apps/isis/generation-api/src/types.tslibs/isis/client/src/types.ts
- Added typed fields for:
- profile identifiers and voice/speaker IDs
- speaker embedding ID/URL/vector and reference audio URLs
- pronunciation lexicon IDs and dictionary locators
- style tokens and consistency strength
- provider capability mode and prompt-preservation policy
- Validation support in generation API
- Added
JobVoiceConsistencyRequestSchemainapps/isis/generation-api/src/schemas/job.schema.ts. - Added strict validation for URL fields, embedding vector bounds, enum values, and numeric ranges.
- Added schema regression tests for valid and invalid payloads.
- Workflow capability exposure
- Extended
voice-performance-synthesisworkflow inputs with explicit voice consistency controls:voice_consistency_profile_id,voice_idspeaker_embedding_id,speaker_embedding_url,speaker_embedding_vector,speaker_reference_audio_urlspronunciation_lexicon_ids,pronunciation_dictionary_locatorsstyle_tokens,voice_consistency_strength,voice_consistency_provider_mode
- Runtime normalization, mapping, and diagnostics
- Added canonical request normalization for
voiceConsistencypayloads. - Added capability-aware input mapping to workflow inputs.
- Added provider capability guard behavior:
providerCapabilityMode: "required"blocks application when workflow does not expose voice consistency inputs.
- Added execution diagnostics at
output.metadata.voiceConsistencywith:- support/blocking status
- requested embedding/lexicon/style token counts
- supported and used workflow input keys
- Regression coverage
- Added executor regression coverage validating voice consistency contract
application and diagnostics for
voice-performance-synthesisworkflow runs.
Verification Commands#
bash
pnpm --filter @isis/workflows exec vitest run src/workflows.spec.ts --reporter=dot
pnpm --filter @isis/generation-api exec vitest run src/schemas/job.schema.spec.ts src/workflows/executor.spec.ts --reporter=dot
Result#
WS08-004 is now implemented as a typed, validated, and runtime-enforced voice
consistency profile system, with first-class support for speaker embeddings,
pronunciation lexicons, and style token controls in ISIS audio voice workflows.