Skip to Content
This documentation is provided with the HEAT environment and is relevant for this HEAT instance only.
RunnersAudio Utilsgenerate-transcript

generate-transcript

The generate-transcript transform runs speech-to-text over audio files listed in an upstream audio-metrics JSON document, using PCM bytes from convert-to-pcm outputs keyed by MD5.

When to use it

Use after convert-to-pcm and audio-metrics in an audio analytics pipeline when you need searchable transcripts (plain text or time-segmented JSON).

It also accepts audio directly, with no metrics document alongside it, which is how hydrate-protobuf SignalPDU feeds it. Two artefact shapes are recognised on that path:

  • A single WAV: transcribed whole, and the transcript is keyed by the audio md5.
  • An origin-audio ZIP (groupByOrigin: true): each origins/<originUuid>.wav is transcribed separately, and the transcript is keyed by originUuid.

Per-origin transcripts

Under groupByOrigin the audio artefact is a delta window, not a cumulative file, so this node carries history forward itself:

  • Each origin stream is transcribed, then stamped with wall clock: segments keep relative start / end seconds inside the stream and gain absolute startMs / endMs from the manifest’s streamStartUnixMs.
  • The node loads its own previous transcript and merges the new window into it per originUuid. Segments repeated across windows are deduplicated on (originUuid, startMs, endMs), the surviving segments are ordered by wall clock, and each entry’s text is rebuilt from them so it never disagrees with its segments.
  • meta.lastAudioMd5 and meta.sourceAudioMd5 record the audio this run consumed. A reprocess over unchanged audio completes without uploading, so a transcript blob is not churned and dashboards are not rescheduled.

Dashboards should prefer startMs / endMs when present and fall back to start / end seconds for legacy single-WAV transcripts.

Limitations

  • On the metrics-driven path, requires audio-metrics JSON and matching PCM blobs in upstream inputs; missing metrics with no direct audio payload fails the node.
  • Supported model values: whisperx (default) and faster-whisper, which share the speech weights baked into the runner image at build time (WHISPER_MODEL_SIZE, default base), so they run without network access. wav2vec downloads its model from Hugging Face on first use and whisper needs the openai-whisper package, which the image does not ship: neither works on an air-gapped cluster.
  • outputFormat: plain or segments (default segments). Invalid values fail the node.

Configuration (summary)

PropertyDefaultDescription
outputFormatsegmentsplain or segments
includeTimestampstrueInclude timing in segment output
modelwhisperxASR backend (see supported list above)
modelSizethe baked size (WHISPER_MODEL_SIZE, base in shipped images)Model size passed to the backend. Only sizes baked into the image load offline.
devicecpuInference device
languageenTranscription language code
dataSourceName(runner default)Object store for outputs

Manifest schema lists outputFormat and includeTimestamps; runtime also accepts model, modelSize, device, and language as used by the processor.

convert-to-pcmvoice-analysis