ssml-builder-js 2.1.0 → 2.2.0

package/README.md

@@ -7,7 +7,7 @@
 
 Azure Speech Service で利用できる SSML を、TypeScript のデータ構造から生成・解析し、React の GUI で編集するための npm ワークスペースモノレポです。公開成果物は `ssml-builder-js` という単一の npm パッケージです。
 
-SSML の XML エスケープや Azure Speech 拡張要素に対応したコアライブラリ、Monaco Editor を利用した React コンポーネント、Azure Text-to-Speech API クライアントをサブパスから提供します。
+SSML の XML エスケープや Azure Speech 拡張要素に対応したコアライブラリ、Monaco Editor を利用した React コンポーネント、フレームワーク非依存の Web Component、Azure Text-to-Speech API クライアントをサブパスから提供します。
 
 ## パッケージ構成
 
@@ -16,6 +16,7 @@ SSML の XML エスケープや Azure Speech 拡張要素に対応したコア
 | `ssml-builder-js` | コア機能と Azure Text-to-Speech クライアント |
 | `ssml-builder-js/core` | SSML の型定義、ドキュメントの生成（`buildSsml`）、XML からの解析（`parseSsml`）、構文検証（`validateSsml`） |
 | `ssml-builder-js/react` | ツールバーと本文の表示エリアを備えた `SsmlEditor` コンポーネント |
+| `ssml-builder-js/elements` | React などに依存しない `<ssml-editor>` Web Component |
 
 `ssml-builder-js` と `ssml-builder-js/core` は同じコア機能を提供します。React エディタは `ssml-builder-js/react` から読み込み、Azure TTS クライアントは `ssml-builder-js` から読み込みます。
 
@@ -35,6 +36,12 @@ React エディタを使用する場合は、React と Monaco Editor のアダ
 npm install ssml-builder-js @monaco-editor/react react react-dom
 ```
 
+Web Component を使用する場合は、Monaco Editor もインストールします。
+
+```sh
+npm install ssml-builder-js monaco-editor
+```
+
 Azure TTS クライアントも `ssml-builder-js` から利用できます。
 
 ### リポジトリを開発する場合
@@ -66,6 +73,14 @@ cp apps/playground/.env.example apps/playground/.env.local
 npm run dev --workspace playground
 ```
 
+Playground の表示言語は `ja`、`en`、`ko`、`zh-Hans`、`fr`、`pt-BR`、`it`、`de`、
+`ru` から選択できます。音声設定では `en-US`、`ja-JP`、`ko`、`zh-Hans`、`fr`、
+`pt-BR`、`it`、`de`、`ru` の各言語について、女性・男性の音声を選択できます。
+Playground の表示言語が日本語以外の場合、埋め込みエディターの UI は英語になります。
+テーマは OS の設定に追従し、ライト・ダークを手動で切り替えて保存できます。現在の
+SSML 全体または選択部分を Azure Speech で合成してブラウザーで再生でき、音声には
+SSML 本文のキャプションが付きます。生成された SSML は画面下部に表示されます。
+
 ## `ssml-core` の利用方法
 
 `SsmlDocument` は `version`、`lang`、`children` を持つオブジェクトです。`children` には文字列、テキストノード、SSML 要素を入れられます。`children` を使う形式が推奨され、旧形式の `content` プロパティも `buildSsml` の入力として利用できます。
@@ -124,7 +139,7 @@ const parsed = parseSsml(ssml);
 
 `SsmlEditor` は `SsmlDocument` を受け取り、ツールバーと本文の表示エリアだけを表示するシンプルなコンポーネントです。ツールバーから選択範囲の速度、音量、ピッチなどの設定、元に戻す・やり直す操作ができます。音声の選択と表示はアプリ側で行います。本文の編集には Monaco Editor を使用し、変更時に SSML の構文を検証します。構文エラーはエディター上のマーカーとエラーメッセージで表示されます。XML のタグ名やパラメータへホバーすると SSML の説明を確認できます。テキストを選択すると、選択文字数と試聴を行うフローティングアクションが表示されます。`showDecorations` が有効な場合、`break` と `prosody` のタグに間やピッチ変化を示すインラインバッジが表示され、Monaco のインライン装飾も有効になります。生成された SSML は `onSsmlChange` で受け取り、アプリ側で自由に表示できます。`SsmlEditorRef` を `ref` に渡すと、全体、選択範囲、または現在行の SSML を取得できます。画面表示は日本語（デフォルト）と英語に対応しています。
 
