{"record":{"id":"b8e7e28e45039060","repo":"SubtitleEdit/subtitleedit","slug":"a-whisper-cpp-model-must-be-a-ggml-bin-file","errorCode":null,"errorMessage":"A whisper.cpp model must be a ggml '.bin' file.","messagePattern":"A whisper\\.cpp model must be a ggml '\\.bin' file\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"src/ui/Features/Video/SpeechToText/Engines/WhisperEngineCpp.cs","lineNumber":146,"sourceCode":"        }\n\n        return modelFileName;\n    }\n\n    public bool SupportsCustomModels => true;\n\n    public bool CustomModelIsFolder => false;\n\n    public string ImportCustomModel(string sourcePath)\n    {\n        if (!File.Exists(sourcePath))\n        {\n            throw new FileNotFoundException(\"Model file not found.\", sourcePath);\n        }\n\n        if (!sourcePath.EndsWith(\".bin\", StringComparison.OrdinalIgnoreCase))\n        {\n            throw new Exception(\"A whisper.cpp model must be a ggml '.bin' file.\");\n        }\n\n        if (new FileInfo(sourcePath).Length < 10_000_000)\n        {\n            throw new Exception(\"The model file is too small (must be at least 10 MB) - is it really a whisper.cpp model?\");\n        }\n\n        var destination = Path.Combine(GetAndCreateWhisperModelFolder(null), Path.GetFileName(sourcePath));\n        File.Copy(sourcePath, destination, true);\n\n        return Path.GetFileNameWithoutExtension(destination);\n    }\n\n    public async Task<string> GetHelpText()\n    {\n        var assetName = $\"{StaticName.Replace(\" \", string.Empty)}.txt\";\n        var uri = new Uri($\"avares://SubtitleEdit/Assets/SpeechToText/{assetName}\");\n","sourceCodeStart":128,"sourceCodeEnd":164,"githubUrl":"https://github.com/SubtitleEdit/subtitleedit/blob/17a9f0748781032255db3526b7215d2fb891e3af/src/ui/Features/Video/SpeechToText/Engines/WhisperEngineCpp.cs#L128-L164","documentation":"Thrown by ImportCustomModel when the source file exists but does not have a .bin extension (case-insensitive). whisper.cpp uses the GGML model format distributed as .bin files. This guard prevents importing unrelated files (e.g. .exe, .zip, .onnx) that would fail at runtime.","triggerScenarios":"The user selects a .gguf, .pt, .onnx, .zip, or any non-.bin file thinking it's a whisper.cpp model. GGUF files are for llama.cpp, not whisper.cpp (which uses the older GGML .bin format).","commonSituations":"Confusing whisper.cpp (GGML .bin) with llama.cpp (GGUF) model formats; selecting a PyTorch (.pt) or ONNX (.onnx) model intended for a different engine; selecting a compressed archive (.zip, .tar.gz) containing the model instead of the model itself.","solutions":["Download the correct GGML .bin model file for whisper.cpp (from the official whisper.cpp releases on GitHub).","If you have a .gguf file, it's for llama.cpp/llama-based engines, not whisper.cpp.","If the model is in a .zip archive, extract it first and select the .bin file inside.","Verify the file extension: right-click > Properties (Windows) or use 'file' command (Linux)."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"var ext = Path.GetExtension(sourcePath);\nif (!string.Equals(ext, \".bin\", StringComparison.OrdinalIgnoreCase))\n    throw new InvalidOperationException($\"'{sourcePath}' is not a .bin file. whisper.cpp requires GGML .bin models, not {ext}.\");","typeGuard":"static bool IsGgmlBinFile(string path) =>\n    path.EndsWith(\".bin\", StringComparison.OrdinalIgnoreCase);","tryCatchPattern":"try { var name = engine.ImportCustomModel(sourcePath); }\ncatch (Exception ex) when (ex.Message.Contains(\"ggml '.bin'\"))\n{ /* inform user to download the correct GGML .bin format, not GGUF/ONNX/PT */ }","preventionTips":["Download whisper.cpp models from the official GitHub releases page (these are .bin files).","Do not confuse whisper.cpp GGML .bin with llama.cpp GGUF files.","Filter the file picker dialog to only show .bin files."],"tags":["validation","whisper","model","file-format"],"backgroundTag":null,"analyzedSha":"17a9f0748781032255db3526b7215d2fb891e3af","analyzedAt":"2026-08-13T18:11:43.374Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}