Go SDK

The official Go client for the Speech Revolutions STT API.

Source on GitHub · report an issue · pkg.go.dev

Install

bash

go get github.com/speechrevolutions/speechrevolutions-go

Quickstart

Transcribe accepts a local file path, an http(s) URL, or raw bytes (TranscribeBytes). The last argument is an optional transcription-progress callback (nil for none). Bool and tier options are pointers, so an unset field is distinct from false. Leave them nil to use the default.

main.go

package main

import (
    "context"
    "fmt"
    "log"

    stt "github.com/speechrevolutions/speechrevolutions-go"
)

func main() {
    ctx := context.Background()

    client, err := stt.NewClient("") // SPEECHREVOLUTIONS_API_KEY
    if err != nil {
        log.Fatal(err)
    }

    result, err := client.Transcribe(ctx, "meeting.mp3", stt.TranscribeOptions{
        SpeakerLabels: stt.Bool(true),
    }, nil)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(result.Text())
    for _, u := range result.Utterances {
        fmt.Printf("%s: %s\n", u.Speaker, u.Text)
    }
}

From a URL or file

// explicit alias
result, err := client.TranscribeURL(ctx, "https://example.com/audio.mp3", stt.TranscribeOptions{}, nil)

// or, since Transcribe detects http(s):
result, err = client.Transcribe(ctx, "https://example.com/audio.mp3", stt.TranscribeOptions{}, nil)

// TranscribeFile is the same for a local path; TranscribeBytes for in-memory audio.

Options

Set fields on TranscribeOptions. An empty TranscribeOptions{} uses every default.

Field	Type	Default	Notes
`OutputType`	`OutputType`	`OutputJSON`	`txt \| json \| srt \| vtt \| docx \| pdf`
`WordTimestamps`	`*bool`	`true`	Per-word start/end times
`SpeakerLabels`	`*bool`	`true`	Label who spoke each segment
`Diarize`	`*bool`	—	Alias for `SpeakerLabels`
`NLTK`	`*bool`	`true`	Restore punctuation & capitalization
`Tier`	`*ProcessingTier`	`TierStandard`	`TierStandard` — the only tier currently available
`CustomVocabulary`	`[]string`	`nil`	Domain terms to bias toward
`Language`	`string`	`""`	ISO 639-1 code (e.g. `"en"`) to skip detection; empty detects the language automatically. When to pin
`OnUploadProgress`	`ProgressFunc`	`nil`	Upload byte-progress callback
`Progress`	`bool`	`false`	Render live console bars

Live progress

The SDK reports progress for both the file upload and the transcription, as a console bar, callbacks, or both. When you enable both, the bars render and your callbacks fire for every event. AssemblyAI and Deepgram expose no percentage for pre-recorded audio.

Files under about 3 MiB may report no transcription progress before they complete. Expect the bar to jump from the end of the upload to done.

// 1. Console bars — a single stderr line, updated in place. Shows an
//    "Uploading" byte bar, then a "Transcribing" bar. Off by default.
result, _ := client.Transcribe(ctx, "meeting.mp3", stt.TranscribeOptions{
    SpeakerLabels: stt.Bool(true),
    Progress:      true,
}, nil)

// 2. Programmatic — Percent() returns (float64, bool); the bool is false when
//    the total is unknown, so treat that as "unknown".
onProgress := func(e stt.ProgressEvent) { // transcription
    if pct, ok := e.Percent(); ok {
        fmt.Printf("%.0f%% %s\n", pct, e.Step) // e.g. 42 "transcribe"
    }
}
onUpload := func(e stt.ProgressEvent) { // upload (e.Step == "upload")
    if pct, ok := e.Percent(); ok {
        fmt.Printf("upload %.0f%%\n", pct)
    }
}

result, _ = client.Transcribe(ctx, "meeting.mp3", stt.TranscribeOptions{
    OnUploadProgress: onUpload,
    Progress:         true, // bars AND callbacks together
}, onProgress)

For a web UI, see Live progress for web apps. It combines both callbacks into a single 0–100 bar for your frontend.

Result shape

With OutputJSON, the SDK parses the response into a result object:

Access	Description
`result.Text()`	Full transcript text
`result.TranscriptText()`	Alias for `result.Text()`
`result.Words`	Words with start, end, and speaker
`result.Utterances`	Speaker turns
`result.ToDeepgram()`	Deepgram-shaped map, for migrations
`result.ToDict()`	Normalized map
`result.Content` / `result.Save(path)`	Raw bytes / write the output to disk

// Save writes output.<output_type> when the path has no extension.
out, err := result.Save("output") // -> "output.json"
if err != nil {
    log.Fatal(err)
}
fmt.Println("saved to", out)

Webhooks

Set CallbackURL to get notified when a job finishes instead of holding the call open. When the job completes or fails permanently, Speech Revolutions sends a signed JSON POST to your URL. The body is {job_id, status: "completed"|"failed", download_url?, step?, reason?}. It is signed with HMAC-SHA256 over the raw body, in the X-SR-Signature: sha256=<hex> header. The request also carries X-SR-Event (the status) and a unique X-SR-Delivery ID. Verify the signature against the raw request bytes with crypto/hmac and crypto/subtle.ConstantTimeCompare. Copy your signing secret from the console (API Keys → Webhook signing secret) into SPEECHREVOLUTIONS_WEBHOOK_SECRET. The webhooks guide covers the payload, retries, and secret rotation.

jobID, err := client.Submit(ctx, "meeting.mp3", stt.TranscribeOptions{
    CallbackURL: "https://you.example.com/hook",
})
if err != nil {
    log.Fatal(err)
}
fmt.Println("submitted", jobID) // the hook fires when it finishes

Retrieve results later

Fetch a job by ID at any time, for example after a webhook arrives or after your service restarts. The download URL is generated on each request, so you can fetch results long after the original upload.

retrieve.go

// List the most-recent jobs (newest first), cursor-paginated.
page, err := client.ListJobs(ctx, 10, "") // (limit, before)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%d job(s); next_before=%q\n", len(page.Jobs), page.NextBefore)
for _, j := range page.Jobs {
    fmt.Printf("  %s  (%s)\n", j.JobID, j.CreatedAt)
}

// Poll a job by id, then fetch its transcript.
status, err := client.GetJobStatus(ctx, jobID)
if err != nil {
    log.Fatal(err)
}
fmt.Println("status:", status.Status)
if status.IsCompleted() {
    result, err := client.GetTranscript(ctx, jobID, stt.OutputJSON)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
} else if status.IsFailed() {
    fmt.Println(status.FailedStage, status.Reason)
}

Authentication

The SDK reads your API key from the environment, or you can pass it directly:

bash

export SPEECHREVOLUTIONS_API_KEY=stt_...

client, _ := stt.NewClient("")           // reads the variable above
explicit, _ := stt.NewClient("stt_...")  // or pass it directly

Under the hood

The SDK uploads the file in parts, retrying any part that fails. It then listens on the SSE job stream and converts the completed and total counts into Percent().