md2speech 0.1.0__py3-none-any.whl

md2speech/__init__.py

@@ -0,0 +1,40 @@
+"""Convert Markdown and plain text files to speech audio using Kokoro-82M."""
+
+from md2speech.audio import AudioWriter
+from md2speech.engine import TTSEngine
+from md2speech.reader import extract_plain_text, read_document
+from md2speech.synthesize import SynthesisResult, synthesize_file
+from md2speech.voices import (
+    DEFAULT_LANG,
+    DEFAULT_VOICE,
+    LANG_CODES,
+    VOICES_BY_LANG,
+    default_voice_for_lang,
+    infer_lang_from_voice,
+    list_languages,
+    list_voices,
+    resolve_lang_code,
+    resolve_voice_and_lang,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AudioWriter",
+    "DEFAULT_LANG",
+    "DEFAULT_VOICE",
+    "LANG_CODES",
+    "SynthesisResult",
+    "TTSEngine",
+    "VOICES_BY_LANG",
+    "default_voice_for_lang",
+    "extract_plain_text",
+    "infer_lang_from_voice",
+    "list_languages",
+    "list_voices",
+    "read_document",
+    "resolve_lang_code",
+    "resolve_voice_and_lang",
+    "synthesize_file",
+    "__version__",
+]

md2speech/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as ``python -m md2speech``."""
+
+from md2speech.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

md2speech/audio.py

@@ -0,0 +1,147 @@
+"""Audio post-processing and format export."""
+
+from __future__ import annotations
+
+import logging
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+from scipy.signal import resample_poly
+from pydub import AudioSegment
+
+logger = logging.getLogger(__name__)
+
+OUTPUT_SAMPLE_RATE = 44_100
+FFMPEG_FORMATS = {"mp3", "ogg", "flac"}
+
+
+@dataclass(frozen=True)
+class WriteResult:
+    """Metadata returned after writing an audio file."""
+
+    path: Path
+    duration_seconds: float
+    sample_rate: int
+
+
+class AudioWriter:
+    """Post-process and export synthesized audio to disk."""
+
+    def __init__(self, sample_rate: int = OUTPUT_SAMPLE_RATE) -> None:
+        self.sample_rate = sample_rate
+
+    @staticmethod
+    def peak_normalize(audio: np.ndarray, target_dbfs: float = -1.5) -> np.ndarray:
+        """Normalize audio peak to the target dBFS level."""
+        if audio.size == 0:
+            return audio
+
+        peak = np.max(np.abs(audio))
+        if peak == 0:
+            return audio
+
+        target_linear = 10 ** (target_dbfs / 20.0)
+        return (audio * (target_linear / peak)).astype(np.float32)
+
+    @staticmethod
+    def add_silence_padding(
+        audio: np.ndarray,
+        sample_rate: int,
+        pad_ms: float = 100,
+    ) -> np.ndarray:
+        """Add silence before and after the audio."""
+        if audio.size == 0:
+            return audio
+
+        pad_samples = int(sample_rate * pad_ms / 1000.0)
+        padding = np.zeros(pad_samples, dtype=np.float32)
+        return np.concatenate([padding, audio, padding])
+
+    @staticmethod
+    def resample(
+        audio: np.ndarray,
+        orig_sr: int,
+        target_sr: int = OUTPUT_SAMPLE_RATE,
+    ) -> np.ndarray:
+        """Resample audio using polyphase filtering."""
+        if audio.size == 0 or orig_sr == target_sr:
+            return audio.astype(np.float32)
+
+        gcd = np.gcd(orig_sr, target_sr)
+        up = target_sr // gcd
+        down = orig_sr // gcd
+        return resample_poly(audio, up, down).astype(np.float32)
+
+    @staticmethod
+    def check_ffmpeg(format_name: str) -> None:
+        """Raise a clear error if ffmpeg is required but not available."""
+        if format_name.lower() not in FFMPEG_FORMATS:
+            return
+        if shutil.which("ffmpeg") is None:
+            raise RuntimeError(
+                "Error: ffmpeg not found. "
+                f"{format_name.upper()} export requires ffmpeg.\n"
+                "Install:\n"
+                "  macOS:   brew install ffmpeg\n"
+                "  Ubuntu:  sudo apt install ffmpeg\n"
+                "  Windows: winget install ffmpeg  (or: choco install ffmpeg)"
+            )
+
+    def process(
+        self,
+        audio: np.ndarray,
+        orig_sr: int,
+        *,
+        target_dbfs: float = -1.5,
+        pad_ms: float = 100,
+    ) -> np.ndarray:
+        """Apply the full post-processing chain."""
+        processed = self.peak_normalize(audio, target_dbfs=target_dbfs)
+        processed = self.resample(processed, orig_sr, self.sample_rate)
+        processed = self.add_silence_padding(processed, self.sample_rate, pad_ms=pad_ms)
+        return processed
+
+    def write_audio(
+        self,
+        audio: np.ndarray,
+        path: Path | str,
+        format_name: str = "mp3",
+        sample_rate: int | None = None,
+    ) -> WriteResult:
+        """Write audio to disk in the requested format."""
+        output_path = Path(path)
+        fmt = format_name.lower().lstrip(".")
+        sr = sample_rate or self.sample_rate
+
+        self.check_ffmpeg(fmt)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        if fmt == "wav":
+            sf.write(str(output_path), audio, sr, subtype="PCM_16")
+        else:
+            self._write_with_pydub(audio, output_path, fmt, sr)
+
+        duration = len(audio) / sr if len(audio) > 0 else 0.0
+        logger.info("Wrote %s (%.1f s, %d Hz)", output_path, duration, sr)
+        return WriteResult(path=output_path, duration_seconds=duration, sample_rate=sr)
+
+    @staticmethod
+    def _write_with_pydub(
+        audio: np.ndarray,
+        path: Path,
+        fmt: str,
+        sample_rate: int,
+    ) -> None:
+        """Encode compressed audio via pydub/ffmpeg."""
+        clipped = np.clip(audio, -1.0, 1.0)
+        pcm = (clipped * 32767).astype(np.int16)
+        segment = AudioSegment(
+            pcm.tobytes(),
+            frame_rate=sample_rate,
+            sample_width=2,
+            channels=1,
+        )
+        segment.export(str(path), format=fmt)

md2speech/cli.py

@@ -0,0 +1,204 @@
+"""Command-line interface for md2speech."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from md2speech import __version__
+from md2speech.synthesize import DEFAULT_SPEED, synthesize_file
+from md2speech.voices import (
+    DEFAULT_LANG,
+    DEFAULT_VOICE,
+    LANG_CODES,
+    format_language_list,
+    format_voice_list,
+    resolve_lang_code,
+)
+
+logger = logging.getLogger(__name__)
+
+SUPPORTED_FORMATS = ("mp3", "wav", "ogg", "flac")
+
+CLI_EPILOG = """
+examples:
+  md2speech article.md
+  md2speech notes.md -o out.mp3 --voice am_adam
+  md2speech doc.md --lang b --voice bf_emma
+  md2speech chapter.txt -f wav -o chapter.wav
+  md2speech --list-languages
+  md2speech --list-voices en-gb
+
+requirements:
+  Python 3.11–3.12, ffmpeg on PATH for mp3/ogg/flac.
+  First run downloads the Kokoro model from Hugging Face (~500 MB).
+
+install:
+  pipx install md2speech
+
+docs:
+  https://github.com/evelasko/md2speech
+"""
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="md2speech",
+        description=(
+            "Convert Markdown or plain text files to speech audio using Kokoro-82M "
+            "(free, local, offline TTS)."
+        ),
+        epilog=CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+    parser.add_argument(
+        "input",
+        nargs="?",
+        type=Path,
+        help="Path to a .md, .markdown, or .txt file",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=None,
+        help="Output audio file path (default: same name as input with new extension)",
+    )
+    parser.add_argument(
+        "-f",
+        "--format",
+        dest="output_format",
+        choices=SUPPORTED_FORMATS,
+        default="mp3",
+        help="Output audio format (default: mp3)",
+    )
+    parser.add_argument(
+        "--voice",
+        default=None,
+        help=(
+            f"Kokoro voice ID (default: {DEFAULT_VOICE} for American English). "
+            "Use --list-voices to see all options."
+        ),
+    )
+    parser.add_argument(
+        "--lang",
+        "--language",
+        dest="lang",
+        default=None,
+        metavar="CODE",
+        help=(
+            f'Kokoro language code or alias (default: inferred from voice, else "{DEFAULT_LANG}"). '
+            "Codes: "
+            + ", ".join(f"{c}={name}" for c, name in sorted(LANG_CODES.items()))
+        ),
+    )
+    parser.add_argument(
+        "--speed",
+        type=float,
+        default=DEFAULT_SPEED,
+        help=f"Speech speed multiplier (default: {DEFAULT_SPEED})",
+    )
+    parser.add_argument(
+        "--no-normalize",
+        action="store_true",
+        help="Skip text normalization (numbers, abbreviations, etc.)",
+    )
+    parser.add_argument(
+        "--paragraph-pause",
+        type=float,
+        default=0.4,
+        help="Seconds of silence between paragraphs (default: 0.4)",
+    )
+    parser.add_argument(
+        "--list-languages",
+        action="store_true",
+        help="List supported languages and exit",
+    )
+    parser.add_argument(
+        "--list-voices",
+        nargs="?",
+        const="all",
+        metavar="LANG",
+        help="List available voices, optionally filtered by language code",
+    )
+    parser.add_argument(
+        "-V",
+        "--verbose",
+        action="store_true",
+        help="Enable debug logging and synthesis progress",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI entry point. Returns exit code."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.list_languages:
+        print(format_language_list())
+        return 0
+
+    if args.list_voices is not None:
+        lang_filter = None if args.list_voices == "all" else args.list_voices
+        if lang_filter is not None:
+            try:
+                lang_filter = resolve_lang_code(lang_filter)
+            except ValueError as exc:
+                print(f"Error: {exc}", file=sys.stderr)
+                return 1
+        print(format_voice_list(lang_filter))
+        return 0
+
+    if args.input is None:
+        parser.error("the following arguments are required: input")
+
+    log_level = logging.DEBUG if args.verbose else logging.INFO
+    logging.basicConfig(
+        level=log_level,
+        format="%(levelname)s: %(message)s",
+    )
+
+    try:
+        result = synthesize_file(
+            args.input,
+            output_path=args.output,
+            output_format=args.output_format,
+            voice=args.voice,
+            speed=args.speed,
+            lang=args.lang,
+            normalize=not args.no_normalize,
+            paragraph_pause=args.paragraph_pause,
+            show_progress=args.verbose,
+            verbose=args.verbose,
+        )
+        print(f"Wrote {result.path} ({result.duration_seconds:.1f}s)")
+        return 0
+    except FileNotFoundError as exc:
+        logger.error("%s", exc)
+        return 1
+    except ValueError as exc:
+        logger.error("%s", exc)
+        return 1
+    except RuntimeError as exc:
+        logger.error("%s", exc)
+        return 1
+    except KeyboardInterrupt:
+        logger.error("Interrupted")
+        return 130
+    except Exception as exc:
+        logger.error("Unexpected error: %s", exc)
+        if args.verbose:
+            logger.exception("Details:")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

md2speech/engine.py

@@ -0,0 +1,90 @@
+"""Kokoro TTS engine wrapper."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+import numpy as np
+import torch
+
+if TYPE_CHECKING:
+    from kokoro import KPipeline
+
+from md2speech.voices import DEFAULT_LANG, resolve_lang_code
+
+logger = logging.getLogger(__name__)
+
+KOKORO_SAMPLE_RATE = 24_000
+DEFAULT_REPO = "hexgrad/Kokoro-82M"
+
+
+def _detect_device() -> str | None:
+    """Pick the best available torch device, or CPU."""
+    if torch.cuda.is_available():
+        return "cuda"
+    if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        return "mps"
+    return None
+
+
+class TTSEngine:
+    """Thin wrapper around Kokoro's ``KPipeline`` with lazy model loading."""
+
+    def __init__(
+        self,
+        lang_code: str = DEFAULT_LANG,
+        repo_id: str = DEFAULT_REPO,
+        device: str | None = None,
+    ) -> None:
+        self.lang_code = resolve_lang_code(lang_code)
+        self.repo_id = repo_id
+        self.device = device if device is not None else _detect_device()
+        self._pipeline: KPipeline | None = None
+
+    def _get_pipeline(self) -> KPipeline:
+        if self._pipeline is None:
+            from kokoro import KPipeline
+
+            logger.info(
+                "Loading Kokoro model from %s (device=%s). "
+                "First run may download weights from Hugging Face.",
+                self.repo_id,
+                self.device or "cpu",
+            )
+            try:
+                self._pipeline = KPipeline(
+                    lang_code=self.lang_code,
+                    repo_id=self.repo_id,
+                    device=self.device,
+                )
+            except Exception as exc:
+                raise RuntimeError(
+                    "Failed to load Kokoro model. Ensure you have network access "
+                    "for the first download from Hugging Face."
+                ) from exc
+        return self._pipeline
+
+    def synthesize(self, text: str, voice: str, speed: float = 1.0) -> np.ndarray:
+        """Synthesize a short text string to a float32 numpy array at 24 kHz."""
+        if not text.strip():
+            return np.array([], dtype=np.float32)
+
+        pipeline = self._get_pipeline()
+        chunks: list[np.ndarray] = []
+
+        try:
+            for result in pipeline(text, voice=voice, speed=speed):
+                audio = result.audio
+                if hasattr(audio, "detach"):
+                    audio = audio.detach().cpu().numpy()
+                else:
+                    audio = np.asarray(audio)
+                chunks.append(audio.astype(np.float32).flatten())
+        except Exception as exc:
+            raise RuntimeError(f"TTS synthesis failed: {exc}") from exc
+
+        if not chunks:
+            return np.array([], dtype=np.float32)
+
+        return np.concatenate(chunks)

md2speech/normalize.py

@@ -0,0 +1,110 @@
+"""Text normalization for improved TTS pronunciation."""
+
+from __future__ import annotations
+
+import re
+
+import inflect
+
+_ENGINE = inflect.engine()
+
+_ABBREVIATIONS: dict[str, str] = {
+    "mr.": "Mister",
+    "mrs.": "Missus",
+    "ms.": "Miss",
+    "dr.": "Doctor",
+    "prof.": "Professor",
+    "sr.": "Senior",
+    "jr.": "Junior",
+    "st.": "Saint",
+    "vs.": "versus",
+    "etc.": "etcetera",
+    "e.g.": "for example",
+    "i.e.": "that is",
+    "approx.": "approximately",
+    "dept.": "department",
+    "inc.": "incorporated",
+    "ltd.": "limited",
+    "no.": "number",
+}
+
+_ORDINAL_RE = re.compile(r"\b(\d+)(st|nd|rd|th)\b", re.IGNORECASE)
+_CURRENCY_RE = re.compile(r"\$(\d+(?:\.\d{1,2})?)")
+_PERCENT_RE = re.compile(r"(\d+(?:\.\d+)?)\s*%")
+_TIME_RE = re.compile(
+    r"\b(\d{1,2}):(\d{2})\s*(AM|PM|am|pm|a\.m\.|p\.m\.)?\b"
+)
+_PLAIN_NUMBER_RE = re.compile(r"\b(\d+(?:\.\d+)?)\b")
+_ABBREV_RE = re.compile(
+    r"\b(" + "|".join(re.escape(k) for k in _ABBREVIATIONS) + r")",
+    re.IGNORECASE,
+)
+
+
+def normalize_text(text: str) -> str:
+    """Expand abbreviations, numbers, currency, percentages, and times."""
+    if not text.strip():
+        return text
+
+    result = text
+
+    def _replace_abbrev(match: re.Match[str]) -> str:
+        key = match.group(1).lower()
+        return _ABBREVIATIONS.get(key, match.group(0))
+
+    result = _ABBREV_RE.sub(_replace_abbrev, result)
+
+    def _replace_ordinal(match: re.Match[str]) -> str:
+        number = int(match.group(1))
+        return _ENGINE.ordinal(_ENGINE.number_to_words(number))
+
+    result = _ORDINAL_RE.sub(_replace_ordinal, result)
+
+    def _replace_currency(match: re.Match[str]) -> str:
+        amount = match.group(1)
+        if "." in amount:
+            dollars, cents = amount.split(".", 1)
+            cents = cents.ljust(2, "0")[:2]
+            dollar_words = _ENGINE.number_to_words(int(dollars))
+            cent_words = _ENGINE.number_to_words(int(cents))
+            return f"{dollar_words} dollars and {cent_words} cents"
+        return f"{_ENGINE.number_to_words(int(amount))} dollars"
+
+    result = _CURRENCY_RE.sub(_replace_currency, result)
+
+    def _replace_percent(match: re.Match[str]) -> str:
+        value = match.group(1)
+        if "." in value:
+            words = _ENGINE.number_to_words(value)
+        else:
+            words = _ENGINE.number_to_words(int(value))
+        return f"{words} percent"
+
+    result = _PERCENT_RE.sub(_replace_percent, result)
+
+    def _replace_time(match: re.Match[str]) -> str:
+        hour = int(match.group(1))
+        minute = int(match.group(2))
+        period = match.group(3)
+        hour_words = _ENGINE.number_to_words(hour)
+        if minute == 0:
+            spoken = f"{hour_words} o'clock"
+        else:
+            minute_words = _ENGINE.number_to_words(minute)
+            spoken = f"{hour_words} {minute_words}"
+        if period:
+            period_clean = period.replace(".", "").upper()
+            if period_clean in {"AM", "PM"}:
+                spoken = f"{spoken} {period_clean}"
+        return spoken
+
+    result = _TIME_RE.sub(_replace_time, result)
+
+    def _replace_number(match: re.Match[str]) -> str:
+        value = match.group(1)
+        if "." in value:
+            return _ENGINE.number_to_words(value)
+        return _ENGINE.number_to_words(int(value))
+
+    result = _PLAIN_NUMBER_RE.sub(_replace_number, result)
+    return result

md2speech/reader.py

@@ -0,0 +1,73 @@
+"""File reading and Markdown-to-plain-text extraction."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+SUPPORTED_EXTENSIONS = {".txt", ".md", ".markdown"}
+
+_FRONT_MATTER_RE = re.compile(r"^---\s*\n.*?\n---\s*\n", re.DOTALL)
+_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
+_FENCED_CODE_RE = re.compile(r"```[^\n]*\n.*?```", re.DOTALL)
+_INLINE_CODE_RE = re.compile(r"`([^`]+)`")
+_IMAGE_RE = re.compile(r"!\[([^\]]*)\]\([^)]+\)")
+_LINK_RE = re.compile(r"\[([^\]]+)\]\([^)]+\)")
+_HEADING_RE = re.compile(r"^#{1,6}\s+", re.MULTILINE)
+_BOLD_RE = re.compile(r"\*\*([^*]+)\*\*|__([^_]+)__")
+_ITALIC_RE = re.compile(r"(?<!\*)\*([^*]+)\*(?!\*)|(?<!_)_([^_]+)_(?!_)")
+_STRIKE_RE = re.compile(r"~~([^~]+)~~")
+_BLOCKQUOTE_RE = re.compile(r"^>\s?", re.MULTILINE)
+_HR_RE = re.compile(r"^[-*_]{3,}\s*$", re.MULTILINE)
+_LIST_MARKER_RE = re.compile(r"^[\s]*[-*+]\s+", re.MULTILINE)
+_ORDERED_LIST_RE = re.compile(r"^[\s]*\d+\.\s+", re.MULTILINE)
+
+
+def read_document(path: Path | str) -> str:
+    """Read a text or Markdown file and return speakable plain text."""
+    file_path = Path(path)
+    if not file_path.exists():
+        raise FileNotFoundError(f"Input file not found: {file_path}")
+
+    suffix = file_path.suffix.lower()
+    if suffix not in SUPPORTED_EXTENSIONS:
+        supported = ", ".join(sorted(SUPPORTED_EXTENSIONS))
+        raise ValueError(
+            f"Unsupported file extension '{suffix}'. Supported types: {supported}"
+        )
+
+    raw = file_path.read_text(encoding="utf-8-sig")
+    if suffix == ".txt":
+        return raw.strip()
+
+    return extract_plain_text(raw)
+
+
+def extract_plain_text(markdown: str) -> str:
+    """Convert Markdown source to speakable plain text.
+
+    Fenced code blocks (``` ... ```) are removed entirely — they are not
+    spoken. Inline code spans are kept and spoken literally.
+    """
+    text = markdown.strip()
+    if not text:
+        return ""
+
+    text = _FRONT_MATTER_RE.sub("", text, count=1)
+    text = _HTML_COMMENT_RE.sub("", text)
+    text = _FENCED_CODE_RE.sub("", text)
+    text = _IMAGE_RE.sub(r"\1", text)
+    text = _LINK_RE.sub(r"\1", text)
+    text = _INLINE_CODE_RE.sub(r"\1", text)
+    text = _HEADING_RE.sub("", text)
+    text = _BOLD_RE.sub(lambda m: m.group(1) or m.group(2), text)
+    text = _ITALIC_RE.sub(lambda m: m.group(1) or m.group(2), text)
+    text = _STRIKE_RE.sub(r"\1", text)
+    text = _BLOCKQUOTE_RE.sub("", text)
+    text = _HR_RE.sub("", text)
+    text = _LIST_MARKER_RE.sub("", text)
+    text = _ORDERED_LIST_RE.sub("", text)
+
+    # Collapse runs of blank lines while preserving paragraph breaks.
+    paragraphs = [p.strip() for p in re.split(r"\n\s*\n", text) if p.strip()]
+    return "\n\n".join(paragraphs)