murmr 0.1.0__tar.gz

murmr-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing / coverage
+.coverage
+.pytest_cache/
+htmlcov/
+
+# Type checking / linting
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+
+# Benchmarks
+.benchmarks/
+
+# OS
+.DS_Store

murmr-0.1.0/CLAUDE.md

@@ -0,0 +1,51 @@
+# murmr Python SDK
+
+## Overview
+
+Python SDK for the murmr TTS API. Mirrors the Node.js SDK (`@murmr/sdk`) in snake_case.
+
+## Structure
+
+```
+src/murmr/
+  __init__.py          # Public exports
+  _client.py           # AsyncMurmrClient + MurmrClient
+  _types.py            # Pydantic v2 response models (frozen)
+  _errors.py           # MurmrError, MurmrChunkError
+  _validate.py         # Input/ID validation
+  _streaming.py        # SSE parsing, collect as WAV/PCM
+  _audio.py            # WAV header, silence, concat
+  _chunker.py          # Sentence-boundary text splitting
+  resources/
+    speech.py          # Batch, streaming, long-form
+    voices.py          # Voice design (batch + streaming)
+    jobs.py            # Job polling
+```
+
+## Commands
+
+```bash
+# Install
+pip install -e ".[dev]"
+
+# Test
+pytest -v
+
+# Type check
+mypy src/murmr/
+
+# Lint
+ruff check src/ tests/
+
+# Coverage
+pytest --cov=murmr --cov-report=term-missing
+```
+
+## Conventions
+
+- **Async-first, sync support:** Every resource has Async + Sync variants
+- **kwargs, not models:** Methods take keyword arguments (like OpenAI SDK)
+- **`input` maps to `text`:** Public API uses `input`, request body uses `text`
+- **Pydantic v2 frozen models:** All response types are immutable
+- **No httpx-sse:** SSE parsed manually via `iter_lines()`
+- **Context managers:** Streaming methods return context managers that yield typed chunks

murmr-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 murmr
+
+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.

