### Install beat-this CLI

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/cli-reference.md

Install the beat-this CLI tool using pip. This command installs the tool along with the Python package.

```bash
pip install beat-this
```

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

### Verify beat-this Installation

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/cli-reference.md

Verify that the beat-this CLI has been installed correctly by checking its help message.

```bash
beat_this --help
```

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

### Install pandas and pedalboard

Source: https://github.com/cpjku/beat_this/blob/main/README.md

Install necessary Python packages for audio preprocessing. This command should be run before executing the preprocessing script.

```bash
pip install pandas pedalboard
```

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

### Checkpoint Dictionary Example

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/types.md

Example demonstrating how to load a checkpoint and access its hyperparameters and state dictionary for model loading.

```python
from beat_this.inference import load_checkpoint

checkpoint = load_checkpoint("final0", device="cpu")

# Access hyperparameters
n_layers = checkpoint["hyper_parameters"]["n_layers"]
transformer_dim = checkpoint["hyper_parameters"]["transformer_dim"]

# State dict can be loaded into model
state_dict = checkpoint["state_dict"]
```

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

### Install Beat This! Package

Source: https://github.com/cpjku/beat_this/blob/main/README.md

Install the beat tracker package using pip. For the development version, use the provided GitHub archive link.

```bash
pip install beat-this
```

```bash
pip install https://github.com/CPJKU/beat_this/archive/main.zip
```

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

### Beat Prediction Example

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/types.md

Example demonstrating how to load audio, process it with Audio2Frames, and access beat and downbeat logits from the predictions.

```python
from beat_this.inference import Audio2Frames
from beat_this.preprocessing import load_audio

audio2frames = Audio2Frames(device="cuda")
signal, sr = load_audio("song.mp3")

predictions = audio2frames(signal, sr)  # type: dict[str, torch.Tensor]
beat_logits = predictions["beat"]       # shape: (frames,)
downbeat_logits = predictions["downbeat"]  # shape: (frames,)
```

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

### Install and Import Beat This Package

Source: https://github.com/cpjku/beat_this/blob/main/beat_this_example.ipynb

Installs the beat_this package from GitHub and imports the necessary classes for inference. For Google Colab, a faster installation command is provided.

```python
# install the beat_this package
!pip install https://github.com/CPJKU/beat_this/archive/main.zip
# on Google Colab, this one is faster:
#!pip install --no-deps rotary-embedding-torch https://github.com/CPJKU/beat_this/archive/main.zip

# load the Python class for beat tracking
from beat_this.inference import File2Beats
from beat_this.inference import File2File
```

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

### Install PyTorch with CUDA support

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/cli-reference.md

Install PyTorch with CUDA support to resolve 'CUDA not available' errors.

```bash
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
```

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

### Audio Signal Example

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/types.md

Example demonstrating how to use Audio2Beats with a numpy array, including handling of stereo signals which are auto-converted to mono.

```python
import numpy as np
from beat_this.inference import Audio2Beats

audio2beats = Audio2Beats(device="cuda")

# From numpy array
signal = np.random.randn(22050 * 60)  # 60 seconds at 22050 Hz
beats, downbeats = audio2beats(signal, sr=22050)

# Stereo audio is auto-converted to mono
stereo_signal = np.random.randn(2, 22050 * 60)
beats, downbeats = audio2beats(stereo_signal, sr=22050)
```

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

### Prepare for Parallel Processing

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/cli-reference.md

Use --touch-first to create empty output files before processing, enabling safe parallel execution with --skip-existing. This example shows how to distribute processing across multiple GPUs.

```bash
# Process multiple files in parallel across multiple GPUs
for gpu in {0..3}; do
  beat_this /input/dir -o /output/dir \
    --touch-first --skip-existing --gpu=$gpu &
done
wait
```

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

### Install FFmpeg on Ubuntu/Debian

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/cli-reference.md

Install FFmpeg on Ubuntu or Debian systems to resolve issues with unreadable audio files.

```bash
# Ubuntu/Debian
sudo apt-get install ffmpeg
```

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

### Install DBN Postprocessing Dependency

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/cli-reference.md

Install the necessary library for Dynamic Bayesian Network postprocessing from its GitHub repository.

```bash
pip install git+https://github.com/CPJKU/madmom.git
```

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

### FeedForward Example Usage

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/transformer-backbone.md

Demonstrates how to instantiate and use the FeedForward layer with random input data. Asserts that the output shape is as expected.

```python
from beat_this.model.roformer import FeedForward
import torch

ff = FeedForward(dim=512, mult=4, dropout=0.1)

x = torch.randn(2, 1500, 512)
output = ff(x)
assert output.shape == (2, 1500, 512)
```

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

### Beat Times Example

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/types.md

Example showing how to use File2Beats to infer beat and downbeat times from an audio file and print the results.

```python
from beat_this.inference import File2Beats

file2beats = File2Beats(device="cuda")
beats, downbeats = file2beats("song.mp3")

print(f"Beats: {beats}")       # array([0.02, 0.52, 1.02, ...])
print(f"Downbeats: {downbeats}") # array([0.02, 2.02, 4.02, ...])
```

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

