Documentation / Administration

GPU acceleration

Speed up light show analysis with an NVIDIA graphics card. Rainy works without one.

Analysing a song for its light show takes a while, and most of that time goes to one step: separating a song's sustained tones from its percussive hits. Rainy can run that step on an NVIDIA GPU. Everything else in the analysis runs on the processor. The scores match whichever device does the separation, up to rounding.

GPU support is optional. Without a usable GPU, Rainy uses the processor and runs that step across several cores.

What it speeds up, and what it doesn't

GPU support only affects light show analysis, and only the separation step inside it, which takes about two thirds of the analysis time.

It does not change:

• the light show itself, which runs in your browser,
• scanning, metadata, artist images, lyrics or imports,
• playback or the results of an analysis. A GPU analysis and a CPU analysis produce the same scores, apart from floating-point rounding.

If you only want faster light shows on a server with no GPU, nothing is needed. Rainy already uses all available cores, up to 8 by default.

Requirements

• An NVIDIA GPU with a recent driver. You don't need a separate CUDA toolkit installed on the system.
• A CUDA build of PyTorch installed in the same Python environment that runs Rainy. The standard PyTorch wheel on some platforms is CPU-only, so install the CUDA build explicitly:

sh pip install torch --index-url https://download.pytorch.org/whl/cu126

• A PyTorch build that supports your GPU. Rainy checks this for each GPU, and skips any it can't use. Older cards, such as the Tesla V100 (compute capability 7.0), may need an older PyTorch build that still includes their kernels.

To confirm PyTorch sees your GPU, run:

python -c "import torch; print(torch.cuda.is_available(), torch.cuda.get_device_name(0))"

Use the GPU in Docker

The bundled compose.yaml asks Docker for all NVIDIA GPUs for the app service. For this to work:

1. Install the NVIDIA Container Toolkit on the host.
2. Add a CUDA build of PyTorch to the image. The default image does not include PyTorch. For example, add pip install torch --index-url https://download.pytorch.org/whl/cu126 to the Dockerfile.
3. Rebuild and restart the container.

Without PyTorch in the image, Rainy uses the processor. If your host has no NVIDIA toolkit, remove the deploy: block from compose.yaml, or Docker will fail to start the container.

Choose the device

Set RAINY_LIGHTSHOW_DEVICE in your .env file or environment.

Rainy checks each GPU before it uses it. A GPU is used only when its PyTorch build supports it and a short test on that GPU produces the same results as the processor. A GPU that fails either check is skipped, and Rainy logs why.

RAINY_LIGHTSHOW_THREADS sets how many processor threads the processor path uses. It defaults to the number of cores, up to 8.

Rainy picks the GPU when the first light show analysis runs, not when the server starts. The device line appears in the log at that point.

Check what Rainy is using

Analyse a song, then look for this line in the server log:

[lightshow-accel] analysis device: cuda:0 (NVIDIA GeForce RTX 4060 Ti)

A processor run logs something like this instead, with the reason:

[lightshow-accel] analysis device: cpu (CPU x8 threads) — no CUDA GPU visible to PyTorch

When something goes wrong

Rainy never fails an analysis because of the GPU. It falls back to the processor instead.

After you fix a driver or PyTorch problem, restart Rainy. The device choice is made once per run.

Related

• Light show
• Configuration
• Install