### Create and Activate Conda Environment

Source: https://github.com/gabrielmittag/nisqa/blob/master/README.md

Installs project requirements using a provided environment file and activates the created Conda environment named 'nisqa'.

```bash
conda env create -f env.yml
```

```bash
conda activate nisqa
```

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

### Start Finetuning NISQA Model

Source: https://github.com/gabrielmittag/nisqa/blob/master/README.md

Use this command to finetune the model on a new dataset using a specified YAML configuration file. Ensure the YAML file is correctly configured with dataset paths and model parameters.

```bash
python run_train.py --yaml config/finetune_nisqa.yaml
```

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

### Minimal Finetune NISQA YAML Configuration

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Example YAML configuration for finetuning NISQA on a custom dataset. Key parameters include data paths, output directories, and CSV file mappings.

```yaml
name: my_finetune_run
data_dir: /data/my_dataset          # folder containing CSV and WAV files
output_dir: /data/trained_models    # output folder for weights and results CSV
pretrained_model: weights/nisqa_mos_only.tar

csv_file: my_dataset.csv            # must contain columns: db, filepath_deg, mos
csv_con: null
csv_deg: filepath_deg
csv_mos_train: mos
csv_mos_val: mos
csv_db_train:
  - MY_TRAIN_SET
csv_db_val:
  - MY_VAL_SET

tr_epochs: 500
tr_early_stop: 20
tr_bs: 40
tr_bs_val: 40
tr_lr: 0.001
tr_lr_patience: 15
tr_num_workers: 4
tr_parallel: True
tr_ds_to_memory: False
tr_ds_to_memory_workers: 0
tr_device: null
tr_checkpoint: best_only
tr_verbose: 2
ms_max_segments: 1300
ms_channel: null
tr_bias_mapping: null
tr_bias_min_r: null
tr_bias_anchor_db: null

```

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

### Start Training NISQA Model

Source: https://github.com/gabrielmittag/nisqa/blob/master/README.md

Initiate training of a new speech quality model using a specific configuration. The command requires a YAML file that defines the model architecture and training parameters.

```bash
python run_train.py --yaml config/train_nisqa_cnn_sa_ap.yaml
```

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

### Evaluate Trained NISQA Model

Source: https://github.com/gabrielmittag/nisqa/blob/master/README.md

Run the evaluation script for trained speech quality models. Before execution, update the paths and options within the `run_evaluate.py` script itself. This can also serve as a conformance test for the model installation.

```bash
python run_evaluate.py
```

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

### Download and Unzip NISQA Corpus (Bash)

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Download the NISQA Corpus using wget and unzip it to a specified directory. Ensure sufficient disk space as the corpus is several gigabytes.

```bash
# Download the corpus (~several GB)
wget https://depositonce.tu-berlin.de/bitstream/11303/13012.5/9/NISQA_Corpus.zip
# Mirror: https://zenodo.org/record/4728081/files/NISQA_Corpus.zip
unzip NISQA_Corpus.zip -d /data/NISQA_Corpus
```

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

### Train New NISQA Model from Scratch

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Execute the training script using the configuration for training a new NISQA model with the CNN-SA-AP architecture. Update paths in the YAML file.

```bash
# Update data_dir and output_dir in the YAML, then run:
python run_train.py --yaml config/train_nisqa_cnn_sa_ap.yaml
```

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

### Programmatic Speech Quality Prediction with nisqaModel

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Demonstrates programmatic usage of the nisqaModel class for predicting speech quality from a single file. Requires model weights and input file path.

```python
from nisqa.NISQA_model import nisqaModel

# Programmatic usage: predict a single file
args = {
    'mode': 'predict_file',
    'pretrained_model': 'weights/nisqa.tar',
    'deg': '/data/speech/call_sample.wav',
    'output_dir': '/data/results',
    'tr_bs_val': 1,
    'tr_num_workers': 0,
    'ms_channel': None,
}

nisqa = nisqaModel(args)
df = nisqa.predict()
# df contains columns: deg, mos_pred, noi_pred, col_pred, dis_pred, loud_pred
print(df[['deg', 'mos_pred', 'noi_pred', 'col_pred', 'dis_pred', 'loud_pred']])
# Example output:
#              deg  mos_pred  noi_pred  col_pred  dis_pred  loud_pred
# 0  call_sample.wav      3.72      3.85      4.10      4.56       3.90
```

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