### Install PyTorch Lightning, Pandas, and mir_eval

Source: https://github.com/cpjku/beat_this/blob/main/README.md

Install Python packages required for computing evaluation metrics. Note that mir_eval is installed from source to ensure compatibility.

```bash
pip install pytorch_lightning pandas
```

```bash
pip install https://github.com/mir-evaluation/mir_eval/archive/main.zip
```

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

### Install FFmpeg on macOS with Homebrew

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/cli-reference.md

Install FFmpeg on macOS using Homebrew to resolve issues with unreadable audio files.

```bash
# macOS (with Homebrew)
brew install ffmpeg
```

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

### Install FFmpeg on Windows with Conda

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/cli-reference.md

Install FFmpeg on Windows using Conda to resolve issues with unreadable audio files.

```bash
# Windows (with conda)
conda install ffmpeg
```

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

### Run Beat Tracking on Demo File

Source: https://github.com/cpjku/beat_this/blob/main/beat_this_example.ipynb

Downloads a demo MP3 file, loads the File2Beats class, applies it to the audio file to get beat and downbeat positions, and prints the first 20 beats and downbeats.

```python
!wget -c "https://github.com/CPJKU/beat_this/raw/main/tests/It%20Don't%20Mean%20A%20Thing%20-%20Kings%20of%20Swing.mp3"
audio_path = "/content/It Don't Mean A Thing - Kings of Swing.mp3"

file2beats = File2Beats(checkpoint_path="final0", dbn=False)
beats, downbeats = file2beats(audio_path)

print("First 20 beats", beats[:20])
print("First 20 downbeats", downbeats[:20])
```

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

### Dropout Dictionary Example

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/types.md

Example of a dropout configuration dictionary, specifying dropout rates for the 'frontend' and 'transformer' components of the model.

```python
dropout = {
    "frontend": 0.1,      # Dropout in convolutional frontend
    "transformer": 0.2,   # Dropout in transformer blocks
}
```

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

### Augmentation Dictionary Example

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/types.md

Example of an augmentation dictionary specifying a pitch shift of 5 semitones up and a time stretch of 110% (10% stretch).

```python
{
    "shift": 5,        # 5 semitones up
    "stretch": 110,    # 110% = 10% time stretch
}
```

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

### Load BeatThis Model via Torch Hub

Source: https://github.com/cpjku/beat_this/blob/main/README.md

Loads the BeatThis model using torch.hub for quick experimentation without package installation.

```python
import torch
beat_this = torch.hub.load('CPJKU/beat_this', 'beat_this', 'final0', device='cuda')
```

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

### Spectrogram Tensor Example

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/types.md

Example showing the conversion of an audio signal to a log-mel spectrogram and then feeding it to Spect2Frames for beat and downbeat logit prediction.

```python
from beat_this.preprocessing import LogMelSpect, load_audio
from beat_this.inference import Spect2Frames
import torch

spect_transform = LogMelSpect(device="cuda")
spect2frames = Spect2Frames(device="cuda")

signal, sr = load_audio("song.mp3")
signal = torch.tensor(signal, dtype=torch.float32, device="cuda")

# Spectrogram shape: (time, 128)
spect = spect_transform(signal)

# Model expects same spectrogram format
beat_logits, downbeat_logits = spect2frames(spect)
```

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

### RMSNorm Example Usage

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/transformer-backbone.md

Shows how to create an RMSNorm instance and apply it to a random tensor. Verifies that the output shape is identical to the input shape.

```python
from beat_this.model.roformer import RMSNorm
import torch

norm = RMSNorm(size=512, dim=-1)

x = torch.randn(2, 1500, 512)
output = norm(x)
assert output.shape == x.shape
```

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

### Load and Use BeatThis Model for Inference

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/inference.md

Loads a pre-trained BeatThis model and performs inference on a spectrogram. This example demonstrates how to use the `split_predict_aggregate` function for processing long audio sequences by splitting them into chunks.

```python
from beat_this.inference import split_predict_aggregate, load_model
import torch

model = load_model("final0", device="cuda")
spect = torch.randn(3000, 128)  # 60 seconds at 50 fps

result = split_predict_aggregate(
    spect=spect,
    chunk_size=1500,
    border_size=6,
    overlap_mode="keep_first",
    model=model
)

beat_logits = result["beat"]
downbeat_logits = result["downbeat"]

```

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

### Attention Module Example Usage

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/transformer-backbone.md

Create and use an Attention module. Input tensor shape is (batch, sequence_length, dim). Output shape is the same.

```python
from beat_this.model.roformer import Attention
from rotary_embedding_torch import RotaryEmbedding
import torch

rotary_embed = RotaryEmbedding(dim_head=32)

attn = Attention(
    dim=512,
    heads=16,
    dim_head=32,
    dropout=0.1,
    rotary_embed=rotary_embed,
    gating=True,
)

x = torch.randn(2, 1500, 512)
output = attn(x)
assert output.shape == x.shape
```

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