murmr-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: murmr
+Version: 0.1.0
+Summary: Python SDK for the murmr TTS API
+Project-URL: Homepage, https://murmr.dev
+Project-URL: Documentation, https://murmr.dev/docs
+Project-URL: Repository, https://github.com/christi4nity/murmr-python
+Author: murmr
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.25
+Requires-Dist: pydantic<3.0,>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# murmr
+
+Python SDK for the [murmr](https://murmr.dev) TTS API. Async-first with full sync support.
+
+```bash
+pip install murmr
+```
+
+## Quick Start
+
+### Voice Design (describe any voice in natural language)
+
+```python
+from murmr import MurmrClient
+
+client = MurmrClient(api_key="murmr_sk_live_...")
+
+# Generate speech with a voice description
+wav = client.voices.design(
+    input="Hello, welcome to murmr!",
+    voice_description="A warm, friendly female voice with a slight British accent",
+)
+
+with open("output.wav", "wb") as f:
+    f.write(wav)
+```
+
+### Saved Voices (batch via RunPod Serverless)
+
+```python
+# Submit a batch job
+job = client.speech.create(input="Hello world", voice="voice_abc123")
+
+# Wait for completion
+result = client.speech.create_and_wait(input="Hello world", voice="voice_abc123")
+audio = result.audio_bytes  # decoded WAV
+```
+
+### Streaming
+
+```python
+# Stream PCM audio chunks
+with client.speech.stream(input="Hello world", voice="voice_abc123") as stream:
+    for chunk in stream:
+        pcm = chunk.audio_bytes  # 24kHz mono 16-bit PCM
+        if chunk.done:
+            break
+```
+
+### Async
+
+```python
+import asyncio
+from murmr import AsyncMurmrClient
+
+async def main():
+    async with AsyncMurmrClient(api_key="murmr_sk_live_...") as client:
+        wav = await client.voices.design(
+            input="Hello from async!",
+            voice_description="A deep male voice",
+        )
+
+asyncio.run(main())
+```
+
+### Long-Form Audio
+
+```python
+# Automatically chunks, retries, and concatenates
+result = client.speech.create_long_form(
+    input=very_long_text,
+    voice="voice_abc123",
+    on_progress=lambda current, total, pct: print(f"{pct}%"),
+)
+
+with open("long_form.wav", "wb") as f:
+    f.write(result.audio)
+```
+
+## API Reference
+
+### Clients
+
+| Class | Description |
+|-------|-------------|
+| `MurmrClient(api_key=...)` | Sync client (context manager) |
+| `AsyncMurmrClient(api_key=...)` | Async client (async context manager) |
+
+### Speech (`client.speech`)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `create(input, voice, ...)` | `AsyncJobResponse` | Submit batch job |
+| `create_and_wait(input, voice, ...)` | `JobStatus` | Submit and poll until done |
+| `stream(input, voice, ...)` | Context manager yielding `AudioStreamChunk` | Stream PCM chunks |
+| `create_long_form(input, voice, ...)` | `LongFormResult` | Chunk + concat long text |
+
+### Voices (`client.voices`)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `design(input, voice_description, ...)` | `bytes` (WAV) | Generate with voice description |
+| `design_stream(input, voice_description, ...)` | Context manager yielding `AudioStreamChunk` | Stream voice design |
+
+### Jobs (`client.jobs`)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `get(job_id)` | `JobStatus` | Get job status |
+| `wait_for_completion(job_id, ...)` | `JobStatus` | Poll until done/failed |
+
+## Supported Languages
+
+Chinese, English, Japanese, Korean, German, French, Russian, Portuguese, Spanish, Italian
+
+## License
+
+MIT

murmr-0.1.0/README.md

@@ -0,0 +1,118 @@
+# murmr
+
+Python SDK for the [murmr](https://murmr.dev) TTS API. Async-first with full sync support.
+
+```bash
+pip install murmr
+```
+
+## Quick Start
+
+### Voice Design (describe any voice in natural language)
+
+```python
+from murmr import MurmrClient
+
+client = MurmrClient(api_key="murmr_sk_live_...")
+
+# Generate speech with a voice description
+wav = client.voices.design(
+    input="Hello, welcome to murmr!",
+    voice_description="A warm, friendly female voice with a slight British accent",
+)
+
+with open("output.wav", "wb") as f:
+    f.write(wav)
+```
+
+### Saved Voices (batch via RunPod Serverless)
+
+```python
+# Submit a batch job
+job = client.speech.create(input="Hello world", voice="voice_abc123")
+
+# Wait for completion
+result = client.speech.create_and_wait(input="Hello world", voice="voice_abc123")
+audio = result.audio_bytes  # decoded WAV
+```
+
+### Streaming
+
+```python
+# Stream PCM audio chunks
+with client.speech.stream(input="Hello world", voice="voice_abc123") as stream:
+    for chunk in stream:
+        pcm = chunk.audio_bytes  # 24kHz mono 16-bit PCM
+        if chunk.done:
+            break
+```
+
+### Async
+
+```python
+import asyncio
+from murmr import AsyncMurmrClient
+
+async def main():
+    async with AsyncMurmrClient(api_key="murmr_sk_live_...") as client:
+        wav = await client.voices.design(
+            input="Hello from async!",
+            voice_description="A deep male voice",
+        )
+
+asyncio.run(main())
+```
+
+### Long-Form Audio
+
+```python
+# Automatically chunks, retries, and concatenates
+result = client.speech.create_long_form(
+    input=very_long_text,
+    voice="voice_abc123",
+    on_progress=lambda current, total, pct: print(f"{pct}%"),
+)
+
+with open("long_form.wav", "wb") as f:
+    f.write(result.audio)
+```
+
+## API Reference
+
+### Clients
+
+| Class | Description |
+|-------|-------------|
+| `MurmrClient(api_key=...)` | Sync client (context manager) |
+| `AsyncMurmrClient(api_key=...)` | Async client (async context manager) |
+
+### Speech (`client.speech`)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `create(input, voice, ...)` | `AsyncJobResponse` | Submit batch job |
+| `create_and_wait(input, voice, ...)` | `JobStatus` | Submit and poll until done |
+| `stream(input, voice, ...)` | Context manager yielding `AudioStreamChunk` | Stream PCM chunks |
+| `create_long_form(input, voice, ...)` | `LongFormResult` | Chunk + concat long text |
+
+### Voices (`client.voices`)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `design(input, voice_description, ...)` | `bytes` (WAV) | Generate with voice description |
+| `design_stream(input, voice_description, ...)` | Context manager yielding `AudioStreamChunk` | Stream voice design |
+
+### Jobs (`client.jobs`)
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `get(job_id)` | `JobStatus` | Get job status |
+| `wait_for_completion(job_id, ...)` | `JobStatus` | Poll until done/failed |
+
+## Supported Languages
+
+Chinese, English, Japanese, Korean, German, French, Russian, Portuguese, Spanish, Italian
+
+## License
+
+MIT

murmr-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "murmr"
+version = "0.1.0"
+description = "Python SDK for the murmr TTS API"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [{ name = "murmr" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.25,<1.0",
+    "pydantic>=2.0,<3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "mypy>=1.0",
+    "ruff>=0.4",
+    "pytest-cov>=4.0",
+]
+
+[project.urls]
+Homepage = "https://murmr.dev"
+Documentation = "https://murmr.dev/docs"
+Repository = "https://github.com/christi4nity/murmr-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/murmr"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.mypy]
+strict = true
+python_version = "3.9"
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]

murmr-0.1.0/src/murmr/__init__.py

@@ -0,0 +1,18 @@
+"""murmr - Python SDK for the murmr TTS API."""
+
+from murmr._client import AsyncMurmrClient, MurmrClient
+from murmr._errors import MurmrChunkError, MurmrError
+from murmr._types import AsyncJobResponse, AudioStreamChunk, JobStatus, LongFormResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncMurmrClient",
+    "MurmrClient",
+    "MurmrError",
+    "MurmrChunkError",
+    "AsyncJobResponse",
+    "AudioStreamChunk",
+    "JobStatus",
+    "LongFormResult",
+]

