playkit-sdk 1.3.0 → 1.4.0-beta.1

package/README.md

@@ -83,6 +83,26 @@ const imgElement = await image.toHTMLImage();
 document.body.appendChild(imgElement);
 ```
 
+### Text-to-Speech (TTS)
+
+```typescript
+const tts = sdk.createTTSClient(); // defaults to 'default-tts-model'
+
+// Get raw audio bytes plus usage metadata
+const result = await tts.synthesize({
+  text: 'Welcome to the game, brave adventurer!',
+  voice: 'male-qn-qingse',
+  format: 'mp3',
+});
+console.log('Characters billed:', result.usageCharacters);
+console.log('Audio length (ms):', result.audioLengthMs);
+
+// Or get a playable object URL directly (browser)
+const url = await tts.synthesizeToObjectURL({ text: 'Hello there!' });
+const audio = new Audio(url);
+audio.play();
+```
+
 ### NPC Conversations
 
 ```typescript

package/dist/playkit-sdk.cjs.js

@@ -1,5 +1,5 @@
 /**
- * playkit-sdk v1.3.0
+ * playkit-sdk v1.4.0-beta.1
  * PlayKit SDK for JavaScript
  * @license SEE LICENSE IN LICENSE
  */
@@ -830,7 +830,7 @@ class TokenStorage {
 }
 
 const SDK_TYPE = 'Javascript';
