hadidy-audio 0.1.2

Official Python SDK for the Hadidy Audio Transcoding API

hadidy-audio

Official Python SDK for the Hadidy Audio Transcoding API. Supports Python 3.10+ with both synchronous and asynchronous clients. Zero required dependencies beyond httpx and pydantic.

Installation

pip install hadidy-audio

Python 3.10+ required. The async client uses asyncio — no extra install needed.

---

Quick Start — Synchronous

from hadidy import AudioClient

client = AudioClient(api_key="had_live_...")

with open("podcast.wav", "rb") as f:
    job = client.jobs.create(f, output_format="mp3", bitrate="192k")

completed = client.jobs.wait_for_completion(job["id"], timeout=300)
print(completed["output_url"])

Quick Start — Async

import asyncio
from hadidy import AsyncAudioClient

async def main():
    async with AsyncAudioClient(api_key="had_live_...") as client:
        async for job in client.jobs.list_all(status="completed"):
            print(f"{job['file_name']} → {job['output_url']}")

asyncio.run(main())

---

Live Streaming

WHIP (OBS 30+ / Larix — recommended)

from hadidy import AudioClient

client = AudioClient(api_key="had_live_...")

# Create a session — WHIP is the default protocol
session = client.live.create_session(
    title="Friday Night Show",
    ingest_protocol="whip",   # default; can be omitted
    recording_enabled=True,
)
client.live.start_session(session["id"])

print("WHIP endpoint:", session["ingest_url"])
# → https://ingest.hadidy.com/{stream_key}/whip

# OBS 30+: Settings → Stream → Service: WHIP
#   Server: paste session["ingest_url"]  (no separate stream key field)

RTMPS (OBS older / vMix / Streamlabs)

session = client.live.create_session(
    title="Friday Night Show",
    ingest_protocol="rtmp",   # externally TLS-encrypted RTMPS on port 4936
    recording_enabled=True,
)
client.live.start_session(session["id"])

print("RTMPS server:", session["ingest_url"])  # rtmps://rtmps.hadidy.com:4936/
print("Stream key:  ", session["stream_key"])

# OBS: Settings → Stream → Service: Custom RTMPS
#   Server:     paste session["ingest_url"]
#   Stream Key: paste session["stream_key"]

Push track metadata mid-stream

# Call on every track change in your DJ software
client.live.update_now_playing(
    session["id"],
    title="Midnight City",
    artist="M83",
    album="Hurry Up, We're Dreaming",
    cover_url="https://example.com/artwork.jpg",
    # Pre-load the upcoming track on listeners' devices:
    next_title="Resonance",
    next_artist="Home",
    next_cover_url="https://example.com/next-artwork.jpg",
)

# Clear track info between sets
client.live.clear_now_playing(session["id"])

Stop and retrieve recordings

client.live.stop_session(session["id"])

recordings = client.live.list_recordings(session["id"])
for r in recordings:
    print(r["download_url"], r["duration_seconds"])

Async live session

import asyncio
from hadidy import AsyncAudioClient

async def broadcast():
    async with AsyncAudioClient(api_key="had_live_...") as client:
        session = await client.live.create_session(title="Night Show", ingest_protocol="whip")
        await client.live.start_session(session["id"])
        print("Streaming at:", session["ingest_url"])

        # Later, on track change:
        await client.live.update_now_playing(session["id"], title="Atlas", artist="Battles")

        # Stop when done
        await client.live.stop_session(session["id"])

asyncio.run(broadcast())

---

Webhook Verification — FastAPI

from hadidy import WebhookVerifier
from fastapi import FastAPI, Request, HTTPException, Depends
import os

app = FastAPI()
verifier = WebhookVerifier(secret=os.environ["HADIDY_WEBHOOK_SECRET"])

@app.post("/hooks/hadidy")
async def webhook(request: Request, _=Depends(verifier.fastapi_dependency())):
    event = await request.json()
    print(event["type"], event["data"])
    return {"ok": True}

---

API Coverage

Resource	Methods
client.jobs	list(), list_all(), get(), create(), delete(), get_output(), wait_for_completion()
client.presets	list(), list_all(), get(), create(), update(), delete()
client.codecs	list_codecs(), list_formats(), capabilities()
client.analysis	analyze(file)
client.audio	waveform_data(), silence(), get_metadata(), update_metadata(), concat()
client.webhooks	list(), get(), create(), update(), delete(), deliveries(), test()
client.billing	balance(), history(), service_costs()
client.folders	list(), get(), breadcrumb(), create(), update(), delete(), move_files()
client.sharing	list(), get(), create(), update(), delete(), get_public_info(), verify_passcode()
client.live	create_session(), get_session(), list_sessions(), list_sessions_all(), update_session(), start_session(), stop_session(), restart_session(), delete_session(), regenerate_key(), update_now_playing(), clear_now_playing(), list_sources(), add_source(), list_participants(), list_recordings()

All methods have async equivalents on AsyncAudioClient.

---

Error Handling

from hadidy import AudioClient, RateLimitError, NotFoundError, ValidationError, HadidyError

client = AudioClient(api_key="had_live_...")

try:
    job = client.jobs.get("nonexistent-id")
except NotFoundError:
    print("Job not found")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
except ValidationError as e:
    print(f"Bad request: {e}")
except HadidyError as e:
    print(f"API error {e.status}: {e}")

---

Configuration

client = AudioClient(
    api_key="had_live_...",              # required
    base_url="https://api.hadidy.com",   # default
    timeout=30.0,                         # seconds — default: 30.0
    max_retries=2,                        # default: 2
)

---

License

MIT