Metadata-Version: 2.4
Name: murmel
Version: 0.1.0
Summary: Python SDK for the Murmel Speech-to-Text API
Project-URL: Homepage, https://murmel.eu
Project-URL: Documentation, https://api.murmel.eu/v1/docs
Project-URL: Repository, https://github.com/The-AI-Factory/murmel-python
Project-URL: Issues, https://github.com/The-AI-Factory/murmel-python/issues
Author-email: Murmel <support@murmel.eu>
License-Expression: MIT
License-File: LICENSE
Keywords: asr,dutch,murmel,speech-to-text,stt,transcription,whisper
Classifier: Development Status :: 4 - Beta
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: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# Murmel Python SDK

Official Python client for the [Murmel](https://murmel.eu) Speech-to-Text API — optimized for Dutch.

## Installation

```bash
pip install murmel
```

## Quick Start

```python
from murmel import Murmel

client = Murmel(api_key="murmel_sk_...")

# Transcribe an audio file
result = client.transcribe("meeting.mp3")
print(result.text)
```

## Usage

### Transcribe Audio

Upload an audio file and get the transcription back directly. Supports WAV, MP3, M4A, WEBM, OGG, FLAC, and more.

```python
# From a file path
result = client.transcribe("interview.mp3")
print(result.text)

# With timestamps
for segment in result.segments:
    print(f"[{segment.start:.1f}s → {segment.end:.1f}s] {segment.text}")

# From a file object
with open("audio.wav", "rb") as f:
    result = client.transcribe(f)
```

### List Transcriptions

```python
# List recent transcriptions
transcriptions = client.transcriptions.list(limit=10)
for t in transcriptions:
    print(f"{t.id}: {t.status} ({t.language})")

# Filter by status
completed = client.transcriptions.list(status="completed")
```

### Get a Transcription

```python
# Get full result by ID
result = client.transcriptions.get("job-id-here")
print(result.text)
print(result.segments)

# Check status only (lightweight)
status = client.transcriptions.status("job-id-here")
print(status.status)  # "pending", "processing", "completed", "failed"
```

### Check Usage

```python
usage = client.usage()
print(f"Plan: {usage.plan}")
print(f"Used: {usage.used_minutes:.1f} / {usage.limit_minutes:.0f} min")
print(f"Remaining: {usage.remaining_minutes:.1f} min")
```

## Error Handling

The SDK raises specific exceptions for different error types:

```python
from murmel import Murmel, AuthenticationError, RateLimitError, InvalidRequestError

client = Murmel(api_key="murmel_sk_...")

try:
    result = client.transcribe("audio.mp3")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Monthly usage limit exceeded")
except InvalidRequestError as e:
    print(f"Bad request: {e.message}")
```

**Exception hierarchy:**

| Exception | HTTP Status | When |
|-----------|-------------|------|
| `AuthenticationError` | 401 | Invalid or missing API key |
| `PermissionDeniedError` | 403 | Account inactive, email not verified |
| `InvalidRequestError` | 400, 413 | Unsupported file format, file too large |
| `NotFoundError` | 404 | Transcription not found |
| `RateLimitError` | 429 | Monthly minutes exhausted |
| `ServerError` | 500 | Transcription processing failed |
| `TimeoutError` | 504 | Transcription took too long |

## Configuration

```python
client = Murmel(
    api_key="murmel_sk_...",
    base_url="https://api.murmel.eu",  # default
    timeout=600,                        # 10 min default (for long audio)
)

# Use as context manager
with Murmel(api_key="murmel_sk_...") as client:
    result = client.transcribe("audio.mp3")
```

## API Reference

Get your API key at [app.murmel.eu](https://app.murmel.eu) → Settings → API Keys.

Full API docs: [api.murmel.eu/v1/docs](https://api.murmel.eu/v1/docs)