-const SDK_VERSION = '"1.3.0"';
+const SDK_VERSION = '"1.4.0-beta.1"';
 function getSDKHeaders() {
     return {
         'X-SDK-Type': SDK_TYPE,
@@ -2426,7 +2426,7 @@ DeviceAuthFlowManager.activeInstance = null;
  * Handles JWT exchange and token management
  */
 // @ts-ignore - replaced at build time
-const DEFAULT_BASE_URL$5 = "https://api.playkit.ai";
+const DEFAULT_BASE_URL$6 = "https://api.playkit.ai";
 const JWT_EXCHANGE_ENDPOINT = '/api/external/exchange-jwt';
 const TOKEN_REFRESH_ENDPOINT = '/api/auth/refresh';
 class AuthManager extends EventEmitter {
@@ -2444,7 +2444,7 @@ class AuthManager extends EventEmitter {
         this.storage = new TokenStorage({
             mode: config.mode === 'server' ? 'server' : 'browser',
         });
-        this.baseURL = config.baseURL || DEFAULT_BASE_URL$5;
+        this.baseURL = config.baseURL || DEFAULT_BASE_URL$6;
         this.authState = {
             isAuthenticated: false,
         };
@@ -3533,7 +3533,7 @@ class RechargeManager extends EventEmitter {
  * Player client for managing player information and credits
  */
 // @ts-ignore - replaced at build time
-const DEFAULT_BASE_URL$4 = "https://api.playkit.ai";
+const DEFAULT_BASE_URL$5 = "https://api.playkit.ai";
 const PLAYER_INFO_ENDPOINT = '/api/external/player-info';
 const SET_NICKNAME_ENDPOINT = '/api/external/set-game-player-nickname';
 class PlayerClient extends EventEmitter {
@@ -3545,7 +3545,7 @@ class PlayerClient extends EventEmitter {
         this.balanceCheckInterval = null;
         this.logger = Logger.getLogger('PlayerClient');
         this.authManager = authManager;
-        this.baseURL = config.baseURL || DEFAULT_BASE_URL$4;
+        this.baseURL = config.baseURL || DEFAULT_BASE_URL$5;
         this.gameId = config.gameId;
         this.rechargeConfig = {
             autoShowBalanceModal: (_a = rechargeConfig.autoShowBalanceModal) !== null && _a !== void 0 ? _a : true,
@@ -3893,12 +3893,12 @@ function contentToString$1(content) {
     return textParts.map(part => part.text).join('');
 }
 // @ts-ignore - replaced at build time
-const DEFAULT_BASE_URL$3 = "https://api.playkit.ai";
+const DEFAULT_BASE_URL$4 = "https://api.playkit.ai";
 class ChatProvider {
     constructor(authManager, config) {
         this.authManager = authManager;
         this.config = config;
-        this.baseURL = config.baseURL || DEFAULT_BASE_URL$3;
+        this.baseURL = config.baseURL || DEFAULT_BASE_URL$4;
     }
     /**
      * Set player client for balance checking
@@ -4225,12 +4225,12 @@ class ChatProvider {
  * Image generation provider for HTTP communication with image API
  */
 // @ts-ignore - replaced at build time
-const DEFAULT_BASE_URL$2 = "https://api.playkit.ai";
+const DEFAULT_BASE_URL$3 = "https://api.playkit.ai";
 class ImageProvider {
     constructor(authManager, config) {
         this.authManager = authManager;
         this.config = config;
-        this.baseURL = config.baseURL || DEFAULT_BASE_URL$2;
+        this.baseURL = config.baseURL || DEFAULT_BASE_URL$3;
     }
     /**
      * Set player client for balance checking
@@ -4314,12 +4314,12 @@ class ImageProvider {
  * Transcription provider for HTTP communication with audio transcription API
  */
 // @ts-ignore - replaced at build time
-const DEFAULT_BASE_URL$1 = "https://api.playkit.ai";
+const DEFAULT_BASE_URL$2 = "https://api.playkit.ai";
 class TranscriptionProvider {
     constructor(authManager, config) {
         this.authManager = authManager;
         this.config = config;
-        this.baseURL = config.baseURL || DEFAULT_BASE_URL$1;
+        this.baseURL = config.baseURL || DEFAULT_BASE_URL$2;
     }
     /**
      * Set player client for balance checking
@@ -4413,6 +4413,116 @@ class TranscriptionProvider {
     }
 }
 
+/**
+ * TTS provider for HTTP communication with the text-to-speech API
+ */
+// @ts-ignore - replaced at build time
+const DEFAULT_BASE_URL$1 = "https://api.playkit.ai";
+class TTSProvider {
+    constructor(authManager, config) {
+        this.authManager = authManager;
+        this.config = config;
+        this.baseURL = config.baseURL || DEFAULT_BASE_URL$1;
+    }
+    /**
+     * Set player client for balance checking
+     */
+    setPlayerClient(playerClient) {
+        this.playerClient = playerClient;
+    }
+    /**
+     * Synthesize text into speech audio
+     */
+    async synthesize(ttsConfig) {
+        // Ensure token is valid, auto-refresh if needed (browser mode only)
+        await this.authManager.ensureValidToken();
+        const token = this.authManager.getToken();
+        if (!token) {
+            throw new PlayKitError('Not authenticated', 'NOT_AUTHENTICATED');
+        }
+        const model = ttsConfig.model || this.config.defaultTTSModel || 'default-tts-model';
+        const endpoint = `/ai/${this.config.gameId}/v2/audio/speech`;
+        const requestBody = {
+            model,
+            text: ttsConfig.text,
+        };
+        // Add optional parameters (only when defined)
+        if (ttsConfig.voice !== undefined) {
+            requestBody.voice = ttsConfig.voice;
+        }
+        if (ttsConfig.speed !== undefined) {
+            requestBody.speed = ttsConfig.speed;
+        }
+        if (ttsConfig.vol !== undefined) {
+            requestBody.vol = ttsConfig.vol;
+        }
+        if (ttsConfig.pitch !== undefined) {
+            requestBody.pitch = ttsConfig.pitch;
+        }
+        if (ttsConfig.emotion !== undefined) {
+            requestBody.emotion = ttsConfig.emotion;
+        }
+        if (ttsConfig.languageBoost !== undefined) {
+            requestBody.language_boost = ttsConfig.languageBoost;
+        }
+        if (ttsConfig.format !== undefined) {
+            requestBody.response_format = ttsConfig.format;
+        }
+        if (ttsConfig.voiceSetting !== undefined) {
+            requestBody.voice_setting = ttsConfig.voiceSetting;
+        }
+        if (ttsConfig.audioSetting !== undefined) {
+            requestBody.audio_setting = ttsConfig.audioSetting;
+        }
+        try {
+            const response = await fetch(`${this.baseURL}${endpoint}`, {
+                method: 'POST',
+                headers: Object.assign({ Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' }, getSDKHeaders()),
+                body: JSON.stringify(requestBody),
+            });
+            if (!response.ok) {
+                const error = await response.json().catch(() => ({ message: 'Speech synthesis failed' }));
+                const playKitError = new PlayKitError(error.message || 'Speech synthesis failed', error.code, response.status);
+                // Check for insufficient credits error
+                if (error.code === 'INSUFFICIENT_CREDITS' ||
+                    error.code === 'PLAYER_INSUFFICIENT_CREDIT' ||
+                    response.status === 402) {
+                    if (this.playerClient) {
+                        await this.playerClient.handleInsufficientCredits(playKitError);
+                    }
+                }
+                throw playKitError;
+            }
+            // SUCCESS: response is raw audio bytes, NOT JSON.
+            const audio = await response.arrayBuffer();
+            const contentType = response.headers.get('Content-Type');
+            const usageHeader = response.headers.get('X-Usage-Characters');
+            const audioLengthHeader = response.headers.get('X-Audio-Length-Ms');
+            const result = {
+                audio,
+                format: contentType || ttsConfig.format || 'mp3',
+                usageCharacters: Number(usageHeader) || 0,
+            };
+            if (audioLengthHeader !== null) {
+                result.audioLengthMs = Number(audioLengthHeader) || 0;
+            }
+            // Check balance after successful API call
+            if (this.playerClient) {
+                this.playerClient.checkBalanceAfterApiCall().catch(() => {
+                    // Silently fail
+                });
+            }
+            return result;
+        }
+        catch (error) {
+            if (error instanceof PlayKitError) {
+                throw error;
+            }
+            throw new PlayKitError(error instanceof Error ? error.message : 'Unknown error', 'TTS_ERROR');
+        }
+    }
+}
+
 /******************************************************************************
 Copyright (c) Microsoft Corporation.
 
@@ -5077,6 +5187,80 @@ class TranscriptionClient {
     }
 }
 
+/**
+ * High-level client for text-to-speech synthesis
+ */
+/**
+ * Resolve an audio format/content-type string into a valid MIME type.
+ * The provider's `result.format` may be a full MIME (e.g. 'audio/mpeg' from
+ * the Content-Type header) or a bare token (e.g. 'mp3' from the fallback).
+ * Full MIME strings pass through; bare tokens are mapped.
+ */
+function contentTypeFor(format) {
+    if (format.includes('/')) {
+        return format;
+    }
+    switch (format.toLowerCase()) {
+        case 'mp3':
+            return 'audio/mpeg';
+        case 'wav':
+            return 'audio/wav';
+        case 'ogg':
+            return 'audio/ogg';
+        case 'flac':
+            return 'audio/flac';
+        case 'aac':
+            return 'audio/aac';
+        case 'pcm':
+            return 'audio/pcm';
+        default:
+            return 'audio/mpeg';
+    }
+}
+class TTSClient {
+    constructor(provider, model) {
+        this.provider = provider;
+        this.model = model || 'default-tts-model';
+    }
+    /**
+     * Get the current model name
+     */
+    get modelName() {
+        return this.model;
+    }
+    /**
+     * Synthesize text into speech audio
+     * @param config - Full TTS configuration
+     * @returns TTS result containing raw audio bytes and usage metadata
+     */
+    async synthesize(config) {
+        return this.provider.synthesize(Object.assign(Object.assign({}, config), { model: config.model || this.model }));
+    }
+    /**
+     * Synthesize text into speech and return it as a Blob (browser-friendly)
+     * @param config - Full TTS configuration
+     * @returns Audio Blob with the appropriate MIME type
+     */
+    async synthesizeToBlob(config) {
+        const result = await this.synthesize(config);
+        return new Blob([result.audio], { type: contentTypeFor(result.format) });
+    }
+    /**
+     * Synthesize text into speech and return an object URL (browser only)
+     * @param config - Full TTS configuration
+     * @returns An object URL that can be assigned to an <audio> element
+     * @throws PlayKitError if URL.createObjectURL is unavailable (e.g. Node.js)
+     */
+    async synthesizeToObjectURL(config) {
+        if (typeof URL === 'undefined' || typeof URL.createObjectURL !== 'function') {
+            throw new PlayKitError('URL.createObjectURL is not available in this environment. ' +
+                'Use synthesize() to access the raw audio bytes instead.', 'TTS_OBJECT_URL_UNAVAILABLE');
+        }
+        const blob = await this.synthesizeToBlob(config);
+        return URL.createObjectURL(blob);
+    }
+}
+
 /**
  * Global AI Context Manager for managing NPC conversations and player context.
  *
@@ -6400,10 +6584,12 @@ class PlayKitSDK extends EventEmitter {
         this.chatProvider = new ChatProvider(this.authManager, this.config);
         this.imageProvider = new ImageProvider(this.authManager, this.config);
         this.transcriptionProvider = new TranscriptionProvider(this.authManager, this.config);
+        this.ttsProvider = new TTSProvider(this.authManager, this.config);
         // Connect providers to player client for balance checking
         this.chatProvider.setPlayerClient(this.playerClient);
         this.imageProvider.setPlayerClient(this.playerClient);
         this.transcriptionProvider.setPlayerClient(this.playerClient);
+        this.ttsProvider.setPlayerClient(this.playerClient);
         // Initialize AI context manager
         this.contextManager = new AIContextManager(this.config.aiContext);
         // Set chat client factory for compaction
@@ -6652,6 +6838,14 @@ class PlayKitSDK extends EventEmitter {
         this.ensureInitialized();
         return new TranscriptionClient(this.transcriptionProvider, model || this.config.defaultTranscriptionModel);
     }
+    /**
+     * Create a TTS client for text-to-speech
+     * @param model - TTS model to use (default: 'default-tts-model')
+     */
+    createTTSClient(model) {
+        this.ensureInitialized();
+        return new TTSClient(this.ttsProvider, model || this.config.defaultTTSModel);
+    }
     /**
      * Create an NPC client
      * Automatically registers with AIContextManager
@@ -7059,6 +7253,7 @@ exports.PlayerClient = PlayerClient;
 exports.RechargeManager = RechargeManager;
 exports.SchemaLibrary = SchemaLibrary;
 exports.StreamParser = StreamParser;
+exports.TTSClient = TTSClient;
 exports.TokenStorage = TokenStorage;
 exports.TokenValidator = TokenValidator;
 exports.TranscriptionClient = TranscriptionClient;