speechmarkdown 0.1.12 → 0.1.14

package/README.md

@@ -2,6 +2,42 @@
 
 High-performance SpeechMarkdown parser written in Rust. Converts [SpeechMarkdown](https://speechmarkdown.com/) syntax to platform-specific SSML for Amazon Alexa, Google Assistant, Microsoft Azure, and more.
 
+## Install
+
+| Language | Package | Install |
+|----------|---------|---------|
+| Rust | [speechmarkdown-rust](https://crates.io/crates/speechmarkdown-rust) | `cargo add speechmarkdown-rust` |
+| Python | [speechmarkdown-rust](https://pypi.org/project/speechmarkdown-rust/) | `pip install speechmarkdown-rust` |
+| Node.js | [speechmarkdown](https://www.npmjs.com/package/speechmarkdown) | `npm install speechmarkdown` |
+| .NET | [SpeechMarkdown](https://www.nuget.org/packages/SpeechMarkdown) | `dotnet add package SpeechMarkdown` |
+| Swift | [Release asset](https://github.com/AACTools/speechmarkdown-rust/releases) | Download `speechmarkdown-swift-package.zip` |
+
+## Supported Platforms
+
+| Platform | String ID |
+|----------|-----------|
+| Amazon Alexa | `"amazon-alexa"` or `"alexa"` |
+| Google Assistant | `"google-assistant"` or `"google"` |
+| Microsoft Azure | `"microsoft-azure"` or `"azure"` |
+| Apple | `"apple"` |
+| W3C | `"w3c"` |
+| Samsung Bixby | `"samsung-bixby"` or `"bixby"` |
+| ElevenLabs | `"elevenlabs"` |
+| IBM Watson | `"ibm-watson"` or `"watson"` |
+
+## API
+
+All bindings expose the same core methods:
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `to_ssml(input, platform)` | `string` | Convert SpeechMarkdown to SSML for the given platform |
+| `to_text(input)` | `string` | Convert SpeechMarkdown to plain text (strips all markup) |
+| `to_smd(ssml)` | `string` | Convert SSML to SpeechMarkdown (best-effort, lossy for unsupported elements) |
+| `parse(input)` | `string` (JSON) | Parse SpeechMarkdown and return the AST as JSON |
+| `is_speech_markdown(input)` | `bool` | Check if a string contains SpeechMarkdown syntax |
+| `validate(input)` | `bool` | Validate that SpeechMarkdown parses without errors |
+
 ## Usage
 
 ### Rust
@@ -14,61 +50,62 @@ let ssml = SpeechMarkdownParser::to_ssml(
     "Hello (world)[emphasis:\"strong\"]",
     Platform::AmazonAlexa,
 )?;
-// => <speak>Hello <emphasis level="strong">world</emphasis></speak>
 
 // Convert to plain text
 let text = SpeechMarkdownParser::to_text("Hello (world)[emphasis:\"strong\"]")?;
-// => Hello world
 
-// Parse to AST (JSON)
+// Parse to AST (JSON string)
 let ast = SpeechMarkdownParser::parse("Hello world")?;
+
+// Check if input contains SpeechMarkdown syntax
+if SpeechMarkdownParser::is_speech_markdown(&input) {
+    // ...
+}
+
+// Validate input
+SpeechMarkdownParser::validate(&input)?;
+
+// Convert SSML back to SpeechMarkdown (best-effort)
+let smd = SpeechMarkdownParser::to_smd(r#"<speak><emphasis level="strong">word</emphasis></speak>"#)?;
+// Returns: ++word++
 ```
 
-### Supported Platforms
+### Python
 
-| Platform | Enum Value | String ID |
-|----------|-----------|-----------|
-| Amazon Alexa | `Platform::AmazonAlexa` | `"amazon-alexa"` or `"alexa"` |
-| Google Assistant | `Platform::GoogleAssistant` | `"google-assistant"` or `"google"` |
-| Microsoft Azure | `Platform::MicrosoftAzure` | `"microsoft-azure"` or `"azure"` |
-| Apple | `Platform::Apple` | `"apple"` |
-| W3C | `Platform::W3c` | `"w3c"` |
-| Samsung Bixby | `Platform::SamsungBixby` | `"samsung-bixby"` or `"bixby"` |
-| ElevenLabs | `Platform::ElevenLabs` | `"elevenlabs"` |
-| IBM Watson | `Platform::IbmWatson` | `"ibm-watson"` or `"watson"` |
+```python
+from speechmarkdown_rust import to_ssml, to_text, parse, is_speech_markdown, validate
 
-## Language Bindings
+ssml = to_ssml('Hello (world)[emphasis:"strong"]', 'amazon-alexa')
+text = to_text('Hello (world)[emphasis:"strong"]')
+ast = parse('Hello world')
 
-The library exposes a C ABI (`cdylib`/`staticlib`) so it can be used from any language. Pre-built bindings are provided for .NET, Swift, and Node.js.
+is_smd = is_speech_markdown('Hello (world)[emphasis:"strong"]')  # True
+is_smd = is_speech_markdown('Hello world')                       # False
 
-### Build the native library
+validate('Hello (world)[emphasis:"strong"]')  # raises ValueError if invalid
 
-```bash
-cargo build --release
+# Convert SSML to SpeechMarkdown (best-effort)
+smd = to_smd('<speak><emphasis level="strong">word</emphasis></speak>')
+# Returns: ++word++
 ```
 
-This produces:
-- **Windows**: `target/release/speechmarkdown_rust.dll`
-- **macOS**: `target/release/libspeechmarkdown_rust.dylib`
-- **Linux**: `target/release/libspeechmarkdown_rust.so`
+### Node.js
 
-### C API
+```js
+const { to_ssml, to_text, parse, is_speech_markdown, validate } = require('speechmarkdown')
 
-```c
-#include "bindings/speechmarkdown.h"
+const ssml = to_ssml('Hello (world)[emphasis:"strong"]', 'amazon-alexa')
+const text = to_text('Hello (world)[emphasis:"strong"]')
+const ast = parse('Hello world')
 
-// Convert SpeechMarkdown to SSML
-const char* ssml = speechmarkdown_to_ssml("Hello (world)[emphasis:\"strong\"]", "amazon-alexa");
-printf("%s\n", ssml);
-speechmarkdown_free((char*)ssml);
+is_speech_markdown('Hello (world)[emphasis:"strong"]')  // true
+is_speech_markdown('Hello world')                       // false
 
-// Convert to plain text
-const char* text = speechmarkdown_to_text("Hello (world)[emphasis:\"strong\"]");
-printf("%s\n", text);
-speechmarkdown_free((char*)text);
+validate('Hello (world)[emphasis:"strong"]')  // throws if invalid
 
-// Get last error (thread-local)
-const char* err = speechmarkdown_get_error();
+// Convert SSML to SpeechMarkdown (best-effort)
+const smd = to_smd('<speak><emphasis level="strong">word</emphasis></speak>')
+// Returns: ++word++
 ```
 
 ### .NET (C#)
@@ -81,12 +118,24 @@ var parser = new SpeechMarkdownParser();
 string ssml = parser.ToSsml("Hello (world)[emphasis:\"strong\"]", Platform.AmazonAlexa);
 string text = parser.ToText("Hello (world)[emphasis:\"strong\"]");
 string json = parser.ParseToJson("Hello world");
-```
 
-Copy `bindings/dotnet/SpeechMarkdown.cs` into your project and place the native library in your output directory alongside the assembly.
+bool isSmd = parser.IsSpeechMarkdown("Hello (world)[emphasis:\"strong\"]"); // true
+parser.Validate("Hello (world)[emphasis:\"strong\"]"); // throws on invalid
+
+// Convert SSML to SpeechMarkdown (best-effort)
+string smd = parser.ToSmd("<speak><emphasis level=\"strong\">word</emphasis></speak>");
+// Returns: ++word++
+```
 
 ### Swift
 
+Download `speechmarkdown-swift-package.zip` from the [latest release](https://github.com/AACTools/speechmarkdown-rust/releases), unzip it, and add it as a local package in Xcode:
+
+1. **Xcode**: File > Add Packages > Add Local > select the unzipped directory
+2. **Or in Package.swift**: `.package(path: "./path/to/speechmarkdown-swift-package")`
+
+To build from source instead: `./build-swift-package.sh` (requires Rust toolchain with `aarch64-apple-darwin` and `x86_64-apple-darwin` targets)
+
 ```swift
 import SpeechMarkdown
 
@@ -95,32 +144,57 @@ let parser = SpeechMarkdownParser()
 let ssml = try parser.toSsml(input: "Hello (world)[emphasis:\"strong\"]", platform: "amazon-alexa")
 let text = try parser.toText(input: "Hello (world)[emphasis:\"strong\"]")
 let json = try parser.parseToJson(input: "Hello world")
+
+let isSmd = parser.isSpeechMarkdown(input: "Hello (world)[emphasis:\"strong\"]") // true
+try parser.validate(input: "Hello (world)[emphasis:\"strong\"]") // throws on invalid
+
+// Convert SSML to SpeechMarkdown (best-effort)
+let smd = try parser.toSmd(ssml: "<speak><emphasis level=\"strong\">word</emphasis></speak>")
+// Returns: ++word++
 ```
 
-Include `bindings/swift/SpeechMarkdown.swift`, `bindings/swift/module.modulemap`, and `bindings/speechmarkdown.h` in your Xcode project. Link against the compiled `.dylib`.
+### C API
 
-### Node.js
+```c
+#include "speechmarkdown.h"
 
-```js
-const { SpeechMarkdownParser } = require('./bindings/nodejs');
+// Convert to SSML
+const char* ssml = speechmarkdown_to_ssml("Hello (world)[emphasis:\"strong\"]", "amazon-alexa");
+speechmarkdown_free((char*)ssml);
 
-const parser = new SpeechMarkdownParser();
+// Convert to plain text
+const char* text = speechmarkdown_to_text("Hello (world)[emphasis:\"strong\"]");
+speechmarkdown_free((char*)text);
 
-const ssml = parser.toSsml('Hello (world)[emphasis:"strong"]', 'amazon-alexa');
-const text = parser.toText('Hello (world)[emphasis:"strong"]');
-const json = parser.parseToJson('Hello world');
-```
+// Parse to JSON
+const char* json = speechmarkdown_parse("Hello world");
+speechmarkdown_free((char*)json);
 
-Install `ffi-napi` and `ref-napi` as dependencies. Build the native library first with `cargo build --release`.
+// Check for SpeechMarkdown syntax
+bool is_smd = speechmarkdown_is_speech_markdown("Hello (world)[emphasis:\"strong\"]");
 
-### Python
+// Validate
+bool valid = speechmarkdown_validate("Hello (world)[emphasis:\"strong\"]");
 
-```python
-from speechmarkdown import to_ssml, to_text, parse
+// Convert SSML to SpeechMarkdown (best-effort)
+const char* smd = speechmarkdown_to_smd("<speak><emphasis level=\"strong\">word</emphasis></speak>");
+speechmarkdown_free((char*)smd);
 
-ssml = to_ssml('Hello (world)[emphasis:"strong"]', 'amazon-alexa')
-text = to_text('Hello (world)[emphasis:"strong"]')
-ast = parse('Hello world')  # returns dict
+// Get last error (thread-local)
+const char* err = speechmarkdown_get_error();
 ```
 
-Available on [PyPI](https://pypi.org/project/speechmarkdown-rust/) as `speechmarkdown-rust`.
+## Building from Source
+
+```bash
+cargo build --release
+```
+
+This produces:
+- **Windows**: `target/release/speechmarkdown_rust.dll`
+- **macOS**: `target/release/libspeechmarkdown_rust.dylib`
+- **Linux**: `target/release/libspeechmarkdown_rust.so`
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "speechmarkdown",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "SpeechMarkdown parser - convert SpeechMarkdown to SSML",
   "main": "index.js",
   "types": "index.d.ts",
@@ -10,7 +10,7 @@
     "build:debug": "napi build --platform",
     "prepublishOnly": "napi prepublish -t npm",
     "test": "node test.js",
-    "version": "0.1.12"
+    "version": "0.1.14"
   },
   "keywords": [
     "speech",