murmr-0.1.0/src/murmr/_audio.py

@@ -0,0 +1,88 @@
+"""Audio utilities: WAV header construction, silence generation, PCM concatenation."""
+
+from __future__ import annotations
+
+import struct
+
+SAMPLE_RATE = 24000
+CHANNELS = 1
+BITS_PER_SAMPLE = 16
+BYTES_PER_SAMPLE = BITS_PER_SAMPLE // 8
+WAV_HEADER_SIZE = 44
+
+
+def create_wav_header(pcm_data_size: int) -> bytes:
+    """Create a 44-byte WAV header for raw PCM data.
+
+    Assumes 24kHz, mono, 16-bit signed little-endian PCM.
+    """
+    byte_rate = SAMPLE_RATE * CHANNELS * BYTES_PER_SAMPLE
+    block_align = CHANNELS * BYTES_PER_SAMPLE
+    file_size = WAV_HEADER_SIZE + pcm_data_size - 8
+
+    return struct.pack(
+        "<4sI4s4sIHHIIHH4sI",
+        b"RIFF",
+        file_size,
+        b"WAVE",
+        b"fmt ",
+        16,  # PCM chunk size
+        1,  # PCM format
+        CHANNELS,
+        SAMPLE_RATE,
+        byte_rate,
+        block_align,
+        BITS_PER_SAMPLE,
+        b"data",
+        pcm_data_size,
+    )
+
+
+def generate_silence(duration_ms: int) -> bytes:
+    """Generate silence as raw PCM (16-bit, little-endian, all zeros)."""
+    num_samples = int((duration_ms / 1000) * SAMPLE_RATE)
+    return b"\x00" * (num_samples * BYTES_PER_SAMPLE)
+
+
+def extract_pcm(wav_buffer: bytes) -> bytes:
+    """Extract raw PCM data from a WAV buffer by walking sub-chunks to find 'data'."""
+    if len(wav_buffer) < 12 or wav_buffer[:4] != b"RIFF":
+        return wav_buffer
+
+    offset = 12
+    while offset + 8 <= len(wav_buffer):
+        chunk_id = wav_buffer[offset : offset + 4]
+        chunk_size = struct.unpack_from("<I", wav_buffer, offset + 4)[0]
+        if chunk_id == b"data":
+            return wav_buffer[offset + 8 : offset + 8 + chunk_size]
+        offset += 8 + chunk_size
+
+    # Fallback: strip standard 44-byte header
+    return wav_buffer[WAV_HEADER_SIZE:]
+
+
+def concatenate_pcm_chunks(
+    chunks: list[bytes],
+    silence_between_ms: int = 0,
+) -> bytes:
+    """Concatenate PCM chunks with optional silence, then wrap in a WAV container."""
+    if not chunks:
+        return b""
+
+    silence = generate_silence(silence_between_ms) if silence_between_ms > 0 else b""
+    parts: list[bytes] = []
+
+    for i, chunk in enumerate(chunks):
+        parts.append(chunk)
+        if silence and i < len(chunks) - 1:
+            parts.append(silence)
+
+    total_pcm = b"".join(parts)
+    return create_wav_header(len(total_pcm)) + total_pcm
+
+
+def estimate_duration_ms(wav_buffer: bytes) -> int:
+    """Estimate audio duration in milliseconds from a WAV buffer."""
+    bytes_per_second = SAMPLE_RATE * CHANNELS * BYTES_PER_SAMPLE
+    data_size = max(0, len(wav_buffer) - WAV_HEADER_SIZE)
+    return round((data_size / bytes_per_second) * 1000)