### Initialize MaskedBCELoss

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/loss-functions.md

Instantiate MaskedBCELoss for standard binary cross-entropy or with a positive weight to upweight positive examples, which is useful for imbalanced beat tracking.

```python
from beat_this.model.loss import MaskedBCELoss
import torch

# Standard binary cross-entropy
loss_fn = MaskedBCELoss(pos_weight=1.0)

# Upweight positive examples (useful for imbalanced beat tracking)
loss_fn = MaskedBCELoss(pos_weight=2.0)
```

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

### Beat This! Inference with DBN Postprocessing

Source: https://github.com/cpjku/beat_this/blob/main/README.md

Use the DBN for postprocessing by adding the `--dbn` flag. Requires the `madmom` package to be installed.

```bash
beat_this input_dir -o output_dir --dbn
```

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

### Transformer Example Usage

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/transformer-backbone.md

Create and use a Transformer model. Requires input tensor shape (batch, sequence_length, dim). Output shape matches input.

```python
from beat_this.model.roformer import Transformer
from rotary_embedding_torch import RotaryEmbedding
import torch

rotary_embed = RotaryEmbedding(dim_head=32)

transformer = Transformer(
    dim=512,
    depth=6,
    dim_head=32,
    heads=16,
    attn_dropout=0.1,
    ff_dropout=0.1,
    ff_mult=4,
    norm_output=True,
    rotary_embed=rotary_embed,
    gating=True,
)

x = torch.randn(2, 1500, 512)  # batch=2, seq_len=1500, dim=512
output = transformer(x)
assert output.shape == x.shape
```

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

### SumHead Forward Pass Example

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/beat-tracker-model.md

Demonstrates the forward pass of the SumHead. It takes an input tensor of shape (batch, time, input_dim) and returns a dictionary containing beat and downbeat logits.

```python
from beat_this.model.beat_tracker import SumHead
import torch

head = SumHead(input_dim=512)
x = torch.randn(2, 1500, 512)  # batch=2, time=1500, features=512

output = head(x)
beat_logits = output["beat"]           # shape: (2, 1500)
downbeat_logits = output["downbeat"]   # shape: (2, 1500)
```

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

### Command-Line Interface (CLI)

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/MANIFEST.txt

This section provides documentation for the Beat This! command-line tool, detailing all available options and their usage for performing beat tracking tasks directly from the terminal.

```APIDOC
## Command-Line Interface (CLI)

This section details the usage and options for the Beat This! command-line tool.

### Usage

```bash
beat_this [OPTIONS] INPUT_FILE OUTPUT_FILE
```

### Options

The CLI offers a wide range of options for controlling inference, model loading, and output formatting. Refer to `cli-reference.md` for a complete list and detailed descriptions of all options, including:

- **Model selection**: Options to specify which pre-trained model to use.
- **Inference parameters**: Settings for the beat tracking process.
- **Output formatting**: Control over the format and content of the output file.
- **Batch processing**: Options for handling multiple files.

### Examples

Refer to `cli-reference.md` for comprehensive usage examples covering various scenarios.
```

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

### Configuration Options

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/MANIFEST.txt

This section details all configurable parameters for the Beat This! library, including hyperparameters for the BeatThis model, inference settings, spectrogram configurations, and more.

```APIDOC
## Configuration Options

This section provides a comprehensive reference for all configuration parameters available in the Beat This! library.

### Categories

Configuration options are organized into several categories:

- **BeatThis Hyperparameters**: Core parameters influencing the beat tracking model's behavior (9 options).
- **Inference Settings**: Parameters controlling the inference process (4 options).
- **Spectrogram Settings**: Options related to spectrogram generation (10 options).
- **Loss Function Options**: Parameters for training loss functions (2 options).
- **CLI Options**: Parameters specific to the command-line interface (13+ options).
- **Checkpoint Listing**: Information about available pre-trained models (30+ models).

### Details

For a complete list of all configuration options, their types, default values, and detailed descriptions, please refer to the `configuration.md` file.
```

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

### Recommended Loss for Training from Scratch

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/loss-functions.md

The paper recommends using ShiftTolerantBCELoss with specific default parameters for training beat detection models from scratch.

```python
ShiftTolerantBCELoss(tolerance=3, pos_weight=1.0)
```

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

### SumHead.__init__

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/beat-tracker-model.md

Initializes the SumHead, which produces beat and downbeat predictions.

```APIDOC
## SumHead.__init__

### Description
Initializes the SumHead, which produces beat and downbeat predictions such that beats = downbeats + separate_beat_logits. This reduces spurious downbeat predictions that are not actual beats.

### Parameters
#### Path Parameters
- **input_dim** (int) - Yes - Dimension of input features from transformer
```

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

### Initialize LogMelSpect with Default Preprocessing Settings

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/configuration.md

Create a LogMelSpect object using the default parameters that match the model's training configuration. The processing will be performed on the CUDA device.

```python
from beat_this.preprocessing import LogMelSpect

# Default (matches model training)
mel_transform = LogMelSpect(device="cuda")
```

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

