Pin transformers dependency, deduplicate TranscriptionError logic, and update installation instructions.

Author: chris-colinsky

Makefile

@@ -15,8 +15,9 @@ install: ## Install production dependencies (excludes whisperx — see install-w
 install-dev: ## Install development dependencies (excludes whisperx — see install-whisperx)
 	uv sync --extra dev
 
-install-whisperx: ## Install whisperx separately (must run after install or install-dev)
-	uv pip install --no-deps "whisperx @ git+https://github.com/m-bain/whisperX.git@v3.1.1"
+install-whisperx: ## Install whisperx and its runtime deps separately (must run after install or install-dev)
+	uv pip install --no-deps "whisperx @ git+https://github.com/m-bain/whisperX.git@741ab9a2a8a1076c171e785363b23c55a91ceff1"
+	uv pip install "av==16.1.0" "ctranslate2==4.7.1" "faster-whisper==1.2.1" "flatbuffers==25.12.19" "nltk==3.9.2" "onnxruntime==1.24.1"
 
 test: ## Run unit tests (no GPU required)
 	uv run python -m pytest tests/ -m "not integration"
@@ -66,7 +67,10 @@ ci: install-dev all-checks ## Run CI pipeline (install deps + all checks)
 	@echo ""
 	@echo "CI pipeline completed successfully!"
 
-dev-setup: install-dev install-whisperx pre-commit-install ## Complete development setup (installs all deps including whisperx + hooks)
+install-torch-cuda: ## Reinstall PyTorch with CUDA 12.1 wheels (run after uv sync, which pulls CPU-only builds)
+	uv pip install torch==2.1.2+cu121 torchaudio==2.1.2+cu121 --extra-index-url https://download.pytorch.org/whl/cu121
+
+dev-setup: install-dev install-whisperx install-torch-cuda pre-commit-install ## Complete development setup (installs all deps including whisperx + hooks)
 	@echo ""
 	@echo "Development environment setup complete!"
 	@echo ""

README.md

@@ -9,20 +9,20 @@ GPU-accelerated audio processing pipeline: vocal separation (Demucs), speaker di
 uv venv --python 3.11.14
 source .venv/bin/activate
 
-# Install PyTorch first (CUDA 12.1 wheel — adjust for your CUDA version)
-uv pip install torch==2.1.2 torchaudio==2.1.2 --extra-index-url https://download.pytorch.org/whl/cu121
+# Install all deps (uv sync, whisperx, CUDA torch wheels, pre-commit hooks)
+make dev-setup
 
-# Install whisperx in isolation to avoid ctranslate2/torch version conflicts
-uv pip install "setuptools<74"
-uv pip install --no-deps --no-build-isolation "whisperx @ git+https://github.com/m-bain/whisperX.git@v3.1.1"
-# whisperx runtime deps (transformers must be <4.42 — newer versions require torch>=2.4)
-uv pip install "ctranslate2>=4.0" "faster-whisper>=1.0.0" "transformers>=4.35.0,<4.42.0" nltk
+# Copy the env template and add your HuggingFace token
+cp .env.example .env
+# Edit .env and set HF_TOKEN=hf_your_token_here
 
-# Install the package and remaining deps
-uv pip install -e .
-uv pip install pytest pytest-mock  # for development
+# Verify the install
+make test
+audio-refinery --help
 ```
 
+> **CUDA note:** `uv sync` resolves torch from PyPI and installs the CPU build. `make dev-setup` automatically reinstalls `torch==2.1.2+cu121` and `torchaudio==2.1.2+cu121` (CUDA 12.1) as its final step. If your system uses a different CUDA version, run `make install-torch-cuda` after editing the wheel URLs in the Makefile.
+
 > **NumPy constraint:** `numpy<2.0.0` is pinned in `pyproject.toml`. Do not upgrade it — WhisperX and some audio libraries break with NumPy 2.x.
 
 ---
@@ -652,17 +652,22 @@ Notifications are fire-and-forget — a failure to deliver never blocks or abort
 ```bash
 uv venv --python 3.11.14
 source .venv/bin/activate
-uv pip install -e ".[dev]"
+
+# Install all deps including whisperx, CUDA torch, dev tools, and pre-commit hooks
+make dev-setup
+
+# Copy the env template and add your HuggingFace token
+cp .env.example .env
 
 # Run unit tests (no GPU required)
-pytest tests/ -m "not integration" -v
+make test
 
 # Run integration tests (requires GPU, HF_TOKEN, and test audio)
-pytest tests/ -m integration -v
+make test-integration
 
 # Lint and format
-ruff check src/ tests/
-ruff format src/ tests/
+make lint
+make format
 ```
 
 ---

pyproject.toml

@@ -39,7 +39,7 @@ dependencies = [
     "ffmpeg-python",
     "click>=8.1",
     "rich>=13.0",
-    "transformers>=4.30.0",
+    "transformers>=4.30.0,<4.40.0",
 ]
 
 [project.optional-dependencies]

src/transcriber.py

@@ -53,13 +53,6 @@ def _suppress_output():
 DEFAULT_LANGUAGE = "en"
 
 
-class TranscriptionError(Exception):
-    """Raised when transcription fails."""
-
-    def __init__(self, message: str):
-        super().__init__(message)
-
-
 def _parse_whisperx_device(device: str) -> tuple[str, int]:
     """Split a PyTorch-style device string for ctranslate2's separate API.
 
@@ -79,6 +72,13 @@ def _parse_whisperx_device(device: str) -> tuple[str, int]:
     return device, 0
 
 
+class TranscriptionError(Exception):
+    """Raised when transcription fails."""
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
 def transcribe(
     input_file: Path,
     device: str = DEFAULT_DEVICE,
@@ -117,12 +117,7 @@ def transcribe(
     try:
         import whisperx
     except ImportError as exc:
-        raise TranscriptionError(
-            "whisperx is not installed. Install it with:\n"
-            "  uv pip install setuptools\n"
-            "  uv pip install --no-deps --no-build-isolation "
-            '"whisperx @ git+https://github.com/m-bain/whisperX.git@main"'
-        ) from exc
+        raise TranscriptionError("whisperx is not installed. Install it with:\n  make install-whisperx") from exc
 
     input_info: AudioFileInfo = probe_audio_file(input_file)
 
@@ -159,10 +154,6 @@ def transcribe(
     for _logger_name in _NOISY_LOGGERS:
         logging.getLogger(_logger_name).setLevel(logging.ERROR)
 
-    # ctranslate2 (whisperx backend) doesn't accept 'cuda:N' — split into device + index.
-    # load_align_model and align use PyTorch directly and understand 'cuda:N' fine.
-    ct2_device, ct2_device_index = _parse_whisperx_device(device)
-
     alignment_fallback = False
 
     with warnings.catch_warnings():
@@ -171,6 +162,7 @@ def transcribe(
         try:
             if _whisperx_model is None:
                 with _suppress_output():
+                    ct2_device, ct2_device_index = _parse_whisperx_device(device)
                     wx_model = whisperx.load_model(
                         model,
                         ct2_device,