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.

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

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

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

Appendix: 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)