### Initialize BeatThis Model with Default Configuration

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/configuration.md

Instantiate the BeatThis model using its default hyperparameters. This configuration is equivalent to loading the 'final0' checkpoint.

```python
from beat_this.model.beat_tracker import BeatThis

# Default configuration (same as "final0" when loaded from checkpoint)
model = BeatThis()
```

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

### Head.__init__

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/beat-tracker-model.md

Initializes the Head, which produces independent beat and downbeat predictions.

```APIDOC
## Head.__init__

### Description
Initializes the Head, which produces independent beat and downbeat predictions using separate linear projections.

### Parameters
#### Path Parameters
- **input_dim** (int) - Yes - Dimension of input features from transformer
```

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

### Initialize BeatThis Model with Custom Configuration

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/configuration.md

Configure a BeatThis model with specific hyperparameters for transformer dimensions, layer count, attention head dimensions, and dropout rates.

```python
from beat_this.model.beat_tracker import BeatThis

# Custom configuration
model = BeatThis(
    transformer_dim=256,
    n_layers=4,
    head_dim=64,
    dropout={"frontend": 0.15, "transformer": 0.25},
)
```

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

### Import BeatThis Model Class

Source: https://github.com/cpjku/beat_this/blob/main/README.md

Imports the BeatThis model class directly from the installed package.

```python
from beat_this.model.beat_tracker import BeatThis
```

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

### Create and Use Padding Mask

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/types.md

Demonstrates how to create a padding mask for variable-length audio batches and use it with the Postprocessor. Ensure the mask correctly identifies valid frames (True) and padding (False).

```python
import torch
from beat_this.model.postprocessor import Postprocessor

postprocessor = Postprocessor(type="minimal")

# Variable-length batch: first item is 1500 frames, second is 1000
beat_logits = torch.randn(2, 1500)
downbeat_logits = torch.randn(2, 1500)

# Mask out padding in second item
padding_mask = torch.ones(2, 1500, dtype=torch.bool)
padding_mask[1, 1000:] = False

beats, downbeats = postprocessor(beat_logits, downbeat_logits, padding_mask)
```

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

### forward()

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/loss-functions.md

Computes the split shift-tolerant BCE loss, combining loss for positive and negative examples.

```APIDOC
## forward()

### Description
Computes the split shift-tolerant BCE loss, which is the sum of positive and negative loss components. This method is used during the training process.

### Method
forward

### Parameters
#### Path Parameters
- **preds** (torch.Tensor) - Required - Predicted logits.
- **targets** (torch.Tensor) - Required - Target binary labels.
- **mask** (torch.Tensor) - Required - Mask tensor, essential for loss computation.

### Returns
torch.Tensor – Sum of positive and negative loss components.

### Algorithm
1. Spread predictions by `spread_preds` (typically 3).
2. Spread targets by `spread_targets` (typically 2*tolerance=6).
3. Compute BCE loss for positive targets: loss_positive.
4. Compute BCE loss for negative targets: loss_negative.
5. Return: loss_positive + loss_negative.
```

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

### __init__()

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/loss-functions.md

Initializes the ShiftTolerantBCELoss class. Note: There is a known bug where tolerance is hardcoded; use ShiftTolerantBCELoss for correct behavior.

```APIDOC
## __init__()

### Description
Initializes the loss function with optional positive weight and tolerance for time shifts.

### Parameters
#### Path Parameters
- **pos_weight** (float) - Optional - Default: 1 - Weight for positive examples.
- **tolerance** (int) - Optional - Default: 3 - Tolerated shift in time steps.

### Note
There is a bug in the implementation: `self.tolerance = 3` is hardcoded instead of using the parameter. For correct behavior, use `ShiftTolerantBCELoss` instead.
```

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

### BeatTracker.__init__

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/beat-tracker-model.md

Initializes the BeatTracker model with specified dimensions, attention heads, and embedding configurations.

```APIDOC
## BeatTracker.__init__

### Description
Initializes the BeatTracker model with specified dimensions, attention heads, and embedding configurations.

### Parameters
#### Path Parameters
- **dim** (int) - Yes - Channel dimension (must be divisible by dim_head)
- **dim_head** (int) - Yes - Dimension of each attention head
- **n_head** (int) - Yes - Number of attention heads
- **direction** (str) - Yes - "F" for frequency direction, "T" for time direction
- **rotary_embed** (RotaryEmbedding) - Yes - Rotary position embedding instance
- **dropout** (float) - Yes - Dropout rate

### Raises
ValueError – If direction is not "F" or "T"
```

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

### Postprocessor Initialization

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/configuration.md

Instantiate the Postprocessor with either 'minimal' or 'dbn' type. The 'dbn' type requires the madmom package.

```python
from beat_this.model.postprocessor import Postprocessor

# Minimal (default)
pp = Postprocessor(type="minimal", fps=50)

# DBN (requires: pip install git+https://github.com/CPJKU/madmom.git)
pp = Postprocessor(type="dbn", fps=50)
```

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

