From 82780185598ea572631c53b9e6b693f0bcd92766 Mon Sep 17 00:00:00 2001
From: skitsanos <evgenios@skitsanos.com>
Date: Mon, 16 Mar 2026 14:51:40 +0200
Subject: [PATCH 1/3] fix: Use portable rpath for binary distribution

Embed @executable_path/lib and @executable_path rpaths so the binary
finds sherpa-onnx dylibs relative to itself, not hardcoded to the
build machine path. Enables portable distribution as:
  transcribeit (binary)
  lib/libsherpa-onnx-c-api.dylib
  lib/libonnxruntime.dylib

Linux uses $ORIGIN/lib and $ORIGIN equivalents.
---
 build.rs | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/build.rs b/build.rs
index d0f5eda..1f852ce 100644
--- a/build.rs
+++ b/build.rs
@@ -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());
     }
 

From a3d64deba5ba89c6afa1729c169dfedfb4a9ae04 Mon Sep 17 00:00:00 2001
From: skitsanos <evgenios@skitsanos.com>
Date: Mon, 16 Mar 2026 15:27:42 +0200
Subject: [PATCH 2/3] docs: Add binary distribution guide and dylib
 troubleshooting

---
 README.md               | 28 ++++++++++++++++++++++++++++
 docs/troubleshooting.md | 25 +++++++++++++++++++++++++
 2 files changed, 53 insertions(+)

diff --git a/README.md b/README.md
index fe88c95..10e3733 100644
--- a/README.md
+++ b/README.md
@@ -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).
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index c93babd..493b182 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -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
+```

From ee652db2df49a27a09e3d09d8d8f600d05195d65 Mon Sep 17 00:00:00 2001
From: skitsanos <evgenios@skitsanos.com>
Date: Mon, 16 Mar 2026 15:33:34 +0200
Subject: [PATCH 3/3] chore: Bump version to 1.2.1

---
 Cargo.lock | 2 +-
 Cargo.toml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 265fba4..b230af5 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1856,7 +1856,7 @@ dependencies = [
 
 [[package]]
 name = "transcribeit"
-version = "1.2.0"
+version = "1.2.1"
 dependencies = [
  "anyhow",
  "async-trait",
diff --git a/Cargo.toml b/Cargo.toml
index 258f59e..30379d1 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "transcribeit"
-version = "1.2.0"
+version = "1.2.1"
 edition = "2024"
 license-file = "LICENSE"