murmr-0.1.0/src/murmr/_chunker.py

@@ -0,0 +1,120 @@
+"""Sentence-boundary text splitting for long-form audio generation."""
+
+from __future__ import annotations
+
+import re
+
+# Split after sentence-ending punctuation (Western + CJK)
+_SENTENCE_SPLIT = re.compile(r"(?<=[.!?])\s+|(?<=[。！？])")
+
+# Split after clause-level punctuation
+_CLAUSE_SPLIT = re.compile(r"(?<=[,;:\u2014])\s+|(?<=[、；：])")
+
+
+def split_into_chunks(text: str, max_chars: int = 3500) -> list[str]:
+    """Split text into chunks at sentence boundaries.
+
+    Never splits mid-sentence. Falls back to clause boundaries for long
+    sentences, then word boundaries as a last resort.
+
+    Args:
+        text: The input text to split.
+        max_chars: Maximum characters per chunk (100-4096).
+
+    Returns:
+        List of text chunks, each within max_chars.
+    """
+    if max_chars < 100:
+        raise ValueError("max_chars must be at least 100")
+    if max_chars > 4096:
+        raise ValueError("max_chars must be at most 4096 (API limit)")
+
+    trimmed = text.strip()
+    if not trimmed:
+        return []
+    if len(trimmed) <= max_chars:
+        return [trimmed]
+
+    sentences = _SENTENCE_SPLIT.split(trimmed)
+    chunks: list[str] = []
+    current = ""
+
+    for sentence in sentences:
+        stripped = sentence.strip()
+        if not stripped:
+            continue
+
+        if len(stripped) > max_chars:
+            if current:
+                chunks.append(current.strip())
+                current = ""
+            chunks.extend(_split_long_sentence(stripped, max_chars))
+            continue
+
+        combined = f"{current} {stripped}" if current else stripped
+
+        if len(combined) > max_chars:
+            chunks.append(current.strip())
+            current = stripped
+        else:
+            current = combined
+
+    if current.strip():
+        chunks.append(current.strip())
+
+    return chunks
+
+
+def _split_long_sentence(sentence: str, max_chars: int) -> list[str]:
+    """Split a sentence that exceeds max_chars at clause boundaries."""
+    clauses = _CLAUSE_SPLIT.split(sentence)
+
+    if len(clauses) > 1:
+        chunks: list[str] = []
+        current = ""
+
+        for clause in clauses:
+            stripped = clause.strip()
+            if not stripped:
+                continue
+
+            if len(stripped) > max_chars:
+                if current:
+                    chunks.append(current.strip())
+                    current = ""
+                chunks.extend(_split_at_words(stripped, max_chars))
+                continue
+
+            combined = f"{current} {stripped}" if current else stripped
+            if len(combined) > max_chars:
+                chunks.append(current.strip())
+                current = stripped
+            else:
+                current = combined
+
+        if current.strip():
+            chunks.append(current.strip())
+
+        return chunks
+
+    return _split_at_words(sentence, max_chars)
+
+
+def _split_at_words(text: str, max_chars: int) -> list[str]:
+    """Last-resort splitting at word boundaries."""
+    words = text.split()
+    chunks: list[str] = []
+    current = ""
+
+    for word in words:
+        combined = f"{current} {word}" if current else word
+        if len(combined) > max_chars and current:
+            chunks.append(current.strip())
+            current = word
+        else:
+            current = combined
+
+    if current.strip():
+        chunks.append(current.strip())
+
+    return chunks