### Training Loop with nisqaModel

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Initiate the NISQA model training loop using `train()`. This method handles the optimizer, learning rate scheduling, early stopping, and checkpointing based on the provided arguments.

```python
import yaml
from nisqa.NISQA_model import nisqaModel

with open('config/finetune_nisqa.yaml', 'r') as f:
    args = yaml.load(f, Loader=yaml.FullLoader)

nisqa = nisqaModel(args)
nisqa.train()
# Training progress printed each epoch, e.g.:
# ep 1 sec 42 es 0 lr 1e-03 loss 0.8431 // r_p_tr 0.61 rmse_map_tr 0.52 // r_p 0.72 rmse_map 0.41 // best_r_p 0.72 best_rmse_map 0.41,
# --> Early stopping. best_r_p 0.91 best_rmse 0.22

```

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

### Train a new NISQA model from scratch

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Instructions for training a new NISQA model from scratch using the CNN-SA-AP architecture. This involves updating specific parameters in a YAML configuration file.

```APIDOC
## Train a new NISQA model from scratch (CNN-SA-AP architecture)

```bash
# Update data_dir and output_dir in the YAML, then run:
python run_train.py --yaml config/train_nisqa_cnn_sa_ap.yaml
```

Key architecture parameters in the YAML:

```yaml
model: NISQA          # NISQA | NISQA_DIM | NISQA_DE
cnn_model: adapt      # adapt | standard | dff | skip
td: self_att          # self_att | lstm
pool: att             # att | avg | max | last_step | last_step_bi
```
```

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

### Command-Line Inference for Directory of WAV Files

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Processes all WAV files within a specified directory using `run_predict.py` for speech quality prediction.

```bash
python run_predict.py \
  --mode predict_dir \
  --pretrained_model weights/nisqa.tar \
  --data_dir /data/speech/calls/ \
  --num_workers 4 \
  --bs 20 \
  --output_dir /data/results
```

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

### Predict Quality of All WAV Files in a Directory

Source: https://github.com/gabrielmittag/nisqa/blob/master/README.md

Predicts quality for all .wav files within a specified directory using the NISQA model. Allows configuration of workers and batch size for performance.

```bash
python run_predict.py --mode predict_dir --pretrained_model weights/nisqa.tar --data_dir /path/to/folder/with/wavs --num_workers 0 --bs 10 --output_dir /path/to/dir/with/results
```

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

### Finetune pretrained NISQA on a custom dataset

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

This section describes how to finetune a pretrained NISQA model on a custom dataset using a YAML configuration file. Key parameters like data directories, CSV files, and model paths need to be updated.

```APIDOC
## Finetune pretrained NISQA on a custom dataset

All options are controlled via a YAML file. Update `data_dir`, `output_dir`, `pretrained_model`, `csv_file`, `csv_deg`, `csv_mos_train`, `csv_mos_val`, `csv_db_train`, and `csv_db_val` before running.

```bash
python run_train.py --yaml config/finetune_nisqa.yaml
```

Minimal `finetune_nisqa.yaml` for a custom dataset:

```yaml
name: my_finetune_run
data_dir: /data/my_dataset          # folder containing CSV and WAV files
output_dir: /data/trained_models    # output folder for weights and results CSV
pretrained_model: weights/nisqa_mos_only.tar

csv_file: my_dataset.csv            # must contain columns: db, filepath_deg, mos
csv_con: null
csv_deg: filepath_deg
csv_mos_train: mos
csv_mos_val: mos
csv_db_train:
  - MY_TRAIN_SET
csv_db_val:
  - MY_VAL_SET

tr_epochs: 500
tr_early_stop: 20
tr_bs: 40
tr_bs_val: 40
tr_lr: 0.001
tr_lr_patience: 15
tr_num_workers: 4
tr_parallel: True
tr_ds_to_memory: False
tr_ds_to_memory_workers: 0
tr_device: null
tr_checkpoint: best_only
tr_verbose: 2
ms_max_segments: 1300
ms_channel: null
tr_bias_mapping: null
tr_bias_min_r: null
tr_bias_anchor_db: null
```
```

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

