|
| 1 | +# Transcript Dock for Java |
| 2 | + |
| 3 | +A synchronous client for the [Transcript Dock API](https://www.transcriptdock.com/docs). |
| 4 | +Java 11 or newer, also usable from Kotlin on the JVM. No runtime dependencies: it |
| 5 | +uses the JDK's `java.net.http.HttpClient` and a small built in JSON reader. |
| 6 | + |
| 7 | +Maven coordinates are `com.transcriptdock:transcriptdock:0.1.0`. |
| 8 | + |
| 9 | +```xml |
| 10 | +<dependency> |
| 11 | + <groupId>com.transcriptdock</groupId> |
| 12 | + <artifactId>transcriptdock</artifactId> |
| 13 | + <version>0.1.0</version> |
| 14 | +</dependency> |
| 15 | +``` |
| 16 | + |
| 17 | +Gradle: |
| 18 | + |
| 19 | +```kotlin |
| 20 | +implementation("com.transcriptdock:transcriptdock:0.1.0") |
| 21 | +``` |
| 22 | + |
| 23 | +The first release to Maven Central is awaiting review. Until it appears there, run |
| 24 | +`mvn install` in this directory to use the library from your local repository. |
| 25 | + |
| 26 | +## Submit and read a transcript |
| 27 | + |
| 28 | +Set `TRANSCRIPTDOCK_API_KEY` in your environment. Keep it out of source control. |
| 29 | + |
| 30 | +```java |
| 31 | +import com.transcriptdock.JobTimeoutException; |
| 32 | +import com.transcriptdock.TranscriptDock; |
| 33 | +import java.time.Duration; |
| 34 | +import java.util.Map; |
| 35 | +import java.util.UUID; |
| 36 | + |
| 37 | +TranscriptDock client = new TranscriptDock(System.getenv("TRANSCRIPTDOCK_API_KEY")); |
| 38 | +System.out.println(client.capabilities()); |
| 39 | + |
| 40 | +// Generate once per intended operation. Save this key and the returned job ID. |
| 41 | +// Reuse the same key and exact body if a submission's response is lost. |
| 42 | +String submissionKey = UUID.randomUUID().toString(); |
| 43 | +Map<String, Object> job = client.createJob(Map.of( |
| 44 | + "source", Map.of("url", "https://www.youtube.com/watch?v=dQw4w9WgXcQ"), |
| 45 | + "mode", "captions_only", |
| 46 | + "max_credits", 1), submissionKey); |
| 47 | +try { |
| 48 | + job = client.waitForJob((String) job.get("id"), Duration.ofSeconds(120), Duration.ofSeconds(3)); |
| 49 | + if ("succeeded".equals(job.get("status"))) { |
| 50 | + String transcriptId = (String) job.get("result_id"); |
| 51 | + System.out.println(client.getTranscript(transcriptId)); |
| 52 | + System.out.println(client.exportTranscript(transcriptId, "srt")); |
| 53 | + } else { |
| 54 | + System.out.println(job.get("status") + " " + job.get("error")); |
| 55 | + } |
| 56 | +} catch (JobTimeoutException error) { |
| 57 | + System.out.println("Still running " + error.getJob()); |
| 58 | +} |
| 59 | +``` |
| 60 | + |
| 61 | +Kotlin: |
| 62 | + |
| 63 | +```kotlin |
| 64 | +val client = TranscriptDock(System.getenv("TRANSCRIPTDOCK_API_KEY")) |
| 65 | +val key = java.util.UUID.randomUUID().toString() |
| 66 | +val job = client.createJob( |
| 67 | + mapOf("source" to mapOf("url" to "https://www.youtube.com/watch?v=dQw4w9WgXcQ"), |
| 68 | + "mode" to "captions_only", "max_credits" to 1), |
| 69 | + key, |
| 70 | +) |
| 71 | +val done = client.waitForJob(job["id"] as String) |
| 72 | +if (done["status"] == "succeeded") println(client.exportTranscript(done["result_id"] as String, "srt")) |
| 73 | +``` |
| 74 | + |
| 75 | +Creating a job can spend credits. This example caps the request at one credit |
| 76 | +and requests captions only. It does not enable AI fallback. Check capabilities |
| 77 | +and your plan before selecting other modes. Never blindly resubmit after a |
| 78 | +network failure: check the job ID or replay the same body with the same |
| 79 | +idempotency key. The client does not retry requests automatically. |
| 80 | + |
| 81 | +## Supported operations |
| 82 | + |
| 83 | +All responses are `Map<String, Object>` values that keep every field the API |
| 84 | +returns, including fields added later. Nested objects are maps, arrays are lists, |
| 85 | +integers are `Long`, other numbers are `Double` (or `BigDecimal` when too large). |
| 86 | +Request bodies use the API's exact field names; the server validates supported |
| 87 | +options. See the [OpenAPI definition](https://www.transcriptdock.com/docs/openapi.yaml) |
| 88 | +for bodies. |
| 89 | + |
| 90 | +* `capabilities()`, `usage()` |
| 91 | +* `createJob(body, idempotencyKey)`, `getJob(id)`, `getJob(id, wait)`, |
| 92 | + `listJobs()`, `listJobs(limit, cursor)`, `cancelJob(id)`, |
| 93 | + `retryJob(id, idempotencyKey)`, `retryJob(id, idempotencyKey, maxCredits)`, |
| 94 | + `waitForJob(id)`, `waitForJob(id, timeout, pollInterval)` |
| 95 | +* `getTranscript(id)`, `exportTranscript(id)`, `exportTranscript(id, format)`, `deleteTranscript(id)` |
| 96 | +* `createBatch(body, idempotencyKey)`, `getBatch(id)` |
| 97 | +* `createVideoDiscovery(body, idempotencyKey)`, `getVideoDiscovery(id)` |
| 98 | +* `createLanguageDiscovery(body, idempotencyKey)`, `getLanguageDiscovery(id)` |
| 99 | +* `createUpload(body)`, `completeUpload(id)` |
| 100 | +* `listWebhookEndpoints()`, `createWebhookEndpoint(body)`, `deleteWebhookEndpoint(id)` |
| 101 | + |
| 102 | +`exportTranscript` returns a `String` for JSON, TXT, SRT and VTT, preserving the |
| 103 | +export response. `getTranscript` preserves raw timing fields without converting |
| 104 | +units. `waitForJob` returns succeeded, failed or cancelled jobs; inspect status |
| 105 | +before using `result_id`. Its defaults are 120 seconds and a 3 second poll |
| 106 | +interval. A timeout leaves the job running and throws `JobTimeoutException`, |
| 107 | +whose `getJob()` returns the last observed response (or `null` if no poll was |
| 108 | +possible). A response with no content, such as 204, returns an empty map. |
| 109 | + |
| 110 | +`createUpload` creates an upload slot only. Transfer bytes to the returned signed |
| 111 | +upload URL separately following the API instructions, without sending your |
| 112 | +Transcript Dock API key to the storage host. Then call `completeUpload`. |
| 113 | +Webhook secrets are sensitive; store them privately and verify callback |
| 114 | +signatures in your receiver according to the API documentation. |
| 115 | + |
| 116 | +`request(method, "/v1/...", body, query, idempotencyKey)` supports public |
| 117 | +endpoints added later. Use `requestText` or the seven argument `request` with |
| 118 | +`text` set to `true` for non JSON responses. Methods must be uppercase. Paths |
| 119 | +cannot contain a query, fragment, backslash or dot segments, even percent |
| 120 | +encoded. Submissions to `/v1/jobs`, `/v1/batches`, `/v1/video-discoveries`, |
| 121 | +`/v1/language-discoveries` and any `/retry` path require an idempotency key of 8 |
| 122 | +to 128 printable ASCII characters. Redirects are never followed. |
| 123 | + |
| 124 | +The client is immutable and thread safe; share one instance. The default request |
| 125 | +timeout is 30 seconds. Use the builder for another origin or timeout: |
| 126 | + |
| 127 | +```java |
| 128 | +TranscriptDock client = TranscriptDock.builder(apiKey) |
| 129 | + .baseUrl("https://www.transcriptdock.com") |
| 130 | + .timeout(Duration.ofSeconds(10)) |
| 131 | + .build(); |
| 132 | +``` |
| 133 | + |
| 134 | +Custom API origins must use HTTPS, except loopback HTTP for local development. |
| 135 | +The default origin is `https://www.transcriptdock.com`; the apex domain redirects. |
| 136 | + |
| 137 | +## Errors |
| 138 | + |
| 139 | +```java |
| 140 | +import com.transcriptdock.ApiException; |
| 141 | + |
| 142 | +try { |
| 143 | + Map<String, Object> jobs = client.listJobs(10, null); |
| 144 | +} catch (ApiException error) { |
| 145 | + System.out.println(error.getCode() + " " + error.getStatus() + " " + error.getRequestId()); |
| 146 | + // isRetryable() and getRetryAfterSeconds() describe the API response. |
| 147 | + // Decide whether to retry using the operation's idempotency rules. |
| 148 | +} |
| 149 | +``` |
| 150 | + |
| 151 | +`ApiException` is unchecked. Transport failures and timeouts use `NETWORK_ERROR` |
| 152 | +with a null status; malformed responses use `INVALID_RESPONSE`. A redirect is an |
| 153 | +`ApiException` with its 3xx status. API messages redact bearer tokens. Error |
| 154 | +responses do not expose raw HTML pages. Invalid arguments throw |
| 155 | +`IllegalArgumentException` before any request is sent. |
| 156 | + |
| 157 | +The client itself never retries. The JDK HTTP client can retry a failed |
| 158 | +connection attempt, and can resend a GET or HEAD once when a reused pooled |
| 159 | +connection turns out to be closed. It does not resend a POST unless you set the |
| 160 | +`jdk.httpclient.enableAllMethodRetry` system property, so leave it unset. |
| 161 | + |
| 162 | +## Platform support |
| 163 | + |
| 164 | +Desktop and server JVMs running Java 11 or newer, from Java or Kotlin. Android |
| 165 | +does not ship `java.net.http`, so this library does not run on Android. |
| 166 | + |
| 167 | +## Development and release |
| 168 | + |
| 169 | +```sh |
| 170 | +mvn -B -ntp verify |
| 171 | +python3 .ci/check.py |
| 172 | +``` |
| 173 | + |
| 174 | +`mvn verify` compiles for Java 11, runs the JUnit tests and builds the main, |
| 175 | +sources and javadoc jars. `.ci/check.py` runs the contract checks in |
| 176 | +`src/test/java/com/transcriptdock/ClientCheck.java` against a loopback fixture |
| 177 | +server; run it after `mvn verify`. Tests spend no credits and never call |
| 178 | +production. Every Maven plugin version is pinned in `pom.xml`; CI installs a |
| 179 | +pinned, checksum verified Maven. Maven has no lockfile format; the only |
| 180 | +dependency is JUnit in test scope. |
| 181 | + |
| 182 | +Maven Central has no OIDC trusted publishing, so the publish job uses a Central |
| 183 | +Portal user token and a GPG key. One time setup by the founder: |
| 184 | + |
| 185 | +1. Sign in at https://central.sonatype.com and add the namespace `com.transcriptdock`. |
| 186 | +2. Verify it by adding the DNS TXT record the portal shows to `transcriptdock.com`. |
| 187 | +3. Generate a user token in the portal. |
| 188 | +4. Create a GPG signing key and upload the public key to https://keys.openpgp.org. |
| 189 | +5. In this repository, create the `maven-central` environment and add the secrets |
| 190 | + `CENTRAL_TOKEN_USERNAME`, `CENTRAL_TOKEN_PASSWORD`, `GPG_PRIVATE_KEY` |
| 191 | + (ASCII armored, from `gpg --armor --export-secret-keys KEY_ID`) and `GPG_PASSPHRASE`. |
| 192 | + |
| 193 | +Run the GitHub Actions workflow on `main` with `publish` enabled for an |
| 194 | +authorized new release. It signs the artifacts and uploads them as a deployment |
| 195 | +that is not published automatically. Review it in the Central Portal and press |
| 196 | +Publish. The normal push workflow checks and builds only. Never put registry or |
| 197 | +API credentials in this directory. A local build is not a release. |
0 commit comments