@supertone/supertone 0.1.2 → 0.1.4

package/README.md

@@ -16,25 +16,25 @@ The SDK can be installed with either [npm](https://www.npmjs.com/), [pnpm](https
 ### NPM
 
 ```bash
-npm add <UNSET>
+npm add @supertone/supertone
 ```
 
 ### PNPM
 
 ```bash
-pnpm add <UNSET>
+pnpm add @supertone/supertone
 ```
 
 ### Bun
 
 ```bash
-bun add <UNSET>
+bun add @supertone/supertone
 ```
 
 ### Yarn
 
 ```bash
-yarn add <UNSET> zod
+yarn add @supertone/supertone zod
 
 # Note that Yarn does not install peer dependencies automatically. You will need
 # to install zod as shown above.

package/custom_test/realtime_tts_player.ts

@@ -6,6 +6,7 @@
 import { spawn, ChildProcess } from "child_process";
 import { Supertone } from "../src/index.js";
 import * as models from "../src/models/index.js";
+import type { PronunciationDictionaryEntry } from "../src/lib/custom_utils/index.js";
 import * as dotenv from "dotenv";
 import * as path from "path";
 import { fileURLToPath } from "url";
@@ -277,11 +278,15 @@ async function simpleStreamingTts(
 	voiceId: string,
 	text: string,
 	language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage = models
-		.APIConvertTextToSpeechUsingCharacterRequestLanguage.Ko
+		.APIConvertTextToSpeechUsingCharacterRequestLanguage.Ko,
+	pronunciationDictionary?: PronunciationDictionaryEntry[]
 ): Promise<boolean> {
 	console.log(`📝 "${text.slice(0, 50)}${text.length > 50 ? "..." : ""}"`);
 	console.log(`📏 Text length: ${text.length} characters`);
 	console.log(`🌐 Language: ${language}`);
+	if (pronunciationDictionary && pronunciationDictionary.length > 0) {
+		console.log(`📖 Pronunciation dictionary: ${pronunciationDictionary.length} entries`);
+	}
 
 	const player = new SimpleMpvPlayer();
 
@@ -295,17 +300,20 @@ async function simpleStreamingTts(
 		player.markApiCallStart();
 		console.log("   ⏱️  API call started...");
 
-		const response = await client.textToSpeech.streamSpeech({
-			voiceId: voiceId,
-			apiConvertTextToSpeechUsingCharacterRequest: {
-				text: text,
-				language: language,
-				outputFormat:
-					models.APIConvertTextToSpeechUsingCharacterRequestOutputFormat.Wav,
-				style: "neutral",
-				model: "sona_speech_1",
+		const response = await client.textToSpeech.streamSpeech(
+			{
+				voiceId: voiceId,
+				apiConvertTextToSpeechUsingCharacterRequest: {
+					text: text,
+					language: language,
+					outputFormat:
+						models.APIConvertTextToSpeechUsingCharacterRequestOutputFormat.Wav,
+					style: "neutral",
+					model: "sona_speech_1",
+				},
 			},
-		});
+			pronunciationDictionary ? { pronunciationDictionary } : undefined
+		);
 
 		// Mark API call end (response received)
 		player.markApiCallEnd();
@@ -387,8 +395,7 @@ async function simpleStreamingTts(
  */
 async function simpleDemo(): Promise<void> {
 	const voiceId = "91992bbd4758bdcf9c9b01";
-	const scenarios: string[] = [];
-	/*[
+	const scenarios: string[] = [
 		"안녕하세요! 심플한 테스트입니다.",
 
 		"실시간 텍스트 음성 변환 기술은 정말 놀랍습니다. 이 기술을 통해 긴 텍스트도 즉시 음성으로 들을 수 있게 되었습니다.",
@@ -403,10 +410,16 @@ async function simpleDemo(): Promise<void> {
 
 		// Scenario 800+ characters (~850 chars)
 		"옛날 한 작은 마을에 천재적인 재능을 가진 젊은 개발자가 살고 있었습니다. 그의 이름은 민준이였고, 어릴 때부터 컴퓨터와 프로그래밍에 남다른 관심을 보였습니다. 대학에서 컴퓨터 과학을 전공한 민준은 졸업 후 스타트업에 입사했습니다. 그곳에서 그는 인공지능과 음성 기술에 대한 깊은 지식을 쌓게 되었습니다. 어느 날, 민준은 시각 장애가 있는 친구 서연을 만났습니다. 서연은 인터넷의 수많은 정보를 텍스트로만 접할 수 있어 많은 불편함을 겪고 있었습니다. 당시의 음성 합성 기술은 로봇 같은 목소리를 내며, 긴 텍스트를 읽어주려면 모든 처리가 끝날 때까지 기다려야 했습니다. 이를 본 민준은 더 자연스럽고 빠른 음성 합성 기술을 만들기로 결심했습니다. 밤낮없이 연구에 매진한 민준은 혁신적인 아이디어를 떠올렸습니다. 긴 텍스트를 작은 단위로 나누어 실시간으로 처리하고, 첫 번째 부분이 완성되는 즉시 재생을 시작하는 스트리밍 방식이었습니다. 이 기술을 구현하기 위해 그는 최신 딥러닝 모델과 신경망 아키텍처를 연구했습니다. 수많은 시행착오를 거쳐 마침내 자연스러운 음성을 실시간으로 생성할 수 있는 시스템을 완성했습니다. 그의 기술은 문장의 문맥과 감정까지 이해하여 적절한 억양과 속도로 읽어주었습니다.",
-	];*/
+	];
 
 	// Additional test scenarios for word-based and character-based chunking
-	const additionalScenarios = [
+	const additionalScenarios: Array<{
+		text: string;
+		label: string;
+		category: string;
+		language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage;
+		pronunciationDictionary?: PronunciationDictionaryEntry[];
+	}> = [
 		{
 			// Korean text WITHOUT punctuation to test word-based chunking
 			// Text length: ~450 characters (exceeds 300 char limit)
@@ -425,6 +438,87 @@ async function simpleDemo(): Promise<void> {
 			category: "Character-based Chunking Test",
 			language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.Ja,
 		},
+		{
+			// English text with ellipsis punctuation (… ‥) - tests fix/text_utils multilingual punctuation
+			// Text length: ~380 characters (exceeds 300 char limit)
+			text: "Sometimes we need to pause and think… The ellipsis character is used to indicate a trailing thought or a pause in speech… This test verifies that the text chunking system correctly handles Unicode ellipsis characters‥ There are multiple types of ellipsis in Unicode… The horizontal ellipsis and the two dot leader are both supported‥ When processing long texts the SDK should split at these punctuation marks… This ensures natural pauses in the generated speech output‥ Let us verify everything works correctly…",
+			label: "Ellipsis punctuation test (… ‥) - 380+ chars",
+			category: "Multilingual Punctuation Test",
+			language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.En,
+		},
+		{
+			// Korean text with ellipsis (…) - tests Korean with Unicode ellipsis
+			// Text length: ~350 characters (exceeds 300 char limit)
+			text: "한국어 텍스트에서 말줄임표는 생각의 흐름을 나타냅니다… 이 테스트는 유니코드 말줄임표 문자가 올바르게 처리되는지 확인합니다… 인공지능 기술이 발전하면서 음성 합성의 품질도 크게 향상되었습니다… 특히 딥러닝을 활용한 최신 시스템은 매우 자연스러운 음성을 생성할 수 있습니다… 긴 텍스트를 처리할 때 SDK는 이러한 구두점에서 적절히 분할해야 합니다… 이를 통해 자연스러운 음성 출력이 가능해집니다… 실시간 스트리밍 기술과 결합하면 더욱 빠른 응답을 제공할 수 있습니다… 음성 합성 기술은 접근성 도구부터 AI 어시스턴트까지 다양하게 활용됩니다… 모든 것이 제대로 작동하는지 확인해 봅시다…",
+			label: "Korean ellipsis punctuation test (…) - 350+ chars",
+			category: "Multilingual Punctuation Test",
+			language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.Ko,
+		},
+		{
+			// Japanese text WITH CJK punctuation (。！？) - tests CJK punctuation splitting
+			// Text length: ~320 characters (exceeds 300 char limit)
+			text: "日本語のテキストは通常スペースを含まないため特別な処理が必要です。このテストは日本語の句読点で正しく分割されることを確認します。自然言語処理技術の発展により音声合成の品質は大幅に向上しました。特にディープラーニングを活用した最新のテキスト音声変換システムは人間の発話に非常に近い自然な音声を生成できます。スペースがない言語では句読点での分割が重要です。このSDKはそのような状況を自動的に検出して適切に処理します。リアルタイムストリーミング技術と組み合わせることで待ち時間を大幅に短縮できます。これにより日本語でも問題なく長いテキストを音声に変換することができます。音声合成技術の未来はとても明るいです。",
+			label: "Japanese CJK punctuation test (。) - 320+ chars",
+			category: "Multilingual Punctuation Test",
+			language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.Ja,
+		},
+		// Pronunciation Dictionary Tests
+		{
+			// Basic pronunciation dictionary test with partial_match=true/false
+			text: "The CEO of OpenAI announced that GPT models are improving. Dr. Smith from MIT said AI research is accelerating.",
+			label: "Pronunciation dictionary (partial_match=true/false)",
+			category: "Pronunciation Dictionary Test",
+			language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.En,
+			pronunciationDictionary: [
+				// partial_match=false: exact word boundary match
+				{ text: "CEO", pronunciation: "Chief Executive Officer", partial_match: false },
+				{ text: "MIT", pronunciation: "Massachusetts Institute of Technology", partial_match: false },
+				{ text: "AI", pronunciation: "Artificial Intelligence", partial_match: false },
+				// partial_match=true: substring match
+				{ text: "GPT", pronunciation: "Generative Pre-trained Transformer", partial_match: true },
+				{ text: "Dr.", pronunciation: "Doctor", partial_match: true },
+			],
+		},
+		{
+			// Pronunciation dictionary causing text expansion to exceed 300 chars (triggers chunking)
+			// Original text: ~190 chars, After expansion: 400+ chars
+			text: "AI and ML are revolutionizing tech. The CEO discussed GPT advancements. Dr. Kim from MIT explained how NLP and CV work together. AWS and GCP provide cloud AI services.",
+			label: "Pronunciation dictionary + Long text chunking (~190 chars -> 400+ chars)",
+			category: "Pronunciation Dictionary + Chunking Test",
+			language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.En,
+			pronunciationDictionary: [
+				// partial_match=false: exact word boundary matches
+				{ text: "AI", pronunciation: "Artificial Intelligence", partial_match: false },
+				{ text: "ML", pronunciation: "Machine Learning", partial_match: false },
+				{ text: "CEO", pronunciation: "Chief Executive Officer", partial_match: false },
+				{ text: "MIT", pronunciation: "Massachusetts Institute of Technology", partial_match: false },
+				{ text: "NLP", pronunciation: "Natural Language Processing", partial_match: false },
+				{ text: "CV", pronunciation: "Computer Vision", partial_match: false },
+				{ text: "AWS", pronunciation: "Amazon Web Services", partial_match: false },
+				{ text: "GCP", pronunciation: "Google Cloud Platform", partial_match: false },
+				// partial_match=true: substring matches
+				{ text: "GPT", pronunciation: "Generative Pre-trained Transformer", partial_match: true },
+				{ text: "Dr.", pronunciation: "Doctor", partial_match: true },
+				{ text: "tech", pronunciation: "technology", partial_match: true },
+			],
+		},
+		{
+			// Korean pronunciation dictionary test
+			text: "SK와 LG의 CEO가 AI와 ML 기술에 대해 발표했습니다. Dr. 김 박사가 MIT에서 NLP 연구 성과를 공개했습니다.",
+			label: "Korean pronunciation dictionary test",
+			category: "Pronunciation Dictionary Test",
+			language: models.APIConvertTextToSpeechUsingCharacterRequestLanguage.Ko,
+			pronunciationDictionary: [
+				{ text: "SK", pronunciation: "에스케이", partial_match: false },
+				{ text: "LG", pronunciation: "엘지", partial_match: false },
+				{ text: "CEO", pronunciation: "최고경영자", partial_match: false },
+				{ text: "AI", pronunciation: "인공지능", partial_match: false },
+				{ text: "ML", pronunciation: "머신러닝", partial_match: false },
+				{ text: "MIT", pronunciation: "매사추세츠 공과대학교", partial_match: false },
+				{ text: "NLP", pronunciation: "자연어처리", partial_match: false },
+				{ text: "Dr.", pronunciation: "닥터", partial_match: true },
+			],
+		},
 	];
 
 	for (let i = 0; i < scenarios.length; i++) {
@@ -472,7 +566,8 @@ async function simpleDemo(): Promise<void> {
 		const success = await simpleStreamingTts(
 			voiceId,
 			scenario.text,
-			scenario.language
+			scenario.language,
+			scenario.pronunciationDictionary
 		);
 
 		if (!success) {
@@ -497,6 +592,15 @@ async function simpleDemo(): Promise<void> {
 	console.log(
 		"   • Character-based chunking: Japanese/Chinese text without spaces"
 	);
+	console.log("\n🌍 Multilingual punctuation tests:");
+	console.log("   • Ellipsis: English (… ‥)");
+	console.log("   • Korean ellipsis: Korean (…)");
+	console.log("   • CJK punctuation: Japanese (。)");
+	console.log("\n📖 Pronunciation dictionary tests:");
+	console.log("   • partial_match=false: Word boundary matching (CEO, MIT, AI)");
+	console.log("   • partial_match=true: Substring matching (GPT, Dr., tech)");
+	console.log("   • Long text chunking: Text expansion exceeding 300 chars");
+	console.log("   • Korean pronunciation: SK, LG, CEO, AI, ML, MIT, NLP");
 }
 
 /**

package/custom_test/test_pronunciation_dictionary.ts

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+/**
+ * Behavior tests for applyPronunciationDictionary().
+ *
+ * Run:
+ *   npx ts-node custom_test/test_pronunciation_dictionary.ts
+ *   # or after build:
+ *   node dist/custom_test/test_pronunciation_dictionary.js
+ */
+
+import {
+	applyPronunciationDictionary,
+	PronunciationDictionaryValidationError,
+	type PronunciationDictionaryEntry,
+} from "../src/lib/custom_utils/pronunciation_utils.js";
+
+function assertEqual(actual: string, expected: string, message: string): void {
+	if (actual !== expected) {
+		throw new Error(`${message}\nexpected=${expected}\nactual=${actual}`);
+	}
+}
+
+function assertThrows(fn: () => void, message: string): void {
+	let threw = false;
+	try {
+		fn();
+	} catch (e) {
+		threw = true;
+		if (!(e instanceof PronunciationDictionaryValidationError)) {
+			throw new Error(`${message}\nexpected PronunciationDictionaryValidationError`);
+		}
+	}
+	if (!threw) {
+		throw new Error(`${message}\nexpected to throw`);
+	}
+}
+
+function runTests(): void {
+	const d = (entries: PronunciationDictionaryEntry[]) => entries;
+
+	assertEqual(applyPronunciationDictionary("hello", undefined), "hello", "none returns original");
+	assertEqual(applyPronunciationDictionary("hello", []), "hello", "empty returns original");
+
+	assertEqual(
+		applyPronunciationDictionary("This is Supertone.", d([{ text: "Supertone", pronunciation: "super tone", partial_match: false }])),
+		"This is super tone.",
+		"basic exact match"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("K-TTS is different from TTSAPI.", d([{ text: "TTS", pronunciation: "text to speech", partial_match: true }])),
+		"K-text to speech is different from text to speechAPI.",
+		"partial match substrings"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("TTS and TTS and TTS.", d([{ text: "TTS", pronunciation: "text to speech", partial_match: true }])),
+		"text to speech and text to speech and text to speech.",
+		"multiple occurrences"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary('He said, "Supertone", (Supertone)!', d([{ text: "Supertone", pronunciation: "super tone", partial_match: false }])),
+		'He said, "super tone", (super tone)!',
+		"punctuation boundaries"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("API_test API test_API", d([{ text: "API", pronunciation: "A P I", partial_match: false }])),
+		"API_test A P I test_API",
+		"word boundary underscore"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("C++ is old, C++11 is newer.", d([{ text: "C++", pronunciation: "cplusplus", partial_match: false }])),
+		"cplusplus is old, C++11 is newer.",
+		"numbers break boundary"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("a(b)c a(b)c", d([{ text: "a(b)c", pronunciation: "X", partial_match: true }])),
+		"X X",
+		"regex meta chars"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("aaaa", d([{ text: "aa", pronunciation: "b", partial_match: true }])),
+		"bb",
+		"non-overlapping left-to-right"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("AAAA", d([
+			{ text: "AA", pronunciation: "B", partial_match: true },
+			{ text: "A", pronunciation: "C", partial_match: true },
+		])),
+		"BB",
+		"order priority AA then A"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("AAAA", d([
+			{ text: "A", pronunciation: "C", partial_match: true },
+			{ text: "AA", pronunciation: "B", partial_match: true },
+		])),
+		"CCCC",
+		"order priority A then AA"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("NY is not New Jersey.", d([
+			{ text: "NY", pronunciation: "New York", partial_match: false },
+			{ text: "New", pronunciation: "Old", partial_match: false },
+		])),
+		"New York is not Old Jersey.",
+		"no resubstitution inside pronunciation"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("이번 APEC 은 한국에서 열립니다", d([
+			{ text: "AP", pronunciation: "에이피", partial_match: true },
+			{ text: "APEC", pronunciation: "에이팩", partial_match: true },
+		])),
+		"이번 에이피EC 은 한국에서 열립니다",
+		"order AP then APEC"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("이번 APEC 은 한국에서 열립니다", d([
+			{ text: "APEC", pronunciation: "에이팩", partial_match: true },
+			{ text: "AP", pronunciation: "에이피", partial_match: true },
+		])),
+		"이번 에이팩 은 한국에서 열립니다",
+		"order APEC then AP"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("Supertone tone", d([
+			{ text: "Supertone", pronunciation: "super tone", partial_match: false },
+			{ text: "tone", pronunciation: "TONE", partial_match: false },
+		])),
+		"super tone TONE",
+		"no resubstitution across rules"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("TTS와 TTSAPI는 다릅니다.", d([{ text: "TTS", pronunciation: "text to speech", partial_match: true }])),
+		"text to speech와 text to speechAPI는 다릅니다.",
+		"Korean partial match"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("東京TTS東京", d([{ text: "TTS", pronunciation: "text to speech", partial_match: false }])),
+		"東京TTS東京",
+		"no boundary in Japanese exact"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("これは「TTS」です。", d([{ text: "TTS", pronunciation: "text to speech", partial_match: false }])),
+		"これは「text to speech」です。",
+		"boundary by punctuation Japanese"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("東京TTS東京", d([{ text: "TTS", pronunciation: "text to speech", partial_match: true }])),
+		"東京text to speech東京",
+		"partial match Japanese"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary(`X \uE000PD0\uE001 Supertone`, d([{ text: "Supertone", pronunciation: "super tone", partial_match: false }])),
+		`X \uE000PD0\uE001 super tone`,
+		"token collision safe"
+	);
+
+	assertEqual(
+		applyPronunciationDictionary("TTS와 TTS.", d([{ text: "TTS", pronunciation: "text to speech", partial_match: false }])),
+		"TTS와 text to speech.",
+		"unicode boundary note"
+	);
+
+	assertThrows(
+		() => applyPronunciationDictionary("hi", {} as any),
+		"validation: dictionary must be array"
+	);
+
+	assertThrows(
+		() => applyPronunciationDictionary("hi", ["not-an-object"] as any),
+		"validation: entry must be object"
+	);
+
+	assertThrows(
+		() => applyPronunciationDictionary("hi", [{ text: 1, pronunciation: "b", partial_match: true }] as any),
+		"validation: text type"
+	);
+
+	assertThrows(
+		() => applyPronunciationDictionary("hi", [{ text: "a", pronunciation: 1, partial_match: true }] as any),
+		"validation: pronunciation type"
+	);
+
+	assertThrows(
+		() => applyPronunciationDictionary("hi", [{ text: "a", pronunciation: "b" }] as any),
+		"validation: missing partial_match"
+	);
+
+	assertThrows(
+		() => applyPronunciationDictionary("hi", [{ text: "a", pronunciation: "b", partial_match: "true" }] as any),
+		"validation: partial_match type"
+	);
+
+	assertThrows(
+		() => applyPronunciationDictionary("hi", [{ text: "", pronunciation: "b", partial_match: true }] as any),
+		"validation: empty text"
+	);
+
+	assertThrows(
+		() => applyPronunciationDictionary("hi", [{ text: "a", pronunciation: "", partial_match: true }] as any),
+		"validation: empty pronunciation"
+	);
+
+	console.log("OK: applyPronunciationDictionary tests passed");
+}
+
+runTests();
+
+