From 69e1e733b2a2805f873ae36dc77c904271838d93 Mon Sep 17 00:00:00 2001 From: Facundo Farias Date: Tue, 17 Nov 2026 07:58:21 +0100 Subject: [PATCH 1/2] feat: add audio transcription support --- README.md | 27 +++++++++++++------ pyproject.toml | 2 +- src/pixelvault/_core.py | 2 +- src/pixelvault/audio.py | 57 ++++++++++++++++++++++++++++++++++++++++- src/pixelvault/types.py | 32 +++++++++++++++++++++++ tests/test_client.py | 54 ++++++++++++++++++++++++++++++++++++++ uv.lock | 2 +- 7 files changed, 164 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 6b4c088..878533f 100644 --- a/README.md +++ b/README.md @@ -49,8 +49,15 @@ audio = pv.audio.upload( expires_in=604800, idempotency_key="episode-v1", ) -print(audio["id"], audio["url"], audio["codec"], audio["duration_seconds"]) +started = pv.audio.enrich(audio["id"]) +print(started["id"], started["enrichment"]["job_id"]) +audio_result = pv.audio.wait_for_enrichment(audio["id"], timeout=600) +if audio_result["timed_out"]: + print("resume later with", audio["id"]) +elif audio_result["status"] == "complete": + print(audio_result["audio"]["enrichment"].get("transcript")) fresh = pv.audio.sign_url(audio["id"], expires_in=3600) +print(fresh["original_url"], fresh["enrichment"].get("transcript")) ``` Asyncio: @@ -85,19 +92,23 @@ async with AsyncPixelVault() as pv: | `videos.optimize(id)` / `enrich(id)` | Start asynchronous optimization or transcript/storyboard enrichment | | `videos.wait_for_optimization(id, ...)` / `wait_for_enrichment(id, ...)` | Bounded polling with backoff; returns video, terminal/current status and `timed_out` | | `audio.upload(file \| url=, ...)` | Host original MP3, PCM/float WAV, AAC M4A, or Opus/Vorbis OGG with privacy, TTL, metadata, organization, and retry safety | -| `audio.get(id)` / `list(...)` / `list_all(...)` / `delete(id)` | Audio discovery and lifecycle by stable `aud_` ID | -| `audio.update(id, metadata=, folder=, collection_id=)` / `sign_url(id, expires_in=)` | Replace organization fields or mint a fresh private original URL | +| `audio.enrich(id)` / `wait_for_enrichment(id, ...)` | Start/resume transcription and poll with bounded backoff for text, WebVTT, and timestamped JSON; local timeout never cancels the job | +| `audio.get(id)` / `list(...)` / `list_all(...)` / `delete(id)` | Audio and transcript discovery/lifecycle by stable `aud_` ID | +| `audio.update(id, metadata=, folder=, collection_id=)` / `sign_url(id, expires_in=)` | Replace organization fields or mint fresh private original/transcript URLs | | `exports.start()` / `wait(job_id)` / `download(job_id)` | Owner-authenticated tar export of non-expired images, videos, audio originals, available derivatives and `manifest.json` relationships | | `usage.get()` | Plan, usage, limits and what is left this month (including generation credits) | | `keys.list()` / `keys.create(label=, environment=)` / `keys.revoke(id)` | Manage your API keys (secret keys only) | | `register(email)` | Create an account, returns a first key once | | `device_login_start(email)` + `device_login_complete(email, code)` | Passwordless key minting | -Audio originals have an approved global maximum of 25,000,000 bytes; this is not -a plan allowance. PixelVault validates actual container/codec bytes and preserves -the original without transcoding. Audio editing, conversion, streaming manifests, -and transcription are intentionally unsupported. Sync and asyncio clients expose -the same audio methods. +Audio originals and enrichment sources have an approved global maximum of +25,000,000 bytes; enrichment additionally accepts up to 10 minutes. The file +ceiling is not a plan allowance. PixelVault validates actual container/codec +bytes and preserves the original without transcoding. Audio and video +enrichment share the existing plan allowance. Audio editing, conversion, +streaming manifests, summaries, chapters, show notes, promo copy, and +storyboards remain unsupported. Sync and asyncio clients expose the same audio +methods. ## Errors and retries diff --git a/pyproject.toml b/pyproject.toml index 4b0928e..c5e65a4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "pixelvault" -version = "0.6.0" +version = "0.7.0" description = "Official Python SDK for PixelVault, agent-first media hosting" readme = "README.md" license = "MIT" diff --git a/src/pixelvault/_core.py b/src/pixelvault/_core.py index f40dbaf..77dcba9 100644 --- a/src/pixelvault/_core.py +++ b/src/pixelvault/_core.py @@ -13,7 +13,7 @@ from .errors import PixelVaultError -__version__ = "0.6.0" +__version__ = "0.7.0" DEFAULT_BASE_URL = "https://api.pixelvault.dev" MAX_BACKOFF = 30.0 diff --git a/src/pixelvault/audio.py b/src/pixelvault/audio.py index ffd5b43..2807a40 100644 --- a/src/pixelvault/audio.py +++ b/src/pixelvault/audio.py @@ -4,6 +4,7 @@ import hashlib import io import json +import time import os from contextlib import contextmanager from pathlib import Path @@ -11,7 +12,7 @@ from urllib.parse import quote from ._core import FileInput, Request, drop_none -from .types import Audio, AudioPage, AudioSignedUrl +from .types import Audio, AudioPage, AudioSignedUrl, AudioWaitResult _AUDIO_MAX_BYTES = 25_000_000 @@ -291,6 +292,33 @@ def sign_url(self, audio_id: str, expires_in: Optional[int] = None) -> AudioSign ) return cast(AudioSignedUrl, self._c._send(request)["data"]) + def enrich(self, audio_id: str) -> Audio: + """Start or resume transcription for a hosted audio asset.""" + request = Request("POST", f"/v1/audio/{_seg(audio_id)}/enrich") + return cast(Audio, self._c._send(request)["data"]) + + def wait_for_enrichment( + self, + audio_id: str, + *, + timeout: float = 600.0, + interval: float = 1.0, + max_interval: float = 5.0, + ) -> AudioWaitResult: + """Poll with backoff; a local timeout never cancels the server job.""" + deadline = time.monotonic() + timeout + delay = interval + while True: + audio = self.get(audio_id) + status = audio["enrichment"]["status"] + if status not in ("pending", "processing"): + return {"audio": audio, "status": status, "timed_out": False} + remaining = deadline - time.monotonic() + if remaining <= 0: + return {"audio": audio, "status": status, "timed_out": True} + time.sleep(min(delay, remaining)) + delay = min(delay * 1.5, max_interval) + class AsyncAudioFiles: def __init__(self, client: Any) -> None: @@ -405,3 +433,30 @@ async def sign_url( json=drop_none({"expires_in": expires_in}), ) return cast(AudioSignedUrl, (await self._c._send(request))["data"]) + + async def enrich(self, audio_id: str) -> Audio: + """Start or resume transcription for a hosted audio asset.""" + request = Request("POST", f"/v1/audio/{_seg(audio_id)}/enrich") + return cast(Audio, (await self._c._send(request))["data"]) + + async def wait_for_enrichment( + self, + audio_id: str, + *, + timeout: float = 600.0, + interval: float = 1.0, + max_interval: float = 5.0, + ) -> AudioWaitResult: + """Poll with backoff; a local timeout never cancels the server job.""" + deadline = time.monotonic() + timeout + delay = interval + while True: + audio = await self.get(audio_id) + status = audio["enrichment"]["status"] + if status not in ("pending", "processing"): + return {"audio": audio, "status": status, "timed_out": False} + remaining = deadline - time.monotonic() + if remaining <= 0: + return {"audio": audio, "status": status, "timed_out": True} + await asyncio.sleep(min(delay, remaining)) + delay = min(delay * 1.5, max_interval) diff --git a/src/pixelvault/types.py b/src/pixelvault/types.py index bf01a0e..cd7e265 100644 --- a/src/pixelvault/types.py +++ b/src/pixelvault/types.py @@ -189,6 +189,29 @@ class VideoPage(TypedDict): meta: ListMeta +AudioEnrichmentStatus = Literal["not_requested", "pending", "processing", "complete", "failed"] + + +class AudioTranscript(TypedDict): + status: Literal["complete"] + text_url: NotRequired[str] + vtt_url: NotRequired[str] + segments_url: NotRequired[str] + language: NotRequired[Optional[str]] + languages: NotRequired[List[str]] + model: NotRequired[Optional[str]] + segment_count: NotRequired[int] + + +class AudioEnrichment(TypedDict): + status: AudioEnrichmentStatus + job_id: NotRequired[str] + requested_at: NotRequired[str] + completed_at: NotRequired[Optional[str]] + transcript: NotRequired[Optional[AudioTranscript]] + error: NotRequired[Dict[str, str]] + + class Audio(TypedDict): id: str kind: Literal["audio"] @@ -206,6 +229,7 @@ class Audio(TypedDict): folder: Optional[str] collection_id: Optional[str] metadata: Optional[Dict[str, Any]] + enrichment: AudioEnrichment created_at: str expires_at: NotRequired[str] temporary: NotRequired[bool] @@ -220,8 +244,16 @@ class AudioPage(TypedDict): class AudioSignedUrl(TypedDict): url: str + original_url: str expires: int visibility: Literal["public", "private"] + enrichment: AudioEnrichment + + +class AudioWaitResult(TypedDict): + audio: Audio + status: AudioEnrichmentStatus + timed_out: bool class VideoUploadSession(TypedDict): diff --git a/tests/test_client.py b/tests/test_client.py index 0bd73d2..c3ac005 100644 --- a/tests/test_client.py +++ b/tests/test_client.py @@ -700,6 +700,7 @@ def handler(req): "folder": None, "collection_id": None, "metadata": None, + "enrichment": {"status": "not_requested"}, "created_at": "2026-11-16T00:00:00Z", } @@ -755,8 +756,10 @@ def handler(req): json={ "data": { "url": "https://signed.example/audio.mp3?sig=x", + "original_url": "https://signed.example/audio.mp3?sig=x", "expires": 123, "visibility": "private", + "enrichment": {"status": "not_requested"}, } }, ) @@ -788,6 +791,40 @@ def handler(req): assert signed["expires"] == 123 +def test_audio_starts_and_waits_for_transcription_with_resumable_timeout(): + calls = [] + responses = [ + {**AUDIO, "enrichment": {"job_id": "aen_1", "status": "processing"}}, + { + **AUDIO, + "enrichment": { + "job_id": "aen_1", + "status": "complete", + "transcript": { + "status": "complete", + "text_url": "https://img.pixelvault.dev/p/aud_1.transcript.txt", + }, + }, + }, + {**AUDIO, "enrichment": {"job_id": "aen_1", "status": "processing"}}, + ] + + def handler(req): + calls.append(req) + return httpx.Response(202 if req.method == "POST" else 200, json={"data": responses.pop(0)}) + + pv = make(handler) + started = pv.audio.enrich("aud/1") + completed = pv.audio.wait_for_enrichment("aud_1", timeout=0) + timed_out = pv.audio.wait_for_enrichment("aud_1", timeout=0) + + assert started["enrichment"]["job_id"] == "aen_1" + assert completed["status"] == "complete" and completed["timed_out"] is False + assert completed["audio"]["enrichment"]["transcript"]["text_url"].endswith(".txt") + assert timed_out["status"] == "processing" and timed_out["timed_out"] is True + assert calls[0].url.raw_path == b"/v1/audio/aud%2F1/enrich" + + @pytest.mark.asyncio async def test_async_audio_upload_and_get(): calls = [] @@ -803,6 +840,23 @@ def handler(req): assert calls[0].url.path == "/v1/audio" +@pytest.mark.asyncio +async def test_async_audio_enrich_and_wait(): + responses = [ + {**AUDIO, "enrichment": {"job_id": "aen_1", "status": "pending"}}, + {**AUDIO, "enrichment": {"job_id": "aen_1", "status": "failed"}}, + ] + + def handler(req): + return httpx.Response(202 if req.method == "POST" else 200, json={"data": responses.pop(0)}) + + async with amake(handler) as pv: + started = await pv.audio.enrich("aud_1") + result = await pv.audio.wait_for_enrichment("aud_1", timeout=0) + assert started["enrichment"]["status"] == "pending" + assert result["status"] == "failed" and result["timed_out"] is False + + def test_audio_rejects_an_unknown_direct_format_before_network_io(): def handler(_req): raise AssertionError("network should not be called") diff --git a/uv.lock b/uv.lock index 0970bca..bfaf19a 100644 --- a/uv.lock +++ b/uv.lock @@ -516,7 +516,7 @@ wheels = [ [[package]] name = "pixelvault" -version = "0.6.0" +version = "0.7.0" source = { editable = "." } dependencies = [ { name = "httpx" }, From 2fe750a2b735643235130e43356bbc4664d1095e Mon Sep 17 00:00:00 2001 From: Facundo Farias Date: Tue, 17 Nov 2026 08:13:24 +0100 Subject: [PATCH 2/2] fix: classify audio API operations --- scripts/check_spec_coverage.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/check_spec_coverage.py b/scripts/check_spec_coverage.py index 1c56ebb..73286c4 100644 --- a/scripts/check_spec_coverage.py +++ b/scripts/check_spec_coverage.py @@ -14,7 +14,7 @@ "register_account", "device_login_start", "device_login_complete", "list_videos", "upload_video", "get_video", "delete_video", "update_video", "optimize_video", "enrich_video", "analyze_video", "generate_video_poster", "sign_video_url", - "upload_audio", "list_audio", "get_audio", "update_audio", "sign_audio_url", "delete_audio", + "upload_audio", "list_audio", "get_audio", "update_audio", "sign_audio_url", "delete_audio", "enrich_audio", "create_video_upload", "upload_video_part", "complete_video_upload", "abort_video_upload", "start_export", "get_export_job", "download_export", } @@ -29,7 +29,7 @@ "start_checkout", "open_billing_portal", "list_collections", "get_collection", "close_collection", # Advanced image, webhook, and anonymous-playground surfaces are intentionally separate. - "describe_image", "edit_image", "list_image_tags", "playground_video_upload", + "describe_image", "edit_image", "list_image_tags", "playground_video_upload", "playground_audio_upload", "list_webhooks", "create_webhook", "update_webhook", "delete_webhook", "rotate_webhook_secret", "list_webhook_deliveries",