@supertone/supertone 0.1.1 → 0.1.2

package/README.md

@@ -3,15 +3,12 @@
 ![LOGO](https://github.com/supertone-inc/supertone-ts/blob/main/images/hero-light.png?raw=true)
 
 <!-- Start Summary [summary] -->
+## Summary
 
-## API & Docs
-
-The official TypesSript SDK for [Supertone API](https://www.supertone.ai/en/api)
-
+Supertone Public API: Supertone API is a RESTful API for using our state-of-the-art AI voice models.
 <!-- End Summary [summary] -->
 
 <!-- Start SDK Installation [installation] -->
-
 ## SDK Installation
 
 The SDK can be installed with either [npm](https://www.npmjs.com/), [pnpm](https://pnpm.io/), [bun](https://bun.sh/) or [yarn](https://classic.yarnpkg.com/en/) package managers.
@@ -19,25 +16,25 @@ The SDK can be installed with either [npm](https://www.npmjs.com/), [pnpm](https
 ### NPM
 
 ```bash
-npm add @supertone/supertone
+npm add <UNSET>
 ```
 
 ### PNPM
 
 ```bash
-pnpm add @supertone/supertone
+pnpm add <UNSET>
 ```
 
 ### Bun
 
 ```bash
-bun add @supertone/supertone
+bun add <UNSET>
 ```
 
 ### Yarn
 
 ```bash
-yarn add @supertone/supertone zod
+yarn add <UNSET> zod
 
 # Note that Yarn does not install peer dependencies automatically. You will need
 # to install zod as shown above.
@@ -45,20 +42,16 @@ yarn add @supertone/supertone zod
 
 > [!NOTE]
 > This package is published with CommonJS and ES Modules (ESM) support.
-
 <!-- End SDK Installation [installation] -->
 
 <!-- Start Requirements [requirements] -->
-
 ## Requirements
 
 For supported JavaScript runtimes, please consult [RUNTIMES.md](RUNTIMES.md).
-
 <!-- End Requirements [requirements] -->
 
 <!-- Start SDK Example Usage [usage] -->
-
-## Speech Generation Example
+## SDK Example Usage
 
 ### Example
 
@@ -84,11 +77,9 @@ async function run() {
 run();
 
 ```
-
 <!-- End SDK Example Usage [usage] -->
 
 <!-- Start Authentication [security] -->
-
 ## Authentication
 
 ### Per-Client Security Schemes
@@ -100,7 +91,6 @@ This SDK supports the following security scheme globally:
 | `apiKey` | apiKey | API key |
 
 To authenticate with the API the `apiKey` parameter must be set when initializing the SDK client instance. For example:
-
 ```typescript
 import { Supertone } from "@supertone/supertone";
 
@@ -123,44 +113,108 @@ async function run() {
 run();
 
 ```
-
 <!-- End Authentication [security] -->
 
-<!-- Start Available Resources and Operations [operations] -->
+<!-- Start Models [models] -->
+
+## Models
+
+Supertone’s Text-to-Speech API provides multiple TTS models, each with different supported languages, available voice settings, and streaming capabilities.
+
+### Model Overview
+
+| Model Name         | Identifier        | Streaming Support (`stream_speech`) | Voice Settings Support                                   |
+|--------------------|-------------------|--------------------------------------|----------------------------------------------------------|
+| **SONA Speech 1**  | `sona_speech_1`   | ✅ Supported                         | Supports **all** Voice Settings                          |
+| **Supertonic API 1** | `supertonic_api_1` | ❌ Not supported                  | Supports **only** the `speed` setting (others are ignored) |
+| **SONA Speech 2**  | `sona_speech_2`   | ❌ Not supported                     | Supports **pitch_shift**, **pitch_variance**, **speed**   |
+
+> [!NOTE]
+> **Streaming Support**
+>
+> Streaming TTS using the `stream_speech` endpoint is **only available for the `sona_speech_1` model**.
+
+---
+
+### Supported Languages by Model
 
+> [!NOTE]
+> The set of supported input languages varies depending on the TTS model.
+
+- **sona_speech_1**
+  - `en`, `ko`, `ja`
+
+- **supertonic_api_1**
+  - `en`, `ko`, `ja`, `es`, `pt`
+
+- **sona_speech_2**
+  - `en`, `ko`, `ja`, `bg`, `cs`, `da`, `el`, `es`, `et`, `fi`, `hu`, `it`, `nl`, `pl`, `pt`, `ro`,  
+    `ar`, `de`, `fr`, `hi`, `id`, `ru`, `vi`
+
+---
+
+### Voice Settings (Optional)
+
+Some TTS models support optional voice settings that allow fine control over output speech characteristics (e.g., speed, pitch, pitch variance).
+
+> [!NOTE]
+> The available Voice Settings vary depending on the TTS model.
+
+- **sona_speech_1**
+  - Supports **all** available Voice Settings.
+
+- **supertonic_api_1**
+  - Supports **only** the `speed` setting.  
+    All other settings will be ignored.
+
+- **sona_speech_2**
+  - Supports the following Voice Settings:
+    - `pitch_shift`
+    - `pitch_variance`
+    - `speed`
+
+> All Voice Settings are optional. When omitted, each model’s default values will be applied.
+
+<!-- End Models [models] -->
+
+<!-- Start Available Resources and Operations [operations] -->
 ## Available Resources and Operations
 
+<details open>
+<summary>Available methods</summary>
+
 ### [customVoices](docs/sdks/customvoices/README.md)
 
-- [createClonedVoice](docs/sdks/customvoices/README.md#createclonedvoice) - Create cloned voice
-- [listCustomVoices](docs/sdks/customvoices/README.md#listcustomvoices) - Gets custom (cloned) voices
-- [searchCustomVoices](docs/sdks/customvoices/README.md#searchcustomvoices) - Search custom (cloned) voices
-- [getCustomVoice](docs/sdks/customvoices/README.md#getcustomvoice) - Get single cloned voice
-- [editCustomVoice](docs/sdks/customvoices/README.md#editcustomvoice) - Update cloned voice (partial update)
-- [deleteCustomVoice](docs/sdks/customvoices/README.md#deletecustomvoice) - Delete cloned voice
+* [createClonedVoice](docs/sdks/customvoices/README.md#createclonedvoice) - Create cloned voice
+* [listCustomVoices](docs/sdks/customvoices/README.md#listcustomvoices) - Gets custom (cloned) voices
+* [searchCustomVoices](docs/sdks/customvoices/README.md#searchcustomvoices) - Search custom (cloned) voices
+* [getCustomVoice](docs/sdks/customvoices/README.md#getcustomvoice) - Get single cloned voice
+* [editCustomVoice](docs/sdks/customvoices/README.md#editcustomvoice) - Update cloned voice (partial update)
+* [deleteCustomVoice](docs/sdks/customvoices/README.md#deletecustomvoice) - Delete cloned voice
+
 
 ### [textToSpeech](docs/sdks/texttospeech/README.md)
 
-- [createSpeech](docs/sdks/texttospeech/README.md#createspeech) - Convert text to speech
-- [streamSpeech](docs/sdks/texttospeech/README.md#streamspeech) - Convert text to speech with streaming response
-- [predictDuration](docs/sdks/texttospeech/README.md#predictduration) - Predict text-to-speech duration
+* [createSpeech](docs/sdks/texttospeech/README.md#createspeech) - Convert text to speech
+* [streamSpeech](docs/sdks/texttospeech/README.md#streamspeech) - Convert text to speech with streaming response
+* [predictDuration](docs/sdks/texttospeech/README.md#predictduration) - Predict text-to-speech duration
 
 ### [usage](docs/sdks/usage/README.md)
 
-- [getVoiceUsage](docs/sdks/usage/README.md#getvoiceusage) - Retrieve TTS API usage data
-- [getUsage](docs/sdks/usage/README.md#getusage) - Retrieve advanced API usage analytics
-- [getCreditBalance](docs/sdks/usage/README.md#getcreditbalance) - Retrieve credit balance
+* [getVoiceUsage](docs/sdks/usage/README.md#getvoiceusage) - Retrieve TTS API usage data
+* [getUsage](docs/sdks/usage/README.md#getusage) - Retrieve advanced API usage analytics
+* [getCreditBalance](docs/sdks/usage/README.md#getcreditbalance) - Retrieve credit balance
 
 ### [voices](docs/sdks/voices/README.md)
 
-- [listVoices](docs/sdks/voices/README.md#listvoices) - Gets available voices
-- [searchVoices](docs/sdks/voices/README.md#searchvoices) - Search voices.
-- [getVoice](docs/sdks/voices/README.md#getvoice) - Get voice details by ID
+* [listVoices](docs/sdks/voices/README.md#listvoices) - Gets available voices
+* [searchVoices](docs/sdks/voices/README.md#searchvoices) - Search voices.
+* [getVoice](docs/sdks/voices/README.md#getvoice) - Get voice details by ID
 
+</details>
 <!-- End Available Resources and Operations [operations] -->
 
 <!-- Start Error Handling [errors] -->
-
 ## Error Handling
 
 [`SupertoneError`](./src/models/errors/supertoneerror.ts) is the base class for all HTTP error responses. It has the following properties:
@@ -174,44 +228,7 @@ run();
 | `error.rawResponse` | `Response` | Raw HTTP response                                                                       |
 | `error.data$`       |            | Optional. Some errors may contain structured data. [See Error Classes](#error-classes). |
 
-### Error Classes
-
-**Primary error:**
-
-- [`SupertoneError`](./src/models/errors/supertoneerror.ts): The base class for HTTP error responses.
-
-<details><summary>Less common errors (16)</summary>
-
-<br />
-
-**Network errors:**
-
-- [`ConnectionError`](./src/models/errors/httpclienterrors.ts): HTTP client was unable to make a request to a server.
-- [`RequestTimeoutError`](./src/models/errors/httpclienterrors.ts): HTTP request timed out due to an AbortSignal signal.
-- [`RequestAbortedError`](./src/models/errors/httpclienterrors.ts): HTTP request was aborted by the client.
-- [`InvalidRequestError`](./src/models/errors/httpclienterrors.ts): Any input used to create a request is invalid.
-- [`UnexpectedClientError`](./src/models/errors/httpclienterrors.ts): Unrecognised or unexpected error.
-
-**Inherit from [`SupertoneError`](./src/models/errors/supertoneerror.ts)**:
-
-- [`UnauthorizedErrorResponse`](./src/models/errors/unauthorizederrorresponse.ts): Unauthorized: Invalid API key. Status code `401`. Applicable to 10 of 15 methods.\*
-- [`InternalServerErrorResponse`](./src/models/errors/internalservererrorresponse.ts): Status code `500`. Applicable to 10 of 15 methods.\*
-- [`NotFoundErrorResponse`](./src/models/errors/notfounderrorresponse.ts): Status code `404`. Applicable to 9 of 15 methods.\*
-- [`BadRequestErrorResponse`](./src/models/errors/badrequesterrorresponse.ts): Status code `400`. Applicable to 5 of 15 methods.\*
-- [`ForbiddenErrorResponse`](./src/models/errors/forbiddenerrorresponse.ts): Status code `403`. Applicable to 4 of 15 methods.\*
-- [`RequestTimeoutErrorResponse`](./src/models/errors/requesttimeouterrorresponse.ts): Status code `408`. Applicable to 4 of 15 methods.\*
-- [`TooManyRequestsErrorResponse`](./src/models/errors/toomanyrequestserrorresponse.ts): Status code `429`. Applicable to 4 of 15 methods.\*
-- [`PaymentRequiredErrorResponse`](./src/models/errors/paymentrequirederrorresponse.ts): Status code `402`. Applicable to 3 of 15 methods.\*
-- [`PayloadTooLargeErrorResponse`](./src/models/errors/payloadtoolargeerrorresponse.ts): Payload Too Large: File size exceeds 3MB limit. Status code `413`. Applicable to 1 of 15 methods.\*
-- [`UnsupportedMediaTypeErrorResponse`](./src/models/errors/unsupportedmediatypeerrorresponse.ts): Unsupported Media Type: Invalid audio file format. Status code `415`. Applicable to 1 of 15 methods.\*
-- [`ResponseValidationError`](./src/models/errors/responsevalidationerror.ts): Type mismatch between the data returned from the server and the structure expected by the SDK. See `error.rawValue` for the raw value and `error.pretty()` for a nicely formatted multi-line string.
-
-</details>
-
-\* Check [the method documentation](#available-resources-and-operations) to see if the error is applicable.
-
-### Error Handling Example
-
+### Example
 ```typescript
 import { Supertone } from "@supertone/supertone";
 import * as errors from "@supertone/supertone/models/errors";
@@ -252,6 +269,38 @@ run();
 
 ```
 
+### Error Classes
+**Primary error:**
+* [`SupertoneError`](./src/models/errors/supertoneerror.ts): The base class for HTTP error responses.
+
+<details><summary>Less common errors (16)</summary>
+
+<br />
+
+**Network errors:**
+* [`ConnectionError`](./src/models/errors/httpclienterrors.ts): HTTP client was unable to make a request to a server.
+* [`RequestTimeoutError`](./src/models/errors/httpclienterrors.ts): HTTP request timed out due to an AbortSignal signal.
+* [`RequestAbortedError`](./src/models/errors/httpclienterrors.ts): HTTP request was aborted by the client.
+* [`InvalidRequestError`](./src/models/errors/httpclienterrors.ts): Any input used to create a request is invalid.
+* [`UnexpectedClientError`](./src/models/errors/httpclienterrors.ts): Unrecognised or unexpected error.
+
+
+**Inherit from [`SupertoneError`](./src/models/errors/supertoneerror.ts)**:
+* [`UnauthorizedErrorResponse`](./src/models/errors/unauthorizederrorresponse.ts): Unauthorized: Invalid API key. Status code `401`. Applicable to 10 of 15 methods.*
+* [`InternalServerErrorResponse`](./src/models/errors/internalservererrorresponse.ts): Status code `500`. Applicable to 10 of 15 methods.*
+* [`NotFoundErrorResponse`](./src/models/errors/notfounderrorresponse.ts): Status code `404`. Applicable to 9 of 15 methods.*
+* [`BadRequestErrorResponse`](./src/models/errors/badrequesterrorresponse.ts): Status code `400`. Applicable to 5 of 15 methods.*
+* [`ForbiddenErrorResponse`](./src/models/errors/forbiddenerrorresponse.ts): Status code `403`. Applicable to 4 of 15 methods.*
+* [`RequestTimeoutErrorResponse`](./src/models/errors/requesttimeouterrorresponse.ts): Status code `408`. Applicable to 4 of 15 methods.*
+* [`TooManyRequestsErrorResponse`](./src/models/errors/toomanyrequestserrorresponse.ts): Status code `429`. Applicable to 4 of 15 methods.*
+* [`PaymentRequiredErrorResponse`](./src/models/errors/paymentrequirederrorresponse.ts): Status code `402`. Applicable to 3 of 15 methods.*
+* [`PayloadTooLargeErrorResponse`](./src/models/errors/payloadtoolargeerrorresponse.ts): Payload Too Large: File size exceeds 3MB limit. Status code `413`. Applicable to 1 of 15 methods.*
+* [`UnsupportedMediaTypeErrorResponse`](./src/models/errors/unsupportedmediatypeerrorresponse.ts): Unsupported Media Type: Invalid audio file format. Status code `415`. Applicable to 1 of 15 methods.*
+* [`ResponseValidationError`](./src/models/errors/responsevalidationerror.ts): Type mismatch between the data returned from the server and the structure expected by the SDK. See `error.rawValue` for the raw value and `error.pretty()` for a nicely formatted multi-line string.
+
+</details>
+
+\* Check [the method documentation](#available-resources-and-operations) to see if the error is applicable.
 <!-- End Error Handling [errors] -->
 
 <!-- Start Additional Example Code [examples] -->
@@ -262,4 +311,5 @@ Additional example code can be found in the [examples](https://github.com/supert
 
 <!-- End Additional Example Code [examples] -->
 
+
 <!-- Placeholder for Future Speakeasy SDK Sections -->

package/custom_test/realtime_tts_player.ts

@@ -275,10 +275,13 @@ class SimpleMpvPlayer {
  */
 async function simpleStreamingTts(
 	voiceId: string,
-	text: string
+	text: string,
+	language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage = models
+		.APIConvertTextToSpeechUsingCharacterRequestLanguage.Ko
 ): Promise<boolean> {
 	console.log(`📝 "${text.slice(0, 50)}${text.length > 50 ? "..." : ""}"`);
 	console.log(`📏 Text length: ${text.length} characters`);
+	console.log(`🌐 Language: ${language}`);
 
 	const player = new SimpleMpvPlayer();
 
@@ -296,7 +299,7 @@ async function simpleStreamingTts(
 			voiceId: voiceId,
 			apiConvertTextToSpeechUsingCharacterRequest: {
 				text: text,
-				language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.Ko,
+				language: language,
 				outputFormat:
 					models.APIConvertTextToSpeechUsingCharacterRequestOutputFormat.Wav,
 				style: "neutral",
@@ -384,7 +387,8 @@ async function simpleStreamingTts(
  */
 async function simpleDemo(): Promise<void> {
 	const voiceId = "91992bbd4758bdcf9c9b01";
-	const scenarios = [
+	const scenarios: string[] = [];
+	/*[
 		"안녕하세요! 심플한 테스트입니다.",
 
 		"실시간 텍스트 음성 변환 기술은 정말 놀랍습니다. 이 기술을 통해 긴 텍스트도 즉시 음성으로 들을 수 있게 되었습니다.",
@@ -399,6 +403,28 @@ async function simpleDemo(): Promise<void> {
 
 		// Scenario 800+ characters (~850 chars)
 		"옛날 한 작은 마을에 천재적인 재능을 가진 젊은 개발자가 살고 있었습니다. 그의 이름은 민준이였고, 어릴 때부터 컴퓨터와 프로그래밍에 남다른 관심을 보였습니다. 대학에서 컴퓨터 과학을 전공한 민준은 졸업 후 스타트업에 입사했습니다. 그곳에서 그는 인공지능과 음성 기술에 대한 깊은 지식을 쌓게 되었습니다. 어느 날, 민준은 시각 장애가 있는 친구 서연을 만났습니다. 서연은 인터넷의 수많은 정보를 텍스트로만 접할 수 있어 많은 불편함을 겪고 있었습니다. 당시의 음성 합성 기술은 로봇 같은 목소리를 내며, 긴 텍스트를 읽어주려면 모든 처리가 끝날 때까지 기다려야 했습니다. 이를 본 민준은 더 자연스럽고 빠른 음성 합성 기술을 만들기로 결심했습니다. 밤낮없이 연구에 매진한 민준은 혁신적인 아이디어를 떠올렸습니다. 긴 텍스트를 작은 단위로 나누어 실시간으로 처리하고, 첫 번째 부분이 완성되는 즉시 재생을 시작하는 스트리밍 방식이었습니다. 이 기술을 구현하기 위해 그는 최신 딥러닝 모델과 신경망 아키텍처를 연구했습니다. 수많은 시행착오를 거쳐 마침내 자연스러운 음성을 실시간으로 생성할 수 있는 시스템을 완성했습니다. 그의 기술은 문장의 문맥과 감정까지 이해하여 적절한 억양과 속도로 읽어주었습니다.",
+	];*/
+
+	// Additional test scenarios for word-based and character-based chunking
+	const additionalScenarios = [
+		{
+			// Korean text WITHOUT punctuation to test word-based chunking
+			// Text length: ~450 characters (exceeds 300 char limit)
+			text: "이것은 구두점 없이 매우 긴 문장을 테스트하는 것으로 삼백 글자를 초과하는 텍스트에서 단어 기반 분할이 올바르게 작동하는지 확인하기 위한 것입니다 이러한 경우 SDK는 문장 경계 대신 단어 경계를 사용하여 텍스트를 적절한 크기로 나누어야 하며 이는 사용자가 생성한 콘텐츠에서 흔히 발생할 수 있는 상황입니다 예를 들어 채팅 메시지나 비공식적인 텍스트 입력에서는 올바른 문법과 구두점이 항상 보장되지 않기 때문입니다 또한 실시간 스트리밍 환경에서는 사용자가 빠르게 입력하는 경우가 많아서 구두점을 생략하는 경우가 빈번하게 발생합니다 이러한 상황에서도 SDK는 안정적으로 텍스트를 처리하고 자연스러운 음성을 생성해야 합니다 따라서 단어 기반 분할 기능은 매우 중요한 역할을 담당합니다",
+			label:
+				"Long sentence without punctuation (Word-based chunking, 450+ chars)",
+			category: "Word-based Chunking Test",
+			language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.Ko,
+		},
+		{
+			// Japanese text WITHOUT punctuation marks (。！？etc) to test pure character-based chunking
+			// Text length: ~450 characters (exceeds 300 char limit)
+			text: "日本語のテキストは通常スペースを含まないため特別な処理が必要ですこのテストは三百文字を超える長い日本語テキストが正しく処理されることを確認します自然言語処理技術の発展により音声合成の品質は大幅に向上しました特にディープラーニングを活用した最新のテキスト音声変換システムは人間の発話に非常に近い自然な音声を生成できますスペースがない言語では文字単位での分割が必要でありこのSDKはそのような状況を自動的に検出して適切に処理しますこれにより日本語中国語韓国語などのアジア言語でも問題なく長いテキストを音声に変換することができます音声合成技術は視覚障害者のためのアクセシビリティツールから対話型AIアシスタントまで幅広い用途で活用されていますさらにリアルタイムストリーミング技術と組み合わせることで待ち時間を大幅に短縮し優れたユーザー体験を提供することができます最新の音声合成技術は感情や抑揚も自然に表現できるようになりました",
+			label:
+				"Japanese text without spaces AND punctuation (Character-based chunking, 450+ chars)",
+			category: "Character-based Chunking Test",
+			language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.Ja,
+		},
 	];
 
 	for (let i = 0; i < scenarios.length; i++) {
@@ -429,6 +455,36 @@ async function simpleDemo(): Promise<void> {
 		}
 	}
 
+	// Run additional scenarios for chunking tests
+	console.log("\n" + "=".repeat(60));
+	console.log("🔧 Additional Chunking Test Scenarios");
+	console.log("=".repeat(60));
+
+	for (let i = 0; i < additionalScenarios.length; i++) {
+		const scenario = additionalScenarios[i];
+		console.log(
+			`\n🔬 Additional Scenario ${i + 1}/${additionalScenarios.length}`
+		);
+		console.log(`📂 Category: ${scenario.category}`);
+		console.log(`📝 ${scenario.label}`);
+		console.log("─".repeat(50));
+
+		const success = await simpleStreamingTts(
+			voiceId,
+			scenario.text,
+			scenario.language
+		);
+
+		if (!success) {
+			console.log(`❌ Additional scenario ${i + 1} failed`);
+		}
+
+		if (i < additionalScenarios.length - 1) {
+			console.log("\n⏳ Waiting...");
+			await new Promise((resolve) => setTimeout(resolve, 2000));
+		}
+	}
+
 	console.log("\n🎉 Demo completed!");
 	console.log("\n📊 Tested text length ranges:");
 	console.log("   • Short text: ~100 chars");
@@ -436,6 +492,11 @@ async function simpleDemo(): Promise<void> {
 	console.log("   • Long text: 300~500 chars");
 	console.log("   • Very long text: 500~800 chars");
 	console.log("   • Extra long text: 800+ chars");
+	console.log("\n🔧 Chunking strategy tests:");
+	console.log("   • Word-based chunking: Long sentences without punctuation");
+	console.log(
+		"   • Character-based chunking: Japanese/Chinese text without spaces"
+	);
 }
 
 /**