@inworld/tts 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- CI workflow for build validation on push and pull requests
+- Release workflow for automated npm publishing via GitHub Actions
+- Initial SDK: generate, stream, voice management, cloning, design

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Inworld AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,332 @@
+# @inworld/tts
+
+[![npm version](https://img.shields.io/npm/v/@inworld/tts.svg)](https://www.npmjs.com/package/@inworld/tts)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js ≥18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+
+Node.js and browser SDK for the Inworld TTS API — generate, stream, and manage voices.
+
+**[API Reference](API_REFERENCE.md)** · **[Changelog](CHANGELOG.md)** · **[Platform](https://platform.inworld.ai)**
+
+---
+
+## Install
+
+```bash
+npm install @inworld/tts
+```
+
+Supports ESM, CommonJS, and browser (Vite, webpack 5, Rollup, esbuild).
+
+---
+
+## Authentication
+
+Pass your API key directly or set `INWORLD_API_KEY` in your environment:
+
+```js
+import { InworldTTS } from '@inworld/tts'; // TypeScript: types are bundled, no @types/ needed
+
+const tts = InworldTTS();                       // reads INWORLD_API_KEY from env
+const tts = InworldTTS({ apiKey: 'your_key' }); // or pass directly
+```
+
+Get your key at [platform.inworld.ai](https://platform.inworld.ai). For browser usage with JWT, see [Browser](#browser).
+
+---
+
+## Quickstart
+
+```js
+import { InworldTTS } from '@inworld/tts';
+
+const tts = InworldTTS();
+await tts.generate({ text: 'Hello, world!', voice: 'Dennis', outputFile: 'hello.mp3' });
+```
+
+---
+
+## Models
+
+| Model ID | Quality | Default for |
+|----------|---------|-------------|
+| `inworld-tts-1.5-max` | Higher quality | `generate()` |
+| `inworld-tts-1.5-mini` | Lower latency | `stream()` |
+
+Use `max` when quality is the priority (e.g. audiobooks, voiceovers). Use `mini` for real-time use cases (e.g. voice assistants).
+
+---
+
+## Constructor
+
+```js
+const tts = InworldTTS({
+  apiKey: 'your_key',           // or set INWORLD_API_KEY env var
+  timeout: 120_000,             // HTTP timeout in ms (default: per-method)
+  maxConcurrentRequests: 4,     // parallel chunk requests for long text (default: 2)
+  maxRetries: 2,                // retry on network errors / 5xx with exponential backoff (default: 2)
+  debug: true,                  // log timing and retry info
+});
+```
+
+See [Constructor](API_REFERENCE.md#constructor) in the API Reference for full parameter details and per-method timeout defaults.
+
+---
+
+## generate()
+
+Synthesize speech from text of any length. Blocks until all audio is ready.
+
+```js
+// Save to file
+await tts.generate({ text: 'Hello!', voice: 'Dennis', outputFile: 'hello.mp3' });
+
+// Get bytes for further processing
+const audio = await tts.generate({ text: 'Hello!', voice: 'Dennis' });
+
+// Generate, save, and play
+await tts.generate({ text: 'Hello!', voice: 'Dennis', outputFile: 'hello.mp3', play: true });
+```
+
+## stream()
+
+Streaming — first audio chunk arrives faster than `generate()`. Max 2000 characters per call.
+
+```js
+for await (const chunk of tts.stream({ text: 'Hello, world!', voice: 'Dennis' })) {
+  // chunk is Uint8Array — pipe to audio player or accumulate
+}
+```
+
+## Timestamps
+
+`generateWithTimestamps()` and `streamWithTimestamps()` return word- or character-level timing alongside audio.
+
+```js
+const { audio, timestamps } = await tts.generateWithTimestamps({
+  text: 'Hello, world!',
+  voice: 'Dennis',
+  timestampType: 'WORD',
+});
+const wa = timestamps.wordAlignment;
+wa.words.forEach((w, i) =>
+  console.log(`${w}: ${wa.wordStartTimeSeconds[i].toFixed(2)}s – ${wa.wordEndTimeSeconds[i].toFixed(2)}s`)
+);
+```
+
+See [generateWithTimestamps()](API_REFERENCE.md#generatewithtimestamps) and [streamWithTimestamps()](API_REFERENCE.md#streamwithtimestamps) for full details.
+
+## play()
+
+Play audio from a `Uint8Array` or file path. Encoding is auto-detected from magic bytes or file extension.
+
+```js
+const audio = await tts.generate({ text: 'Hello!', voice: 'Dennis' });
+await tts.play(audio);
+
+await tts.play('hello.mp3');                        // file path also accepted (Node.js only)
+await tts.play(pcmBytes, { encoding: 'PCM' });      // encoding hint for raw PCM/ALAW/MULAW
+```
+
+See [play()](API_REFERENCE.md#play) for platform player details and browser constraints.
+
+---
+
+## listVoices()
+
+List voices in your workspace, with optional language filter.
+
+```js
+const voices = await tts.listVoices();
+const enVoices = await tts.listVoices({ lang: 'EN_US' });
+const multi = await tts.listVoices({ lang: ['EN_US', 'ES_ES'] });
+```
+
+## getVoice()
+
+Get details of a specific voice.
+
+```js
+const voice = await tts.getVoice('workspace__my_clone');
+```
+
+## updateVoice()
+
+Update a voice's display name, description, or tags.
+
+```js
+await tts.updateVoice({ voice: 'workspace__my_clone', displayName: 'Narrator', tags: ['calm'] });
+```
+
+## deleteVoice()
+
+Delete a voice from your workspace.
+
+```js
+await tts.deleteVoice('workspace__my_clone');
+```
+
+## cloneVoice()
+
+Clone a voice from one or more audio recordings (WAV/MP3). Accepts `Uint8Array` buffers or file path strings (Node.js only).
+
+```js
+const result = await tts.cloneVoice({
+  audioSamples: ['sample.wav'],
+  displayName: 'My Clone',
+});
+const voiceId = result.voice.voiceId;
+```
+
+> **Note:** Voice cloning is a long-running operation (up to 5 min). If it times out, check `listVoices()` — the voice may have been created anyway.
+
+## designVoice()
+
+Design a voice from a text description — no recording needed.
+
+```js
+const result = await tts.designVoice({
+  designPrompt: 'A warm, friendly narrator',
+  previewText: 'Hello, welcome to our audiobook.',
+});
+const preview = result.previewVoices[0];
+```
+
+## publishVoice()
+
+Publish a designed or cloned voice preview to your library.
+
+```js
+await tts.publishVoice({ voice: preview.voiceId, displayName: 'My Custom Voice' });
+```
+
+## migrateFromElevenLabs()
+
+Migrate a voice from ElevenLabs to your Inworld workspace. No ElevenLabs SDK required.
+
+```js
+const result = await tts.migrateFromElevenLabs({
+  elevenLabsApiKey: 'el_...',
+  elevenLabsVoiceId: 'abc123',
+});
+console.log(`${result.elevenLabsName} → ${result.inworldVoiceId}`);
+```
+
+See [Voice Management](API_REFERENCE.md#voice-management) in the API Reference for all parameters.
+
+---
+
+## Errors
+
+| Class | When |
+|-------|------|
+| `MissingApiKeyError` | No API key or token found at construction |
+| `ApiError` | API returned 4xx/5xx — has `.code` and `.details` |
+| `NetworkError` | Connection or timeout failure |
+
+All inherit from `InworldTTSError`.
+
+```js
+import { InworldTTS, ApiError, MissingApiKeyError, NetworkError } from '@inworld/tts';
+
+try {
+  const audio = await tts.generate({ text: 'Hello!', voice: 'Dennis' });
+} catch (err) {
+  if (err instanceof MissingApiKeyError) console.error('Missing API key');
+  else if (err instanceof ApiError) console.error(`HTTP ${err.code}: ${err.message}`);
+  else if (err instanceof NetworkError) console.error(`Network error: ${err.message}`);
+  else throw err;
+}
+```
+
+---
+
+## Browser
+
+For browser usage, use a short-lived JWT token from your backend instead of exposing your API key.
+
+```js
+const fetchToken = async () => {
+  const { token } = await fetch('/api/tts-token').then(r => r.json());
+  return token;
+};
+
+const tts = InworldTTS({
+  token: await fetchToken(),
+  onTokenExpiring: fetchToken, // called automatically when token is about to expire
+});
+
+// play() must be called inside a user event handler (browser autoplay policy)
+button.onclick = async () => {
+  const audio = await tts.generate({ text: 'Hello!', voice: 'Dennis', encoding: 'MP3' });
+  await tts.play(audio);
+};
+```
+
+For development only, you can use an API key directly with `dangerouslyAllowBrowser: true` — but your key will be visible in DevTools and billed to your account.
+
+A complete working example is in [`examples/browser/`](examples/browser/).
+
+> **Encoding in browser:** Prefer `encoding: 'MP3'` — supported natively in all browsers. `OGG_OPUS`/`FLAC` work in Chrome and Firefox but not Safari. `LINEAR16`, `PCM`, `ALAW`, `MULAW` cannot be played by `play()` in browser.
+
+---
+
+## Examples
+
+Runnable examples are in the [`examples/`](examples/) directory:
+
+| File | What it shows |
+|------|---------------|
+| [`hello_world.js`](examples/hello_world.js) | Text → MP3 in 3 lines |
+| [`stream_audio.js`](examples/stream_audio.js) | Real-time streaming |
+| [`list_voices.js`](examples/list_voices.js) | List all voices with optional language filter |
+| [`clone_voice.js`](examples/clone_voice.js) | Clone a voice from a WAV/MP3 recording |
+| [`design_voice.js`](examples/design_voice.js) | Design a voice from a text description, preview, and publish |
+| [`generate_timestamps.js`](examples/generate_timestamps.js) | Word-level timestamps |
+| [`examples/browser/`](examples/browser/) | Browser usage with JWT auth |
+
+---
+
+## Troubleshooting
+
+### `MissingApiKeyError` / `ApiError` 401
+
+Set `INWORLD_API_KEY` or pass `apiKey` directly. If the key is set but rejected, regenerate it at [platform.inworld.ai](https://platform.inworld.ai).
+
+### `play()` blocked by browser (autoplay policy)
+
+Move `play()` inside a user event handler:
+
+```js
+button.onclick = async () => await tts.play(audio);
+```
+
+### `ApiError`: text exceeds 2000 character limit
+
+`stream()` accepts at most 2000 characters per call. Use `generate()` instead — it handles any text length automatically.
+
+### `NetworkError: Request timed out`
+
+Increase the timeout or add retries:
+
+```js
+const tts = InworldTTS({ timeout: 120_000, maxRetries: 3 });
+```
+
+### `require('@inworld/tts')` throws `ERR_REQUIRE_ESM`
+
+Both ESM and CommonJS are supported. Ensure you are on Node.js ≥18 and using a bundler that respects the `exports` field (webpack 5, Vite, Rollup, esbuild).
+
+```js
+// ESM
+import { InworldTTS } from '@inworld/tts';
+
+// CommonJS
+const { InworldTTS } = require('@inworld/tts');
+```
+
+---
+
+## License
+
+[MIT](LICENSE)