A synchronous client for the Transcript Dock API.
Java 11 or newer, also usable from Kotlin on the JVM. No runtime dependencies: it
uses the JDK's java.net.http.HttpClient and a small built in JSON reader.
Maven coordinates are com.transcriptdock:transcriptdock:0.1.0.
<dependency>
<groupId>com.transcriptdock</groupId>
<artifactId>transcriptdock</artifactId>
<version>0.1.0</version>
</dependency>Gradle:
implementation("com.transcriptdock:transcriptdock:0.1.0")The first release to Maven Central is awaiting review. Until it appears there, run
mvn install in this directory to use the library from your local repository.
Set TRANSCRIPTDOCK_API_KEY in your environment. Keep it out of source control.
import com.transcriptdock.JobTimeoutException;
import com.transcriptdock.TranscriptDock;
import java.time.Duration;
import java.util.Map;
import java.util.UUID;
TranscriptDock client = new TranscriptDock(System.getenv("TRANSCRIPTDOCK_API_KEY"));
System.out.println(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.
String submissionKey = UUID.randomUUID().toString();
Map<String, Object> job = client.createJob(Map.of(
"source", Map.of("url", "https://www.youtube.com/watch?v=dQw4w9WgXcQ"),
"mode", "captions_only",
"max_credits", 1), submissionKey);
try {
job = client.waitForJob((String) job.get("id"), Duration.ofSeconds(120), Duration.ofSeconds(3));
if ("succeeded".equals(job.get("status"))) {
String transcriptId = (String) job.get("result_id");
System.out.println(client.getTranscript(transcriptId));
System.out.println(client.exportTranscript(transcriptId, "srt"));
} else {
System.out.println(job.get("status") + " " + job.get("error"));
}
} catch (JobTimeoutException error) {
System.out.println("Still running " + error.getJob());
}Kotlin:
val client = TranscriptDock(System.getenv("TRANSCRIPTDOCK_API_KEY"))
val key = java.util.UUID.randomUUID().toString()
val job = client.createJob(
mapOf("source" to mapOf("url" to "https://www.youtube.com/watch?v=dQw4w9WgXcQ"),
"mode" to "captions_only", "max_credits" to 1),
key,
)
val done = client.waitForJob(job["id"] as String)
if (done["status"] == "succeeded") println(client.exportTranscript(done["result_id"] as String, "srt"))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.
All responses are Map<String, Object> values that keep every field the API
returns, including fields added later. Nested objects are maps, arrays are lists,
integers are Long, other numbers are Double (or BigDecimal when too large).
Request bodies use the API's exact field names; the server validates supported
options. See the OpenAPI definition
for bodies.
capabilities(),usage()createJob(body, idempotencyKey),getJob(id),getJob(id, wait),listJobs(),listJobs(limit, cursor),cancelJob(id),retryJob(id, idempotencyKey),retryJob(id, idempotencyKey, maxCredits),waitForJob(id),waitForJob(id, timeout, pollInterval)getTranscript(id),exportTranscript(id),exportTranscript(id, format),deleteTranscript(id)createBatch(body, idempotencyKey),getBatch(id)createVideoDiscovery(body, idempotencyKey),getVideoDiscovery(id)createLanguageDiscovery(body, idempotencyKey),getLanguageDiscovery(id)createUpload(body),completeUpload(id)listWebhookEndpoints(),createWebhookEndpoint(body),deleteWebhookEndpoint(id)
exportTranscript returns a String for JSON, TXT, SRT and VTT, preserving the
export response. getTranscript preserves raw timing fields without converting
units. waitForJob returns succeeded, failed or cancelled jobs; inspect status
before using result_id. Its defaults are 120 seconds and a 3 second poll
interval. A timeout leaves the job running and throws JobTimeoutException,
whose getJob() returns the last observed response (or null if no poll was
possible). A response with no content, such as 204, returns an empty map.
createUpload 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 completeUpload.
Webhook secrets are sensitive; store them privately and verify callback
signatures in your receiver according to the API documentation.
request(method, "/v1/...", body, query, idempotencyKey) supports public
endpoints added later. Use requestText or the seven argument request with
text set to true for non JSON responses. Methods must be uppercase. Paths
cannot contain a query, fragment, backslash or dot segments, even percent
encoded. Submissions to /v1/jobs, /v1/batches, /v1/video-discoveries,
/v1/language-discoveries and any /retry path require an idempotency key of 8
to 128 printable ASCII characters. Redirects are never followed.
The client is immutable and thread safe; share one instance. The default request timeout is 30 seconds. Use the builder for another origin or timeout:
TranscriptDock client = TranscriptDock.builder(apiKey)
.baseUrl("https://www.transcriptdock.com")
.timeout(Duration.ofSeconds(10))
.build();Custom API origins must use HTTPS, except loopback HTTP for local development.
The default origin is https://www.transcriptdock.com; the apex domain redirects.
import com.transcriptdock.ApiException;
try {
Map<String, Object> jobs = client.listJobs(10, null);
} catch (ApiException error) {
System.out.println(error.getCode() + " " + error.getStatus() + " " + error.getRequestId());
// isRetryable() and getRetryAfterSeconds() describe the API response.
// Decide whether to retry using the operation's idempotency rules.
}ApiException is unchecked. Transport failures and timeouts use NETWORK_ERROR
with a null status; malformed responses use INVALID_RESPONSE. A redirect is an
ApiException with its 3xx status. API messages redact bearer tokens. Error
responses do not expose raw HTML pages. Invalid arguments throw
IllegalArgumentException before any request is sent.
The client itself never retries. The JDK HTTP client can retry a failed
connection attempt, and can resend a GET or HEAD once when a reused pooled
connection turns out to be closed. It does not resend a POST unless you set the
jdk.httpclient.enableAllMethodRetry system property, so leave it unset.
Desktop and server JVMs running Java 11 or newer, from Java or Kotlin. Android
does not ship java.net.http, so this library does not run on Android.
mvn -B -ntp verify
python3 .ci/check.pymvn verify compiles for Java 11, runs the JUnit tests and builds the main,
sources and javadoc jars. .ci/check.py runs the contract checks in
src/test/java/com/transcriptdock/ClientCheck.java against a loopback fixture
server; run it after mvn verify. Tests spend no credits and never call
production. Every Maven plugin version is pinned in pom.xml; CI installs a
pinned, checksum verified Maven. Maven has no lockfile format; the only
dependency is JUnit in test scope.
Maven Central has no OIDC trusted publishing, so the publish job uses a Central Portal user token and a GPG key. One time setup by the founder:
- Sign in at https://central.sonatype.com and add the namespace
com.transcriptdock. - Verify it by adding the DNS TXT record the portal shows to
transcriptdock.com. - Generate a user token in the portal.
- Create a GPG signing key and upload the public key to https://keys.openpgp.org.
- In this repository, create the
maven-centralenvironment and add the secretsCENTRAL_TOKEN_USERNAME,CENTRAL_TOKEN_PASSWORD,GPG_PRIVATE_KEY(ASCII armored, fromgpg --armor --export-secret-keys KEY_ID) andGPG_PASSPHRASE.
Run the GitHub Actions workflow on main with publish enabled for an
authorized new release. It signs the artifacts and uploads them as a deployment
that is not published automatically. Review it in the Central Portal and press
Publish. The normal push workflow checks and builds only. Never put registry or
API credentials in this directory. A local build is not a release.