-`<mstts:express-as>` の `style` 属性補完と標準の感情メニューは、カーソルまたは選択範囲を囲む最内の `<voice name="...">` が対応するスタイルだけを表示します。登録済みでスタイル非対応の音声では候補がないことを表示し、音声が未指定または未登録の場合は従来の全候補へフォールバックします。`emotionStyles` を指定した場合、感情メニューではその値と登録済み音声の対応スタイルの共通部分を使用します。
+`<mstts:express-as>` の `style` 属性補完と標準の感情メニューは、カーソルまたは選択範囲を囲む最内の `<voice name="...">` が対応するスタイルだけを表示します。音声名が未指定の場合は全候補を表示し、登録済みでスタイル非対応の音声や未登録の音声では候補がないことを表示します。`emotionStyles` を指定した場合、感情メニューではその値と登録済み音声の対応スタイルの共通部分を使用します。
 
 ```tsx
 import { useState } from "react";
@@ -158,7 +173,7 @@ export function App() {
 - `document`: 編集対象の `SsmlDocument`
 - `onChange`: 編集後の `SsmlDocument` を受け取るコールバック
 - `onSsmlChange`: 編集後に生成された SSML 文字列を受け取るコールバック
-- `ref`: `SsmlEditorRef` の `getFullSsml()` で全体の SSML、`getSelectedSsml()` で選択範囲（未選択時はカーソル行）の SSML、`getCurrentLineSsml()` で現在行の SSML を取得
+- `ref`: `SsmlEditorRef` の `getFullSsml()` で全体の SSML、`getSelectedSsml()` で選択範囲（未選択時は内容が空でないカーソル行）の SSML、`getCurrentLineSsml()` で現在行の SSML を取得。選択範囲やカーソル行が空の場合は `null` を返します
 - `onSelectionChange`: 選択テキスト、文字数、選択状態を受け取るコールバック
 - `onPreviewSelection`: フローティングアクションの試聴ボタン押下時に、選択部分の SSML を受け取るコールバック。省略時は試聴ボタンが無効になります。Azure などの音声 API はこのコールバックから呼び出してください
 - `locale`: 画面表示の言語（`"ja"` または `"en"`）。省略時は `"ja"`。ホバーヘルプを含む UI の翻訳にも使用されます
@@ -187,6 +202,25 @@ export function App() {
 
 「説明」ボタンを押すと、各コントロール、ボタン、設定の説明を表示できます。ボタンの設定はアコーディオンで表示され、デフォルトでは閉じています。アコーディオンのタイトルにはボタンの説明と生成される XML のタグ名が表示され、各設定の意味を確認できます。「全てクリア」ボタンは `voice` 要素を保持したまま、それ以外の XML 要素を削除して本文を残します。ドキュメントの `version`、`lang`、その他の属性も保持されます。
 
+## `ssml-editor-elements` の利用方法
+
+`ssml-builder-js/elements` は、React などに依存しない `<ssml-editor>` Web Component を登録します。`monaco-editor` を別途インストールし、`value`、`theme`、`readonly` 属性または同名プロパティを使用できます。React エディターと同じ SSML ツールバーと説明表示も利用でき、`locale`、`show-toolbar`、`show-toolbar-labels`、`show-decorations` で表示を調整できます。編集時には `{ value }` を `detail` に持つ `change` イベントが発生します。
+
+```ts
+import "ssml-builder-js/elements";
+import type { SsmlEditorElement } from "ssml-builder-js/elements";
+
+const editor = document.querySelector("ssml-editor") as SsmlEditorElement | null;
+if (editor) {
+  editor.value = '<speak version="1.0">編集する本文</speak>';
+  editor.theme = "vs-dark";
+  editor.locale = "ja";
+  editor.addEventListener("change", (event) => {
+    console.log((event as CustomEvent<{ value: string }>).detail.value);
+  });
+}
+```
+
 ## `azure-tts-client` の利用方法
 
 `AzureTtsClient` に Azure Speech のサブスクリプションキーとリージョンを渡し、`synthesize` に SSML を渡します。戻り値は音声データの `ArrayBuffer` です。
@@ -219,7 +253,7 @@ const audio = await synthesizeSpeech(ssml, {
 内部では Microsoft Cognitive Services Speech SDK の `SpeechSynthesizer` を使用します。`AzureTtsClient` の `endpoint` を省略すると `https://{region}.tts.speech.microsoft.com/cognitiveservices/v1` が使用されます。上の Playground の例では `.env.example` に合わせて WebSocket エンドポイントを明示しています。独自エンドポイントに `{region}` を含めた場合は、設定したリージョンに置き換えられます。
 `outputFormat` には Speech SDK がサポートする出力形式を指定できます。省略時は `audio-16khz-128kbitrate-mono-mp3` が使用されます。
 
