@pie-players/pie-tts 0.3.43 → 0.3.45

package/README.md

@@ -2,6 +2,9 @@
 
 TTS interfaces and types for PIE Assessment Toolkit - Pure TypeScript with no UI dependencies.
 
+For the cross-package TTS architecture, provider layering, and server/client
+runtime flow, see [TTS Architecture](../../docs/accessibility/tts-architecture.md).
+
 ## Purpose
 
 This package provides the foundational interfaces and types for building TTS (Text-to-Speech) providers in the PIE ecosystem. It has **zero dependencies** and no UI framework requirements, making it suitable for:

package/dist/index.d.ts

@@ -5,4 +5,3 @@
  * No UI dependencies - pure TypeScript interfaces.
  */
 export type { ITTSProvider, ITTSProviderImplementation, StandardTTSConfig, TTSSpeechSegment, TTSConfig, TTSConfigExtensions, TTSFeature, TTSProviderCapabilities, } from "./provider-interface.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG","sourcesContent":["/**\n * @pie-players/pie-tts-core\n *\n * Core TTS interfaces and types for PIE Assessment Toolkit.\n * No UI dependencies - pure TypeScript interfaces.\n */\n\nexport type {\n\tITTSProvider,\n\tITTSProviderImplementation,\n\tStandardTTSConfig,\n\tTTSSpeechSegment,\n\tTTSConfig,\n\tTTSConfigExtensions,\n\tTTSFeature,\n\tTTSProviderCapabilities,\n} from \"./provider-interface.js\";\n"]}

package/dist/provider-interface.d.ts

@@ -66,6 +66,11 @@ export interface TTSConfigExtensions {
      * @example { engine: 'neural' } for AWS Polly
      */
     providerOptions?: Record<string, unknown>;
+    /**
+     * Internal read-along hint used by the assessment toolkit to choose between
+     * per-token math highlighting and expression-level math highlighting.
+     */
+    mathTokenHighlighting?: boolean;
 }
 /**
  * Complete TTS configuration combining standard parameters and extensions.
@@ -211,6 +216,19 @@ export interface TTSProviderCapabilities {
      * Supports pitch control
      */
     supportsPitchControl: boolean;
+    /**
+     * Supports SSML markup (W3C SSML 1.1) in the text passed to `speak`.
+     *
+     * When `true`, callers may pass an SSML document (e.g. `<speak>…</speak>`)
+     * and the provider will voice the markup rather than read the tags aloud.
+     * When `false` or omitted, callers must pass plain text — the browser Web
+     * Speech API, for example, speaks tags literally.
+     *
+     * Treat a missing value as `false`.
+     *
+     * @standard W3C SSML 1.1
+     */
+    supportsSSML?: boolean;
     /**
      * Maximum text length (if limited)
      */