### run_predict.py - Predict Directory

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Command-line interface for predicting speech quality for all `.wav` files within a specified directory. Allows configuration of batch size and number of workers for efficient processing.

```APIDOC
## python run_predict.py --mode predict_dir

### Description
This command-line script processes all `.wav` files located in a specified directory to predict their speech quality. It supports parallel processing through the `--num_workers` argument and allows for batch processing via the `--bs` argument, making it suitable for large datasets.

### Method
```bash
python run_predict.py \
  --mode predict_dir \
  --pretrained_model weights/nisqa.tar \
  --data_dir /data/speech/calls/ \
  --num_workers 4 \
  --bs 20 \
  --output_dir /data/results
```

### Parameters
#### Command-line Arguments
- `--mode` (str): Specifies the operation mode. Set to `predict_dir` for directory-based prediction.
- `--pretrained_model` (str): Path to the pre-trained model weights file.
- `--data_dir` (str): Path to the directory containing the `.wav` files to be processed.
- `--num_workers` (int): Number of worker processes to use for parallel data loading and processing.
- `--bs` (int): Batch size for processing audio files.
- `--output_dir` (str): Directory where the prediction results will be saved.

### Request Example
```bash
python run_predict.py \
  --mode predict_dir \
  --pretrained_model weights/nisqa.tar \
  --data_dir /data/speech/calls/ \
  --num_workers 4 \
  --bs 20 \
  --output_dir /data/results
```
```

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

### Run NISQA Corpus Evaluation (Python)

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Execute the standard evaluation script for the NISQA Corpus. Update data_dir and output_dir in run_evaluate.py before running. Expected output metrics are provided.

```python
# Run the standard evaluation on the corpus (conformance test)
# Update data_dir and output_dir in run_evaluate.py, then:
python run_evaluate.py
# Expected output (per-condition, after first-order mapping):
# r_p_mean_con: ~0.93, rmse_star_map_mean_con: ~0.16
```

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

### Predict Quality of a Single WAV File

Source: https://github.com/gabrielmittag/nisqa/blob/master/README.md

Uses the NISQA model to predict the quality of a single .wav file. Specify the pretrained model, input file path, and output directory.

```bash
python run_predict.py --mode predict_file --pretrained_model weights/nisqa.tar --deg /path/to/wav/file.wav --output_dir /path/to/dir/with/results
```

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

### Train Double-Ended NISQA Model

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Run the training script for a double-ended (full-reference) NISQA model. This requires specifying `csv_ref` and double-ended fusion parameters in the YAML.

```bash
python run_train.py --yaml config/train_nisqa_double_ended.yaml
```

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

### Train Multidimensional NISQA Model

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Execute the training script for a multidimensional NISQA model. The CSV file must include columns for MOS, noisiness, coloration, discontinuity, and loudness.

```bash
python run_train.py --yaml config/finetune_nisqa_multidimensional.yaml
```

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

### NISQA Architecture Configuration Options (YAML)

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Configure NISQA model architecture, including CNN framewise model, time-dependency model (self-attention or LSTM), and pooling strategy. Options cover layer outputs, kernel sizes, dropout rates, and attention parameters.

```yaml
model: NISQA          # NISQA | NISQA_DIM | NISQA_DE

# CNN framewise model
cnn_model: adapt      # adapt | standard | dff | skip
cnn_c_out_1: 16
cnn_c_out_2: 32
cnn_c_out_3: 64
cnn_kernel_size: !!python/tuple [3,3]
cnn_dropout: 0.2
cnn_fc_out_h: null
cnn_pool_1: [24,7]
cnn_pool_2: [12,5]
cnn_pool_3: [6,3]

# Time-dependency model
td: self_att          # self_att | lstm
td_sa_d_model: 64
td_sa_nhead: 1
td_sa_pos_enc: False
td_sa_num_layers: 2
td_sa_h: 64
td_sa_dropout: 0.1

# Pooling
pool: att             # att | avg | max | last_step | last_step_bi
pool_att_h: 128
pool_att_dropout: 0
```

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