-Speech SDK の合成エラーでは `AzureTtsSdkError`（`AzureTtsError` のサブクラス）がスローされ、`errorDetails` または `responseBody` から SDK のエラー詳細を確認できます。SDK が HTTP ステータスやリクエスト ID を公開しないため、SDK 経由のエラーでは `status` は `0`、`statusText` は `"Speech SDK"`、`requestId` は `null` です。Playground のサーバー側ログにもこれらの情報とリージョン、SSML の文字数が出力されます。ログに出力するエラー詳細は 4,096 文字までに制限されます。サブスクリプションキーや SSML 本文自体はログに出力されません。
+Speech SDK の合成エラーでは `AzureTtsSdkError`（`AzureTtsError` のサブクラス）がスローされ、`errorDetails` から SDK のエラー詳細を確認できます。SDK が HTTP ステータスやリクエスト ID を公開しないため、SDK 経由のエラーでは `status` は `0`、`statusText` は `"Speech SDK"`、`requestId` は `null` です。Playground のサーバー側ログにもこれらの情報とリージョン、SSML の文字数が出力されます。ログに出力するエラー詳細は 4,096 文字までに制限されます。サブスクリプションキーや SSML 本文自体はログに出力されません。
 
 サブスクリプションキーはリクエストヘッダーに含まれるため、ソースコードへハードコードしたりログへ出力したりしないでください。ブラウザから直接呼び出す場合はキーが利用者へ公開されるため、通常はサーバー側で Azure TTS を呼び出す構成にします。
 
@@ -262,7 +296,7 @@ npm test
 
 SSML-Builder is an npm workspace monorepo for generating and parsing SSML supported by Azure Speech Service from TypeScript data structures and editing it in a React GUI. Its published output is a single npm package, `ssml-builder-js`.
 
-It provides a core library with XML escaping and Azure Speech extension support, a React component based on Monaco Editor, and an Azure Text-to-Speech API client through package subpaths.
+It provides a core library with XML escaping and Azure Speech extension support, a React component based on Monaco Editor, a framework-independent Web Component, and an Azure Text-to-Speech API client through package subpaths.
 
 ## Package structure
 
@@ -271,6 +305,7 @@ It provides a core library with XML escaping and Azure Speech extension support,
 | `ssml-builder-js` | Core functionality and the Azure Text-to-Speech client |
 | `ssml-builder-js/core` | SSML type definitions, document generation (`buildSsml`), XML parsing (`parseSsml`), and syntax validation (`validateSsml`) |
 | `ssml-builder-js/react` | The `SsmlEditor` component with a toolbar and text display area |
