Installation Guide

This page explains how to install and configure SeriesIntroRecognizer on systems using NVIDIA or AMD GPUs.

TL;DR

1. Install a matching CuPy version for your GPU.
   Guide: https://docs.cupy.dev/en/stable/install.html
2. Verify with pytest or cupy.cuda.runtime.getDeviceCount().
3. Run pip install series_intro_recognizer.

The system is ready once both GPU and dependency checks succeed.

Basic Installation

pip install series_intro_recognizer

The library depends on CuPy for GPU acceleration and NumPy, SciPy, scikit-learn, and librosa for signal processing.

System Requirements

Component	Requirement
Python	≥ 3.12
GPU Backend	CUDA (NVIDIA) or ROCm (AMD)
RAM	≥ 4 GB recommended
Storage	~200 MB for dependencies
Supported OS	Linux, macOS, Windows (64-bit)

Installing CuPy

SeriesIntroRecognizer does not install CuPy automatically, because the correct version depends on your GPU and driver.

Visit the CuPy Installation Guide and install the variant for your hardware.

Examples:

# For NVIDIA CUDA 12.x
pip install cupy-cuda12x

# For AMD ROCm
pip install cupy-rocm-5-4

To verify installation:

import cupy as cp
print(cp.cuda.runtime.getDeviceCount())

Common Issues and Fixes

Problem	Cause	Solution
CuPy not found	Wrong CuPy variant installed	Reinstall matching version for your GPU backend (CUDA/ROCm).
OMP_NUM_THREADS warning	Known scikit-learn issue (memory leak)	Set OMP_NUM_THREADS=1 in your environment. Safe for short runs.
Excessive runtime	Entire episodes passed instead of trimmed clips	Use only first or last few minutes of each file; long inputs slow correlation. You also can adjust configuration parameters to use longer segments for processing.
No GPU detected	Missing CUDA/ROCm drivers	Install proper drivers and recheck with cupy.cuda.runtime.getDeviceCount().

Development Setup

To install optional dependencies for testing and local builds:

git clone https://github.com/HRAshton/SeriesIntroRecognizer.git
cd SeriesIntroRecognizer
pip install -r requirements-dev.txt

Optional dev packages include:

• pytest — runs all test suites under tests/.
• soundfile — enables reading and writing audio files in multiple formats.