SubtitleEdit/subtitleedit · error · Exception

A whisper.cpp model must be a ggml '.bin' file.

Error message

A whisper.cpp model must be a ggml '.bin' file.

What it means

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.

Source

Thrown at src/ui/Features/Video/SpeechToText/Engines/WhisperEngineCpp.cs:146

        }

        return modelFileName;
    }

    public bool SupportsCustomModels => true;

    public bool CustomModelIsFolder => false;

    public string ImportCustomModel(string sourcePath)
    {
        if (!File.Exists(sourcePath))
        {
            throw new FileNotFoundException("Model file not found.", sourcePath);
        }

        if (!sourcePath.EndsWith(".bin", StringComparison.OrdinalIgnoreCase))
        {
            throw new Exception("A whisper.cpp model must be a ggml '.bin' file.");
        }

        if (new FileInfo(sourcePath).Length < 10_000_000)
        {
            throw new Exception("The model file is too small (must be at least 10 MB) - is it really a whisper.cpp model?");
        }

        var destination = Path.Combine(GetAndCreateWhisperModelFolder(null), Path.GetFileName(sourcePath));
        File.Copy(sourcePath, destination, true);

        return Path.GetFileNameWithoutExtension(destination);
    }

    public async Task<string> GetHelpText()
    {
        var assetName = $"{StaticName.Replace(" ", string.Empty)}.txt";
        var uri = new Uri($"avares://SubtitleEdit/Assets/SpeechToText/{assetName}");

View on GitHub (pinned to 17a9f07487)

Solutions

1. Download the correct GGML .bin model file for whisper.cpp (from the official whisper.cpp releases on GitHub).
2. If you have a .gguf file, it's for llama.cpp/llama-based engines, not whisper.cpp.
3. If the model is in a .zip archive, extract it first and select the .bin file inside.
4. Verify the file extension: right-click > Properties (Windows) or use 'file' command (Linux).

var ext = Path.GetExtension(sourcePath);
if (!string.Equals(ext, ".bin", StringComparison.OrdinalIgnoreCase))
    throw new InvalidOperationException($"'{sourcePath}' is not a .bin file. whisper.cpp requires GGML .bin models, not {ext}.");

static bool IsGgmlBinFile(string path) =>
    path.EndsWith(".bin", StringComparison.OrdinalIgnoreCase);

try { var name = engine.ImportCustomModel(sourcePath); }
catch (Exception ex) when (ex.Message.Contains("ggml '.bin'"))
{ /* inform user to download the correct GGML .bin format, not GGUF/ONNX/PT */ }

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Model file not found.
• The model file is too small (must be at least 10 MB) - is it
• Model folder not found: {sourceDir}
• A faster-whisper model folder must contain a 'model.bin' fil
• No Blu-Ray sup subtitles found in: {filePath}

AI-assisted analysis of SubtitleEdit/subtitleedit@17a9f07487 (2026-08-13). Data as JSON: /api/errors/b8e7e28e45039060. Report an issue: GitHub.