Metadata-Version: 2.5
Name: wyzie-subs
Version: 0.1.0
Summary: Python client for the Wyzie Subs API (subtitle search, download, transcribe, fix, extract).
Project-URL: Documentation, https://docs.wyzie.io/subs/usage/clients
Project-URL: Homepage, https://wyzie.io
License-Expression: MIT
License-File: LICENSE
Keywords: srt,subtitles,transcribe,wyzie
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# wyzie-subs

Python client for the [Wyzie Subs API](https://docs.wyzie.io/subs/usage/clients): subtitle search, download, transcribe, fix and extract. Sync and async, one dependency (`httpx`), Python 3.9+.

## Install

```
pip install wyzie-subs
```

## Quick start

```python
from wyzie_subs import Wyzie

wyzie = Wyzie("YOUR_KEY")
results = wyzie.search("tt0111161", language="en")
srt = wyzie.download(results[0], to="vtt", shift="-1.5")
print(wyzie.last_cost, wyzie.last_balance)  # from X-Wyzie-Cost / X-Wyzie-Balance
```

Async: `AsyncWyzie` has the same methods; await each call.

```python
from wyzie_subs import AsyncWyzie

async with AsyncWyzie("YOUR_KEY") as wyzie:
    best = await wyzie.search_best("tt0111161", language="en")
```

Constructor: `Wyzie(key, base_url="https://sub.wyzie.io", timeout=15.0, retries=2)`.

## Methods

All return plain dicts and lists unless noted. Download options (`to`, `offset`, `shift`, `fps`, `plain`, `sdh`, `clean`, `dual`, `lines`, `maxlines`, `mindur`) work wherever they are listed.

| Method | Example |
|---|---|
| `search(id, season, episode, language, format, hi, source, release, filename, origin, video, hash, sort, limit, page, refresh)` | `wyzie.search("tt0903747", season=1, episode=1, language="es")` returns `[]` when nothing matches |
| `search_best(...)` | `wyzie.search_best("tt0111161")` returns one dict, or `None` on a 404 |
| `search_batch(items, best=False, **defaults)` | `wyzie.search_batch(["tt0111161", 286217], language="en")` |
| `download(url_or_result, **download_options)` | `wyzie.download(results[0], to="srt", lines=42)` returns text (JSON format too) |
| `download_best(id, **search_and_download_options)` | `wyzie.download_best("tt0111161", language="en", to="vtt")` |
| `with_download_options(url, **options)` | `wyzie.with_download_options(results[0], to="vtt", shift="+2s")` returns a URL, no request |
| `sources(key=True)` | `wyzie.sources()` |
| `languages()` | `wyzie.languages()` |
| `status(days=0)` | `wyzie.status(days=7)` |
| `quote(q, language, limit)` | `wyzie.quote("may the force be with you")` |
| `transcribe(media, format="srt", language, speakers, sounds, translate, cache, webhook, poll_interval)` | `wyzie.transcribe("talk.mp3", format="json").json` returns a `TranscribeResult`; long jobs are polled |
| `transcribe_url(url, ..., dry_run=False)` | `job = wyzie.transcribe_url("https://example.com/ep.mp3")` returns the 202 body |
| `get_transcribe(id, format="srt")` | `wyzie.get_transcribe(job["jobId"])` returns a result, or `None` while running |
| `fix(media, subtitle, url, id, season, episode, language, format, retime, cache, webhook)` | `wyzie.fix("movie.mkv", subtitle=srt_text, language="en")` returns a `FixResult` |
| `extract(media, list_tracks, track, language, all_tracks, **download_options)` | `wyzie.extract("subs.mks", list_tracks=True)` gives a dict, one track a `str`, `all_tracks=True` zip `bytes` |
| `usage(days=30)` | `wyzie.usage()["balance"]` |
| `set_usage_webhook(url)` | `wyzie.set_usage_webhook("https://example.com/balance")` |
| `clear_usage_webhook()` | `wyzie.clear_usage_webhook()` |

`media` is `bytes`, a path, or a binary file object. Cloudflare caps a request body near 100 MB: for a big film send only the subtitle tracks (`ffmpeg -i movie.mkv -map 0:s -c copy subs.mks`).

## Errors

Any non-2xx answer raises `WyzieError` with `status`, `message`, `details`, `body` (the full JSON error, including extras like `topup` or `reset_at`) and `retry_after`. Use `err.is_rate_limited` (429) and `err.is_auth_error` (401/403).

```python
from wyzie_subs import WyzieError

try:
    wyzie.search("tt0111161")
except WyzieError as err:
    if err.is_rate_limited:
        print("retry in", err.retry_after)
```

"No subtitles found" and "No matching release found" are not errors: `search` gives `[]`, `search_best` gives `None`.

GETs are retried on network errors, 5xx and short 429s (`Retry-After` of 10 s or less) with backoff. POSTs (batch, transcribe, fix, extract) are never retried, because they are billed. Other network failures raise the underlying `httpx` exception.

## Key safety

Use your API key on a server only. Do not ship it in a browser, mobile app or public repo; use a browser-safe `wyzie-pub-` key for front-end code. The client never logs or prints the key (it is redacted from `httpx` request logs and from `repr`), but a URL you build yourself with the key in it is yours to protect.

## More

Docs: https://docs.wyzie.io/subs/usage/clients
