murmel 0.1.0

Python SDK for the Murmel Speech-to-Text API

Murmel Python SDK

Official Python client for the Murmel Speech-to-Text API — optimized for Dutch.

Installation

pip install murmel

Quick Start

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.

# 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

# 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

# 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

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:

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

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 → Settings → API Keys.

Full API docs: api.murmel.eu/v1/docs