Skip to content

The truly free, open-source, local-first, cross-platform CapCut replacement. Scriptable through a JSON-RPC API & MCP.

feat(transcribe): bundle whisper-cli; users never install the engine

Jareerf5863bab15cb
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 9dbc0285..8555e694 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -114,6 +114,49 @@ jobs:
desktop/src-tauri/ffmpeg/ffmpeg -version | head -1
desktop/src-tauri/ffmpeg/ffprobe -version | head -1
+ # The transcriber ships too: users never install a binary (see desktop
+ # decision 0010). Built from source where no official binary exists,
+ # cached by version so it costs one cold build per platform.
+ - name: Cache whisper-cli (unix)
+ if: matrix.platform != 'windows'
+ uses: actions/cache@v4
+ with:
+ path: whisper-stage
+ key: whisper-cli-v1.8.2-${{ matrix.platform }}
+
+ - name: Stage bundled whisper-cli (unix)
+ if: matrix.platform != 'windows'
+ run: |
+ set -euo pipefail
+ if [ ! -x whisper-stage/whisper-cli ]; then
+ git clone --depth 1 --branch v1.8.2 https://github.com/ggml-org/whisper.cpp.git wbuild
+ cmake -S wbuild -B wbuild/build -DCMAKE_BUILD_TYPE=Release \
+ -DBUILD_SHARED_LIBS=OFF -DGGML_METAL_EMBED_LIBRARY=ON -DWHISPER_BUILD_TESTS=OFF
+ cmake --build wbuild/build --config Release -j 4 --target whisper-cli
+ mkdir -p whisper-stage
+ cp wbuild/build/bin/whisper-cli whisper-stage/whisper-cli
+ fi
+ mkdir -p desktop/src-tauri/whisper
+ cp whisper-stage/whisper-cli desktop/src-tauri/whisper/whisper-cli
+ chmod +x desktop/src-tauri/whisper/whisper-cli
+ desktop/src-tauri/whisper/whisper-cli --help >/dev/null 2>&1 || true
+
+ - name: Stage bundled whisper-cli (Windows)
+ if: matrix.platform == 'windows'
+ shell: pwsh
+ run: |
+ $ErrorActionPreference = "Stop"
+ New-Item -ItemType Directory -Force desktop/src-tauri/whisper | Out-Null
+ curl.exe -fsSL --retry 5 --retry-all-errors -o whisper-win.zip `
+ "https://github.com/ggml-org/whisper.cpp/releases/download/v1.8.2/whisper-bin-x64.zip"
+ Expand-Archive whisper-win.zip -DestinationPath wdl
+ Copy-Item (Get-ChildItem wdl -Recurse -Filter whisper-cli.exe | Select-Object -First 1).FullName desktop/src-tauri/whisper/
+ # The official build is dynamic; its DLLs ride along in the same
+ # resource folder, which is also the executable's search path.
+ Get-ChildItem wdl -Recurse -Filter *.dll | ForEach-Object {
+ Copy-Item $_.FullName desktop/src-tauri/whisper/
+ }
+
- name: Stage bundled FFmpeg (Windows)
if: matrix.platform == 'windows'
shell: pwsh
diff --git a/desktop/docs/decisions/0010-the-app-installs-its-own-tools.md b/desktop/docs/decisions/0010-the-app-installs-its-own-tools.md
new file mode 100644
index 00000000..48f0d1d1
--- /dev/null
+++ b/desktop/docs/decisions/0010-the-app-installs-its-own-tools.md
@@ -0,0 +1,36 @@
+# 0010 - The app installs its own tools
+
+## Decision
+No feature may arrive as a setup chore. Every binary WolfCut needs ships
+inside the bundle or installs itself behind a single button with progress.
+Concretely, as of this note:
+
+- `whisper-cli` is staged at build like FFmpeg (`src-tauri/whisper/`,
+ declared in the bundle's resources) and the release guard in `build.rs`
+ refuses to build without it - a release that would ask the user to "locate
+ whisper-cli" does not get to exist. CI builds it from source on macOS and
+ Linux (cached by version) and takes the official binary on Windows.
+- Models remain downloads, because half a gigabyte of weights someone may
+ never use does not belong in every installer - but the download is one
+ button in Settings with a progress bar, which is the ceiling for what a
+ feature may ask.
+- The Settings "Locate..." picker survives only as a dev-build escape hatch
+ and is hidden whenever the bundled copy is in use.
+
+## Why
+The product's one-line promise is "install it and start cutting, no setup".
+The transcriber shipped as the opposite: a feature that greeted its user
+with a binary hunt. The user's words, verbatim, now policy: "never offload
+technical jobs to the user... At most, the user should do some basic config
+and have to click a 'Install' button, AT MOST."
+
+## What it costs
+- CI builds whisper.cpp once per platform per version bump (~4 minutes cold,
+ then cached), and installers grow by a few megabytes.
+- The bundled copy is CPU/Metal only; exotic accelerators mean the escape
+ hatch in a dev build.
+
+## What would change our mind
+Nothing about the principle. The mechanics move if the engine grows an
+audio-analysis seam (this note's staging follows the runner there, per the
+note in `transcribe.rs`).
diff --git a/desktop/src-tauri/.gitignore b/desktop/src-tauri/.gitignore
index a330a67f..3e889b5d 100644
--- a/desktop/src-tauri/.gitignore
+++ b/desktop/src-tauri/.gitignore
@@ -8,3 +8,5 @@
# Staged FFmpeg pair for bundled builds (downloaded in CI, ~100 MB)
/ffmpeg/
+/whisper/whisper-cli*
+/whisper/*.dll
diff --git a/desktop/src-tauri/build.rs b/desktop/src-tauri/build.rs
index 5196c696..6e5d45f3 100644
--- a/desktop/src-tauri/build.rs
+++ b/desktop/src-tauri/build.rs
@@ -16,6 +16,18 @@ fn main() {
);
}
println!("cargo:rerun-if-changed=ffmpeg");
+
+ // Same rule for the transcriber: users are never asked to install a
+ // binary and point the app at it, so a release ships its own
+ // whisper-cli or it does not ship.
+ let whisper = std::path::Path::new("whisper").join(format!("whisper-cli{suffix}"));
+ assert!(
+ whisper.is_file(),
+ "release build without a bundled whisper-cli: stage it in \
+ desktop/src-tauri/whisper/ first (see the Build App workflow), or \
+ transcription would arrive as a setup chore instead of a feature"
+ );
+ println!("cargo:rerun-if-changed=whisper");
}
tauri_build::build()
diff --git a/desktop/src-tauri/src/transcribe.rs b/desktop/src-tauri/src/transcribe.rs
index 7696c34b..d63d676e 100644
--- a/desktop/src-tauri/src/transcribe.rs
+++ b/desktop/src-tauri/src/transcribe.rs
@@ -8,10 +8,11 @@
//!
//! Three pieces:
//!
-//! 1. **The binary.** `whisper-cli` is not bundled (yet). It is looked for in
-//! the app data folder, beside the executable, then on PATH - and the user
-//! can point at a copy from Settings, which is remembered in
-//! `transcriber.json` in the config directory.
+//! 1. **The binary.** `whisper-cli` ships inside the app, staged at build
+//! like FFmpeg; the release guard refuses to build without it. The search
+//! below still honours a remembered override first and falls back to the
+//! app data folder, beside the executable, then PATH - for dev builds and
+//! for anyone who insists on their own copy.
//! 2. **Models.** Downloaded on demand from Hugging Face into the app data
//! folder as plain `.bin` files, streamed with progress events, written to
//! a `.part` and renamed - a torn download must never look usable.
@@ -203,6 +204,8 @@ pub struct ModelStatus {
pub struct TranscriberStatus {
/// Where `whisper-cli` was found, or null when it was not.
binary: Option<String>,
+ /// True when the binary in use is the copy shipped inside the app.
+ bundled: bool,
/// Where models are stored, so the settings panel can say so.
models_dir: String,
models: Vec<ModelStatus>,
@@ -212,8 +215,14 @@ pub struct TranscriberStatus {
#[tauri::command]
pub fn transcriber_status(app: tauri::AppHandle) -> Result<TranscriberStatus, String> {
let dir = models_dir(&app)?;
+ let binary = find_binary(&app);
+ let bundled = match (&binary, app.path().resource_dir()) {
+ (Some(path), Ok(resources)) => path.starts_with(&resources),
+ _ => false,
+ };
Ok(TranscriberStatus {
- binary: find_binary(&app).map(|path| path.to_string_lossy().into_owned()),
+ binary: binary.map(|path| path.to_string_lossy().into_owned()),
+ bundled,
models_dir: dir.to_string_lossy().into_owned(),
models: KNOWN_MODELS
.iter()
diff --git a/desktop/src-tauri/tauri.conf.json b/desktop/src-tauri/tauri.conf.json
index 839614df..42352a9f 100644
--- a/desktop/src-tauri/tauri.conf.json
+++ b/desktop/src-tauri/tauri.conf.json
@@ -45,7 +45,8 @@
"icons/icon.ico"
],
"resources": {
- "ffmpeg/*": "ffmpeg/"
+ "ffmpeg/*": "ffmpeg/",
+ "whisper/*": "whisper/"
}
}
}
diff --git a/desktop/src-tauri/whisper/README.md b/desktop/src-tauri/whisper/README.md
new file mode 100644
index 00000000..e64fddb0
--- /dev/null
+++ b/desktop/src-tauri/whisper/README.md
@@ -0,0 +1,3 @@
+# Staged at build, never committed: the bundled transcription engine.
+# CI stages per platform (see the Build App workflow); locally, build
+# whisper.cpp v1.8.2 with BUILD_SHARED_LIBS=OFF and copy whisper-cli here.
diff --git a/desktop/src/components/SettingsDialog.tsx b/desktop/src/components/SettingsDialog.tsx
index 8b5b5fe7..f84d52d9 100644
--- a/desktop/src/components/SettingsDialog.tsx
+++ b/desktop/src/components/SettingsDialog.tsx
@@ -189,7 +189,7 @@ function TranscriberSettings() {
<section>
<h3 className="mb-2 flex items-center gap-1.5 text-[11px] font-semibold uppercase tracking-wider text-tertiary">
Engine
- <HelpTip text="Transcription runs whisper.cpp locally - nothing leaves this machine. Download whisper-cli from the whisper.cpp releases page and point Relay at it once." />
+ <HelpTip text="Transcription runs whisper.cpp locally - nothing leaves this machine. The engine ships inside WolfCut; pick a model below and captions work." />
</h3>
<div className="flex items-center gap-2 rounded-lg bg-sunken px-3 py-2.5">
<span
@@ -200,16 +200,22 @@ function TranscriberSettings() {
<span className="min-w-0 flex-1 truncate text-xs text-secondary">
{status === null
? "Checking..."
- : (status.binary ?? "whisper-cli not found - locate it to enable captions")}
+ : status.bundled
+ ? "Included with WolfCut"
+ : (status.binary ?? "Transcription engine not found in this dev build")}
</span>
- <button
- type="button"
- onClick={() => void locate()}
- className="shrink-0 cursor-pointer rounded-md bg-panel px-2.5 py-1 text-[11px]
- text-primary ring-1 ring-hairline transition-colors hover:bg-hover"
- >
- Locate...
- </button>
+ {/* The picker is a dev-build escape hatch, never a user chore: a
+ packaged app always carries its own copy and hides this. */}
+ {status !== null && !status.bundled && (
+ <button
+ type="button"
+ onClick={() => void locate()}
+ className="shrink-0 cursor-pointer rounded-md bg-panel px-2.5 py-1 text-[11px]
+ text-primary ring-1 ring-hairline transition-colors hover:bg-hover"
+ >
+ Locate...
+ </button>
+ )}
</div>
</section>
diff --git a/desktop/src/lib/engine.ts b/desktop/src/lib/engine.ts
index 17e6db03..d24c2f6d 100644
--- a/desktop/src/lib/engine.ts
+++ b/desktop/src/lib/engine.ts
@@ -454,6 +454,8 @@ export interface TranscriberModel {
export interface TranscriberStatus {
/** Where `whisper-cli` was found, or null when it was not. */
binary: string | null;
+ /** True when the binary in use is the copy shipped inside the app. */
+ bundled: boolean;
/** Where models are stored on disk. */
modelsDir: string;
models: TranscriberModel[];