Support native macOS speech relocation and safe indexing

2026-10-23 09:43:42 +02:00
1 parent 9a93ee6375
commit 5b93dd67a7
@@ -258,9 +258,143 @@ claim an untested platform, hardware backend or UI interaction works.
 ```

 Building needs internet access, disk space for the toolchain and local models,
-and permission to install dependencies. macOS native execution remains
-unverified in this repository; your agent should verify its build on your Mac
-and report any issue. See [platform build instructions](docs/BUILDING.md).
+and permission to install dependencies. An Apple Silicon source installation
+was tested on 23 October 2026; follow the Mac guide below. Other host/architecture
+combinations still need their own checks. See [platform build instructions](docs/BUILDING.md).
+
+### macOS: build and install from source
+
+Tested with source commit `9a93ee6375d610d580ef16c5ec52218727fab187`
+on an Apple M4 Mac with 16 GiB unified memory and macOS 26.6.2. The installed
+0.1.9 app opened outside the checkout, used Metal for genuine Google embeddings,
+and passed English/German document retrieval and code-only semantic search.
+There is currently no downloadable Mac installer. Intel Macs, Developer ID
+signing and notarization remain unverified.
+
+**Prerequisites:** Xcode command-line tools (or full Xcode), stable Rust/Cargo,
+Node **24 LTS**, Python 3.11+ and CMake. Check that `cargo`, `node`, `npm`,
+`python3` and `cmake` are on your `PATH`; run `xcode-select -p` to check the
+Apple toolchain. If it is missing, run `xcode-select --install` and complete
+Apple's installation before continuing. Use the official [Rust installer](https://rustup.rs/)
+if Cargo is missing. With Homebrew, `brew install node@24 cmake python` supplies
+the other tools; select Node 24 with
+`export PATH="$(brew --prefix node@24)/bin:$PATH"` and verify `node --version`.
+Node 26 failed a Unicode-highlighting test on the tested machine; Node 24.19.0
+passed all 66 frontend tests.
+
+Allow space for native build outputs and the model assets. The pinned text
+model and media projector download totals **864,676,480 bytes** (about 865 MB).
+The steps below also copy those assets into the app, so the download size is
+not the total disk-space requirement. Existing valid model files are reused
+and verified by size and SHA-256.
+
+```sh
+git clone https://tea.karlcom.de/karl/searchi.git
+cd searchi
+# Record the current revision, including the Mac speech/scan fixes:
+git rev-parse HEAD
+
+python3 tools/embeddinggemma2/build_runtime.py --backend auto --jobs 2
+python3 tools/embeddinggemma2/download.py
+python3 tools/embeddinggemma2/stage_runtime.py --backend auto --bundle-model
+python3 tools/stage_extraction_worker.py
+```
+
+Use the normal `auto` backend: on macOS it builds Metal support with CPU support
+in the same worker. The builder embeds Metal kernels and checks the native
+architecture and Apple framework dependencies. Do not substitute an explicit
+CPU-only worker for this normal installation. See [macOS runtime details](docs/MACOS-RUNTIME.md).
+
+**Optional media helpers:** the pinned decoder-provisioning manifest currently
+covers Windows and Linux. For a local Mac installation with Homebrew FFmpeg,
+stage the existing tools before packaging:
+
+```sh
+brew install ffmpeg
+mkdir -p apps/desktop/src-tauri/resources/media-runtime/bin
+install -m 755 "$(brew --prefix)/bin/ffmpeg" \
+  apps/desktop/src-tauri/resources/media-runtime/bin/ffmpeg
+install -m 755 "$(brew --prefix)/bin/ffprobe" \
+  apps/desktop/src-tauri/resources/media-runtime/bin/ffprobe
+```
+
+These binaries retain dependencies on Homebrew libraries. Keep that Homebrew
+installation available; this does not create a portable Mac media distribution.
+Speech recognition uses the separate worker/models staged below. The setup
+panel reports readiness and any missing capabilities.
+
+**Local speech recognition:** build and stage the normal Metal/CPU speech runtime
+before packaging the desktop. The app provisions about149MB of verified speech
+models separately from the Google assets.
+
+```sh
+git clone https://github.com/ggml-org/whisper.cpp.git .searchi/references/whisper.cpp
+git -C .searchi/references/whisper.cpp checkout d1be6fde11ac6e0407606b4e42fe72d34add8037
+python3 tools/speech-runtime/build.py --source .searchi/references/whisper.cpp \
+  --output .searchi/speech-runtime/macos-auto --device auto
+python3 tools/stage_speech_worker.py --runtime .searchi/speech-runtime/macos-auto/runtime \
+  --platform macos --architecture aarch64
+```
+
+Use a fresh speech build output directory. The Mac runtime uses loader-relative
+library paths, so the installed app does not depend on the build tree. Speech
+recognition, video-frame retrieval, timestamped audio/video previews and music
+metadata lookup were exercised in the installed Mac app. A known spoken sentence
+was found in both audio and video; an artist search found a piano recording.
+The optional CLI command `searchi setup --speech --model-dir PATH` can provision
+the same verified models explicitly. Normal Mac app profiles use
+`~/Library/Application Support/dev.searchi.desktop/SpeechModels`.
+
+Build the desktop bundle using Node 24:
+
+```sh
+cd apps/desktop
+npm ci
+npm test
+npm run tauri -- build --features custom-protocol --bundles app \
+  --config '{"bundle":{"active":true}}'
+cd ../..
+```
+
+Install the generated bundle in your user Applications folder. If searchi is
+already running, choose Quit before replacing it. Retain an existing installed
+copy separately if you need to roll back; the app's data is stored separately.
+
+```sh
+mkdir -p "$HOME/Applications"
+ditto apps/desktop/src-tauri/target/release/bundle/macos/searchi.app \
+  "$HOME/Applications/searchi.app"
+codesign --force --deep --sign - "$HOME/Applications/searchi.app"
+codesign --verify --deep --strict "$HOME/Applications/searchi.app"
+open "$HOME/Applications/searchi.app"
+```
+
+This applies a local ad-hoc signature, not Developer ID signing or notarization.
+The installed bundle contains the embedding worker, extraction worker and model
+files; it does not need a frontend development server or the original checkout
+to serve search. Any staged Homebrew media helpers still need their libraries.
+
+**First-run coverage:** settings and the index live in
+`~/Library/Application Support/dev.searchi.desktop/`. Review your indexed folders
+before starting a large scan. Automatic discovery starts at `/` on macOS but prunes `/System`, `/Volumes`,
+`/private` and the user Library app-state directory. You can also use explicit
+personal-folder roots to control coverage. A dedicated sample folder makes an initial
+semantic check easy. Known credential directories, build caches and searchi's
+own data/model directories are excluded; macOS permissions still determine
+which files can be read. Adding a folder does not mean its semantic index is
+immediately ready—wait for the setup status.
+
+Try a filename, an exact phrase and a description using different words. Select
+the result and inspect its original passage. The tested sample agreement said
+“sixty days of written notice”; “ending the supplier partnership” and the German
+“Kündigung beim Lieferanten” both found it. Code scope found a retry function
+from a description of increasing delays. These were small fixture checks, not
+a whole-library accuracy or performance benchmark.
+
+The Mac launcher shortcut is **Shift + Command + Space**, as configured in the
+app; shortcut/tray interaction was not verified during this installation test.
+Optional external Ask/summarization remains unconfigured unless you choose an
+endpoint explicitly.

 ### Your first search