### Get Beats and Downbeats from Audio File

Source: https://github.com/cpjku/beat_this/blob/main/README.md

Obtain a list of beats and downbeats for a given audio file using the instantiated File2Beats object.

```python
audio_path = "path/to/audio.file"
beats, downbeats = file2beats(audio_path)
```

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

### Postprocessor.__init__

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/postprocessor.md

Initializes the Postprocessor class. It allows selection between 'minimal' (peak picking) and 'dbn' (Dynamic Bayesian Network) postprocessing methods and sets the frames per second (fps) for the model's predictions.

```APIDOC
## Postprocessor.__init__

### Description
Initializes the Postprocessor class. It allows selection between 'minimal' (peak picking) and 'dbn' (Dynamic Bayesian Network) postprocessing methods and sets the frames per second (fps) for the model's predictions.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **type** (str) - Optional - Default: "minimal" - Postprocessing method: "minimal" (peak picking) or "dbn" (Dynamic Bayesian Network)
- **fps** (int) - Optional - Default: 50 - Frames per second of the model's framewise predictions

### Request Example
```python
from beat_this.model.postprocessor import Postprocessor

# Minimal postprocessing (faster, no dependencies)
minimal_pp = Postprocessor(type="minimal", fps=50)

# DBN postprocessing (requires madmom package)
# dbn_pp = Postprocessor(type="dbn", fps=50)
```

### Response
None

### Raises
AssertionError – If type is not "minimal" or "dbn"
```

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

### Loss for Imbalanced Datasets

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/loss-functions.md

To address imbalanced datasets where negative frames outweigh beat frames, increase the 'pos_weight' parameter to give more importance to beat examples.

```python
ShiftTolerantBCELoss(pos_weight=2.0)
```

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

### Process MP3 files with optimizations

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/cli-reference.md

Use this command to process all MP3 files in a directory with various optimizations and settings. It specifies input files, output directory, model, precision, GPU usage, file naming, and existing file handling.

```bash
beat_this /music/library/*.mp3 \
  -o /beat_output/ \
  --model final0 \
  --float16 \
  --gpu 0 \
  -s .beats \
  --skip-existing
```

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

### Beat This! Command Line Usage

Source: https://github.com/cpjku/beat_this/blob/main/README.md

Basic command line usage for predicting beats from an audio file. Supports multiple input files or directories and specifies output locations.

```bash
beat_this --help
```

```bash
beat_this path/to/audio.file -o path/to/output.beats
```

```bash
beat_this path/to/*.mp3 path/to/whole_directory/ -o path/to/output_directory
```

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

### Compute results with DBN on test set (Table 2)

Source: https://github.com/cpjku/beat_this/blob/main/README.md

Calculate results for the 'final' model configurations on the test set, including DBN. This requires the 'madmom' package to be installed.

```bash
python launch_scripts/compute_paper_metrics.py --models final0 final1 final2 --datasplit test --dbn
```

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

### Beat This CLI Basic Usage

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/configuration.md

Execute the beat detection tool with various options for input files, output paths, and processing parameters.

```bash
# Basic usage
beat_this song.mp3 -o song.beats

# Multiple files to directory
beat_this /path/to/*.mp3 -o /output/directory

# GPU with float16
beat_this song.mp3 -o song.beats --gpu=0 --float16

# DBN postprocessing
beat_this song.mp3 -o song.beats --dbn

# Save activations and beats
beat_this song.mp3 -o song.beats --activations

# Parallel processing on multiple GPUs
for gpu in {0..3}; do
  beat_this input_dir -o output_dir --gpu=$gpu --skip-existing --touch-first &
done
```

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

### Head Forward Pass Example

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/beat-tracker-model.md

Illustrates the forward pass of the Head. It accepts an input tensor of shape (batch, time, input_dim) and outputs a dictionary with beat and downbeat logits.

```python
from beat_this.model.beat_tracker import Head
import torch

head = Head(input_dim=512)
x = torch.randn(2, 1500, 512)

output = head(x)
beat_logits = output["beat"]         # shape: (2, 1500)
downbeat_logits = output["downbeat"] # shape: (2, 1500)
```

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

### Initialize File2Beats with Default Inference Settings

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/configuration.md

Instantiate the File2Beats class using default settings, which loads the 'final0' checkpoint and uses the CPU for inference.

```python
from beat_this.inference import File2Beats

# Default: final0 on CPU
file2beats = File2Beats()
```

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

### ShiftTolerantBCELoss Initialization

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/configuration.md

Configure the loss function with adjustable positive weight and temporal tolerance. Higher tolerance allows for more flexibility in beat alignment.

```python
from beat_this.model.loss import ShiftTolerantBCELoss

# Standard (matches training in paper)
loss = ShiftTolerantBCELoss(pos_weight=1.0, tolerance=3)

# For imbalanced data (many non-beat frames)
loss = ShiftTolerantBCELoss(pos_weight=2.0, tolerance=3)

# For stricter beat alignment
loss = ShiftTolerantBCELoss(pos_weight=1.0, tolerance=1)
```

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

