ssmd 0.1.0__py3-none-any.whl

ssmd/__init__.py

@@ -0,0 +1,143 @@
+"""SSMD - Speech Synthesis Markdown to SSML converter.
+
+SSMD provides a lightweight markdown-like syntax for creating SSML
+(Speech Synthesis Markup Language) documents. It's designed to be
+more human-friendly than raw SSML while maintaining full compatibility.
+
+Example:
+    Basic usage::
+
+        import ssmd
+
+        # Create and build a document
+        doc = ssmd.Document()
+        doc.add_sentence("Hello *world*!")
+        doc.add_sentence("This is SSMD.")
+
+        # Export to different formats
+        ssml = doc.to_ssml()
+        text = doc.to_text()
+
+        # Or use convenience functions for one-off conversions
+        ssml = ssmd.to_ssml("Hello *world*!")
+
+    Advanced usage with streaming::
+
+        # Create parser with custom config
+        doc = ssmd.Document(
+            capabilities='pyttsx3',
+            config={'auto_sentence_tags': True}
+        )
+
+        # Build document incrementally
+        doc.add_paragraph("# Welcome")
+        doc.add_sentence("Hello and *welcome* to SSMD!")
+
+        # Stream to TTS
+        for sentence in doc.sentences():
+            tts_engine.speak(sentence)
+"""
+
+from typing import Any
+
+from ssmd.document import Document
+from ssmd.ssml_parser import SSMLParser
+from ssmd.capabilities import (
+    TTSCapabilities,
+    get_preset,
+    ESPEAK_CAPABILITIES,
+    PYTTSX3_CAPABILITIES,
+    GOOGLE_TTS_CAPABILITIES,
+    AMAZON_POLLY_CAPABILITIES,
+    AZURE_TTS_CAPABILITIES,
+    MINIMAL_CAPABILITIES,
+    FULL_CAPABILITIES,
+)
+
+try:
+    from ssmd._version import version as __version__
+except ImportError:
+    __version__ = "unknown"
+
+
+# ═══════════════════════════════════════════════════════════
+# CONVENIENCE FUNCTIONS
+# ═══════════════════════════════════════════════════════════
+
+
+def to_ssml(ssmd_text: str, **config: Any) -> str:
+    """Convert SSMD to SSML (convenience function).
+
+    Creates a temporary Document and converts to SSML.
+    For repeated conversions with the same config, create a Document instance.
+
+    Args:
+        ssmd_text: SSMD markdown text
+        **config: Optional configuration parameters
+
+    Returns:
+        SSML string
+
+    Example:
+        >>> ssmd.to_ssml("Hello *world*!")
+        '<speak>Hello <emphasis>world</emphasis>!</speak>'
+    """
+    return Document(ssmd_text, config).to_ssml()
+
+
+def to_text(ssmd_text: str, **config: Any) -> str:
+    """Convert SSMD to plain text (convenience function).
+
+    Strips all SSMD markup, returning plain text.
+
+    Args:
+        ssmd_text: SSMD markdown text
+        **config: Optional configuration parameters
+
+    Returns:
+        Plain text with markup removed
+
+    Example:
+        >>> ssmd.to_text("Hello *world* @marker!")
+        'Hello world!'
+    """
+    return Document(ssmd_text, config).to_text()
+
+
+def from_ssml(ssml_text: str, **config: Any) -> str:
+    """Convert SSML to SSMD format (convenience function).
+
+    Args:
+        ssml_text: SSML XML string
+        **config: Optional configuration parameters
+
+    Returns:
+        SSMD markdown string
+
+    Example:
+        >>> ssml = '<speak><emphasis>Hello</emphasis> world</speak>'
+        >>> ssmd.from_ssml(ssml)
+        '*Hello* world'
+    """
+    parser = SSMLParser(config)
+    return parser.to_ssmd(ssml_text)
+
+
+__all__ = [
+    "Document",
+    "to_ssml",
+    "to_text",
+    "from_ssml",
+    "SSMLParser",
+    "TTSCapabilities",
+    "get_preset",
+    # Capability presets
+    "ESPEAK_CAPABILITIES",
+    "PYTTSX3_CAPABILITIES",
+    "GOOGLE_TTS_CAPABILITIES",
+    "AMAZON_POLLY_CAPABILITIES",
+    "AZURE_TTS_CAPABILITIES",
+    "MINIMAL_CAPABILITIES",
+    "FULL_CAPABILITIES",
+    "__version__",
+]

