### Install Pychorus

Source: https://github.com/vivjay30/pychorus/blob/master/README.md

Install the Pychorus library using pip. This is the first step to using the library.

```bash
pip install pychorus
```

--------------------------------

### find_and_output_chorus

Source: https://context7.com/vivjay30/pychorus/llms.txt

Loads an audio file, runs the full chorus-detection pipeline, prints the detected start time, and writes the extracted chorus clip to a WAV file. Returns the start time in seconds as a float, or None if no chorus was detected.

```APIDOC
## find_and_output_chorus

### Description
Loads an audio file, runs the full chorus-detection pipeline, prints the detected start time, and writes the extracted chorus clip to a WAV file. Returns the start time in seconds as a float, or `None` if no chorus was detected.

### Method Signature
`find_and_output_chorus(audio_file: str, output_file: Optional[str], clip_length: int = 15) -> Optional[float]`

### Parameters
- **audio_file** (str) - Required - Path to the input audio file (any format librosa supports).
- **output_file** (Optional[str]) - Required - Path to the output WAV file for the extracted clip. Pass `None` to detect without saving.
- **clip_length** (int) - Optional - Minimum chorus duration in seconds (default: 15).

### Request Example
```python
from pychorus import find_and_output_chorus

chorus_start_sec = find_and_output_chorus("song.mp3", "chorus_out.wav", clip_length=15)