### Enable DBN Postprocessing

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/cli-reference.md

Apply Dynamic Bayesian Network postprocessing for musically plausible beat patterns. This is slower than the default minimal peak-picking method.

```bash
beat_this song.mp3 -o song.beats --dbn
```

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

### Use smaller model to avoid out of memory

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/cli-reference.md

Run Beat This with a smaller model ('small0') to reduce memory usage and avoid out-of-memory errors.

```bash
beat_this song.mp3 -o song.beats --model small0
```

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

### Get Raw Beat and Downbeat Logits

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/README.md

Access framewise predictions (logits) from the model before postprocessing using the Audio2Frames inference class. Convert logits to probabilities using sigmoid activation. This provides detailed, raw output for further analysis or custom processing.

```python
from beat_this.inference import Audio2Frames
import torch

audio2frames = Audio2Frames(device="cuda")
beat_logits, downbeat_logits = audio2frames(signal, sr)

# Convert logits to probabilities
beat_probs = torch.sigmoid(beat_logits)
downbeat_probs = torch.sigmoid(downbeat_logits)
```

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

### Train Base Model

Source: https://github.com/cpjku/beat_this/blob/main/README.md

Launches training for the base Beat This model across multiple seeds.

```bash
for seed in 0 1 2; do
    python launch_scripts/train.py --seed=$seed
done
```

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

### Initialize File2Beats with DBN Postprocessing

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/configuration.md

Enable the use of madmom's DBN postprocessing by setting the 'dbn' parameter to True during File2Beats initialization. Requires the 'madmom' package.

```python
from beat_this.inference import File2Beats

# With DBN postprocessing
file2beats = File2Beats(checkpoint_path="final0", device="cuda", dbn=True)
```

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

### Initialize BeatThis Model with Smaller Configuration

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/configuration.md

Create a smaller BeatThis model by adjusting hyperparameters like transformer_dim. This results in a model size similar to the 'small0' checkpoint.

```python
from beat_this.model.beat_tracker import BeatThis

# Smaller model (8.1 MB, like "small0")
model = BeatThis(
    spect_dim=128,
    transformer_dim=128,  # smaller
    ff_mult=4,
    n_layers=6,
    head_dim=32,
    stem_dim=32,
)
```

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

### Python API Entry Points

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/MANIFEST.txt

This section outlines the primary Python classes and functions users can leverage for inference and audio processing tasks. It details core components like File2Beats, Audio2Beats, and utility functions for model loading and prediction.

```APIDOC
## Python API Entry Points

This section details the core Python classes and functions available for direct use.

### Classes

- **File2Beats**: Processes audio files for beat tracking.
- **Audio2Beats**: Handles beat tracking directly from audio data.
- **Audio2Frames**: Extracts audio features and frames.
- **Spect2Frames**: Processes spectrograms to extract frames.
- **File2File**: Handles file-based input and output for beat tracking.
- **BeatThis**: The main model class for beat tracking.
- **PartialFTTransformer**: A component of the BeatThis model.
- **PartialRoformer**: Another component of the BeatThis model.
- **SumHead**: A head component for the transformer.
- **Head**: A generic head component.
- **Postprocessor**: Handles the postprocessing of beat tracking results.
- **Transformer**: A general transformer module.
- **Attention**: An attention mechanism module.

### Functions

- **load_model**: Loads a pre-trained Beat This! model.
- **load_checkpoint**: Loads a model checkpoint.
- **split_predict_aggregate**: Performs batched inference and aggregates results.
- **save_beat_tsv**: Exports detected beats to a TSV file.
- **infer_beat_numbers**: Infers beat timestamps from model outputs.
- **deduplicate_peaks**: Removes redundant beat predictions.
- **load_audio**: Loads audio files for processing.
- **replace_state_dict_key**: Utility for modifying model state dictionaries.

For detailed signatures, parameters, and examples, refer to the module-specific documentation in the `api-reference/` directory.
```

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

### Configure GPU for Inference

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/cli-reference.md

Select the GPU device for inference. Use -1 to force CPU usage. Defaults to GPU 0 if CUDA is available.

```bash
beat_this song.mp3 -o song.beats --gpu 0
beat_this song.mp3 -o song.beats --gpu 1
beat_this song.mp3 -o song.beats --gpu -1  # CPU only
```

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

### Initialize File2Beats with a Smaller Model on a Specific GPU

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/configuration.md

Load a smaller model ('small0') for inference and specify a particular GPU (e.g., 'cuda:1') for execution.

```python
from beat_this.inference import File2Beats

# Smaller model
file2beats = File2Beats(checkpoint_path="small0", device="cuda:1")
```

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

### Instantiate File2Beats for Inference

Source: https://github.com/cpjku/beat_this/blob/main/README.md

Instantiate the File2Beats class for beat tracking. Specify the checkpoint path, device (e.g., 'cuda'), and whether to use DBN.

```python
from beat_this.inference import File2Beats
file2beats = File2Beats(checkpoint_path="final0", device="cuda", dbn=False)
```

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