ssmd/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

ssmd/annotations/__init__.py

@@ -0,0 +1,44 @@
+"""SSMD annotations for extended syntax in [text](annotations) format."""
+
+from typing import Optional
+
+from ssmd.annotations.base import BaseAnnotation
+
+
+def get_annotation(annotation_str: str) -> BaseAnnotation | None:
+    """Try to create an annotation from a string.
+
+    Args:
+        annotation_str: Annotation string (e.g., "en", "ph: dIC", "vrp: 555")
+
+    Returns:
+        Annotation instance or None if no match
+    """
+    from ssmd.annotations.audio import AudioAnnotation
+    from ssmd.annotations.extension import ExtensionAnnotation
+    from ssmd.annotations.language import LanguageAnnotation
+    from ssmd.annotations.phoneme import PhonemeAnnotation
+    from ssmd.annotations.prosody import ProsodyAnnotation
+    from ssmd.annotations.say_as import SayAsAnnotation
+    from ssmd.annotations.substitution import SubstitutionAnnotation
+
+    # Try each annotation type in order
+    annotation_types: list[type[BaseAnnotation]] = [
+        AudioAnnotation,  # Try audio first (has URL pattern)
+        ExtensionAnnotation,  # Extensions (ext: name)
+        SayAsAnnotation,  # Say-as (as: type)
+        PhonemeAnnotation,  # Phonemes (ph: ..., ipa: ...)
+        ProsodyAnnotation,  # Prosody (vrp: 555, v: 5, etc.)
+        SubstitutionAnnotation,  # Substitution (sub: alias)
+        LanguageAnnotation,  # Language (en, en-US, etc.)
+    ]
+
+    for annotation_type in annotation_types:
+        annotation = annotation_type.try_create(annotation_str)
+        if annotation:
+            return annotation
+
+    return None
+
+
+__all__ = ["get_annotation"]

ssmd/annotations/audio.py

@@ -0,0 +1,52 @@
+"""Audio annotation: [desc](url.mp3 alt) → <audio>desc</audio>"""
+
+import re
+
+from ssmd.annotations.base import BaseAnnotation
+
+
+class AudioAnnotation(BaseAnnotation):
+    """Process audio file annotations.
+
+    Examples:
+        [boing](https://example.com/sounds/boing.mp3) →
+            <audio src="..."><desc>boing</desc></audio>
+        [purr](cat.ogg Sound didn't load) →
+            <audio src="cat.ogg"><desc>purr</desc>Sound didn't load</audio>
+        [](miaou.mp3) → <audio src="miaou.mp3"></audio>
+    """
+
+    def __init__(self, match: re.Match):
+        """Initialize with URL and optional alt text.
+
+        Args:
+            match: Regex match containing URL and alt text
+        """
+        self.url = match.group(1).strip()
+        self.alt_text = match.group(2).strip() if match.group(2) else ""
+
+    @classmethod
+    def regex(cls) -> re.Pattern:
+        """Match audio file URLs.
+
+        Returns:
+            Pattern matching audio file extensions with optional alt text
+        """
+        # Match URL (anything starting with http/https or ending in audio extension)
+        # Followed by optional alt text
+        return re.compile(
+            r"^((?:https?://)?[^\s]+\.(?:mp3|ogg|wav|m4a|aac|flac))(?:\s+(.+))?$",
+            re.IGNORECASE,
+        )
+
+    def wrap(self, text: str) -> str:
+        """Wrap in audio tag with description and alt text.
+
+        Args:
+            text: Description text (used in <desc>)
+
+        Returns:
+            SSML <audio> element
+        """
+        desc = f"<desc>{text}</desc>" if text else ""
+        return f'<audio src="{self.url}">{desc}{self.alt_text}</audio>'

ssmd/annotations/base.py