@@ -220,4 +238,3 @@ export interface TTSProviderCapabilities {
  * TTS features for capability checking
  */
 export type TTSFeature = "pause" | "resume" | "wordBoundary" | "voiceSelection" | "rateControl" | "pitchControl";
-//# sourceMappingURL=provider-interface.d.ts.map

package/dist/provider-interface.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider-interface.js","sourceRoot":"","sources":["../src/provider-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}
+{"version":3,"file":"provider-interface.js","sourceRoot":"","sources":["../src/provider-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG","sourcesContent":["/**\n * TTS Provider Interfaces\n *\n * Defines the contract for text-to-speech providers.\n * Providers are stateless factories that create configured TTS implementations.\n *\n * Part of PIE TTS Core - No UI dependencies.\n */\n\n/**\n * Standard TTS configuration parameters based on W3C Web Speech API.\n *\n * These are portable across all TTS providers (browser, AWS Polly, Google Cloud, etc.)\n * and align with the W3C Web Speech API specification.\n *\n * @see https://w3c.github.io/speech-api/\n */\nexport interface StandardTTSConfig {\n\t/**\n\t * Voice identifier (provider-specific)\n\t *\n\t * @standard W3C Web Speech API (concept)\n\t * @example \"Joanna\" (Polly), \"en-US-Standard-A\" (Google), browser voice name\n\t */\n\tvoice?: string;\n\n\t/**\n\t * Speech rate (speed multiplier)\n\t *\n\t * @standard W3C Web Speech API\n\t * @range 0.25 to 4.0\n\t * @default 1.0\n\t */\n\trate?: number;\n\n\t/**\n\t * Pitch adjustment\n\t *\n\t * @standard W3C Web Speech API\n\t * @range 0 to 2 (as multiplier)\n\t * @default 1.0\n\t */\n\tpitch?: number;\n}\n\n/**\n * Provider-specific extensions for TTS configuration.\n *\n * These are NOT part of W3C standards and support varies by provider.\n */\nexport interface TTSConfigExtensions {\n\t/**\n\t * Organization/tenant identifier\n\t *\n\t * @extension Application-specific\n\t * @use Multi-tenant applications\n\t */\n\torganizationId?: string;\n\n\t/**\n\t * Provider region or endpoint\n\t *\n\t * @extension Provider-specific\n\t * @example \"us-east-1\" (AWS), \"us-central1\" (Google Cloud)\n\t */\n\tregion?: string;\n\n\t/**\n\t * Arbitrary provider-specific options\n\t *\n\t * @extension Extensibility point\n\t * @example { engine: 'neural' } for AWS Polly\n\t */\n\tproviderOptions?: Record<string, unknown>;\n\n\t/**\n\t * Internal read-along hint used by the assessment toolkit to choose between\n\t * per-token math highlighting and expression-level math highlighting.\n\t */\n\tmathTokenHighlighting?: boolean;\n}\n\n/**\n * Complete TTS configuration combining standard parameters and extensions.\n *\n * @example Basic usage (portable)\n * ```typescript\n * const config: TTSConfig = {\n *   voice: \"Joanna\",\n *   rate: 1.0,\n *   pitch: 1.0\n * };\n * ```\n *\n * @example Advanced usage with extensions\n * ```typescript\n * const config: TTSConfig = {\n *   voice: \"Joanna\",\n *   rate: 1.0,\n *   // Extensions\n *   region: \"us-east-1\",\n *   organizationId: \"acme-corp\",\n *   providerOptions: { engine: \"neural\" }\n * };\n * ```\n */\nexport interface TTSConfig extends StandardTTSConfig, TTSConfigExtensions {}\n\n/**\n * TTS Provider interface\n *\n * Providers are stateless factories that create TTS implementations.\n * They describe capabilities and create configured instances.\n */\nexport interface ITTSProvider {\n\t/**\n\t * Unique identifier for this provider\n\t */\n\treadonly providerId: string;\n\n\t/**\n\t * Human-readable provider name\n\t */\n\treadonly providerName: string;\n\n\t/**\n\t * Provider version\n\t */\n\treadonly version: string;\n\n\t/**\n\t * Initialize and create a configured TTS implementation\n\t */\n\tinitialize(config: TTSConfig): Promise<ITTSProviderImplementation>;\n\n\t/**\n\t * Check if a specific feature is supported\n\t */\n\tsupportsFeature(feature: TTSFeature): boolean;\n\n\t/**\n\t * Get provider capabilities\n\t */\n\tgetCapabilities(): TTSProviderCapabilities;\n\n\t/**\n\t * Clean up provider resources\n\t */\n\tdestroy(): void;\n}\n\n/**\n * TTS Provider Implementation interface\n *\n * The actual TTS implementation that handles playback.\n * Created by ITTSProvider.initialize()\n */\nexport interface ITTSProviderImplementation {\n\t/**\n\t * Speak text\n\t */\n\tspeak(text: string): Promise<void>;\n\n\t/**\n\t * Speak pre-segmented text with optional pause metadata.\n\t *\n\t * Providers that support this can preserve segment boundaries\n\t * while still emitting word boundaries in global offsets.\n\t */\n\tspeakSegments?(segments: TTSSpeechSegment[]): Promise<void>;\n\n\t/**\n\t * Pause playback\n\t */\n\tpause(): void;\n\n\t/**\n\t * Resume playback\n\t */\n\tresume(): void;\n\n\t/**\n\t * Stop playback\n\t */\n\tstop(): void;\n\n\t/**\n\t * Check if currently playing\n\t */\n\tisPlaying(): boolean;\n\n\t/**\n\t * Check if paused\n\t */\n\tisPaused(): boolean;\n\n\t/**\n\t * Word boundary callback (optional)\n\t * Called during speech for word highlighting\n\t */\n\tonWordBoundary?: (word: string, position: number, length?: number) => void;\n}\n\n/**\n * Pre-segmented speech unit with global offsets.\n */\nexport interface TTSSpeechSegment {\n\ttext: string;\n\tstartOffset: number;\n\tpauseMsAfter?: number;\n}\n\n/**\n * TTS Provider capabilities\n *\n * Describes which features a provider supports\n */\nexport interface TTSProviderCapabilities {\n\t/**\n\t * Supports pause/resume\n\t */\n\tsupportsPause: boolean;\n\n\t/**\n\t * Supports resume after pause\n\t */\n\tsupportsResume: boolean;\n\n\t/**\n\t * Supports word boundary events for highlighting\n\t */\n\tsupportsWordBoundary: boolean;\n\n\t/**\n\t * Supports voice selection\n\t */\n\tsupportsVoiceSelection: boolean;\n\n\t/**\n\t * Supports rate control (speed)\n\t */\n\tsupportsRateControl: boolean;\n\n\t/**\n\t * Supports pitch control\n\t */\n\tsupportsPitchControl: boolean;\n\n\t/**\n\t * Supports SSML markup (W3C SSML 1.1) in the text passed to `speak`.\n\t *\n\t * When `true`, callers may pass an SSML document (e.g. `<speak>…</speak>`)\n\t * and the provider will voice the markup rather than read the tags aloud.\n\t * When `false` or omitted, callers must pass plain text — the browser Web\n\t * Speech API, for example, speaks tags literally.\n\t *\n\t * Treat a missing value as `false`.\n\t *\n\t * @standard W3C SSML 1.1\n\t */\n\tsupportsSSML?: boolean;\n\n\t/**\n\t * Maximum text length (if limited)\n\t */\n\tmaxTextLength?: number;\n}\n\n/**\n * TTS features for capability checking\n */\nexport type TTSFeature =\n\t| \"pause\"\n\t| \"resume\"\n\t| \"wordBoundary\"\n\t| \"voiceSelection\"\n\t| \"rateControl\"\n\t| \"pitchControl\";\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-tts",
-	"version": "0.3.43",
+	"version": "0.3.45",
 	"author": "PIE Framework",
 	"repository": {
 		"type": "git",

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACX,YAAY,EACZ,0BAA0B,EAC1B,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,mBAAmB,EACnB,UAAU,EACV,uBAAuB,GACvB,MAAM,yBAAyB,CAAC"}

package/dist/provider-interface.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"provider-interface.d.ts","sourceRoot":"","sources":["../src/provider-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,SAAU,SAAQ,iBAAiB,EAAE,mBAAmB;CAAG;AAE5E;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAEnE;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;IAE9C;;OAEG;IACH,eAAe,IAAI,uBAAuB,CAAC;IAE3C;;OAEG;IACH,OAAO,IAAI,IAAI,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IAC1C;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;;;;OAKG;IACH,aAAa,CAAC,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5D;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;OAEG;IACH,MAAM,IAAI,IAAI,CAAC;IAEf;;OAEG;IACH,IAAI,IAAI,IAAI,CAAC;IAEb;;OAEG;IACH,SAAS,IAAI,OAAO,CAAC;IAErB;;OAEG;IACH,QAAQ,IAAI,OAAO,CAAC;IAEpB;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3E;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACvC;;OAEG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,cAAc,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAE9B;;OAEG;IACH,sBAAsB,EAAE,OAAO,CAAC;IAEhC;;OAEG;IACH,mBAAmB,EAAE,OAAO,CAAC;IAE7B;;OAEG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAE9B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GACnB,OAAO,GACP,QAAQ,GACR,cAAc,GACd,gBAAgB,GAChB,aAAa,GACb,cAAc,CAAC"}