### Initialize BeatTracker

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/beat-tracker-model.md

Initializes the BeatTracker model with specified dimensions, attention heads, and embedding configurations. Ensure the direction is either 'F' or 'T'.

```python
def __init__(
    self,
    dim: int,
    dim_head: int,
    n_head: int,
    direction: str,
    rotary_embed: RotaryEmbedding,
    dropout: float,
)
```

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

### ShiftTolerantBCELoss Initialization

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/loss-functions.md

Initializes the ShiftTolerantBCELoss with optional positive weight and tolerance for time step shifts. Note: There's a known bug where tolerance is hardcoded; use ShiftTolerantBCELoss for correct behavior.

```python
def __init__(self, pos_weight: float = 1, tolerance: int = 3)
```

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

### Run audio preprocessing script

Source: https://github.com/cpjku/beat_this/blob/main/README.md

Execute the script to convert audio files to spectrograms. This script creates intermediary files that are reused on subsequent runs.

```bash
python launch_scripts/preprocess_audio.py
```

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

### Use CPU for processing to avoid out of memory

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/cli-reference.md

Process audio using the CPU instead of the GPU to avoid out-of-memory errors. This is slower but uses system RAM.

```bash
beat_this song.mp3 -o song.beats --gpu -1
```

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

### Loading Model for Custom Pipelines

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/README.md

Load the model directly using `load_model` for integration into custom pipelines. Requires manual input preparation (e.g., spectrograms).

```python
from beat_this.inference import load_model
import torch

model = load_model("final0", device="cuda")
spect = torch.randn(1, 1500, 128)  # batch of 1, 30 seconds, 128 mel bins

with torch.no_grad():
    predictions = model(spect)
    # predictions["beat"] shape: (1, 1500)
    # predictions["downbeat"] shape: (1, 1500)
```

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

### Select Model for Inference

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/cli-reference.md

Specify the model checkpoint to use for beat detection. Supports default models, local files, and remote URLs.

```bash
beat_this song.mp3 -o song.beats --model final0
beat_this song.mp3 -o song.beats --model small0
beat_this song.mp3 -o song.beats --model ./custom_weights.ckpt
```

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

### BeatThis Model Initialization

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/beat-tracker-model.md

Initializes the BeatThis model with configurable parameters for spectrogram dimensions, transformer architecture, and dropout rates. The `sum_head` parameter determines whether to use a combined or independent head for beat and downbeat predictions.

```python
def __init__(
    self,
    spect_dim: int = 128,
    transformer_dim: int = 512,
    ff_mult: int = 4,
    n_layers: int = 6,
    head_dim: int = 32,
    stem_dim: int = 32,
    dropout: dict = {"frontend": 0.1, "transformer": 0.2},
    sum_head: bool = True,
    partial_transformers: bool = True,
)
```

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

### Initialize ShiftTolerantBCELoss

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/loss-functions.md

Instantiate ShiftTolerantBCELoss with specified positive weight and temporal tolerance. The tolerance parameter determines the allowed shift in time steps for matching predictions to targets.

```python
from beat_this.model.loss import ShiftTolerantBCELoss

# ±3 frame tolerance (~60ms at 50 fps)
loss_fn = ShiftTolerantBCELoss(pos_weight=1.0, tolerance=3)

# ±6 frame tolerance (~120ms at 50 fps)
loss_fn = ShiftTolerantBCELoss(pos_weight=2.0, tolerance=6)
```

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

### Initialize LogMelSpect Module

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/preprocessing.md

Creates an instance of the LogMelSpect module for converting audio waveforms to log-mel spectrograms. This module wraps torchaudio's MelSpectrogram transform and can be configured with various audio and spectrogram parameters. It's recommended to place the transform on the same device as your audio tensors.

```python
from beat_this.preprocessing import LogMelSpect, load_audio
import torch

# Create the log-mel spectrogram transform
mel_transform = LogMelSpect(
    sample_rate=22050,
    n_mels=128,
    device="cuda"
)

# Load audio and convert to spectrogram
waveform, sr = load_audio("song.mp3")

# Ensure waveform is on the correct device
waveform_tensor = torch.tensor(waveform, dtype=torch.float32, device="cuda")

# Get log-mel spectrogram
spectrogram = mel_transform(waveform_tensor)

print(f"Spectrogram shape: {spectrogram.shape}")  # (time, 128)
```

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

### Load Activations in Python

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/cli-reference.md

Load the saved raw activation logits from a .npy file into a NumPy array for further analysis in Python.

```python
import numpy as np

activations = np.load("song.npy")
beat_logits = activations[0]
downbeat_logits = activations[1]
```

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

### PartialFTTransformer Initialization

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/beat-tracker-model.md

Initializes the PartialFTTransformer module, which applies sequential self-attention and feed-forward operations across frequency and time dimensions. Requires specifying dimensions, attention heads, rotary embeddings, and dropout rate.

```python
def __init__(
    self,
    dim: int,
    dim_head: int,
    n_head: int,
    rotary_embed: RotaryEmbedding,
    dropout: float,
)
```

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