@@ -0,0 +1,61 @@
+"""Base annotation class for SSMD conversion."""
+
+import re
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class BaseAnnotation(ABC):
+    """Abstract base class for annotations.
+
+    Annotations are specified in the format [text](annotation)
+    where annotation can be language codes, phonemes, prosody, etc.
+    """
+
+    @classmethod
+    @abstractmethod
+    def regex(cls) -> re.Pattern:
+        """Pattern to match this annotation type.
+
+        Returns:
+            Compiled regex pattern
+        """
+        pass
+
+    @classmethod
+    def try_create(cls, annotation_str: str) -> Optional["BaseAnnotation"]:
+        """Try to create annotation from string.
+
+        Args:
+            annotation_str: Annotation string to parse
+
+        Returns:
+            Annotation instance or None if no match
+        """
+        match = cls.regex().match(annotation_str.strip())
+        if match:
+            return cls(match)  # type: ignore[call-arg]
+        return None
+
+    @abstractmethod
+    def wrap(self, text: str) -> str:
+        """Wrap text in SSML element.
+
+        Args:
+            text: Content to wrap
+
+        Returns:
+            SSML string with text wrapped
+        """
+        pass
+
+    def combine(self, other: "BaseAnnotation") -> None:  # noqa: B027
+        """Combine with duplicate annotation.
+
+        Default behavior: first annotation wins, ignore duplicates.
+        Override this method to implement custom combining logic.
+
+        Args:
+            other: Another annotation of the same type
+        """
+        pass  # Default: ignore duplicate

ssmd/annotations/extension.py

@@ -0,0 +1,87 @@
+"""Extension annotation: [text](ext: whisper) → platform-specific SSML"""
+
+import re
+from collections.abc import Callable
+from typing import Optional
+
+from ssmd.annotations.base import BaseAnnotation
+
+
+class ExtensionAnnotation(BaseAnnotation):
+    """Process platform-specific extension annotations.
+
+    Examples:
+        [whispers](ext: whisper) →
+            <amazon:effect name="whispered">whispers</amazon:effect>
+        [url](ext: audio) → <audio src="url"/>
+
+    Extensions can be registered via config['extensions'].
+    """
+
+    # Built-in extensions
+    DEFAULT_EXTENSIONS: dict[str, Callable[[str], str]] = {
+        "whisper": lambda text: (
+            f'<amazon:effect name="whispered">{text}</amazon:effect>'
+        ),
+        "audio": lambda text: f'<audio src="{text}"/>',
+    }
+
+    def __init__(
+        self,
+        match: re.Match,
+        custom_extensions: dict[str, Callable[[str], str]] | None = None,
+    ):
+        """Initialize with extension name.
+
+        Args:
+            match: Regex match containing extension name
+            custom_extensions: Optional custom extension handlers
+        """
+        self.extension_name = match.group(1).strip()
+        self.extensions: dict[str, Callable[[str], str]] = {
+            **self.DEFAULT_EXTENSIONS,
+            **(custom_extensions or {}),
+        }
+
+    @classmethod
+    def regex(cls) -> re.Pattern:
+        """Match extension annotations.
+
+        Returns:
+            Pattern matching ext: annotations
+        """
+        return re.compile(r"^ext:\s*(\w+)$")
+
+    @classmethod
+    def try_create(cls, annotation_str: str) -> Optional["ExtensionAnnotation"]:
+        """Try to create annotation with custom extensions from config.
+
+        Note: This override is needed to pass custom extensions from config.
+        In practice, the AnnotationProcessor should handle this.
+
+        Args:
+            annotation_str: Annotation string
+
+        Returns:
+            ExtensionAnnotation instance or None
+        """
+        match = cls.regex().match(annotation_str.strip())
+        if match:
+            return cls(match)
+        return None
+
+    def wrap(self, text: str) -> str:
+        """Wrap text using extension handler.
+
+        Args:
+            text: Content to wrap
+
+        Returns:
+            Platform-specific SSML
+        """
+        handler = self.extensions.get(self.extension_name)
+        if handler is not None:
+            return handler(text)
+
+        # Unknown extension, return unchanged
+        return text

ssmd/annotations/language.py

