Skip to content

Latest commit

 

History

History
197 lines (161 loc) · 8.73 KB

README.md

File metadata and controls

197 lines (161 loc) · 8.73 KB

Transcript Dock for Java

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.

Submit and read a transcript

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.

Supported operations

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.

Errors

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.

Platform support

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.

Development and release

mvn -B -ntp verify
python3 .ci/check.py

mvn 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:

  1. Sign in at https://central.sonatype.com and add the namespace com.transcriptdock.
  2. Verify it by adding the DNS TXT record the portal shows to transcriptdock.com.
  3. Generate a user token in the portal.
  4. Create a GPG signing key and upload the public key to https://keys.openpgp.org.
  5. In this repository, create the maven-central environment and add the secrets CENTRAL_TOKEN_USERNAME, CENTRAL_TOKEN_PASSWORD, GPG_PRIVATE_KEY (ASCII armored, from gpg --armor --export-secret-keys KEY_ID) and GPG_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.