+| `ssml-builder-js/elements` | The framework-independent `<ssml-editor>` Web Component |
 
 `ssml-builder-js` and `ssml-builder-js/core` provide the same core functionality. Import the React editor from `ssml-builder-js/react`; the Azure TTS client is available from `ssml-builder-js`.
 
@@ -290,6 +325,12 @@ To use the React editor, also install React and the Monaco Editor adapter:
 npm install ssml-builder-js @monaco-editor/react react react-dom
 ```
 
+To use the Web Component, also install Monaco Editor:
+
+```sh
+npm install ssml-builder-js monaco-editor
+```
+
 The Azure TTS client is also available from `ssml-builder-js`.
 
 ### Developing this repository
@@ -320,6 +361,15 @@ cp apps/playground/.env.example apps/playground/.env.local
 npm run dev --workspace playground
 ```
 
+The playground UI can be displayed in `ja`, `en`, `ko`, `zh-Hans`, `fr`, `pt-BR`, `it`,
+`de`, or `ru`. Speech settings provide female and male voices for `en-US`, `ja-JP`,
+`ko`, `zh-Hans`, `fr`, `pt-BR`, `it`, `de`, and `ru`. The embedded editor supports
+Japanese and English UI, so non-Japanese playground locales use the English editor UI.
+The theme follows the operating system preference until a light or dark mode is selected
+manually, and the manual choice is stored in the browser. You can synthesize the full
+SSML document or the selected text and play it in the browser with an SSML caption track;
+the generated SSML is shown below the editor.
+
 ## Using `ssml-core`
 
 `SsmlDocument` is an object with `version`, `lang`, and `children` properties. `children` can contain strings, text nodes, and SSML elements. The `children` form is recommended; the legacy `content` property is also accepted as input by `buildSsml`.
@@ -378,7 +428,7 @@ Typed representations are available for elements such as `voice`, `prosody`, `br
 
 `SsmlEditor` accepts an `SsmlDocument` and renders only a toolbar and text display area. The toolbar applies rate, volume, and pitch settings to the selection and provides undo and redo actions. The application is responsible for selecting and displaying the voice. Monaco Editor is used for text editing, and SSML syntax is validated whenever the text changes. Syntax errors are shown with editor markers and an error message. Hovering over XML tag names or parameters shows SSML descriptions. Selecting text displays a floating action bar with the character count and preview action. When `showDecorations` is enabled, inline badges for pause and pitch changes are rendered next to `break` and `prosody` tags, and Monaco inline decorations are enabled. Generated SSML is provided through `onSsmlChange` so the application can display it wherever it needs. Pass an `SsmlEditorRef` through `ref` to retrieve full, selected, or current-line SSML, and use `onSelectionChange` to observe selection text and state. The UI supports Japanese (the default) and English.
 
-Completion for the `<mstts:express-as>` `style` attribute and the built-in Emotion menu only show styles supported by the innermost `<voice name="...">` around the cursor or selection. A registered voice with no styles displays an empty-state message, while a missing or unregistered voice falls back to all legacy candidates. When `emotionStyles` is supplied, the Emotion menu uses its intersection with the registered voice's supported styles.
+Completion for the `<mstts:express-as>` `style` attribute and the built-in Emotion menu only show styles supported by the innermost `<voice name="...">` around the cursor or selection. When no voice name is available, all candidates are shown; a registered voice without supported styles or an explicitly unregistered voice displays an empty-state message. When `emotionStyles` is supplied, the Emotion menu uses its intersection with the registered voice's supported styles.
 
 ```tsx
 import { useState } from "react";
