Skip to content

Latest commit

 

History

History
135 lines (107 loc) · 5.42 KB

README.md

File metadata and controls

135 lines (107 loc) · 5.42 KB

Transcript Dock for Python

A synchronous client for the Transcript Dock API. Python 3.10 or newer. No runtime dependencies.

Install from PyPI:

python -m pip install transcriptdock

For local development, use python -m pip install . from this directory.

Submit and read a transcript

Set TRANSCRIPTDOCK_API_KEY in your environment. Keep it out of source control.

import os
from uuid import uuid4
from transcriptdock import TranscriptDock, JobTimeoutError

client = TranscriptDock(os.environ["TRANSCRIPTDOCK_API_KEY"])
print(client.capabilities())

# Generate once per intended operation. Save this key and the returned job ID.
# Reuse the same key and exact body if a submission's response is lost.
submission_key = str(uuid4())
job = client.create_job(
    {"source": {"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"},
     "mode": "captions_only", "max_credits": 1},
    idempotency_key=submission_key,
)
try:
    job = client.wait_for_job(job["id"], timeout=120)
except JobTimeoutError as error:
    print("Still running", error.job)
else:
    if job["status"] == "succeeded":
        transcript = client.get_transcript(job["result_id"])
        print(transcript)
        print(client.export_transcript(job["result_id"], "srt"))
    else:
        print(job["status"], job.get("error"))

Creating a job can spend credits. This example caps the request at one credit and requests captions only. It does not enable AI fallback. Check capabilities and your plan before selecting other modes. Never blindly resubmit after a network failure: check the job ID or replay the same body with the same idempotency key. The client does not retry requests automatically.

Supported operations

All responses are dictionaries retaining the API's fields. Request bodies use the API's exact field names; the server validates supported options. See the OpenAPI definition for bodies.

  • capabilities(), usage()
  • create_job(body, idempotency_key=...), get_job(id, wait=0), list_jobs(limit=20, cursor=None), cancel_job(id), retry_job(id, idempotency_key=..., max_credits=None), wait_for_job(id, ...)
  • get_transcript(id), export_transcript(id, format="txt"), delete_transcript(id)
  • create_batch(body, idempotency_key=...), get_batch(id)
  • create_video_discovery(body, idempotency_key=...), get_video_discovery(id)
  • create_language_discovery(body, idempotency_key=...), get_language_discovery(id)
  • create_upload(body), complete_upload(id)
  • list_webhook_endpoints(), create_webhook_endpoint(body), delete_webhook_endpoint(id)

export_transcript returns a string for JSON, TXT, SRT and VTT, preserving the export response. get_transcript preserves raw timing fields without converting units. wait_for_job returns succeeded, failed or cancelled jobs; inspect status before using result_id. Timeout leaves the job running and exposes its last observed response as JobTimeoutError.job (or None if no poll was possible).

create_upload creates an upload slot only. Transfer bytes to the returned signed upload URL separately following the API instructions, without sending your Transcript Dock API key to the storage host. Then call complete_upload. Webhook secrets are sensitive; store them privately and verify callback signatures in your receiver according to the API documentation.

request(method, "/v1/...", body=..., query=...) supports public endpoints added later. It rejects absolute URLs, traversal paths and redirects. Custom API origins must use HTTPS, except loopback HTTP for local development. The default origin is https://www.transcriptdock.com; the apex domain redirects. A success with no body (204 No Content, such as deleting a webhook endpoint) returns an empty dictionary, or an empty string with text=True.

Errors

from transcriptdock import ApiError

try:
    jobs = client.list_jobs(limit=10)
except ApiError as error:
    print(error.code, error.status, error.request_id)
    # retryable and retry_after_seconds describe the API response.
    # Decide whether to retry using the operation's idempotency rules.

Transport failures use NETWORK_ERROR; malformed responses use INVALID_RESPONSE. API messages redact bearer tokens. Error responses do not expose raw HTML pages.

Development and release

PYTHONPATH=src python -m unittest discover -s tests -v
uv build
uvx --from twine==7.0.0 twine check dist/*

Build backend versions are pinned in pyproject.toml; runtime dependencies are empty. Tests use a loopback fixture server and spend no credits.

Before publishing, review artifacts, configure the Transcript Dock publisher on PyPI, enable two factor authentication and use a scoped token or trusted publishing. The founder handles registry sign-in. Upload only the reviewed version with uv publish; verify the public package version afterward. Never put registry or API credentials in this directory. A local build is not a release.

The PyPI trusted publisher uses:

Field Value
Project name transcriptdock
Owner TranscriptDock
Repository transcriptdock-python
Workflow filename release.yml
Environment pypi

Run the GitHub Actions workflow on main with publish enabled for an authorized new release. The normal push workflow checks and builds only. The initial 0.1.0 release and publisher registration completed on 2026-11-15.