Batch audio fallback: mode param, processing entries, drop cached

The batch endpoint now transcribes captionless entries from audio by
default. Type that end to end:

- transcripts.batch() (sync + async) gains mode="auto" | "captions";
  omitted means the server default (auto). "audio" is not accepted on
  batch.
- BatchResult gains job_id and status for entries that came back as
  outcome "processing" (free on that call, billed on delivery at the
  audio rate; re-send the batch or poll transcripts.job()).
- BatchResult.cached deprecated: the API omits the key entirely now, so
  a defaulted bool silently misreported. Optional[bool] = None keeps
  1.x import/attribute compatibility without inventing False.
- Segment gains optional speaker (int), the best-effort diarization
  label podcast transcriptions carry.
- Map wire code "upstream_error" (503 upstream platform block) to
  UpstreamUnavailableError by code as well as status; retries already
  covered 503 and are unchanged. Per-key limits remain 429.

Version 1.0.2.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Chandler Casey

CHANGELOG.md

@@ -3,6 +3,31 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org).
 
+## [1.0.2] - 2026-08-28
+
+Batch grew audio fallback on the API side; this release types it.
+
+- `transcripts.batch()` (sync + async) gains `mode="auto" | "captions"`.
+  `"auto"` (the API default) transcribes captionless entries from audio: those
+  come back with `outcome == "processing"` and a `job_id`, cost nothing on that
+  call, and are charged on delivery at the audio rate — re-send the same batch
+  later, or poll the job via `transcripts.job()`. `"captions"` keeps the old
+  behaviour (captionless entries fail as `no_transcript`). `"audio"` is not
+  accepted on batch.
+- `BatchResult` gains `job_id` and `status` for those processing entries.
+- Deprecated: `BatchResult.cached`. The API no longer reports cache hits on
+  batch results (the key is omitted entirely), so the field is now
+  `Optional[bool]` defaulting to `None` instead of a silently-false `bool`.
+  Kept for import/attribute compatibility within 1.x; do not branch on it.
+- `Segment` gains optional `speaker` (int): best-effort diarization label on
+  podcast transcriptions — ids are voice-separation hints, not named
+  identification, and non-podcast sources never carry them.
+- Error mapping: the wire code `upstream_error` (503, upstream platform
+  blocked) now maps to `UpstreamUnavailableError` by code as well as by
+  status. Behaviour is unchanged — 503 already mapped and retried — but the
+  docstring no longer claims 502 only. Per-key rate limits remain 429
+  (`RateLimitError`); upstream blocks are never 429.
+
 ## [1.0.0] - 2026-08-05
 
 First stable release. The published docs promise the SDKs follow semver, and a

README.md

@@ -31,7 +31,7 @@ Get an API key (100 free credits) at <https://transcriptfetch.com/app>. One cred
 
 ```python
 tf.transcripts.video(video)                        # single transcript (text + segments)
-tf.transcripts.batch(video_ids)                    # up to 50 transcripts in one call
+tf.transcripts.batch(video_ids, mode=)             # up to 50 transcripts in one call
 tf.transcripts.channel(channel, limit=, cursor=)   # a YouTube channel's videos (metadata)
 tf.transcripts.playlist(playlist, limit=, cursor=) # a YouTube playlist's videos
 tf.transcripts.search(query, limit=, cursor=)      # search YouTube
@@ -64,6 +64,17 @@ print(t.platform)          # "podcast"
 print(t.podcast.show, "-", t.podcast.episode)
 ```
 
+Podcast transcriptions include best-effort speaker diarization: each segment may carry a `speaker` integer (0, 1, …) identifying who is talking. The ids are hints from voice separation, not named identification, and non-podcast sources never carry them.
+
+Batch works the same way by default (`mode="auto"`): entries with no caption track are transcribed from audio, come back with `outcome == "processing"` and a `job_id`, cost nothing on that call, and are charged on delivery at the audio rate. Re-send the same batch once the jobs have had time to finish and the text comes back normally — or poll each `job_id` with `tf.transcripts.job()`. Pass `mode="captions"` to read existing caption tracks only, in which case a captionless video fails as `no_transcript` (the old behaviour):
+
+```python
+res = tf.transcripts.batch(ids)                    # captionless entries -> "processing" + job_id
+pending = [r.job_id for r in res.results if r.outcome == "processing"]
+
+res = tf.transcripts.batch(ids, mode="captions")   # captions only, no audio fallback
+```
+
 ## Pagination
 
 List endpoints are cursor-paginated. Iterate every result without managing cursors:

src/transcriptfetch/_version.py

@@ -1 +1 @@
-__version__ = "1.0.1"
+__version__ = "1.0.2"

src/transcriptfetch/errors.py

@@ -77,7 +77,11 @@ def __init__(self, message: str, *, retry_after: Optional[float] = None, **kwarg
 
 
 class UpstreamUnavailableError(APIError):
-    """502: the upstream transcript service was unreachable. Safe to retry."""
+    """502/503: the upstream platform blocked or was unreachable. Safe to retry.
+
+    Upstream platform blocks answer 503 with code ``upstream_error`` — never
+    429, which is reserved for per-key rate limits (:class:`RateLimitError`).
+    """
 
 
 class InternalServerError(APIError):
@@ -91,6 +95,7 @@ class InternalServerError(APIError):
     "idempotency_conflict": IdempotencyConflictError,
     "rate_limited": RateLimitError,
     "upstream_unavailable": UpstreamUnavailableError,
+    "upstream_error": UpstreamUnavailableError,
     "internal_error": InternalServerError,
 }
 

src/transcriptfetch/models.py

@@ -25,11 +25,18 @@ class Usage(_Model):
 
 
 class Segment(_Model):
-    """A single timestamped caption cue."""
+    """A single timestamped caption cue.
+
+    ``speaker`` is set only on podcast episodes transcribed from audio, where
+    best-effort diarization labels each segment with a small integer (0, 1, …)
+    identifying who is talking. The ids are hints from voice separation, not
+    named identification, and non-podcast sources never carry them.
+    """
 
     start: float = 0.0
     duration: float = 0.0
     text: str = ""
+    speaker: Optional[int] = None
 
 
 class Podcast(_Model):
@@ -110,14 +117,34 @@ class VideoList(_Model):
 
 
 class BatchResult(_Model):
-    """One video's result inside a batch response."""
+    """One video's result inside a batch response.
+
+    Entries with no caption track are transcribed from audio by default (batch
+    ``mode="auto"``): those come back with ``outcome == "processing"`` and a
+    ``job_id``, cost nothing on that call, and are charged on delivery at the
+    audio rate. Either re-send the same batch once the jobs have had time to
+    finish (the text then comes back normally) or poll ``job_id`` via
+    ``transcripts.job()``. Send ``mode="captions"`` to keep the old behaviour,
+    where captionless entries fail as ``no_transcript`` instead.
+    """
 
     video_id: str = ""
-    outcome: Optional[str] = None  # ok | no_transcript | blocked | error | null
+    outcome: Optional[str] = None  # ok | processing | no_transcript | blocked | error | null
     title: Optional[str] = None
     text: Optional[str] = None
     segments: Optional[List[Segment]] = None
-    cached: bool = False
+    cached: Optional[bool] = None
+    """Deprecated. The API no longer reports cache hits on batch results and
+    omits the key entirely, so this is ``None`` on current responses; it is kept
+    (rather than removed) so 1.0.x code reading it keeps importing and running.
+    Do not branch on it."""
+    job_id: Optional[str] = None
+    """Set when ``outcome == "processing"``: the audio-transcription job that
+    will deliver this entry. Poll it with ``transcripts.job(job_id)``, or just
+    re-send the same batch later."""
+    status: Optional[str] = None
+    """Job state for an audio-transcription entry (``"processing"`` until the
+    job delivers). ``None`` for ordinary caption results."""
     bytes: int = 0
 
 

src/transcriptfetch/resources/transcripts.py