### run_predict.py - Stereo File Channel Selection

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Command-line interface for predicting speech quality on stereo audio files, allowing selection of a specific channel (left or right) for analysis.

```APIDOC
## python run_predict.py --ms_channel

### Description
When processing stereo audio files, this option allows the user to specify which channel should be used for speech quality assessment. This is useful for analyzing individual channels of a stereo recording independently.

### Method
```bash
python run_predict.py \
  --mode predict_file \
  --pretrained_model weights/nisqa.tar \
  --deg /data/stereo_call.wav \
  --ms_channel 0 \
  --output_dir /data/results
```

### Parameters
#### Command-line Arguments
- `--mode` (str): Set to `predict_file`.
- `--pretrained_model` (str): Path to the pre-trained model weights file.
- `--deg` (str): Path to the input stereo `.wav` audio file.
- `--ms_channel` (int): Specifies the channel to process. Use `0` for the left channel and `1` for the right channel.
- `--output_dir` (str): Directory to save the results.

### Request Example
```bash
python run_predict.py \
  --mode predict_file \
  --pretrained_model weights/nisqa.tar \
  --deg /data/stereo_call.wav \
  --ms_channel 0 \
  --output_dir /data/results
```

### Response
Prediction results for the selected audio channel will be saved to the specified `--output_dir`.
```

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

### `nisqaModel.train()` – Training Loop

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

This method executes the full training loop, including Adam optimizer, learning rate scheduling, early stopping, and optional bias loss. Checkpoints are managed based on the `tr_checkpoint` setting.

```APIDOC
## `nisqaModel.train()` – Training Loop

Runs the full training loop with Adam optimiser, learning rate scheduler (ReduceLROnPlateau), early stopping, and optional bias loss. Checkpoints are saved according to the `tr_checkpoint` setting.

```python
import yaml
from nisqa.NISQA_model import nisqaModel

with open('config/finetune_nisqa.yaml', 'r') as f:
    args = yaml.load(f, Loader=yaml.FullLoader)

nisqa = nisqaModel(args)
nisqa.train()
# Training progress printed each epoch, e.g.:
# ep 1 sec 42 es 0 lr 1e-03 loss 0.8431 // r_p_tr 0.61 rmse_map_tr 0.52 // r_p 0.72 rmse_map 0.41 // best_r_p 0.72 best_rmse_map 0.41,
# --> Early stopping. best_r_p 0.91 best_rmse 0.22
```
```

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

### Train a double-ended (full-reference) model

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Guidance on training a double-ended NISQA model, which requires a `csv_ref` column for reference file paths and specific fusion parameters.

```APIDOC
## Train a double-ended (full-reference) model

```bash
python run_train.py --yaml config/train_nisqa_double_ended.yaml
```

The double-ended YAML additionally requires a `csv_ref` column (reference file paths) and double-ended fusion parameters:

```yaml
model: NISQA_DE
csv_ref: filepath_ref
de_align: cosine       # bahd | luong | dot | cosine | distance | none
de_align_apply: hard   # soft | hard
de_fuse: "x/y/-"       # x/y/- | +/- | x/y
de_fuse_dim: null
td_2: self_att         # second time-dependency stage for DE model
```
```

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

### nisqaModel - Predict Single File

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Programmatic usage of the `nisqaModel` class to predict the quality of a single audio file. It handles model initialization, loading, and prediction, returning a DataFrame with quality scores.

```APIDOC
## nisqaModel.predict()

### Description
Predicts speech quality for a single audio file using the `nisqaModel` class. This method handles model loading and inference, returning a pandas DataFrame containing various quality assessment scores.

### Method
```python
from nisqa.NISQA_model import nisqaModel

args = {
    'mode': 'predict_file',
    'pretrained_model': 'weights/nisqa.tar',
    'deg': '/data/speech/call_sample.wav',
    'output_dir': '/data/results',
    'tr_bs_val': 1,
    'tr_num_workers': 0,
    'ms_channel': None,
}

