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 with speaker diarization
result = client.transcribe("meeting.mp3", identify_speakers=True)
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", identify_speakers=True)
print(result.text)

# With timestamps and speakers
for segment in result.segments:
    speaker_info = f"[{segment.speaker}] " if hasattr(segment, 'speaker') and segment.speaker else ""
    print(f"[{segment.start:.1f}s → {segment.end:.1f}s] {speaker_info}{segment.text}")

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

Webhook (callback URL)

Don't want to keep the request open? Pass a callback_url and Murmel POSTs the finished transcription to your endpoint instead:

job = client.transcribe(
    "interview.mp3",
    callback_url="https://example.com/murmel-webhook?token=your-secret",
)
print(job.id, job.status)  # "pending"

The POST body has the same fields as Transcription, plus event (transcription.completed or transcription.failed). Respond with a 2xx status; anything else is retried a few times with increasing delays. Put a secret token in the URL to check the call really comes from Murmel.

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:

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.nl/ontwikkelaar.

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