Metadata-Version: 2.4
Name: wavetable
Version: 0.1.2
Summary: A Python library to log audio files and their spectrograms into a single HTML file for easy inspection.
Author: Bernardo Torres
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: soundfile
Requires-Dist: matplotlib
Requires-Dist: librosa
Requires-Dist: jinja2
Requires-Dist: pandas

# wavetable

A Python library for generating organized HTML tables of audio samples, waveforms, and spectrograms. wavetable allows you to compare "Generated" vs "Ground Truth" audio directly in your browser or Jupyter Notebook with zero-dependency static HTML output.

## Features

- **Static HTML Output:** Generates self-contained (embedded) or lightweight (linked assets) HTML files.
- **Visualizations:** Automatic Waveform and Spectrogram (STFT or Mel) display.
- **Comparisons:** Native support for overlaying Ground Truth waveforms and displaying reference audio.
- **Customizable:** Control colormaps, frequency scales (Log/Mel/Linear), and magnitude scaling (dB/Linear).

## Installation

```bash
pip install wavetable # if using pip
poetry add wavetable # if using poetry
...
```

## Quick Start

```python
import numpy as np
from wavetable import AudioLogger

# 1. Initialize
logger = AudioLogger(name="my_experiment",
                     sr=44100,
                     root_dir="audio_logs",
                     save_mode="embed" # or "link"
                    )

# 2. Create Dummy Audio
audio_gen = np.sin(2 * np.pi * 440 * np.linspace(0, 2, 44100*2))
audio_gt  = np.sin(2 * np.pi * 440 * np.linspace(0, 2, 44100*2)) + 0.1

# 3. Log a cell
logger.log(
    row="Epoch_1",
    col="Sample_A",
    audio=audio_gen,
    ground_truth=audio_gt,
    meta="Loss: 0.02"  # Text metadata displayed above the cell
)

# 4. Save to disk (creates audio_logs/my_experiment.html)
save_path = logger.save()

# Optional: Display in Jupyter Notebook
logger.display()
```

## Configuration

You can customize the logger by passing a `plot_config` dictionary during initialization. The full configuration options available in the file `wavetable/config.py`.

### 1\. General Settings

| Parameter      | Type | Default        | Description                                                           |
| :------------- | :--- | :------------- | :-------------------------------------------------------------------- |
| `sr`           | int  | 44100          | Global sampling rate.                                                 |
| `save_mode`    | str  | `'embed'`      | `'embed'` (single huge HTML file) or `'link'` (HTML + assets folder). |
| `hover_effect` | bool | `True`         | Highlights the active row on mouse hover.                             |
| `root_dir`     | str  | `'audio_logs'` | Directory where logs are saved.                                       |

### 2\. Spectrogram Configuration

Passed via `plot_config={'spectrogram': {...}}`:

| Parameter          | Options             | Default     | Description                                          |
| :----------------- | :------------------ | :---------- | :--------------------------------------------------- |
| `spectrogram_type` | `'stft'`, `'mel'`   | `'stft'`    | The type of spectrogram to compute.                  |
| `plot_freq_scale`  | `'log'`, `'linear'` | `'log'`     | Y-axis scaling (only used if type is 'stft').        |
| `magnitude_scale`  | `'db'`, `'linear'`  | `'db'`      | Compression of magnitude/power.                      |
| `n_mels`           | int                 | `80`        | Number of Mel bands (only used if type is 'mel').    |
| `cmap`             | str                 | `'inferno'` | Matplotlib colormap name (e.g., 'viridis', 'magma'). |
| `n_fft`            | int                 | `2048`      | FFT window size.                                     |
| `hop_length`       | int                 | `512`       | STFT hop length.                                     |

### 3\. Waveform Configuration

Passed via `plot_config={'waveform': {...}}`:

| Parameter    | Type  | Default     | Description                                                 |
| :----------- | :---- | :---------- | :---------------------------------------------------------- |
| `overlay_gt` | bool  | `False`     | If True, plots Ground Truth signal behind Generated signal. |
| `color_gen`  | str   | `'#007bff'` | Hex color for Generated audio (Blue).                       |
| `color_gt`   | str   | `'#fd7e14'` | Hex color for Ground Truth audio (Orange).                  |
| `ylim`       | tuple | `(-1, 1)`   | Y-axis limits for the waveform plot.                        |

## Advanced Example

```python
logger = AudioLogger(
    name="Mel_Spectrogram_Test",
    sr=22050,
    hover_effect=False, # Disable row highlighting
    plot_config={
        'spectrogram': {
            'spectrogram_type': 'mel',
            'n_mels': 128,
            'magnitude_scale': 'db',
            'cmap': 'magma',
            'dimensions': (300, 80) # W, H in pixels
        },
        'waveform': {
            'overlay_gt': True,     # See Gen and GT on top of each other
            'dimensions': (300, 40)
        }
    }
)
```