nisqa = nisqaModel(args)
df = nisqa.predict()
print(df[['deg', 'mos_pred', 'noi_pred', 'col_pred', 'dis_pred', 'loud_pred']])
```

### Parameters
- **args** (dict): A dictionary containing configuration parameters for the model and prediction process. Key parameters include:
  - `mode` (str): Set to 'predict_file' for single file prediction.
  - `pretrained_model` (str): Path to the pre-trained model weights file (e.g., 'weights/nisqa.tar').
  - `deg` (str): Path to the input audio file to be assessed.
  - `output_dir` (str): Directory to save output results.
  - `tr_bs_val` (int): Batch size for validation during training (used here for consistency, typically 1 for prediction).
  - `tr_num_workers` (int): Number of worker processes for data loading (typically 0 for single file prediction).
  - `ms_channel` (int or None): For stereo files, specifies the channel to use (0 for left, 1 for right). `None` processes both or defaults to mono.

### Response
- **df** (pandas.DataFrame): A DataFrame containing the prediction results. Columns typically include:
  - `deg` (str): The path to the input audio file.
  - `mos_pred` (float): Predicted Mean Opinion Score.
  - `noi_pred` (float): Predicted noisiness score.
  - `col_pred` (float): Predicted coloration score.
  - `dis_pred` (float): Predicted discontinuity score.
  - `loud_pred` (float): Predicted loudness score.

### Request Example
```python
args = {
    'mode': 'predict_file',
    'pretrained_model': 'weights/nisqa.tar',
    'deg': '/data/speech/call_sample.wav',
    'output_dir': '/data/results',
    'tr_bs_val': 1,
    'tr_num_workers': 0,
    'ms_channel': None,
}
nisqa = nisqaModel(args)
df = nisqa.predict()
```

### Response Example
```
              deg  mos_pred  noi_pred  col_pred  dis_pred  loud_pred
0  call_sample.wav      3.72      3.85      4.10      4.56       3.90
```
```

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

### run_predict.py - Predict Single File

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Command-line interface for predicting the quality of a single `.wav` file using a specified pre-trained model. Outputs scores to the console and an optional CSV file.

```APIDOC
## python run_predict.py --mode predict_file

### Description
This command-line script performs non-intrusive speech quality assessment on a single `.wav` file. It loads a specified pre-trained model and outputs detailed quality scores, including MOS, noisiness, coloration, discontinuity, and loudness, to both the console and a CSV file in the specified output directory.

### Method
```bash
python run_predict.py \
  --mode predict_file \
  --pretrained_model weights/nisqa.tar \
  --deg /data/speech/sample.wav \
  --output_dir /data/results
```

### Parameters
#### Command-line Arguments
- `--mode` (str): Specifies the operation mode. Set to `predict_file` for single file prediction.
- `--pretrained_model` (str): Path to the pre-trained model weights file (e.g., `weights/nisqa.tar`).
- `--deg` (str): Path to the input `.wav` audio file for quality assessment.
- `--output_dir` (str): Directory where the prediction results (e.g., CSV file) will be saved.

### Request Example
```bash
python run_predict.py \
  --mode predict_file \
  --pretrained_model weights/nisqa.tar \
  --deg /data/speech/sample.wav \
  --output_dir /data/results
```

### Response
#### Console Output Example
```
         deg  mos_pred  noi_pred  col_pred  dis_pred  loud_pred  model
sample.wav      3.54      3.80      4.05      4.60      3.77  nisqa
```
#### File Output
Results are saved to a CSV file named `NISQA_results.csv` in the specified `--output_dir`.
```

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

### Train a multidimensional model

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Instructions for training a multidimensional NISQA model that predicts MOS, Noisiness, Coloration, Discontinuity, and Loudness. The CSV file must contain corresponding columns.

```APIDOC
## Train a multidimensional model (MOS + Noisiness + Coloration + Discontinuity + Loudness)

```bash
python run_train.py --yaml config/finetune_nisqa_multidimensional.yaml
```

The multidimensional CSV must contain columns `mos`, `noi`, `dis`, `col`, `loud` alongside `db` and `filepath_deg`.
```

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

### Command-Line Inference for Single WAV File Quality

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Uses `run_predict.py` to predict speech quality for a single WAV file. Outputs scores to console and optionally saves to a CSV file.

