@pie-players/pie-tts 0.1.0

package/README.md

@@ -0,0 +1,111 @@
+# @pie-players/pie-tts
+
+TTS interfaces and types for PIE Assessment Toolkit - Pure TypeScript with no UI dependencies.
+
+## 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:
+
+- Implementing custom TTS providers
+- Type-safe TTS integration
+- Framework-agnostic TTS solutions
+
+## What's Included
+
+### Interfaces
+
+- **`ITTSProvider`** - Stateless factory for creating TTS implementations
+- **`ITTSProviderImplementation`** - Actual TTS playback implementation
+- **`TTSProviderCapabilities`** - Feature support description
+- **`TTSConfig`** - Provider configuration
+
+### Types
+
+- **`TTSFeature`** - Union type of supported features
+- Configuration and capability types
+
+## Installation
+
+```bash
+npm install @pie-players/pie-tts
+# or
+bun add @pie-players/pie-tts
+```
+
+## Usage
+
+### Implementing a Custom TTS Provider
+
+```typescript
+import type {
+  ITTSProvider,
+  ITTSProviderImplementation,
+  TTSConfig,
+  TTSProviderCapabilities,
+  TTSFeature
+} from '@pie-players/pie-tts';
+
+class MyTTSImplementation implements ITTSProviderImplementation {
+  async speak(text: string): Promise<void> {
+    // Your implementation
+  }
+
+  pause(): void { /* ... */ }
+  resume(): void { /* ... */ }
+  stop(): void { /* ... */ }
+  isPlaying(): boolean { return false; }
+  isPaused(): boolean { return false; }
+}
+
+export class MyTTSProvider implements ITTSProvider {
+  readonly providerId = 'my-tts';
+  readonly providerName = 'My TTS Provider';
+  readonly version = '1.0.0';
+
+  async initialize(config: TTSConfig): Promise<ITTSProviderImplementation> {
+    return new MyTTSImplementation(config);
+  }
+
+  supportsFeature(feature: TTSFeature): boolean {
+    return feature === 'pause' || feature === 'resume';
+  }
+
+  getCapabilities(): TTSProviderCapabilities {
+    return {
+      supportsPause: true,
+      supportsResume: true,
+      supportsWordBoundary: false,
+      supportsVoiceSelection: true,
+      supportsRateControl: true,
+      supportsPitchControl: false,
+    };
+  }
+
+  destroy(): void {
+    // Cleanup if needed
+  }
+}
+```
+
+## Official Implementations
+
+- **Browser TTS** (in `@pie-players/pie-assessment-toolkit`) - Uses Web Speech API, always available as fallback
+- **AWS Polly** (`@pie-players/pie-tts-polly`) - High-quality neural voices with full SSML support
+
+## Design Philosophy
+
+This core package intentionally:
+- ✅ Has **zero runtime dependencies**
+- ✅ Contains **only TypeScript interfaces and types**
+- ✅ Is **framework-agnostic** (no React, Svelte, Vue, etc.)
+- ✅ Supports **pluggable architecture**
+- ✅ Enables **type-safe TTS implementations**
+
+## License
+
+MIT
+
+## Related Packages
+
+- [@pie-players/pie-assessment-toolkit](../assessment-toolkit) - Includes TTSService and BrowserTTSProvider
+- [@pie-players/pie-tts-polly](../tts-polly) - AWS Polly TTS provider

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @pie-players/pie-tts-core
+ *
+ * Core TTS interfaces and types for PIE Assessment Toolkit.
+ * No UI dependencies - pure TypeScript interfaces.
+ */
+export type { ITTSProvider, ITTSProviderImplementation, StandardTTSConfig, TTSConfig, TTSConfigExtensions, TTSFeature, TTSProviderCapabilities, } from "./provider-interface";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * @pie-players/pie-tts-core
+ *
+ * Core TTS interfaces and types for PIE Assessment Toolkit.
+ * No UI dependencies - pure TypeScript interfaces.
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/provider-interface.d.ts

