Unsupported transcript file extension: ${ext}. Use .json, .s

Error message

Unsupported transcript file extension: ${ext}. Use .json, .srt, or .vtt

What it means

Thrown by detectFormat when a transcript file has an extension other than .json, .srt, or .vtt. The function dispatches on file extension to select the appropriate parser, and any unrecognized extension has no parser available.

Source

Thrown at packages/cli/src/whisper/normalize.ts:42

   *  auto-detection: true when any entry contains internal whitespace. */
  preGrouped?: boolean;
}

// ---------------------------------------------------------------------------
// Format detection + parsing
// ---------------------------------------------------------------------------

export type TranscriptFormat = "whisper-cpp" | "openai" | "srt" | "vtt" | "words-json";

/**
 * Detect the format of a transcript file from its extension and content.
 */
export function detectFormat(filePath: string): TranscriptFormat {
  const ext = extname(filePath).toLowerCase();
  if (ext === ".srt") return "srt";
  if (ext === ".vtt") return "vtt";
  if (ext === ".json") return detectJsonFormat(JSON.parse(readFileSync(filePath, "utf-8")));
  throw new Error(`Unsupported transcript file extension: ${ext}. Use .json, .srt, or .vtt`);
}

function detectJsonFormat(raw: unknown): TranscriptFormat {
  if (raw && typeof raw === "object" && !Array.isArray(raw)) {
    const obj = raw as Record<string, unknown>;
    if (obj.transcription && Array.isArray(obj.transcription)) return "whisper-cpp";
    if (obj.words && Array.isArray(obj.words)) return "openai";
  }
  if (Array.isArray(raw) && raw[0]?.text !== undefined && raw[0]?.start !== undefined) {
    return "words-json";
  }
  throw new Error(
    "Unrecognized JSON transcript format. Expected whisper.cpp (transcription[].tokens), " +
      "OpenAI API (words[]), or normalized ([{text, start, end}]).",
  );
}

// ---------------------------------------------------------------------------

View on GitHub (pinned to c2996c8626)

Solutions

Convert the transcript to .srt, .vtt, or .json format before passing it.
If the file is actually JSON/SRT/VTT but has a wrong extension, rename it.
For plain-text transcripts, convert to SRT format with proper timestamps.
Verify you're pointing at the transcript file, not the video/audio source.

Example fix

// before: hyperframes transcribe --transcript recording.txt
// after:  convert to .srt first, then:
//        hyperframes transcribe --transcript recording.srt

Defensive patterns

Strategy: validation

Validate before calling

import { extname } from "node:path";

function isSupportedTranscriptExt(filePath: string): boolean {
  const ext = extname(filePath).toLowerCase();
  return ext === ".json" || ext === ".srt" || ext === ".vtt";
}

Try / catch

try {
  const format = detectFormat(filePath);
} catch (err) {
  if (err instanceof Error && err.message.includes("Unsupported transcript file extension")) {
    console.error(`${err.message}. Convert to .json, .srt, or .vtt.`);
    process.exit(1);
  }
  throw err;
}

Prevention

Always export transcripts in .srt or .vtt format from external tools.
Validate the file extension before passing it to the transcribe command.
Double-check that you're pointing at the transcript file, not the media source.

When it happens

Trigger: Passing a transcript file with an unsupported extension like .txt, .xml, .mp4, .csv, or a file with no extension to a command that calls detectFormat (e.g. hyperframes transcribe --transcript).

Common situations: Exporting a transcript from a tool that saves as .txt or .docx; a file extension typo; pointing at the wrong file (e.g. the video instead of the transcript); a custom transcript format that isn't supported.

Related errors

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/13c6064a650c10c9. Report an issue: GitHub.