Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 19 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
4 changes: 2 additions & 2 deletions scripts/check_spec_coverage.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
}
Expand All @@ -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",

Expand Down
2 changes: 1 addition & 1 deletion src/pixelvault/_core.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
57 changes: 56 additions & 1 deletion src/pixelvault/audio.py
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,15 @@
import hashlib
import io
import json
import time
import os
from contextlib import contextmanager
from pathlib import Path
from typing import Any, AsyncIterator, BinaryIO, Dict, Iterator, Optional, Tuple, cast
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

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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)
32 changes: 32 additions & 0 deletions src/pixelvault/types.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand All @@ -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]
Expand All @@ -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):
Expand Down
54 changes: 54 additions & 0 deletions tests/test_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
}

Expand Down Expand Up @@ -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"},
}
},
)
Expand Down Expand Up @@ -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 = []
Expand All @@ -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")
Expand Down
2 changes: 1 addition & 1 deletion uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading