kawi-tts 1.1.2__tar.gz

kawi_tts-1.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kawi-TTS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kawi_tts-1.1.2/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: kawi-tts
+Version: 1.1.2
+Summary: Deterministic pronunciation and reconstruction engine for Old Javanese/Kawi.
+Author: Project-TTS-Kawi
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/krispypasta/kawi-tts
+Project-URL: Repository, https://github.com/krispypasta/kawi-tts
+Project-URL: Bug Tracker, https://github.com/krispypasta/kawi-tts/issues
+Project-URL: Documentation, https://github.com/krispypasta/kawi-tts#readme
+Keywords: kawi,old-javanese,linguistics,phonology,g2p,text-to-speech,reconstruction,austronesian
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Text Processing :: Linguistic
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# Kawi-TTS
+
+An open-source deterministic pronunciation and reconstruction engine for Old Javanese (Kawi).
+
+Kawi-TTS is **not** a natural neural TTS system, it does **not** claim to generate historically authentic speech, and it is **not** a linguistic oracle. It is a strictly deterministic pipeline that implements a documented linguistic reconstruction policy and provides reproducible acoustic output through a selected backend.
+
+## What It Does
+
+Kawi-TTS transforms Old Javanese text into phonetic representations and synthesizes them into audio. The pipeline is strictly deterministic:
+
+`Text → Normalization → G2P / Tokenization → Canonical Representation → Profile A / Profile B → Acoustic Mapping → eSpeak-ng → WAV`
+
+The engine resolves linguistic features through two distinct profiles:
+* **Profile A (Reconstructed Spoken):** Represents the historical spoken target. It is explicitly evidence-scoped, includes documented spoken mergers and adaptations, and strictly preserves unresolved items as unresolved where evidence is lacking.
+* **Profile B (Scholarly/Orthographic):** A scholarly reading profile that artificially preserves the intended distinctions of the scholarly orthographic representation (such as unmerged Sanskrit distinctions).
+
+## Important Epistemic Limitation
+
+**The generated audio is NOT claimed to reproduce exactly how historical Old Javanese speakers sounded.**
+
+The software simply operationalizes the project's documented linguistic reconstruction and backend policy. Users must clearly distinguish between:
+1. **Evidence-backed linguistic rules** (e.g., historical spoken mergers)
+2. **Provisional reconstructions** (e.g., adaptation of Sanskrit vocalic liquids to native Javanese phonotactics)
+3. **Engineering policy** (e.g., deferring vowel duration resolution)
+4. **Backend approximations** (e.g., dropping retroflex distinctions due to eSpeak limitations)
+
+## Current Status
+
+* **Core:** The deterministic core is accepted and historically frozen.
+* **Tests:** The current test suite passes 97/97. The 100-form regression corpus passes fully.
+* **Backend:** eSpeak-ng is the current acoustic backend. The `id` (Indonesian) voice is utilized with explicit backend-scoped approximations where native eSpeak support is lacking.
+* **Infrastructure:** Neural TTS is explicitly deferred. The project remains strictly zero-budget compatible. No cloud service or proprietary data is required for core operation.
+* **Distribution:** The package is not yet published to PyPI.
+
+## Quick Start
+
+You can run the engine locally without any cloud dependencies.
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/krispypasta/kawi-tts.git
+cd kawi-tts
+
+# 2. Create and activate a Python virtual environment
+python -m venv venv
+# On Windows: venv\Scripts\activate
+# On Linux/macOS: source venv/bin/activate
+
+# 3. Install the package locally in editable mode
+pip install -e .
+
+# 4. Verify installation by running tests
+python -m unittest discover -s tests -p "test_*.py"
+
+# 5. Use the trace diagnostics CLI
+kawi-trace "sĕkar"
+
+# 6. Generate demo audio (requires eSpeak-ng installed on your system)
+python run_audio_demo.py
+```
+
+## eSpeak Dependency
+
+The deterministic linguistic processing (Normalization, G2P, Profiling) operates entirely independent of eSpeak. However, actual WAV synthesis requires `espeak-ng` to be installed on your system path.
+
+If eSpeak-ng is missing, the pipeline produces an actionable error. The package will **not** silently pretend that dummy audio is real synthesis. Current acoustic mapping supports the eSpeak `id` voice, utilizing explicit `BACKEND_APPROXIMATION` rules to bypass unsupported IPA characters safely.
+
+## Examples
+
+* `sĕkar` — Standard Javanese lexical item. Both profiles map identically to Javanese schwa and native consonants.
+* `BHAṬĀRA` — Sanskrit loan.
+  * *Profile B* preserves the aspirated `bʱ`, retroflex `ṭ`, and duration `aː`.
+  * *Profile A* merges the aspirate to `b`, maps the retroflex to `ṭ`, and leaves duration unresolved.
+  * *Acoustic Mapper* then approximates retroflex `ṭ` to dental `t` for eSpeak compatibility.
+* `śānti` — Sanskrit loan.
+  * *Profile B* preserves palatal sibilant `ś`.
+  * *Profile A* merges it to native `s`.
+* `kṝta` — Sanskrit loan with a long vocalic liquid.
+  * *Profile B* preserves canonical long `r̩ː`.
+  * *Profile A* adapts it to native phonotactics as a short Javanese schwa base (`rə`), deliberately discarding non-native duration as per reconstruction policy.
+
+## Trace / Diagnostics
+
+The `kawi-trace` CLI utility exposes the exact transformation of every string. It traces:
+`Input → Normalized → Canonical → Profile Target → Backend Target`
+
+Backend approximations (e.g., eSpeak's inability to pronounce retroflex consonants) are visibly distinguished in the terminal output from intentional linguistic targets.
+
+## Project Structure
+
+```text
+kawi_tts/        # Core engine (normalization, g2p, acoustic mappers)
+docs/            # Project documentation, policies, and research logs
+tests/           # Test suite and regression corpora
+artifacts/       # Generated WAVs and manifest outputs
+pyproject.toml   # Project build configuration
+```
+
+## Open-Source & Contributing
+
+Kawi-TTS is an open-source research tool.
+* **Evidence Before Code:** Research and evidence must precede any linguistic rule changes. Contributors must not invent pronunciation rules.
+* **Changes:** Modifying linguistic policy requires cited evidence and corresponding regression coverage.
+* **Boundaries:** Backend approximations must remain strictly backend-scoped (within the `AcousticMapper`). The canonical representation must remain protected.
+
+Please see the `docs/` folder for architectural decisions and governance.
+
+## Kawi Learn Relationship
+
+**Kawi Learn** is considered a future, external educational application that may consume Kawi-TTS.
+* **Kawi-TTS:** A strict pronunciation and reconstruction engine.
+* **Kawi Learn:** A future end-user application.
+
+Kawi-TTS must remain entirely independent of Kawi Learn. Kawi Learn does not currently exist as a finished product.
+
+## Future / Deferred Work
+
+The following items are explicitly deferred to protect the zero-budget constraint:
+* Neural TTS models
+* Custom recorded speech corpora
+* New acoustic backends requiring unavailable computational resources
+
+These will only be reopened if specific, resource-compatible packaging requirements are met.
+
+## Research & Citation
+
+Linguistic decisions, open questions, and principal references are maintained in `docs/RESEARCH_LOG.md` and the adjacent policy documents (e.g., `docs/P5_002_ACOUSTIC_PROFILE_POLICY.md`). All linguistic claims within the codebase are tied to these cited policy rules.
+
+## License
+
+Kawi-TTS is licensed under the MIT License. See the `LICENSE` file for details.

kawi_tts-1.1.2/README.md

@@ -0,0 +1,131 @@
+# Kawi-TTS
+
+An open-source deterministic pronunciation and reconstruction engine for Old Javanese (Kawi).
+
+Kawi-TTS is **not** a natural neural TTS system, it does **not** claim to generate historically authentic speech, and it is **not** a linguistic oracle. It is a strictly deterministic pipeline that implements a documented linguistic reconstruction policy and provides reproducible acoustic output through a selected backend.
+
+## What It Does
+
+Kawi-TTS transforms Old Javanese text into phonetic representations and synthesizes them into audio. The pipeline is strictly deterministic:
+
+`Text → Normalization → G2P / Tokenization → Canonical Representation → Profile A / Profile B → Acoustic Mapping → eSpeak-ng → WAV`
+
+The engine resolves linguistic features through two distinct profiles:
+* **Profile A (Reconstructed Spoken):** Represents the historical spoken target. It is explicitly evidence-scoped, includes documented spoken mergers and adaptations, and strictly preserves unresolved items as unresolved where evidence is lacking.
+* **Profile B (Scholarly/Orthographic):** A scholarly reading profile that artificially preserves the intended distinctions of the scholarly orthographic representation (such as unmerged Sanskrit distinctions).
+
+## Important Epistemic Limitation
+
+**The generated audio is NOT claimed to reproduce exactly how historical Old Javanese speakers sounded.**
+
+The software simply operationalizes the project's documented linguistic reconstruction and backend policy. Users must clearly distinguish between:
+1. **Evidence-backed linguistic rules** (e.g., historical spoken mergers)
+2. **Provisional reconstructions** (e.g., adaptation of Sanskrit vocalic liquids to native Javanese phonotactics)
+3. **Engineering policy** (e.g., deferring vowel duration resolution)
+4. **Backend approximations** (e.g., dropping retroflex distinctions due to eSpeak limitations)
+
+## Current Status
+
+* **Core:** The deterministic core is accepted and historically frozen.
+* **Tests:** The current test suite passes 97/97. The 100-form regression corpus passes fully.
+* **Backend:** eSpeak-ng is the current acoustic backend. The `id` (Indonesian) voice is utilized with explicit backend-scoped approximations where native eSpeak support is lacking.
+* **Infrastructure:** Neural TTS is explicitly deferred. The project remains strictly zero-budget compatible. No cloud service or proprietary data is required for core operation.
+* **Distribution:** The package is not yet published to PyPI.
+
+## Quick Start
+
+You can run the engine locally without any cloud dependencies.
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/krispypasta/kawi-tts.git
+cd kawi-tts
+
+# 2. Create and activate a Python virtual environment
+python -m venv venv
+# On Windows: venv\Scripts\activate
+# On Linux/macOS: source venv/bin/activate
+
+# 3. Install the package locally in editable mode
+pip install -e .
+
+# 4. Verify installation by running tests
+python -m unittest discover -s tests -p "test_*.py"
+
+# 5. Use the trace diagnostics CLI
+kawi-trace "sĕkar"
+
+# 6. Generate demo audio (requires eSpeak-ng installed on your system)
+python run_audio_demo.py
+```
+
+## eSpeak Dependency
+
+The deterministic linguistic processing (Normalization, G2P, Profiling) operates entirely independent of eSpeak. However, actual WAV synthesis requires `espeak-ng` to be installed on your system path.
+
+If eSpeak-ng is missing, the pipeline produces an actionable error. The package will **not** silently pretend that dummy audio is real synthesis. Current acoustic mapping supports the eSpeak `id` voice, utilizing explicit `BACKEND_APPROXIMATION` rules to bypass unsupported IPA characters safely.
+
+## Examples
+
+* `sĕkar` — Standard Javanese lexical item. Both profiles map identically to Javanese schwa and native consonants.
+* `BHAṬĀRA` — Sanskrit loan.
+  * *Profile B* preserves the aspirated `bʱ`, retroflex `ṭ`, and duration `aː`.
+  * *Profile A* merges the aspirate to `b`, maps the retroflex to `ṭ`, and leaves duration unresolved.
+  * *Acoustic Mapper* then approximates retroflex `ṭ` to dental `t` for eSpeak compatibility.
+* `śānti` — Sanskrit loan.
+  * *Profile B* preserves palatal sibilant `ś`.
+  * *Profile A* merges it to native `s`.
+* `kṝta` — Sanskrit loan with a long vocalic liquid.
+  * *Profile B* preserves canonical long `r̩ː`.
+  * *Profile A* adapts it to native phonotactics as a short Javanese schwa base (`rə`), deliberately discarding non-native duration as per reconstruction policy.
+
+## Trace / Diagnostics
+
+The `kawi-trace` CLI utility exposes the exact transformation of every string. It traces:
+`Input → Normalized → Canonical → Profile Target → Backend Target`
+
+Backend approximations (e.g., eSpeak's inability to pronounce retroflex consonants) are visibly distinguished in the terminal output from intentional linguistic targets.
+
+## Project Structure
+
+```text
+kawi_tts/        # Core engine (normalization, g2p, acoustic mappers)
+docs/            # Project documentation, policies, and research logs
+tests/           # Test suite and regression corpora
+artifacts/       # Generated WAVs and manifest outputs
+pyproject.toml   # Project build configuration
+```
+
+## Open-Source & Contributing
+
+Kawi-TTS is an open-source research tool.
+* **Evidence Before Code:** Research and evidence must precede any linguistic rule changes. Contributors must not invent pronunciation rules.
+* **Changes:** Modifying linguistic policy requires cited evidence and corresponding regression coverage.
+* **Boundaries:** Backend approximations must remain strictly backend-scoped (within the `AcousticMapper`). The canonical representation must remain protected.
+
+Please see the `docs/` folder for architectural decisions and governance.
+
+## Kawi Learn Relationship
+
+**Kawi Learn** is considered a future, external educational application that may consume Kawi-TTS.
+* **Kawi-TTS:** A strict pronunciation and reconstruction engine.
+* **Kawi Learn:** A future end-user application.
+
+Kawi-TTS must remain entirely independent of Kawi Learn. Kawi Learn does not currently exist as a finished product.
+
+## Future / Deferred Work
+
+The following items are explicitly deferred to protect the zero-budget constraint:
+* Neural TTS models
+* Custom recorded speech corpora
+* New acoustic backends requiring unavailable computational resources
+
+These will only be reopened if specific, resource-compatible packaging requirements are met.
+
+## Research & Citation
+
+Linguistic decisions, open questions, and principal references are maintained in `docs/RESEARCH_LOG.md` and the adjacent policy documents (e.g., `docs/P5_002_ACOUSTIC_PROFILE_POLICY.md`). All linguistic claims within the codebase are tied to these cited policy rules.
+
+## License
+
+Kawi-TTS is licensed under the MIT License. See the `LICENSE` file for details.

kawi_tts-1.1.2/kawi_tts/__init__.py

@@ -0,0 +1,3 @@
+"""Kawi-TTS: Research-grade Text-to-Speech system for Old Javanese."""
+
+__version__ = "1.1.2"

kawi_tts-1.1.2/kawi_tts/acoustic/__init__.py

@@ -0,0 +1,28 @@
+"""Acoustic mapping and backend synthesis interfaces for Kawi-TTS."""
+
+from kawi_tts.acoustic.espeak_backend import (
+    ESpeakBackend,
+    ESpeakNotFoundError,
+    SynthesisResult,
+    create_minimal_wav_header,
+)
+from kawi_tts.acoustic.mapper import (
+    AcousticMapper,
+    AcousticMappingResult,
+    MappedToken,
+    MappingStatus,
+)
+from kawi_tts.acoustic.pipeline import PipelineResult, synthesize
+
+__all__ = [
+    "AcousticMapper",
+    "AcousticMappingResult",
+    "MappedToken",
+    "MappingStatus",
+    "ESpeakBackend",
+    "ESpeakNotFoundError",
+    "SynthesisResult",
+    "create_minimal_wav_header",
+    "PipelineResult",
+    "synthesize",
+]

kawi_tts-1.1.2/kawi_tts/acoustic/espeak_backend.py

@@ -0,0 +1,213 @@
+"""eSpeak-ng acoustic backend interface for Kawi-TTS.
+
+This module invokes eSpeak-ng via its phoneme/IPA input interface to synthesize
+speech from mapped phonetic tokens. It provides mock/dry-run support when eSpeak-ng
+is not installed on the host machine.
+"""
+
+from __future__ import annotations
+
+import shutil
+import struct
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional
+
+
+class ESpeakNotFoundError(RuntimeError):
+    """Raised when an attempt is made to synthesize real audio but eSpeak-ng is not installed."""
+
+
+@dataclass(frozen=True)
+class SynthesisResult:
+    """Detailed result of an acoustic synthesis invocation.
+
+    Attributes:
+        phoneme_input: The phonetic/IPA string passed to the backend.
+        voice: The voice identifier requested (e.g. 'jv', 'id').
+        output_path: Target path for the output WAV file.
+        command: Full CLI argument list constructed for eSpeak-ng.
+        dry_run: Whether synthesis was executed in dry-run/mock mode.
+        audio_generated: Whether a valid WAV file was produced on disk or in memory.
+        bytes_written: Number of bytes written to output_path.
+        audio_bytes: Raw WAV bytes if output_path is None.
+    """
+
+    phoneme_input: str
+    voice: str
+    output_path: Optional[str]
+    command: List[str]
+    dry_run: bool
+    audio_generated: bool
+    bytes_written: int = 0
+    audio_bytes: Optional[bytes] = None
+
+
+def create_minimal_wav_header(sample_rate: int = 22050) -> bytes:
+    """Generate a canonical 44-byte RIFF/WAVE header with 0 data samples for dry-run testing."""
+    num_channels = 1
+    bits_per_sample = 16
+    byte_rate = sample_rate * num_channels * bits_per_sample // 8
+    block_align = num_channels * bits_per_sample // 8
+    data_size = 0
+    riff_chunk_size = 36 + data_size
+    return struct.pack(
+        "<4sI4s4sIHHIIHH4sI",
+        b"RIFF",
+        riff_chunk_size,
+        b"WAVE",
+        b"fmt ",
+        16,
+        1,  # PCM
+        num_channels,
+        sample_rate,
+        byte_rate,
+        block_align,
+        bits_per_sample,
+        b"data",
+        data_size,
+    )
+
+
+class ESpeakBackend:
+    """Wrapper around the eSpeak-ng command-line phoneme synthesis engine."""
+
+    _ESPEAK_ID_APPROXIMATION = {
+        "ə": "@", "əː": "@",
+        "ŋ": "N", "ɲ": "n^", "ɟ": "dZ",
+        "aː": "a", "iː": "i", "uː": "u",
+        "ʈ": "t", "ɖ": "d", "ɳ": "n",
+        "ʃ": "s", "ʂ": "s",
+        "tʰ": "th", "pʰ": "ph", "kʰ": "kh", "cʰ": "ch", "ʈʰ": "th",
+        "bʱ": "bh", "dʱ": "dh", "gʱ": "gh", "ɟʱ": "dZh", "ḍʱ": "dh",
+        "r̩": "r@", "l̩": "l@", "r̩ː": "r@", "l̩ː": "l@",
+        "rə": "r@", "lə": "l@",
+    }
+
+    def __init__(self, executable: Optional[str] = None, voice: str = "jv"):
+        """Initialize the eSpeak backend interface.
+
+        Args:
+            executable: Custom path to espeak-ng/espeak binary. If None, discovers via PATH.
+            voice: Voice name or language code (default 'jv' for Javanese).
+        """
+        self.voice = voice
+        self.executable_path = executable or self._find_executable()
+
+    @property
+    def is_available(self) -> bool:
+        """Check whether a usable eSpeak-ng executable was located on the system."""
+        return self.executable_path is not None
+
+    @staticmethod
+    def _find_executable() -> Optional[str]:
+        """Discover espeak-ng or espeak in system PATH."""
+        return shutil.which("espeak-ng") or shutil.which("espeak")
+
+    def synthesize(
+        self,
+        phoneme_str: str,
+        output_path: Optional[str] = None,
+        *,
+        dry_run: bool = False,
+        create_dummy_wav: bool = False,
+    ) -> SynthesisResult:
+        """Synthesize a phonetic/IPA string to audio.
+
+        Args:
+            phoneme_str: Space-separated backend-ready phoneme string.
+            output_path: File path to save output WAV file. If None, audio is returned in memory.
+            dry_run: If True, simulates execution without invoking the real binary.
+            create_dummy_wav: If True in dry_run mode, writes a minimal 44-byte WAV header
+                to output_path to test file generation workflows.
+
+        Returns:
+            SynthesisResult object documenting the invocation.
+
+        Raises:
+            ESpeakNotFoundError: If dry_run is False but eSpeak-ng is not installed.
+            subprocess.CalledProcessError: If eSpeak-ng execution fails.
+        """
+        target_path = str(output_path) if output_path else None
+        
+        # Apply backend-specific phonetic approximations if using Indonesian voice
+        final_phoneme_str = phoneme_str
+        if self.voice == "id":
+            # Sort replacements by length descending to prevent substring collisions
+            sorted_replacements = sorted(self._ESPEAK_ID_APPROXIMATION.items(), key=lambda x: len(x[0]), reverse=True)
+            for k, v in sorted_replacements:
+                final_phoneme_str = final_phoneme_str.replace(k, v)
+        
+        # Format input phoneme string inside eSpeak [[...]] brackets
+        phoneme_bracketed = f"[[{final_phoneme_str}]]"
+
+        exec_cmd = [
+            self.executable_path or "espeak-ng",
+            "-v",
+            self.voice,
+        ]
+        if target_path:
+            exec_cmd.extend(["-w", target_path])
+        else:
+            exec_cmd.append("--stdout")
+            
+        exec_cmd.append(phoneme_bracketed)
+
+        if dry_run:
+            bytes_written = 0
+            wav_bytes = create_minimal_wav_header() if create_dummy_wav else None
+            if target_path and wav_bytes:
+                Path(target_path).parent.mkdir(parents=True, exist_ok=True)
+                with open(target_path, "wb") as f:
+                    f.write(wav_bytes)
+                bytes_written = len(wav_bytes)
+
+            return SynthesisResult(
+                phoneme_input=final_phoneme_str,
+                voice=self.voice,
+                output_path=target_path,
+                command=exec_cmd,
+                dry_run=True,
+                audio_generated=(create_dummy_wav),
+                bytes_written=bytes_written,
+                audio_bytes=wav_bytes if not target_path else None,
+            )
+
+        # Real execution requested
+        if not self.is_available:
+            raise ESpeakNotFoundError(
+                "eSpeak-ng executable not found in system PATH. To generate real audio:\n"
+                "  1. Install eSpeak-ng (e.g., via 'winget install eSpeak-ng' on Windows, "
+                "'apt install espeak-ng' on Debian/Ubuntu, or from https://github.com/espeak-ng/espeak-ng/releases).\n"
+                "  2. Or instantiate ESpeakBackend(executable='/path/to/espeak-ng').\n"
+                "Alternatively, specify dry_run=True to verify pipeline data flow without generating audio."
+            )
+
+        if target_path:
+            Path(target_path).parent.mkdir(parents=True, exist_ok=True)
+            
+        result = subprocess.run(
+            exec_cmd,
+            check=True,
+            capture_output=True,
+        )
+
+        audio_bytes = None
+        file_size = 0
+        if target_path:
+            file_size = Path(target_path).stat().st_size if Path(target_path).exists() else 0
+        else:
+            audio_bytes = result.stdout
+            file_size = len(audio_bytes)
+
+        return SynthesisResult(
+            phoneme_input=final_phoneme_str,
+            voice=self.voice,
+            output_path=target_path,
+            command=exec_cmd,
+            dry_run=False,
+            audio_generated=(file_size > 0),
+            bytes_written=file_size,
+            audio_bytes=audio_bytes,
+        )