Metadata-Version: 2.4
Name: series-intro-recognizer
Version: 1.3.0
Summary: Find the intro of episodes of a series
Author: HRAshton
License-Expression: MIT
Project-URL: Homepage, https://github.com/HRAshton/series-intro-recognizer
Project-URL: Documentation, https://github.com/HRAshton/series-intro-recognizer/wiki
Project-URL: Issues, https://github.com/HRAshton/series-intro-recognizer/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: librosa>=0.10.1
Requires-Dist: numpy>=1.26.4
Requires-Dist: scikit-learn>=1.4.2
Requires-Dist: scipy>=1.13
Requires-Dist: soundfile>=0.12.1
Provides-Extra: dev
Requires-Dist: pytest>=8.1.1; extra == "dev"
Dynamic: license-file

# Series Intro Recognizer

Detailed documentation is available at [Wiki](https://github.com/HRAshton/series-intro-recognizer/wiki).

Comparing episodes of a series to find the opening/endings of the series.

This library receives a list of episodes, extracts the audio features of each
episode and compares them to find the common part of the series.

To reduce the number of comparisons, the library compares 4 sequential episodes.
The number of episodes to be compared can be changed in configuration.

## Installation

The project uses Cupy. It supports both Cuda and AMD GPUs. Please refer to
the [Cupy installation guide](https://docs.cupy.dev/en/stable/install.html)
to install the correct version for your system.

```bash
pip install series-intro-recognizer
```

## Options

### Input options:

- Iterator of audio samples (numpy ndarrays), offset and duration
- Iterator of audio files
- Iterator of audio files, offset and duration

Offset and duration are used to extract the audio features of the episodes and
can be None. If None, the whole audio will be used.

WARN: See the warning #1 in the Usage section.

### Output:

- List of intervals of the same fragment in the episodes

To find an opening, pass the first minutes (e.g. 5 minutes) of the episodes.
To find an ending, pass the last minutes (e.g. 5 minutes) of the episodes.

WARN: See the warning #2 in the Usage section.

### Configuration:

Every call of methods should pass a configuration object. Feel free to just pass
the default configuration.

The configuration object has the following fields:

- rate: Audio sample rate.
- min_segment_length_sec: Minimum length of the intro in seconds.
- max_segment_length_sec: Maximum length of the intro in seconds.
- precision_secs: Precision of the correlation in seconds.
- series_window: Number of sequential audio samples to be matched with each other.
- offset_searcher__sequential_secs: Number of sequential 'non-intro' seconds
  that signal the end of the intro.
- adjustment_threshold: Threshold for adjusting the borders of the intro.
- adjustment_threshold_secs: Threshold for adjusting the borders of the intro to
  the borders of the audio.
- save_intermediate_results: Save the correlation results.

## Important warnings

**WARNING #1**: Do not pass the whole episodes, it will take a long time to process
and the results will not be accurate (in this case, the library will find the
intro or outro, depending on which part is longer).

**WARNING #2**: If you use recognise_from_audio_files_with_offsets and offsets
are provided, the library WILL NOT add it to the output intervals.
Please, add it manually.

**WARNING #3**: There is a well-known memory leak in sklearn. You will see a warning
when running the app. The memory leak should not be a problem for a short run,
but it is recommended to add `OMP_NUM_THREADS=1` to the environment variables.

## Usage

You can find other examples in the tests/processors folder.

To find the opening of a series by audio paths:

```python
cfg = Config()
files = [f'assets/audio_files/{i}.wav' for i in paths]
recognised = recognise_from_audio_files(files, cfg)
# Returns a list of intervals
# [(start=0.25, end=30.25), (start=0.20, end=30.20), ...]
```

To find the opening of a series by audio samples:

```python
def some_audio_loading_function() -> np.ndarray:
    return np.random.rand(1000)


cfg = Config()
samples = map(lambda _: (some_audio_loading_funciton(), None, None), range(10))
recognised = recognise_from_audio_samples(samples, cfg)
# Returns a list of intervals
# [(start=0.25, end=30.25), (start=0.20, end=30.20), ...]
```

To find the ending of a series by audio paths, analysing intervals
from 1 to 35 seconds:

```python
cfg = Config()
files = [(f'assets/audio_files/{i}.wav', 2, 30) for i in paths]
recognised = recognise_from_audio_files(files, cfg)
# Returns a list of intervals
# [(start=0, end=28.25), (start=0, end=28.20), ...]
```

## Development & Contributing

### Quality Standards

The project enforces strict code quality checks:

- **Type Checking**: All code must pass `mypy` in strict mode with 100% type coverage
- **Test Coverage**: Minimum 80% test coverage is required (enforced in CI/CD)
- **Unit Tests**: All new features must include unit tests
- **Code Style**: Code must pass ruff linting checks

### Running Tests Locally

```bash
# Run all tests with coverage report
pytest --cov=series_intro_recognizer --cov-report=html tests/
```

```bash
# Run type checking
mypy --strict series_intro_recognizer tests
```

### Coverage Reports

Coverage reports are automatically generated and commented on pull requests. The project maintains an 80% minimum coverage threshold. Coverage reports can be:

- Viewed in CI/CD workflow runs
- Downloaded from codecov
- Generated locally using `pytest --cov=series_intro_recognizer --cov-report=html tests/`

### Pull Request Requirements

All pull requests must:

1. Pass all automated checks (tests, type checking, linting)
2. Maintain or improve the current test coverage (minimum 80%)
3. Include type hints for all new functions/methods
4. Have meaningful commit messages