```bash
python run_predict.py \
  --mode predict_file \
  --pretrained_model weights/nisqa.tar \
  --deg /data/speech/sample.wav \
  --output_dir /data/results
# Console output:
#          deg  mos_pred  noi_pred  col_pred  dis_pred  loud_pred  model
# sample.wav      3.54      3.80      4.05      4.60      3.77  nisqa
# Results saved to /data/results/NISQA_results.csv
```

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

### run_predict.py - Predict CSV

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Command-line interface for predicting speech quality based on a list of audio files specified in a CSV file. Requires specifying the column containing file paths.

```APIDOC
## python run_predict.py --mode predict_csv

### Description
This script predicts speech quality for audio files listed in a CSV file. The CSV must contain a column that specifies the paths to the audio files, which are relative to the `--data_dir`. This allows for flexible input management and batch processing of audio files.

### Method
```bash
# files.csv contains a column 'filepath_deg' with relative paths to .wav files
python run_predict.py \
  --mode predict_csv \
  --pretrained_model weights/nisqa.tar \
  --data_dir /data/speech/ \
  --csv_file files.csv \
  --csv_deg filepath_deg \
  --num_workers 4 \
  --bs 40 \
  --output_dir /data/results
```

### Parameters
#### Command-line Arguments
- `--mode` (str): Specifies the operation mode. Set to `predict_csv` for CSV-based prediction.
- `--pretrained_model` (str): Path to the pre-trained model weights file.
- `--data_dir` (str): Base directory for locating the audio files specified in the CSV.
- `--csv_file` (str): Path to the CSV file containing the list of audio files.
- `--csv_deg` (str): The name of the column in the CSV file that contains the relative paths to the audio files.
- `--num_workers` (int): Number of worker processes for parallel data loading.
- `--bs` (int): Batch size for processing audio files.
- `--output_dir` (str): Directory where the prediction results will be saved.

### Request Example
```bash
# files.csv contains a column 'filepath_deg' with relative paths to .wav files
python run_predict.py \
  --mode predict_csv \
  --pretrained_model weights/nisqa.tar \
  --data_dir /data/speech/ \
  --csv_file files.csv \
  --csv_deg filepath_deg \
  --num_workers 4 \
  --bs 40 \
  --output_dir /data/results
```
```

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

### Mel-Spectrogram Configuration Options (YAML)

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Configure Mel-Spectrogram parameters for audio feature extraction. Options control resampling, frequency limits, FFT windowing, Mel bands, segment length, and channel selection.

```yaml
ms_sr: null           # resample to this sample rate (null = keep original)
ms_fmax: 20000        # maximum Mel-band frequency in Hz (20000 for fullband)
ms_n_fft: 4096        # FFT window length in bins
ms_hop_length: 0.01   # FFT hop in seconds
ms_win_length: 0.02   # FFT window in seconds (zero-padded to ms_n_fft)
ms_n_mels: 48         # number of Mel bands
ms_seg_length: 15     # Mel-spec segment width in bins (~40ms per bin)
ms_seg_hop_length: 4  # segment hop in bins
ms_max_segments: 1300 # max segments (1300 * 40ms = 52 sec max duration)
ms_channel: null      # stereo channel: 0=left, 1=right, null=mono mix
```

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

### NISQA CNN-SA-AP Architecture Parameters

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Key architecture parameters for training a NISQA model from scratch. Select the desired model type, CNN backbone, time-dependency method, and pooling strategy.

```yaml
model: NISQA          # NISQA | NISQA_DIM | NISQA_DE
cnn_model: adapt      # adapt | standard | dff | skip
td: self_att          # self_att | lstm
pool: att             # att | avg | max | last_step | last_step_bi

```

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

### Command-Line Inference from CSV File List

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Predicts speech quality for WAV files listed in a CSV file. Requires specifying the CSV file and the column containing file paths.

```bash
# files.csv contains a column 'filepath_deg' with relative paths to .wav files
python run_predict.py \
  --mode predict_csv \
  --pretrained_model weights/nisqa.tar \
  --data_dir /data/speech/ \
  --csv_file files.csv \
  --csv_deg filepath_deg \
  --num_workers 4 \
  --bs 40 \
  --output_dir /data/results
```

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

