Merge pull request #2 from transcriptintel/develop

v1.2.1 — Portable binary distribution, docs

Author: skitsanos

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "transcribeit"
-version = "1.2.0"
+version = "1.2.1"
 edition = "2024"
 license-file = "LICENSE"
 

Cargo.toml

@@ -116,6 +116,34 @@ DIARIZE_SEGMENTATION_MODEL=.cache/sherpa-onnx-pyannote-segmentation-3-0/model.on
 DIARIZE_EMBEDDING_MODEL=.cache/wespeaker_en_voxceleb_CAM++.onnx
 ```
 
+## Binary distribution
+
+Pre-built binaries can be deployed without Rust or build tools. The binary needs FFmpeg on PATH and the sherpa-onnx shared libraries alongside it:
+
+```
+transcribeit              # binary
+lib/                      # sherpa-onnx shared libraries
+  libsherpa-onnx-c-api.dylib
+  libonnxruntime.dylib
+```
+
+On first run, use `transcribeit setup` to download models and additional components. The binary looks for shared libraries in `lib/` relative to itself — no environment variables needed at runtime.
+
+To build a distributable binary:
+
+```bash
+cargo build --release
+# Copy binary + libs
+cp target/release/transcribeit dist/
+cp vendor/sherpa-onnx-*/lib/lib*.dylib dist/lib/
+```
+
+To build without sherpa-onnx (no shared library dependency):
+
+```bash
+cargo build --release --no-default-features
+```
+
 ## License
 
 This project is licensed under the [Business Source License 1.1](LICENSE).

README.md

@@ -15,10 +15,21 @@ fn main() {
             path.to_path_buf()
         };
 
-        // Tell the linker where to find the shared libs
+        // Tell the linker where to find the shared libs at build time
         println!("cargo:rustc-link-search=native={}", absolute.display());
 
-        // Embed rpath so the binary finds dylibs at runtime
+        // Embed rpaths for runtime dylib resolution:
+        // 1. @executable_path/lib — for portable distribution (dylibs next to binary in lib/)
+        // 2. @executable_path — for dylibs in the same directory as the binary
+        // 3. The absolute build-time path — for development convenience
+        if cfg!(target_os = "macos") {
+            println!("cargo:rustc-link-arg=-Wl,-rpath,@executable_path/lib");
+            println!("cargo:rustc-link-arg=-Wl,-rpath,@executable_path");
+        } else {
+            println!("cargo:rustc-link-arg=-Wl,-rpath,$ORIGIN/lib");
+            println!("cargo:rustc-link-arg=-Wl,-rpath,$ORIGIN");
+        }
+        // Also keep the build-time path for local development
         println!("cargo:rustc-link-arg=-Wl,-rpath,{}", absolute.display());
     }
 

build.rs

@@ -213,3 +213,28 @@ Fix:
 SenseVoice models are capable of detecting emotions and audio events (laughter, applause, music, etc.), but the sherpa-onnx C API strips these tags from the output. Only the transcription text is available. This is a limitation of the sherpa-onnx C-level bindings, not of transcribeit.
 
 Additionally, the SenseVoice 2025 model is a quality regression compared to the 2024 version. Prefer using the 2024 SenseVoice model for best results.
+
+### Binary fails with "Library not loaded: libsherpa-onnx-c-api.dylib"
+
+Symptoms:
+- `dyld: Library not loaded: @rpath/libsherpa-onnx-c-api.dylib`
+- Binary crashes immediately on startup
+
+Fix: The binary expects sherpa-onnx shared libraries in a `lib/` directory next to itself:
+
+```
+transcribeit              # binary
+lib/                      # create this directory
+  libsherpa-onnx-c-api.dylib
+  libonnxruntime.dylib
+  libonnxruntime.1.23.2.dylib
+```
+
+Copy the dylibs from `vendor/sherpa-onnx-*/lib/` or download them with `transcribeit setup -c sherpa-libs`.
+
+If you see a hardcoded path from another machine (e.g., `/Users/someone/...`), the binary was built with an old `build.rs`. Rebuild with the latest code — the portable `@executable_path/lib` rpath is now used.
+
+To avoid this dependency entirely, build without sherpa-onnx:
+```bash
+cargo build --release --no-default-features
+```