if chorus_start_sec is not None:
    minutes = int(chorus_start_sec // 60)
    seconds = chorus_start_sec % 60
    print(f"Chorus starts at {minutes}m {seconds:.2f}s")
else:
    print("No chorus detected — try reducing clip_length")

start_only = find_and_output_chorus("song.mp3", None, clip_length=10)
```

### Response
- **chorus_start_sec** (Optional[float]) - The start time of the detected chorus in seconds, or `None` if no chorus was detected.
```

--------------------------------

### find_chorus

Source: https://context7.com/vivjay30/pychorus/llms.txt

Detects the chorus start time from a pre-computed chromogram. Builds similarity matrices, denoises, detects repeating lines, scores them, and returns the start time in seconds of the best chorus candidate.

```APIDOC
## find_chorus

### Description
Runs the full chorus-detection algorithm on a pre-computed chromogram. Builds time-time and time-lag similarity matrices, denoises, detects repeating lines, scores them, and returns the start time in seconds of the best chorus candidate. Useful when you want to reuse the chromogram for multiple clip lengths without re-reading the audio file.

### Method Signature
`find_chorus(chroma: np.ndarray, sr: int, song_length_sec: float, clip_length: int = 15) -> Optional[float]`

### Parameters
- **chroma** (np.ndarray) - Required - The chromogram computed by `create_chroma`.
- **sr** (int) - Required - The sample rate of the audio.
- **song_length_sec** (float) - Required - The total duration of the song in seconds.
- **clip_length** (int) - Optional - The minimum duration of the chorus to detect in seconds (default: 15).

### Returns
- **chorus_start** (Optional[float]) - The start time of the detected chorus in seconds, or `None` if no chorus was found.

### Request Example
```python
from pychorus import create_chroma, find_chorus
import soundfile as sf

chroma, wav_data, sr, song_length_sec = create_chroma("song.mp3")

chorus_start = find_chorus(chroma, sr, song_length_sec, clip_length=10)

if chorus_start is not None:
    print(f"Chorus at {chorus_start:.2f}s")
    clip_length = 10
    chorus_clip = wav_data[int(chorus_start * sr) : int((chorus_start + clip_length) * sr)]
    sf.write("my_chorus.wav", chorus_clip, sr)
else:
    print("No chorus found — try a smaller clip_length value")

for length in [8, 12, 20]:
    start = find_chorus(chroma, sr, song_length_sec, clip_length=length)
    print(f"clip_length={length}s -> chorus at {start}s")
```
```

--------------------------------

### Find Chorus from Chromogram

Source: https://context7.com/vivjay30/pychorus/llms.txt

Detects the chorus start time from a pre-computed chromogram. This function is useful when you want to reuse the chromogram for different analyses or clip lengths without re-reading the audio file. It returns the start time in seconds or None if no chorus is found.

```python
from pychorus import create_chroma, find_chorus

chroma, wav_data, sr, song_length_sec = create_chroma("song.mp3")

# Find the chorus that is at least 10 seconds long
chorus_start = find_chorus(chroma, sr, song_length_sec, clip_length=10)

if chorus_start is not None:
    print(f"Chorus at {chorus_start:.2f}s")

    # Manually extract and save the clip using soundfile
    import soundfile as sf
    clip_length = 10
    chorus_clip = wav_data[int(chorus_start * sr) : int((chorus_start + clip_length) * sr)]
    sf.write("my_chorus.wav", chorus_clip, sr)
else:
    print("No chorus found — try a smaller clip_length value")

# Try multiple clip lengths to find the best result
for length in [8, 12, 20]:
    start = find_chorus(chroma, sr, song_length_sec, clip_length=length)
    print(f"clip_length={length}s -> chorus at {start}s")
```

--------------------------------

### Command-line interface via main.py

Source: https://context7.com/vivjay30/pychorus/llms.txt

A CLI wrapper around find_and_output_chorus for terminal use.

```APIDOC
## Command-line interface via `main.py`

### Description
A CLI wrapper around `find_and_output_chorus` for quick terminal use. Accepts an input audio path, an optional output WAV path (defaults to `chorus.wav`), and an optional minimum clip length.

### Usage
```bash
# Basic usage — detects chorus and saves to chorus.wav
python main.py song.mp3

# Specify output file
python main.py song.mp3 --output_file=my_chorus.wav

# Set minimum chorus length to 20 seconds
python main.py song.mp3 --output_file=chorus_20s.wav --min_clip_length=20

# Process multiple files in a shell loop
for f in *.mp3; do
    python main.py "$f" --output_file="${f%.mp3}_chorus.wav"
done
```

### Expected terminal output:
```
Best chorus found at 1 min 14.30 sec
```
```

--------------------------------

### Pychorus Command-Line Interface Usage

Source: https://context7.com/vivjay30/pychorus/llms.txt

Demonstrates basic and advanced usage of the Pychorus command-line interface for detecting and saving chorus sections from audio files.

```bash
# Basic usage — detects chorus and saves to chorus.wav
python main.py song.mp3

# Specify output file
python main.py song.mp3 --output_file=my_chorus.wav

# Set minimum chorus length to 20 seconds
python main.py song.mp3 --output_file=chorus_20s.wav --min_clip_length=20

# Process multiple files in a shell loop
for f in *.mp3; do
    python main.py "$f" --output_file="${f%.mp3}_chorus.wav"
done

# Expected terminal output:
# Best chorus found at 1 min 14.30 sec
```

--------------------------------

### Create and Visualize Similarity Matrices

Source: https://github.com/vivjay30/pychorus/blob/master/README.md

Generate chromogram, time-time, and time-lag similarity matrices from an audio file. The `create_chroma` function extracts the chroma features, and then `TimeTimeSimilarityMatrix` and `TimeLagSimilarityMatrix` can be instantiated and visualized.

```python
from pychorus import create_chroma
from pychorus.similarity_matrix import TimeTimeSimilarityMatrix, TimeLagSimilarityMatrix

chroma, _, sr, _ = create_chroma("path/to/audio_file")
time_time_similarity = TimeTimeSimilarityMatrix(chroma, sr)
time_lag_similarity = TimeLagSimilarityMatrix(chroma, sr)

# Visualize the results
time_time_similarity.display()
time_lag_similarity.display()
```

--------------------------------

### Pychorus Command Line Tool

Source: https://github.com/vivjay30/pychorus/blob/master/README.md

Execute Pychorus from the command line to find and output a chorus. This method requires specifying the input audio file and an optional output file path.

```bash
python main.py path/to/audio_file --output_file=path/to/output_file
```

--------------------------------

### create_chroma

Source: https://context7.com/vivjay30/pychorus/llms.txt

Loads an audio file and computes a 12-tone chroma feature matrix (chromogram) via Short-Time Fourier Transform. Returns the raw components needed for downstream similarity matrix construction and chorus detection.

```APIDOC
## create_chroma

### Description
Loads an audio file with librosa and computes a 12-tone chroma feature matrix (chromogram) via Short-Time Fourier Transform. Returns the raw components needed for downstream similarity matrix construction and chorus detection.

### Method Signature
`create_chroma(audio_file: str, n_fft: int = 16384) -> Tuple[np.ndarray, np.ndarray, int, float]`

### Parameters
- **audio_file** (str) - Required - Path to the input audio file.
- **n_fft** (int) - Optional - The FFT window size. Affects time resolution (default: 16384).

### Returns
- **chroma** (np.ndarray) - Numpy array of shape (12, n_frames) representing pitch class energy over time.
- **wav_data** (np.ndarray) - Raw waveform as a 1D numpy float32 array.
- **sample_rate** (int) - Audio sample rate, typically 22050 Hz.
- **song_length_sec** (float) - Total song duration in seconds.

### Request Example
```python
from pychorus import create_chroma

chroma, wav_data, sample_rate, song_length_sec = create_chroma("song.mp3")

print(f"Chroma shape: {chroma.shape}")
print(f"Sample rate: {sample_rate} Hz")
print(f"Song length: {song_length_sec:.1f}s")

chroma_fine, wav_data, sr, length = create_chroma("song.mp3", n_fft=2048)
print(f"Fine chroma shape: {chroma_fine.shape}")
```
```

--------------------------------

### Create Chromogram from Audio File

Source: https://context7.com/vivjay30/pychorus/llms.txt

Generates a chromogram (pitch-class representation) from an audio file using librosa. This function returns the chromogram matrix, raw waveform data, sample rate, and song duration. It can also accept a custom FFT size for finer time resolution.

```python
from pychorus import create_chroma

chroma, wav_data, sample_rate, song_length_sec = create_chroma("song.mp3")

# chroma:          numpy array of shape (12, n_frames) — pitch class energy over time
# wav_data:        raw waveform as a 1D numpy float32 array
# sample_rate:     audio sample rate, almost always 22050 Hz
# song_length_sec: total song duration in seconds

print(f"Chroma shape: {chroma.shape}")       # e.g. (12, 4312)
print(f"Sample rate: {sample_rate} Hz")      # 22050
print(f"Song length: {song_length_sec:.1f}s") # e.g. 214.3s

# Use a custom FFT size for finer time resolution (default N_FFT=2**14=16384)
chroma_fine, wav_data, sr, length = create_chorus("song.mp3", n_fft=2048)
print(f"Fine chroma shape: {chroma_fine.shape}")  # more frames, finer resolution
```

--------------------------------

### Find and Output Chorus using Pychorus

Source: https://context7.com/vivjay30/pychorus/llms.txt

Use this function to automatically detect a chorus in an audio file and save it as a WAV file. Specify the input audio, output WAV file path, and optionally the minimum clip length. If no chorus is found, it returns None.

```python
from pychorus import find_and_output_chorus

# Detect the chorus and save a 15-second clip starting at the chorus
chorus_start_sec = find_and_output_chorus(
    "song.mp3",          # Input audio file (any format librosa supports)
    "chorus_out.wav",    # Output WAV file for the extracted clip
    clip_length=15       # Minimum chorus duration in seconds (default: 15)
)

if chorus_start_sec is not None:
    minutes = int(chorus_start_sec // 60)
    seconds = chorus_start_sec % 60
    print(f"Chorus starts at {minutes}m {seconds:.2f}s")
else:
    print("No chorus detected — try reducing clip_length")

# To detect without saving any file, pass None as output_file
start_only = find_and_output_chorus("song.mp3", None, clip_length=10)
```

```python
# Output: Best chorus found at 1 min 14.30 sec
```

--------------------------------

### Find and Output Chorus

Source: https://github.com/vivjay30/pychorus/blob/master/README.md

Use the `find_and_output_chorus` function to detect and save a chorus section from an audio file. Specify input and output file paths, and optionally a clip length.

```python
from pychorus import find_and_output_chorus

chorus_start_sec = find_and_output_chorus("path/to/audio_file", "path/to/output_file", clip_length)
```

--------------------------------

### Compute and Analyze Time-Time Similarity Matrix

Source: https://context7.com/vivjay30/pychorus/llms.txt

Computes the time-time similarity matrix from a chromogram. Entry (i, j) measures the similarity between audio frame i and frame j. Requires matplotlib for visualization.

```python
from pychorus import create_chroma
from pychorus.similarity_matrix import TimeTimeSimilarityMatrix

chroma, _, sr, _ = create_chroma("song.mp3")

tt_matrix = TimeTimeSimilarityMatrix(chroma, sr)

print(f"Matrix shape: {tt_matrix.matrix.shape}")  # (n_frames, n_frames)
print(f"Value range: {tt_matrix.matrix.min():.3f} – {tt_matrix.matrix.max():.3f}")
# e.g. 0.000 – 1.000

# Diagonal is always 1.0 (a frame is identical to itself)
import numpy as np
print(f"Diagonal mean: {np.diag(tt_matrix.matrix).mean():.3f}")  # 1.000

# Visualize the similarity matrix (requires matplotlib)
tt_matrix.display()  # Opens an interactive spectrogram-style heatmap
```

--------------------------------

### TimeTimeSimilarityMatrix

Source: https://context7.com/vivjay30/pychorus/llms.txt

Computes the frame-to-frame similarity matrix. Entry (i, j) measures the similarity between audio frame i and frame j.

```APIDOC
## TimeTimeSimilarityMatrix

### Description
A class that computes the time-time similarity matrix from a chromogram. Entry `(i, j)` in the matrix measures how similar audio frame `i` is to frame `j`, using normalized Euclidean distance in 12-dimensional chroma space. Values range from 0 (no similarity) to 1 (identical).

### Usage
```python
from pychorus import create_chroma
from pychorus.similarity_matrix import TimeTimeSimilarityMatrix

chroma, _, sr, _ = create_chroma("song.mp3")

tt_matrix = TimeTimeSimilarityMatrix(chroma, sr)

print(f"Matrix shape: {tt_matrix.matrix.shape}")
print(f"Value range: {tt_matrix.matrix.min():.3f} – {tt_matrix.matrix.max():.3f}")
import numpy as np
print(f"Diagonal mean: {np.diag(tt_matrix.matrix).mean():.3f}")

tt_matrix.display()
```

### Attributes
- **matrix** (numpy.ndarray): The computed similarity matrix.

### Methods
- **display()**: Visualizes the similarity matrix.
```

--------------------------------

### Compute and Denoise Time-Lag Similarity Matrix

Source: https://context7.com/vivjay30/pychorus/llms.txt

Computes the time-lag similarity matrix, where entry (lag, i) measures similarity between frame i and frame i - lag. Denoising suppresses noise to highlight repeating song sections. Requires matplotlib for visualization.

```python
from pychorus import create_chroma
from pychorus.similarity_matrix import TimeTimeSimilarityMatrix, TimeLagSimilarityMatrix

chroma, _, sr, song_length_sec = create_chroma("song.mp3")

tt_matrix = TimeTimeSimilarityMatrix(chroma, sr)
tl_matrix = TimeLagSimilarityMatrix(chroma, sr)

print(f"Time-lag matrix shape: {tl_matrix.matrix.shape}")  # (n_frames, n_frames)

# Visualize the raw time-lag matrix (horizontal lines = repeated segments)
tl_matrix.display()

# Denoise the matrix to emphasize horizontal lines
import numpy as np
chroma_sr = chroma.shape[1] / song_length_sec  # frames per second
smoothing_size_samples = int(2.5 * chroma_sr)  # 2.5 second smoothing window

tl_matrix.denoise(tt_matrix.matrix, smoothing_size_samples)

# Visualize the denoised matrix — chorus lines should now be clearly visible
tl_matrix.display()

print(f"Post-denoise range: {tl_matrix.matrix.min():.3f} – {tl_matrix.matrix.max():.3f}")
```

--------------------------------

### TimeLagSimilarityMatrix

Source: https://context7.com/vivjay30/pychorus/llms.txt

Computes the lag-based similarity matrix. Entry (lag, i) measures similarity between frame i and frame i - lag.

```APIDOC
## TimeLagSimilarityMatrix

### Description
Computes the time-lag similarity matrix from a chromogram, where entry `(lag, i)` measures how similar frame `i` is to frame `i - lag`. Horizontal lines in this matrix correspond to song sections that repeat at a fixed time offset (the lag), which is the key signature of a chorus.

### Usage
```python
from pychorus import create_chroma
from pychorus.similarity_matrix import TimeTimeSimilarityMatrix, TimeLagSimilarityMatrix

chroma, _, sr, song_length_sec = create_chroma("song.mp3")

tt_matrix = TimeTimeSimilarityMatrix(chroma, sr)
tl_matrix = TimeLagSimilarityMatrix(chroma, sr)

print(f"Time-lag matrix shape: {tl_matrix.matrix.shape}")

tl_matrix.display()

import numpy as np
chroma_sr = chroma.shape[1] / song_length_sec
smoothing_size_samples = int(2.5 * chroma_sr)

tl_matrix.denoise(tt_matrix.matrix, smoothing_size_samples)

tl_matrix.display()

print(f"Post-denoise range: {tl_matrix.matrix.min():.3f} – {tl_matrix.matrix.max():.3f}")
```

### Attributes
- **matrix** (numpy.ndarray): The computed time-lag similarity matrix.

### Methods
- **display()**: Visualizes the time-lag similarity matrix.
- **denoise(tt_matrix, smoothing_size_samples)**: Denoises the time-lag matrix to emphasize horizontal lines.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.