@@ -0,0 +1,67 @@
+"""Language annotation: [text](en) → <lang xml:lang="en-US">text</lang>"""
+
+import re
+
+from ssmd.annotations.base import BaseAnnotation
+
+
+class LanguageAnnotation(BaseAnnotation):
+    """Process language code annotations.
+
+    Examples:
+        [text](en) → <lang xml:lang="en-US">text</lang>
+        [text](en-GB) → <lang xml:lang="en-GB">text</lang>
+        [text](de) → <lang xml:lang="de-DE">text</lang>
+    """
+
+    # Language code defaults (2-letter code → full locale)
+    DEFAULTS = {
+        "en": "en-US",
+        "de": "de-DE",
+        "fr": "fr-FR",
+        "es": "es-ES",
+        "it": "it-IT",
+        "pt": "pt-PT",
+        "ru": "ru-RU",
+        "zh": "zh-CN",
+        "ja": "ja-JP",
+        "ko": "ko-KR",
+        "ar": "ar-SA",
+        "hi": "hi-IN",
+        "nl": "nl-NL",
+        "pl": "pl-PL",
+        "sv": "sv-SE",
+        "da": "da-DK",
+        "no": "no-NO",
+        "fi": "fi-FI",
+    }
+
+    def __init__(self, match: re.Match):
+        """Initialize with language code.
+
+        Args:
+            match: Regex match containing language code
+        """
+        lang_code = match.group(1)
+        # Auto-complete if only 2-letter code
+        self.lang = self.DEFAULTS.get(lang_code, lang_code)
+
+    @classmethod
+    def regex(cls) -> re.Pattern:
+        """Match language codes.
+
+        Returns:
+            Pattern matching 2-letter or full locale codes
+        """
+        return re.compile(r"^([a-z]{2}(?:-[A-Z]{2})?)$")
+
+    def wrap(self, text: str) -> str:
+        """Wrap text in lang tag.
+
+        Args:
+            text: Content to wrap
+
+        Returns:
+            SSML <lang> element
+        """
+        return f'<lang xml:lang="{self.lang}">{text}</lang>'

ssmd/annotations/phoneme.py

@@ -0,0 +1,100 @@
+"""Phoneme annotation: [text](ph: dIC) → <phoneme>text</phoneme>"""
+
+import re
+from pathlib import Path
+
+from ssmd.annotations.base import BaseAnnotation
+
+
+class PhonemeAnnotation(BaseAnnotation):
+    """Process phoneme annotations.
+
+    Supports both X-SAMPA and IPA notation:
+        [text](ph: dIC) → <phoneme alphabet="ipa" ph="dɪç">text</phoneme>
+        [text](ipa: dɪç) → <phoneme alphabet="ipa" ph="dɪç">text</phoneme>
+    """
+
+    # Lazy-loaded X-SAMPA to IPA conversion table
+    _XSAMPA_TABLE: dict[str, str] | None = None
+
+    def __init__(self, match: re.Match):
+        """Initialize with phoneme data.
+
+        Args:
+            match: Regex match containing alphabet type and phonemes
+        """
+        alphabet = match.group(1)  # 'ph' or 'ipa'
+        phonemes = match.group(2).strip()
+
+        # Convert X-SAMPA to IPA if needed
+        if alphabet == "ph":
+            self.phonemes = self._xsampa_to_ipa(phonemes)
+        else:
+            self.phonemes = phonemes
+
+    @classmethod
+    def regex(cls) -> re.Pattern:
+        """Match phoneme annotations.
+
+        Returns:
+            Pattern matching ph: or ipa: annotations
+        """
+        return re.compile(r"^(ph|ipa):\s*(.+)$")
+
+    def wrap(self, text: str) -> str:
+        """Wrap text in phoneme tag.
+
+        Args:
+            text: Content to wrap
+
+        Returns:
+            SSML <phoneme> element
+        """
+        return f'<phoneme alphabet="ipa" ph="{self.phonemes}">{text}</phoneme>'
+
+    @classmethod
+    def _load_xsampa_table(cls) -> dict[str, str]:
+        """Load X-SAMPA to IPA conversion table.
+
+        Returns:
+            Dictionary mapping X-SAMPA to IPA
+        """
+        if cls._XSAMPA_TABLE is not None:
+            return cls._XSAMPA_TABLE
+
+        table = {}
+        table_file = Path(__file__).parent / "xsampa_to_ipa.txt"
+
+        if table_file.exists():
+            with open(table_file, encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if line and not line.startswith("#"):
+                        parts = line.split(maxsplit=1)
+                        if len(parts) == 2:
+                            xsampa, ipa = parts
+                            table[xsampa] = ipa
+
+        cls._XSAMPA_TABLE = table
+        return table
+
+    @classmethod
+    def _xsampa_to_ipa(cls, xsampa: str) -> str:
+        """Convert X-SAMPA notation to IPA.
+
+        Args:
+            xsampa: X-SAMPA phoneme string
+
+        Returns:
+            IPA phoneme string
+        """
+        table = cls._load_xsampa_table()
+
+        # Sort by length (longest first) for proper replacement
+        sorted_keys = sorted(table.keys(), key=len, reverse=True)
+
+        result = xsampa
+        for x in sorted_keys:
+            result = result.replace(x, table[x])
+
+        return result