{"record":{"id":"13c6064a650c10c9","repo":"heygen-com/hyperframes","slug":"unsupported-transcript-file-extension-ext-use","errorCode":null,"errorMessage":"Unsupported transcript file extension: ${ext}. Use .json, .srt, or .vtt","messagePattern":"Unsupported transcript file extension: (.+?)\\. Use \\.json, \\.srt, or \\.vtt","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/whisper/normalize.ts","lineNumber":42,"sourceCode":"   *  auto-detection: true when any entry contains internal whitespace. */\n  preGrouped?: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Format detection + parsing\n// ---------------------------------------------------------------------------\n\nexport type TranscriptFormat = \"whisper-cpp\" | \"openai\" | \"srt\" | \"vtt\" | \"words-json\";\n\n/**\n * Detect the format of a transcript file from its extension and content.\n */\nexport function detectFormat(filePath: string): TranscriptFormat {\n  const ext = extname(filePath).toLowerCase();\n  if (ext === \".srt\") return \"srt\";\n  if (ext === \".vtt\") return \"vtt\";\n  if (ext === \".json\") return detectJsonFormat(JSON.parse(readFileSync(filePath, \"utf-8\")));\n  throw new Error(`Unsupported transcript file extension: ${ext}. Use .json, .srt, or .vtt`);\n}\n\nfunction detectJsonFormat(raw: unknown): TranscriptFormat {\n  if (raw && typeof raw === \"object\" && !Array.isArray(raw)) {\n    const obj = raw as Record<string, unknown>;\n    if (obj.transcription && Array.isArray(obj.transcription)) return \"whisper-cpp\";\n    if (obj.words && Array.isArray(obj.words)) return \"openai\";\n  }\n  if (Array.isArray(raw) && raw[0]?.text !== undefined && raw[0]?.start !== undefined) {\n    return \"words-json\";\n  }\n  throw new Error(\n    \"Unrecognized JSON transcript format. Expected whisper.cpp (transcription[].tokens), \" +\n      \"OpenAI API (words[]), or normalized ([{text, start, end}]).\",\n  );\n}\n\n// ---------------------------------------------------------------------------","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/whisper/normalize.ts#L24-L60","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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."],"exampleFix":"// before: hyperframes transcribe --transcript recording.txt\n// after:  convert to .srt first, then:\n//        hyperframes transcribe --transcript recording.srt","handlingStrategy":"validation","validationCode":"import { extname } from \"node:path\";\n\nfunction isSupportedTranscriptExt(filePath: string): boolean {\n  const ext = extname(filePath).toLowerCase();\n  return ext === \".json\" || ext === \".srt\" || ext === \".vtt\";\n}","typeGuard":null,"tryCatchPattern":"try {\n  const format = detectFormat(filePath);\n} catch (err) {\n  if (err instanceof Error && err.message.includes(\"Unsupported transcript file extension\")) {\n    console.error(`${err.message}. Convert to .json, .srt, or .vtt.`);\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["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."],"tags":["whisper","transcript","format","validation"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}