### load_audio()

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/preprocessing.md

Loads audio from a specified file path. It supports multiple backends for robust loading and returns the audio waveform and its sample rate.

```APIDOC
## load_audio()

### Description
Loads audio from a file using multiple backends for robustness.

### Method Signature
```python
def load_audio(path: str, dtype: str = "float64") -> tuple[np.ndarray, int]
```

### Parameters
#### Path Parameters
- **path** (str) - Required - Path to audio file
- **dtype** (str) - Optional - NumPy data type for the output waveform. Defaults to "float64".

### Returns
tuple[numpy.ndarray, int] – (waveform, sample_rate) where waveform is 1D array of audio samples

### Raises
RuntimeError – If audio cannot be loaded with torchaudio, soundfile, or madmom

### Example
```python
from beat_this.preprocessing import load_audio
import numpy as np

# Load audio
waveform, sr = load_audio("song.mp3")

print(f"Sample rate: {sr} Hz")
print(f"Duration: {len(waveform) / sr:.2f} seconds")
print(f"Data type: {waveform.dtype}")  # float64 by default
```
```

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

### Attend Initialization

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/transformer-backbone.md

Initializes the Attend module, allowing for custom dropout rates and scaling factors for attention weights.

```python
def __init__(self, dropout: float = 0.0, scale: float | None = None)
```

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

### Attend

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/transformer-backbone.md

Initializes the Attend module, implementing a scaled dot-product attention mechanism using PyTorch's optimized implementation. It supports dropout and custom scaling.

```APIDOC
## Attend

Scaled dot-product attention mechanism using PyTorch's efficient implementation.

### `__init__`
```python
def __init__(self, dropout: float = 0.0, scale: float | None = None)
```

#### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| dropout | float | No | 0.0 | Dropout rate for attention weights |
| scale | float | No | None | Custom scaling factor; if None, uses 1/sqrt(d_k) |

### `forward`
```python
def forward(
    self, q: torch.Tensor, k: torch.Tensor, v: torch.Tensor
) -> torch.Tensor
```

Compute scaled dot-product attention.

#### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| q | torch.Tensor | Yes | Query tensor of shape (..., seq_len, d_k) |
| k | torch.Tensor | Yes | Key tensor of shape (..., seq_len, d_k) |
| v | torch.Tensor | Yes | Value tensor of shape (..., seq_len, d_v) |

#### Returns

torch.Tensor – Attended values of shape (..., seq_len, d_v)

### Implementation

Uses `torch.nn.functional.scaled_dot_product_attention` which provides:
- Automatic kernel selection for efficiency
- Support for FlashAttention on compatible GPUs
- Dropout during training, disabled during inference
```

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

### Train main results models (Table 2)

Source: https://github.com/cpjku/beat_this/blob/main/README.md

Train the main system models (final0, final1, final2) for Table 2. This loop runs the training script for each seed.

```bash
for seed in 0 1 2; do
    python launch_scripts/train.py --seed=$seed --no-val
done
```

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

### Audio2Beats.__init__

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/inference.md

Initializes the Audio2Beats class, which is used for extracting beat and downbeat positions from audio signals with postprocessing.

```APIDOC
## Audio2Beats.__init__()

### Description
Initializes the Audio2Beats class for extracting beat and downbeat positions (in seconds) from an audio tensor. It includes postprocessing to convert framewise predictions to beat times.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **checkpoint_path** (str) - Optional - Default: "final0" - Model checkpoint name, path, or URL
- **device** (str or torch.device) - Optional - Default: "cpu" - Device for inference
- **float16** (bool) - Optional - Default: False - Use half-precision floating point arithmetic
- **dbn** (bool) - Optional - Default: False - Use madmom's DBN for post-processing instead of minimal postprocessing

### Returns
None

### Request Example
```python
from beat_this.inference import Audio2Beats

audio2beats = Audio2Beats(checkpoint_path="final0", device="cuda", dbn=False)
```

### Response
None

```

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

### Distribute Beat Tracking Load

Source: https://github.com/cpjku/beat_this/blob/main/README.md

Distribute the load over multiple processes for processing many files. Uses `--touch-first`, `--skip-existing`, and assigns different GPUs.

```bash
for gpu in {0..3}; do beat_this input_dir -o output_dir --touch-first --skip-existing --gpu=$gpu & done
```

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

### Initialize Attention Module

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/transformer-backbone.md

Instantiate the multi-head self-attention module. Configure dimension, heads, dimension per head, dropout, and rotary embeddings.

```python
def __init__(
    self,
    dim: int,
    heads: int = 8,
    dim_head: int = 64,
    dropout: float = 0.0,
    rotary_embed: RotaryEmbedding | None = None,
    gating: bool = True,
)
```

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

### Initialize SumHead

Source: https://github.com/cpjku/beat_this/blob/main/_autodocs/api-reference/beat-tracker-model.md

Initializes the SumHead, which produces beat and downbeat predictions. Requires the input feature dimension from the transformer.

```python
def __init__(self, input_dim: int)
```