@@ -412,7 +462,7 @@ export function App() {
 - `document`: The `SsmlDocument` being edited
 - `onChange`: A callback that receives the edited `SsmlDocument`
 - `onSsmlChange`: A callback that receives the generated SSML string
-- `ref`: An `SsmlEditorRef`; `getFullSsml()` returns the full SSML, `getSelectedSsml()` returns the selected text (or the cursor line when no text is selected), and `getCurrentLineSsml()` returns the current cursor line
+- `ref`: An `SsmlEditorRef`; `getFullSsml()` returns the full SSML, `getSelectedSsml()` returns the selected text (or the cursor line when it contains content), and `getCurrentLineSsml()` returns the current cursor line. The selection and line methods return `null` when their target is empty
 - `onSelectionChange`: A callback that receives selected text, its character count, and whether a selection exists
 - `onPreviewSelection`: A callback that receives the selected partial SSML when the floating preview action is pressed. The preview action is disabled when this callback is omitted; call an audio API such as Azure from the callback
 - `locale`: The UI language (`"ja"` or `"en"`); defaults to `"ja"` and also controls hover-help translations
@@ -441,6 +491,25 @@ The built-in insertion menus are `break`, `emphasis`, `rate`, `pitch`, `volume`,
 
 Click the **Description** button to see descriptions of each control, button, and setting. Button settings are shown in accordions that are closed by default, with the button description and generated XML tag name as the accordion title and the meaning of each setting inside. The **Clear all** button preserves `voice` elements, removes the other XML elements, and leaves the text in place. The document's `version`, `lang`, and other attributes are also preserved.
 
+## Using `ssml-editor-elements`
+
+`ssml-builder-js/elements` registers a framework-independent `<ssml-editor>` Web Component without React. Install `monaco-editor` separately, then use the `value`, `theme`, and `readonly` attributes or properties. The component includes the same SSML toolbar and help display as the React editor; use `locale`, `show-toolbar`, `show-toolbar-labels`, and `show-decorations` to customize it. Editing dispatches a `change` event whose `detail` is `{ value: string }`.
+
+```ts
+import "ssml-builder-js/elements";
+import type { SsmlEditorElement } from "ssml-builder-js/elements";
+
+const editor = document.querySelector("ssml-editor") as SsmlEditorElement | null;
+if (editor) {
+  editor.value = '<speak version="1.0">Text to edit</speak>';
+  editor.theme = "vs-dark";
+  editor.locale = "en";
+  editor.addEventListener("change", (event) => {
+    console.log((event as CustomEvent<{ value: string }>).detail.value);
+  });
+}
+```
+
 ## Using `azure-tts-client`
 
 Pass an Azure Speech subscription key and region to `AzureTtsClient`, then pass SSML to `synthesize`. The return value is an `ArrayBuffer` containing audio data.
@@ -473,7 +542,7 @@ const audio = await synthesizeSpeech(ssml, {
 Internally, the client uses the Microsoft Cognitive Services Speech SDK's `SpeechSynthesizer`. If `endpoint` is omitted from `AzureTtsClient`, `https://{region}.tts.speech.microsoft.com/cognitiveservices/v1` is used. The Playground example explicitly uses the WebSocket endpoint from `.env.example`. If a custom endpoint contains `{region}`, it is replaced with the configured region.
 Set `outputFormat` to a format supported by the Speech SDK. If omitted, `audio-16khz-128kbitrate-mono-mp3` is used.
 
-Speech SDK synthesis errors throw `AzureTtsSdkError` (a subclass of `AzureTtsError`); its `errorDetails` and `responseBody` fields contain the SDK error details. Because the SDK does not expose HTTP status or request IDs, SDK errors use `0` for `status`, `"Speech SDK"` for `statusText`, and `null` for `requestId`. The playground's server-side logs include these fields along with the region and SSML character count. Logged error details are limited to 4,096 characters. The subscription key and SSML content itself are not written to logs.
+Speech SDK synthesis errors throw `AzureTtsSdkError` (a subclass of `AzureTtsError`); its `errorDetails` field contains the SDK error details. Because the SDK does not expose HTTP status or request IDs, SDK errors use `0` for `status`, `"Speech SDK"` for `statusText`, and `null` for `requestId`. The playground's server-side logs include these fields along with the region and SSML character count. Logged error details are limited to 4,096 characters. The subscription key and SSML content itself are not written to logs.
 
 The subscription key is sent in a request header, so do not hard-code it in source code or write it to logs. Calling Azure TTS directly from a browser exposes the key to users; a server-side Azure TTS integration is normally recommended.