@@ -0,0 +1,208 @@
+/**
+ * TTS Provider Interfaces
+ *
+ * Defines the contract for text-to-speech providers.
+ * Providers are stateless factories that create configured TTS implementations.
+ *
+ * Part of PIE TTS Core - No UI dependencies.
+ */
+/**
+ * Standard TTS configuration parameters based on W3C Web Speech API.
+ *
+ * These are portable across all TTS providers (browser, AWS Polly, Google Cloud, etc.)
+ * and align with the W3C Web Speech API specification.
+ *
+ * @see https://w3c.github.io/speech-api/
+ */
+export interface StandardTTSConfig {
+    /**
+     * Voice identifier (provider-specific)
+     *
+     * @standard W3C Web Speech API (concept)
+     * @example "Joanna" (Polly), "en-US-Standard-A" (Google), browser voice name
+     */
+    voice?: string;
+    /**
+     * Speech rate (speed multiplier)
+     *
+     * @standard W3C Web Speech API
+     * @range 0.25 to 4.0
+     * @default 1.0
+     */
+    rate?: number;
+    /**
+     * Pitch adjustment
+     *
+     * @standard W3C Web Speech API
+     * @range 0 to 2 (as multiplier)
+     * @default 1.0
+     */
+    pitch?: number;
+}
+/**
+ * Provider-specific extensions for TTS configuration.
+ *
+ * These are NOT part of W3C standards and support varies by provider.
+ */
+export interface TTSConfigExtensions {
+    /**
+     * Organization/tenant identifier
+     *
+     * @extension Application-specific
+     * @use Multi-tenant applications
+     */
+    organizationId?: string;
+    /**
+     * Provider region or endpoint
+     *
+     * @extension Provider-specific
+     * @example "us-east-1" (AWS), "us-central1" (Google Cloud)
+     */
+    region?: string;
+    /**
+     * Arbitrary provider-specific options
+     *
+     * @extension Extensibility point
+     * @example { engine: 'neural' } for AWS Polly
+     */
+    providerOptions?: Record<string, unknown>;
+}
+/**
+ * Complete TTS configuration combining standard parameters and extensions.
+ *
+ * @example Basic usage (portable)
+ * ```typescript
+ * const config: TTSConfig = {
+ *   voice: "Joanna",
+ *   rate: 1.0,
+ *   pitch: 1.0
+ * };
+ * ```
+ *
+ * @example Advanced usage with extensions
+ * ```typescript
+ * const config: TTSConfig = {
+ *   voice: "Joanna",
+ *   rate: 1.0,
+ *   // Extensions
+ *   region: "us-east-1",
+ *   organizationId: "acme-corp",
+ *   providerOptions: { engine: "neural" }
+ * };
+ * ```
+ */
+export interface TTSConfig extends StandardTTSConfig, TTSConfigExtensions {
+}
+/**
+ * TTS Provider interface
+ *
+ * Providers are stateless factories that create TTS implementations.
+ * They describe capabilities and create configured instances.
+ */
+export interface ITTSProvider {
+    /**
+     * Unique identifier for this provider
+     */
+    readonly providerId: string;
+    /**
+     * Human-readable provider name
+     */
+    readonly providerName: string;
+    /**
+     * Provider version
+     */
+    readonly version: string;
+    /**
+     * Initialize and create a configured TTS implementation
+     */
+    initialize(config: TTSConfig): Promise<ITTSProviderImplementation>;
+    /**
+     * Check if a specific feature is supported
+     */
+    supportsFeature(feature: TTSFeature): boolean;
+    /**
+     * Get provider capabilities
+     */
+    getCapabilities(): TTSProviderCapabilities;
+    /**
+     * Clean up provider resources
+     */
+    destroy(): void;
+}
+/**
+ * TTS Provider Implementation interface
+ *
+ * The actual TTS implementation that handles playback.
+ * Created by ITTSProvider.initialize()
+ */
+export interface ITTSProviderImplementation {
+    /**
+     * Speak text
+     */
+    speak(text: string): Promise<void>;
+    /**
+     * Pause playback
+     */
+    pause(): void;
+    /**
+     * Resume playback
+     */
+    resume(): void;
+    /**
+     * Stop playback
+     */
+    stop(): void;
+    /**
+     * Check if currently playing
+     */
+    isPlaying(): boolean;
+    /**
+     * Check if paused
+     */
+    isPaused(): boolean;
+    /**
+     * Word boundary callback (optional)
+     * Called during speech for word highlighting
+     */
+    onWordBoundary?: (word: string, position: number) => void;
+}
+/**
+ * TTS Provider capabilities
+ *
+ * Describes which features a provider supports
+ */
+export interface TTSProviderCapabilities {
+    /**
+     * Supports pause/resume
+     */
+    supportsPause: boolean;
+    /**
+     * Supports resume after pause
+     */
+    supportsResume: boolean;
+    /**
+     * Supports word boundary events for highlighting
+     */
+    supportsWordBoundary: boolean;
+    /**
+     * Supports voice selection
+     */
+    supportsVoiceSelection: boolean;
+    /**
+     * Supports rate control (speed)
+     */
+    supportsRateControl: boolean;
+    /**
+     * Supports pitch control
+     */
+    supportsPitchControl: boolean;
+    /**
+     * Maximum text length (if limited)
+     */
+    maxTextLength?: number;
+}
+/**
+ * TTS features for capability checking
+ */
+export type TTSFeature = "pause" | "resume" | "wordBoundary" | "voiceSelection" | "rateControl" | "pitchControl";
+//# sourceMappingURL=provider-interface.d.ts.map

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

@@ -0,0 +1 @@
+{"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;;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,KAAK,IAAI,CAAC;CAC1D;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"}

package/dist/provider-interface.js

@@ -0,0 +1,10 @@
+/**
+ * TTS Provider Interfaces
+ *
+ * Defines the contract for text-to-speech providers.
+ * Providers are stateless factories that create configured TTS implementations.
+ *
+ * Part of PIE TTS Core - No UI dependencies.
+ */
+export {};
+//# sourceMappingURL=provider-interface.js.map

package/dist/provider-interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-interface.js","sourceRoot":"","sources":["../src/provider-interface.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@pie-players/pie-tts",
+  "version": "0.1.0",
+  "description": "TTS interfaces and types for PIE Assessment Toolkit - No UI dependencies",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "pie",
+    "tts",
+    "text-to-speech",
+    "interfaces",
+    "accessibility"
+  ],
+  "author": "PIE Framework",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.7.2"
+  }
+}