### Command-Line Inference for TTS Naturalness Prediction

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Uses `run_predict.py` with the `nisqa_tts.tar` model to predict the naturalness of synthesized speech.

```bash
python run_predict.py \
  --mode predict_file \
  --pretrained_model weights/nisqa_tts.tar \
  --deg /data/tts/synthesized_utterance.wav \
  --output_dir /data/results
# Output column is 'noi_pred' mapped to naturalness score
```

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

### Command-Line Inference with Stereo Channel Selection

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Specifies which channel (left or right) of a stereo audio file to use for prediction using the `--ms_channel` argument.

```bash
python run_predict.py \
  --mode predict_file \
  --pretrained_model weights/nisqa.tar \
  --deg /data/stereo_call.wav \
  --ms_channel 0 \
  --output_dir /data/results
# --ms_channel 0 selects the left channel; 1 selects the right channel
```

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

### Model Evaluation with nisqaModel

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Evaluate the NISQA model's performance using `evaluate()`. This computes PCC and RMSE, with options for polynomial mapping and plotting correlation diagrams.

```python
from nisqa.NISQA_model import nisqaModel

args = {
    'mode': 'predict_csv',
    'pretrained_model': 'weights/nisqa.tar',
    'data_dir': '/data/NISQA_Corpus',
    'output_dir': '/data/NISQA_Corpus',
    'csv_file': 'NISQA_corpus_file.csv',
    'csv_con': 'NISQA_corpus_con.csv',   # per-condition CSV (optional)
    'csv_deg': 'filepath_deg',
    'csv_mos_val': 'mos',
    'tr_num_workers': 6,
    'tr_bs_val': 40,
    'ms_channel': None,
}

nisqa = nisqaModel(args)
nisqa.predict()
nisqa.evaluate(
    mapping='first_order',  # apply first-order polynomial mapping before RMSE
    do_print=True,
    do_plot=True            # generates scatter plots of predicted vs. actual MOS
)
# Console output example:
# --> MOS:
# r_p_mean_con: 0.93, rmse_mean_con: 0.18, rmse_star_map_mean_con: 0.16

```

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

### Programmatic Prediction with nisqaModel

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Use the `nisqaModel` class to perform batch predictions on files listed in a CSV. Results are returned as a pandas DataFrame and optionally saved to a CSV file.

```python
from nisqa.NISQA_model import nisqaModel

# Predict all files listed in a CSV (batch mode)
args = {
    'mode': 'predict_csv',
    'pretrained_model': 'weights/nisqa.tar',
    'data_dir': '/data/speech/',
    'csv_file': 'test_files.csv',   # columns: db, filepath_deg
    'csv_deg': 'filepath_deg',
    'output_dir': '/data/results',
    'tr_bs_val': 40,
    'tr_num_workers': 4,
    'ms_channel': None,
}

nisqa = nisqaModel(args)
df = nisqa.predict()

# Access results
print(df[['filepath_deg', 'mos_pred', 'noi_pred', 'col_pred', 'dis_pred', 'loud_pred']])
# MOS scores are on a 1–5 scale; higher is better

```

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

### Double-Ended NISQA Model Configuration

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

YAML configuration for a double-ended NISQA model. Includes `csv_ref` for reference file paths and parameters for alignment and fusion.

```yaml
model: NISQA_DE
csv_ref: filepath_ref
de_align: cosine       # bahd | luong | dot | cosine | distance | none
de_align_apply: hard   # soft | hard
de_fuse: "x/y/-"       # x/y/- | +/- | x/y
de_fuse_dim: null
td_2: self_att         # second time-dependency stage for DE model

```

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

### run_predict.py - Predict TTS Naturalness

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

Command-line interface for predicting the naturalness of synthetic speech generated by TTS or Voice Conversion systems. Uses a specific pre-trained model (`nisqa_tts.tar`).

```APIDOC
## python run_predict.py --mode predict_file (TTS)

### Description
This command-line usage of `run_predict.py` is specifically for evaluating the naturalness of synthetic speech. It utilizes the `nisqa_tts.tar` pre-trained model, and the output is interpreted as a naturalness score, typically mapped to the 'noi_pred' column.

### Method
```bash
python run_predict.py \
  --mode predict_file \
  --pretrained_model weights/nisqa_tts.tar \
  --deg /data/tts/synthesized_utterance.wav \
  --output_dir /data/results
