Skip to content

Commit 912c624

Browse files
committed
Add Transcript Dock Python API client and release checks
0 parents  commit 912c624

8 files changed

Lines changed: 599 additions & 0 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Check and release Python package
2+
on:
3+
push:
4+
branches: [main]
5+
pull_request:
6+
workflow_dispatch:
7+
inputs:
8+
publish:
9+
description: Publish the checked version to PyPI
10+
type: boolean
11+
default: false
12+
permissions:
13+
contents: read
14+
jobs:
15+
test:
16+
runs-on: ubuntu-latest
17+
strategy:
18+
matrix:
19+
python: ['3.10', '3.12', '3.14']
20+
steps:
21+
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
22+
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
23+
with:
24+
python-version: ${{ matrix.python }}
25+
- run: PYTHONPATH=src python -W error::ResourceWarning -m unittest discover -s tests -v
26+
build:
27+
needs: test
28+
runs-on: ubuntu-latest
29+
steps:
30+
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
31+
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
32+
with:
33+
python-version: '3.12'
34+
- run: python -m pip install build==1.6.1 twine==7.0.0
35+
- run: python -m build
36+
- run: python -m twine check dist/*
37+
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
38+
with:
39+
name: distributions
40+
path: dist/*
41+
publish:
42+
if: github.event_name == 'workflow_dispatch' && inputs.publish && github.ref == 'refs/heads/main'
43+
needs: build
44+
runs-on: ubuntu-latest
45+
environment: pypi
46+
permissions:
47+
id-token: write
48+
steps:
49+
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
50+
with:
51+
name: distributions
52+
path: dist/
53+
- uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
dist/
2+
__pycache__/
3+
*.pyc
4+
.venv/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Transcript Dock
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Transcript Dock for Python
2+
3+
A synchronous client for the [Transcript Dock API](https://www.transcriptdock.com/docs).
4+
Python 3.10 or newer. No runtime dependencies.
5+
6+
Release status: source and local distribution preparation. Version 0.1.0 is
7+
not published on PyPI yet. Install from this directory:
8+
9+
```sh
10+
python -m pip install .
11+
```
12+
13+
Once a PyPI release is verified, the install command will be
14+
`python -m pip install transcriptdock`.
15+
16+
## Submit and read a transcript
17+
18+
Set `TRANSCRIPTDOCK_API_KEY` in your environment. Keep it out of source control.
19+
20+
```python
21+
import os
22+
from uuid import uuid4
23+
from transcriptdock import TranscriptDock, JobTimeoutError
24+
25+
client = TranscriptDock(os.environ["TRANSCRIPTDOCK_API_KEY"])
26+
print(client.capabilities())
27+
28+
# Generate once per intended operation. Save this key and the returned job ID.
29+
# Reuse the same key and exact body if a submission's response is lost.
30+
submission_key = str(uuid4())
31+
job = client.create_job(
32+
{"source": {"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"},
33+
"mode": "captions_only", "max_credits": 1},
34+
idempotency_key=submission_key,
35+
)
36+
try:
37+
job = client.wait_for_job(job["id"], timeout=120)
38+
except JobTimeoutError as error:
39+
print("Still running", error.job)
40+
else:
41+
if job["status"] == "succeeded":
42+
transcript = client.get_transcript(job["result_id"])
43+
print(transcript)
44+
print(client.export_transcript(job["result_id"], "srt"))
45+
else:
46+
print(job["status"], job.get("error"))
47+
```
48+
49+
Creating a job can spend credits. This example caps the request at one credit
50+
and requests captions only. It does not enable AI fallback. Check capabilities
51+
and your plan before selecting other modes. Never blindly resubmit after a
52+
network failure: check the job ID or replay the same body with the same
53+
idempotency key. The client does not retry requests automatically.
54+
55+
## Supported operations
56+
57+
All responses are dictionaries retaining the API's fields. Request bodies use
58+
the API's exact field names; the server validates supported options. See the
59+
[OpenAPI definition](https://www.transcriptdock.com/docs/openapi.yaml) for bodies.
60+
61+
* `capabilities()`, `usage()`
62+
* `create_job(body, idempotency_key=...)`, `get_job(id, wait=0)`,
63+
`list_jobs(limit=20, cursor=None)`, `cancel_job(id)`,
64+
`retry_job(id, idempotency_key=..., max_credits=None)`, `wait_for_job(id, ...)`
65+
* `get_transcript(id)`, `export_transcript(id, format="txt")`, `delete_transcript(id)`
66+
* `create_batch(body, idempotency_key=...)`, `get_batch(id)`
67+
* `create_video_discovery(body, idempotency_key=...)`, `get_video_discovery(id)`
68+
* `create_language_discovery(body, idempotency_key=...)`, `get_language_discovery(id)`
69+
* `create_upload(body)`, `complete_upload(id)`
70+
* `list_webhook_endpoints()`, `create_webhook_endpoint(body)`, `delete_webhook_endpoint(id)`
71+
72+
`export_transcript` returns a string for JSON, TXT, SRT and VTT, preserving the
73+
export response. `get_transcript` preserves raw timing fields without converting
74+
units. `wait_for_job` returns succeeded, failed or cancelled jobs; inspect status
75+
before using `result_id`. Timeout leaves the job running and exposes its last
76+
observed response as `JobTimeoutError.job` (or `None` if no poll was possible).
77+
78+
`create_upload` creates an upload slot only. Transfer bytes to the returned signed
79+
upload URL separately following the API instructions, without sending your
80+
Transcript Dock API key to the storage host. Then call `complete_upload`.
81+
Webhook secrets are sensitive; store them privately and verify callback
82+
signatures in your receiver according to the API documentation.
83+
84+
`request(method, "/v1/...", body=..., query=...)` supports public endpoints added
85+
later. It rejects absolute URLs, traversal paths and redirects. Custom API
86+
origins must use HTTPS, except loopback HTTP for local development. The default
87+
origin is `https://www.transcriptdock.com`; the apex domain redirects.
88+
89+
## Errors
90+
91+
```python
92+
from transcriptdock import ApiError
93+
94+
try:
95+
jobs = client.list_jobs(limit=10)
96+
except ApiError as error:
97+
print(error.code, error.status, error.request_id)
98+
# retryable and retry_after_seconds describe the API response.
99+
# Decide whether to retry using the operation's idempotency rules.
100+
```
101+
102+
Transport failures use `NETWORK_ERROR`; malformed responses use `INVALID_RESPONSE`.
103+
API messages redact bearer tokens. Error responses do not expose raw HTML pages.
104+
105+
## Development and release
106+
107+
```sh
108+
PYTHONPATH=src python -m unittest discover -s tests -v
109+
uv build
110+
uvx --from twine==7.0.0 twine check dist/*
111+
```
112+
113+
Build backend versions are pinned in `pyproject.toml`; runtime dependencies are
114+
empty. Tests use a loopback fixture server and spend no credits.
115+
116+
Before publishing, review artifacts, configure the Transcript Dock publisher on
117+
PyPI, enable two factor authentication and use a scoped token or trusted
118+
publishing. The founder handles registry sign-in. Upload only the reviewed
119+
version with `uv publish`; verify the public package version afterward. Never
120+
put registry or API credentials in this directory. A local build is not a release.
121+
122+
123+
For the first release, add a pending trusted publisher in PyPI with:
124+
125+
| Field | Value |
126+
| --- | --- |
127+
| Project name | `transcriptdock` |
128+
| Owner | `TranscriptDock` |
129+
| Repository | `transcriptdock-python` |
130+
| Workflow filename | `release.yml` |
131+
| Environment | `pypi` |
132+
133+
Then run the GitHub Actions workflow on `main` with `publish` enabled. The
134+
normal push workflow checks and builds only. Sign-in and initial publisher
135+
registration are still required; no PyPI account has been created for you.

‎pyproject.toml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
[build-system]
2+
requires = ["hatchling==1.33.0"]
3+
build-backend = "hatchling.build"
4+
5+
[project]
6+
name = "transcriptdock"
7+
version = "0.1.0"
8+
description = "Python client for the Transcript Dock video transcription API"
9+
readme = "README.md"
10+
requires-python = ">=3.10"
11+
license = "MIT"
12+
license-files = ["LICENSE"]
13+
authors = [{name = "Transcript Dock", email = "transcriptdock@volods.com"}]
14+
keywords = ["transcription", "youtube", "tiktok", "subtitles", "api", "mcp"]
15+
classifiers = ["Programming Language :: Python :: 3", "Operating System :: OS Independent"]
16+
dependencies = []
17+
18+
[project.urls]
19+
Homepage = "https://www.transcriptdock.com"
20+
Documentation = "https://www.transcriptdock.com/docs"
21+
Repository = "https://github.com/TranscriptDock/transcriptdock-python"
22+
Issues = "https://github.com/TranscriptDock/transcriptdock-python/issues"
23+
24+
[tool.hatch.build.targets.wheel]
25+
packages = ["src/transcriptdock"]

0 commit comments

Comments
 (0)