@@ -158,11 +158,33 @@ def search(
         return _parse_videolist(env)
 
     def batch(
-        self, video_ids: Iterable[str], *, idempotency_key: Optional[str] = None
+        self,
+        video_ids: Iterable[str],
+        *,
+        mode: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
     ) -> BatchResponse:
-        """Fetch up to 50 transcripts in one call (same inputs as :meth:`video`)."""
+        """Fetch up to 50 transcripts in one call (same inputs as :meth:`video`).
+
+        ``mode`` controls where each entry's text may come from:
+
+        - ``"auto"`` (the default) reads captions and transcribes the audio
+          when there are none. Captionless entries come back with ``outcome ==
+          "processing"`` and a ``job_id``, cost nothing on this call, and are
+          charged on delivery at the audio rate. Re-send the same batch once
+          they have finished and the text is returned normally — or poll each
+          ``job_id`` via :meth:`job`.
+        - ``"captions"`` reads an existing caption track only, so a captionless
+          video fails as ``no_transcript`` — the behaviour batch had before
+          audio fallback existed.
+
+        (``"audio"`` is not accepted on batch.)
+        """
+        body: dict[str, Any] = {"videoIds": list(video_ids)}
+        if mode is not None:
+            body["mode"] = mode
         env = self._c._request(
-            "POST", _BATCH, body={"videoIds": list(video_ids)},
+            "POST", _BATCH, body=body,
             idempotent=True, idempotency_key=idempotency_key,
         )
         return _parse_batch(env)
@@ -253,10 +275,21 @@ async def search(
         return _parse_videolist(env)
 
     async def batch(
-        self, video_ids: Iterable[str], *, idempotency_key: Optional[str] = None
+        self,
+        video_ids: Iterable[str],
+        *,
+        mode: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
     ) -> BatchResponse:
+        """Fetch up to 50 transcripts in one call. See :meth:`Transcripts.batch`
+        for the ``mode`` semantics (``"auto"`` transcribes captionless entries
+        from audio and returns them as ``outcome == "processing"`` jobs;
+        ``"captions"`` keeps the old captions-only behaviour)."""
+        body: dict[str, Any] = {"videoIds": list(video_ids)}
+        if mode is not None:
+            body["mode"] = mode
         env = await self._c._request(
-            "POST", _BATCH, body={"videoIds": list(video_ids)},
+            "POST", _BATCH, body=body,
             idempotent=True, idempotency_key=idempotency_key,
         )
         return _parse_batch(env)

tests/data.py

@@ -25,12 +25,20 @@
     "data": {
         "kind": "transcript_batch",
         "results": [
-            {"video_id": "a", "outcome": "ok", "text": "one", "cached": False, "bytes": 10},
+            # The API no longer includes a "cached" key on batch results.
+            {"video_id": "a", "outcome": "ok", "text": "one", "bytes": 10},
             {
                 "video_id": "b",
                 "outcome": "no_transcript",
                 "segments": None,
-                "cached": True,
+                "bytes": 0,
+            },
+            # mode="auto" (default): a captionless entry escalates to audio.
+            {
+                "video_id": "c",
+                "outcome": "processing",
+                "status": "processing",
+                "job_id": "asr_batch_1",
                 "bytes": 0,
             },
         ],

tests/test_client.py

@@ -83,10 +83,28 @@ def test_batch() -> None:
         return_value=httpx.Response(200, json=BATCH_ENV)
     )
     with _client() as tf:
-        res = tf.transcripts.batch(["a", "b"])
-    assert [r.video_id for r in res.results] == ["a", "b"]
+        res = tf.transcripts.batch(["a", "b", "c"])
+    assert [r.video_id for r in res.results] == ["a", "b", "c"]
     assert res.results[1].outcome == "no_transcript"
-    assert json.loads(route.calls.last.request.content)["videoIds"] == ["a", "b"]
+    # "cached" is gone from the API; the deprecated field must not invent False.
+    assert res.results[0].cached is None
+    # A captionless entry escalated to audio: processing + a pollable job_id.
+    assert res.results[2].outcome == "processing"
+    assert res.results[2].status == "processing"
+    assert res.results[2].job_id == "asr_batch_1"
+    body = json.loads(route.calls.last.request.content)
+    assert body["videoIds"] == ["a", "b", "c"]
+    assert "mode" not in body  # server default (auto) unless asked for
+
+
+@respx.mock
+def test_batch_mode_captions() -> None:
+    route = respx.post(f"{BASE}/api/v1/transcripts/batch").mock(
+        return_value=httpx.Response(200, json=BATCH_ENV)
+    )
+    with _client() as tf:
+        tf.transcripts.batch(["a", "b", "c"], mode="captions")
+    assert json.loads(route.calls.last.request.content)["mode"] == "captions"
 
 
 @respx.mock