```

### Parameters
#### Command-line Arguments
- `--mode` (str): Set to `predict_file`.
- `--pretrained_model` (str): Path to the TTS-specific pre-trained model weights, `weights/nisqa_tts.tar`.
- `--deg` (str): Path to the synthesized `.wav` audio file.
- `--output_dir` (str): Directory to save the results.

### Request Example
```bash
python run_predict.py \
  --mode predict_file \
  --pretrained_model weights/nisqa_tts.tar \
  --deg /data/tts/synthesized_utterance.wav \
  --output_dir /data/results
```

### Response
The output will contain a `noi_pred` column representing the naturalness score of the synthetic speech.
```

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

### `nisqaModel.evaluate()` – Model Evaluation

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

This method computes evaluation metrics such as PCC and RMSE between predictions and ground-truth MOS labels. It supports optional polynomial mapping and plotting of correlation diagrams.

```APIDOC
## `nisqaModel.evaluate()` – Model Evaluation

Computes Pearson Correlation Coefficient (PCC) and RMSE between predictions and ground-truth MOS labels. Optionally applies first-order polynomial mapping and plots correlation diagrams.

```python
from nisqa.NISQA_model import nisqaModel

args = {
    'mode': 'predict_csv',
    'pretrained_model': 'weights/nisqa.tar',
    'data_dir': '/data/NISQA_Corpus',
    'output_dir': '/data/NISQA_Corpus',
    'csv_file': 'NISQA_corpus_file.csv',
    'csv_con': 'NISQA_corpus_con.csv',   # per-condition CSV (optional)
    'csv_deg': 'filepath_deg',
    'csv_mos_val': 'mos',
    'tr_num_workers': 6,
    'tr_bs_val': 40,
    'ms_channel': None,
}

nisqa = nisqaModel(args)
nisqa.predict()
nisqa.evaluate(
    mapping='first_order',  # apply first-order polynomial mapping before RMSE
    do_print=True,
    do_plot=True            # generates scatter plots of predicted vs. actual MOS
)
# Console output example:
# --> MOS:
# r_p_mean_con: 0.93, rmse_mean_con: 0.18, rmse_star_map_mean_con: 0.16
```
```

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

### `nisqaModel.predict()` – Programmatic Prediction

Source: https://context7.com/gabrielmittag/nisqa/llms.txt

This method performs prediction on files listed in a CSV. It returns a pandas DataFrame with predictions and optionally writes results to a CSV file.

```APIDOC
## `nisqaModel.predict()` – Programmatic Prediction

Returns a pandas DataFrame with per-file predictions; also writes `NISQA_results.csv` to `output_dir` if set.

```python
from nisqa.NISQA_model import nisqaModel

# Predict all files listed in a CSV (batch mode)
args = {
    'mode': 'predict_csv',
    'pretrained_model': 'weights/nisqa.tar',
    'data_dir': '/data/speech/',
    'csv_file': 'test_files.csv',   # columns: db, filepath_deg
    'csv_deg': 'filepath_deg',
    'output_dir': '/data/results',
    'tr_bs_val': 40,
    'tr_num_workers': 4,
    'ms_channel': None,
}

nisqa = nisqaModel(args)
df = nisqa.predict()

# Access results
print(df[['filepath_deg', 'mos_pred', 'noi_pred', 'col_pred', 'dis_pred', 'loud_pred']])
# MOS scores are on a 1–5 scale; higher is better
```
```

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

### Predict Quality from a CSV File

Source: https://github.com/gabrielmittag/nisqa/blob/master/README.md

Predicts speech quality for files listed in a CSV table. Requires specifying the CSV file path, the column containing file paths, and the output directory.

```bash
python run_predict.py --mode predict_csv --pretrained_model weights/nisqa.tar --csv_file files.csv --csv_deg column_name_of_filepaths --num_workers 0 --bs 10 --output_dir /path/to/dir/with/results
```

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