Add setup-venv.sh, clean up setup-venv-local-build.sh

setup-venv.sh: simple PyPI install path — just pip install faster-whisper.
Use this when the PyPI ctranslate2 wheel matches the system CUDA version.

setup-venv-local-build.sh:
- PYTHON_ENV env var for venv path override (consistent with tts-server)
- HF_TOKEN_FILE env var instead of hardcoded path
- HF_HUB_CACHE env var surfaced in output when set
- Remove stray chmod on faster-whisper-server.py (not part of this repo)
- Remove voice-experiment-specific "run with" message
- Add python3 to tool prerequisite check
- Arch Linux package suggestions extended to cover CUDA and python
- Document why each script exists and when to use which

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

setup-venv-local-build.sh

@@ -1,11 +1,33 @@
 #!/usr/bin/env bash
+#
+# setup-venv-local-build.sh — builds ctranslate2 from source and installs faster-whisper.
+#
+# USE THIS SCRIPT when the PyPI ctranslate2 wheel does not match your CUDA version.
+# The PyPI wheel targets a specific CUDA major version (e.g. CUDA 12). If your system
+# has a newer version (e.g. CUDA 13), the wheel will fail at runtime because it tries
+# to dlopen libcublas.so.12 which does not exist. Building from source compiles against
+# your actual installed CUDA and links correctly.
+#
+# For systems where the PyPI wheel works (CUDA version matches), use setup-venv.sh
+# instead — it is much faster and simpler.
+#
+# Environment overrides:
+#   PYTHON_ENV      path to venv (default: ./venv)
+#   HF_TOKEN_FILE   path to HuggingFace token file (default: ~/.secrets/hugging-face.token)
+#   HF_HUB_CACHE    path to HuggingFace hub cache (default: ~/.cache/huggingface/hub)
+#   CUDA_HOME       path to CUDA toolkit (auto-detected if not set)
+#
+# Arch Linux packages needed before running this script:
+#   sudo pacman -S cuda cmake git python
+#   (cuda is in the extra repo; if not found: yay -S cuda or check community/AUR)
+#
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-VENV="${SCRIPT_DIR}/venv"
+VENV="${PYTHON_ENV:-${SCRIPT_DIR}/venv}"
 BUILD_DIR="${SCRIPT_DIR}/build/ctranslate2"
 MODEL="${1:-base.en}"
-TOKEN_FILE="${HOME}/.secrets/hugging-face.token"
+TOKEN_FILE="${HF_TOKEN_FILE:-${HOME}/.secrets/hugging-face.token}"
 
 # Locate CUDA
 if [ -z "${CUDA_HOME:-}" ]; then
@@ -18,14 +40,14 @@ if [ -z "${CUDA_HOME:-}" ]; then
 fi
 
 if [ -z "${CUDA_HOME:-}" ]; then
-	echo "ERROR: CUDA not found. Set CUDA_HOME manually." >&2
+	echo "ERROR: CUDA not found. Set CUDA_HOME manually or install: sudo pacman -S cuda" >&2
 	exit 1
 fi
 
 echo "==> CUDA: ${CUDA_HOME}"
 "${CUDA_HOME}/bin/nvcc" --version | head -1
 
-for tool in cmake git; do
+for tool in cmake git python3; do
 	if ! command -v "${tool}" &>/dev/null; then
 		echo "ERROR: ${tool} not found — install with: sudo pacman -S ${tool}" >&2
 		exit 1
@@ -79,7 +101,8 @@ ls "${VENV}/lib/libctranslate2"* 2>/dev/null || { echo "ERROR: libctranslate2 no
 grep "WITH_CUDA" "${BUILD_DIR}/cmake-build/CMakeCache.txt" | grep -v "^#" || true
 
 # --- Python bindings ---
-# Always reinstall from source to ensure we use our CUDA 13 build, not a PyPI wheel
+# Always reinstall from source to ensure we use our locally built library,
+# not a PyPI wheel that may have been pulled in as a dependency.
 echo "==> removing any existing ctranslate2 install..."
 "${VENV}/bin/pip" uninstall -y ctranslate2 2>/dev/null || true
 
@@ -97,6 +120,7 @@ else
 	echo "==> faster-whisper already installed, skipping"
 fi
 
+# --- model download ---
 if [ -f "${TOKEN_FILE}" ]; then
 	export HF_TOKEN="$(cat "${TOKEN_FILE}")"
 	echo "==> HuggingFace token loaded from ${TOKEN_FILE}"
@@ -104,6 +128,10 @@ else
 	echo "==> no token found at ${TOKEN_FILE} — unauthenticated download"
 fi
 
+if [ -n "${HF_HUB_CACHE:-}" ]; then
+	echo "==> HuggingFace cache: ${HF_HUB_CACHE}"
+fi
+
 echo "==> pre-downloading model: ${MODEL}"
 "${VENV}/bin/python3" - <<EOF
 from faster_whisper import WhisperModel
@@ -112,7 +140,5 @@ WhisperModel("${MODEL}", device="cuda", compute_type="int8_float16")
 print("done")
 EOF
 
-chmod +x "${SCRIPT_DIR}/faster-whisper-server.py"
-
 echo ""
-echo "==> done. Run with: node query-demo.mjs --stt faster-whisper"
+echo "==> done. Venv ready at ${VENV}"

setup-venv.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+#
+# setup-venv.sh — installs faster-whisper from PyPI into a venv.
+#
+# USE THIS SCRIPT when the PyPI ctranslate2 wheel matches your CUDA version.
+# PyPI wheels target a specific CUDA major version; if your system matches,
+# this is the fastest way to get started — no compilation required.
+#
+# If you see errors like "libcublas.so.12: cannot open shared object file" at
+# runtime, your CUDA version does not match the wheel. Use setup-venv-local-build.sh
+# instead, which compiles ctranslate2 against your actual CUDA installation.
+#
+# Environment overrides:
+#   PYTHON_ENV      path to venv (default: ./venv)
+#
+# Arch Linux packages needed before running this script:
+#   sudo pacman -S python cuda
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VENV="${PYTHON_ENV:-${SCRIPT_DIR}/venv}"
+
+if [ ! -d "${VENV}" ]; then
+	echo "==> creating venv at ${VENV}"
+	python3 -m venv "${VENV}"
+fi
+
+echo "==> installing faster-whisper"
+"${VENV}/bin/pip" install --upgrade pip --quiet
+"${VENV}/bin/pip" install faster-whisper
+
+echo ""
+echo "==> done. Venv ready at ${VENV}"