chore: add cpu/cu124 extras for PyTorch index selection

.github/workflows/ci.yml

@@ -51,7 +51,10 @@ jobs:
         uses: FedericoCarboni/setup-ffmpeg@v2
         id: setup-ffmpeg
 
+      - name: Install dependencies (CPU-only PyTorch for CI)
+        run: uv sync --extra cpu
+
       - name: Test with unittest
         working-directory: ./tests
         run: |
-          uv run python -m unittest discover -s . -p 'test_*.py'
+          uv run --extra cpu python -m unittest discover -s . -p 'test_*.py'

README.md

@@ -77,59 +77,93 @@ into `.lrc` subtitles with LLMs such as
 
 ## Installation ⚙️
 
-1. Install CUDA 11.x and [cuDNN 8 for CUDA 11](https://developer.nvidia.com/cudnn) first according
-   to https://opennmt.net/CTranslate2/installation.html to enable `faster-whisper`.
-
-   `faster-whisper` also needs [cuBLAS for CUDA 11](https://developer.nvidia.com/cublas) installed.
-   <details>
-   <summary>For Windows Users (click to expand)</summary> 
-
-   (Windows only) You can download the libraries from Purfview's repository:
-
-   Purfview's [whisper-standalone-win](https://github.com/Purfview/whisper-standalone-win) provides the required NVIDIA
-   libraries for Windows in a [single archive](https://github.com/Purfview/whisper-standalone-win/releases/tag/libs).
-   Decompress the archive and place the libraries in a directory included in the `PATH`.
-
-   </details>
-
-
-2. Add LLM API keys (recommended for most users: `OPENROUTER_API_KEY`):
+1. Add LLM API keys (recommended for most users: `OPENROUTER_API_KEY`):
    - Add your [OpenAI API key](https://platform.openai.com/account/api-keys) to environment variable `OPENAI_API_KEY`.
    - Add your [Anthropic API key](https://console.anthropic.com/settings/keys) to environment variable
      `ANTHROPIC_API_KEY`.
    - Add your [Google API Key](https://aistudio.google.com/app/apikey) to environment variable `GOOGLE_API_KEY`.
    - Add your [OpenRouter API key](https://openrouter.ai/keys) to environment variable `OPENROUTER_API_KEY`.
 
-3. Install [ffmpeg](https://ffmpeg.org/download.html) and add `bin` directory
+2. Install [ffmpeg](https://ffmpeg.org/download.html) and add `bin` directory
    to your `PATH`.
 
-4. This project can be installed from PyPI:
+3. Install from PyPI:
 
-    ```shell
-    pip install openlrc
-    ```
-
-   or install directly from GitHub:
+   ```shell
+   pip install openlrc
+   ```
 
-    ```shell
-    pip install git+https://github.com/zh-plus/openlrc
-    ```
+   By default this installs the GPU-enabled PyTorch from PyPI (same as upstream PyTorch behavior).
+   To explicitly install a CPU-only or CUDA 12.4 build, use an extra:
 
-5. Install the latest [faster-whisper](https://github.com/guillaumekln/faster-whisper) from source:
    ```shell
-   pip install "faster-whisper @ https://github.com/SYSTRAN/faster-whisper/archive/8327d8cc647266ed66f6cd878cf97eccface7351.tar.gz"
+   pip install openlrc[cpu]      # CPU-only (smaller download, no GPU required)
+   pip install openlrc[cu124]    # CUDA 12.4 (explicit GPU build from PyTorch index)
    ```
 
-6. Install [PyTorch](https://pytorch.org/get-started/locally/):
+   Or install directly from GitHub:
+
    ```shell
-   pip install --force-reinstall torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
+   pip install git+https://github.com/zh-plus/openlrc
    ```
 
-7. Fix the `typing-extensions` issue:
+4. Install the latest [faster-whisper](https://github.com/guillaumekln/faster-whisper) from source:
    ```shell
-   pip install typing-extensions -U
+   pip install "faster-whisper @ https://github.com/SYSTRAN/faster-whisper/archive/8327d8cc647266ed66f6cd878cf97eccface7351.tar.gz"
    ```
 
+   <details>
+   <summary>For GPU users: CUDA runtime requirements (click to expand)</summary>
+
+   Running with GPU acceleration requires the
+   [CUDA 12 Toolkit](https://developer.nvidia.com/cuda-toolkit) (provides `libcudart`, `libcublas`, etc.).
+   If you installed PyTorch with `openlrc[cu124]` or the default GPU build from PyPI, make sure the
+   CUDA 12 runtime libraries are available on your system.
+
+   Additionally, `faster-whisper` requires
+   [cuDNN 9 for CUDA 12](https://developer.nvidia.com/cudnn) to run on GPU.
+   See the [CTranslate2 documentation](https://opennmt.net/CTranslate2/installation.html) for details.
+
+   (Windows only) You can download the libraries from Purfview's repository:
+
+   Purfview's [whisper-standalone-win](https://github.com/Purfview/whisper-standalone-win) provides the required NVIDIA
+   libraries for Windows in a [single archive](https://github.com/Purfview/whisper-standalone-win/releases/tag/libs).
+   Decompress the archive and place the libraries in a directory included in the `PATH`.
+
+   </details>
+
+### Using openlrc as a dependency
+
+If your project depends on openlrc and you want to switch between CPU and GPU
+PyTorch builds (e.g. CPU for development/CI, GPU for production),
+map openlrc's extras through your own `pyproject.toml`:
+
+```toml
+[project]
+dependencies = [
+    "openlrc",
+]
+
+[project.optional-dependencies]
+cpu = ["openlrc[cpu]"]
+cu124 = ["openlrc[cu124]"]
+
+[tool.uv]
+conflicts = [
+    [{ extra = "cpu" }, { extra = "cu124" }],
+]
+```
+
+Then select the variant at install time:
+
+```shell
+# Local development (CPU)
+uv sync --extra cpu
+
+# Production with GPU
+uv sync --extra cu124
+```
+
 ## Usage 🐍
 
 [//]: # (### GUI)
@@ -303,7 +337,15 @@ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | ie
 
 ```shell
 uv venv
+
+# Default (GPU-enabled PyTorch from PyPI)
 uv sync
+
+# CPU-only (for CI, or machines without GPU)
+uv sync --extra cpu
+
+# CUDA 12.4 (explicit GPU build from PyTorch index)
+uv sync --extra cu124
 ```
 
 ### Code quality checks

openlrc/preprocess.py

@@ -4,8 +4,6 @@
 from concurrent.futures import ProcessPoolExecutor
 from pathlib import Path
 
-import torch
-from df.enhance import enhance, init_df, load_audio, save_audio
 from ffmpeg_normalize import FFmpegNormalize
 from tqdm import tqdm
 
@@ -60,6 +58,11 @@ def noise_suppression(self, audio_paths: list[Path], atten_lim_db: int = 15):
         """
         Suppress noise in audio.
         """
+        # Lazy import: torch and deepfilternet are heavy dependencies that may not be available
+        # in all environments (e.g. CI with CPU-only PyTorch). Only import when actually needed.
+        import torch
+        from df.enhance import enhance, init_df, load_audio, save_audio
+
         if not audio_paths:
             return []
 

pyproject.toml

@@ -56,7 +56,19 @@ dependencies = [
     "torch>=2.6.0",
     "torchvision>=0.21.0",
     "torchaudio>=2.0.0",
-    "pip>=25.1"
+    "pip>=25.1",
+]
+
+[project.optional-dependencies]
+cpu = [
+    "torch>=2.6.0",
+    "torchvision>=0.21.0",
+    "torchaudio>=2.0.0",
+]
+cu124 = [
+    "torch>=2.6.0",
+    "torchvision>=0.21.0",
+    "torchaudio>=2.0.0",
 ]
 
 [project.urls]
@@ -77,12 +89,20 @@ dev = [
 ]
 
 [tool.uv]
+conflicts = [
+    [{ extra = "cpu" }, { extra = "cu124" }],
+]
 
 [[tool.uv.index]]
 name = "PyPI"
 url = "https://pypi.org/simple/"
 default = true
 
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
 [[tool.uv.index]]
 name = "pytorch-cu124"
 url = "https://download.pytorch.org/whl/cu124"
@@ -91,13 +111,16 @@ explicit = true
 [tool.uv.sources]
 faster-whisper = { url = "https://github.com/SYSTRAN/faster-whisper/archive/8327d8cc647266ed66f6cd878cf97eccface7351.tar.gz" }
 torch = [
-    { index = "pytorch-cu124", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
+    { index = "pytorch-cpu", extra = "cpu" },
+    { index = "pytorch-cu124", extra = "cu124" },
 ]
 torchvision = [
-    { index = "pytorch-cu124", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
+    { index = "pytorch-cpu", extra = "cpu" },
+    { index = "pytorch-cu124", extra = "cu124" },
 ]
 torchaudio = [
-    { index = "pytorch-cu124", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
+    { index = "pytorch-cpu", extra = "cpu" },
+    { index = "pytorch-cu124", extra = "cu124" },
 ]
 
 [tool.ruff]