Metadata-Version: 2.4
Name: audio-toolset
Version: 0.1.0
Summary: Tools for processing audio signals
Author-email: moshe-stanylov <maxoshe@gmail.com>
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: numpy==2.0.1
Requires-Dist: plotly==5.23.0
Requires-Dist: pydantic>=2.11.7
Requires-Dist: scipy==1.13.1
Requires-Dist: soundfile==0.12.1
Description-Content-Type: text/markdown

# Audio Toolset


![CI Workflow status](https://github.com/maxoshe/audio-toolset/actions/workflows/ci.yml/badge.svg)
![GitHub top language](https://img.shields.io/github/languages/top/maxoshe/audio-toolset)


A Python library for **processing audio signals**.

`audio_toolset` provides an intuitive and flexible way to process audio files in Python. Each `Channel` object handles a single **mono audio file**, allowing you to apply filters, EQ, dynamics processing, gain adjustments, noise reduction, and more.

Stereo files can be handled by first splitting them into mono channels using `split_to_mono` and then recombining them with `join_to_stereo`.

## Features

- High level [`Channel`](https://github.com/maxoshe/audio-toolset/blob/main/src/audio_toolset/channel.py) object for simple user interface
- Load audio from a file or [`AudioData`](https://github.com/maxoshe/audio-toolset/blob/a609df16c37a2e08653ee153a3ecde7f48faa41c/src/audio_toolset/audio_data.py)
- Gain processing
  - `gain`, `normalize`, `fade`
- Filters
  - `lowpass`, `highpass`, `eq_band`
  - `noise_reduction` (spectral gating)
- Dynamics
  - `compressor`, `limiter`, `soft_clipping`
- Plotting tools ([see examples](#plotting))
  - `plot_signal` - generate signal time and frequency plot
  - Dynamic plots - `compressor`, `limiter` can generate attenuation plots
  - Bode plots - `lowpass`, `highpass`, `eq_band` can generate filter bode plots

## Installation

```bash
pip install git+https://github.com/maxoshe/audio-toolset.git
```

## Examples

### Process with a channel strip

```python
from audio_toolset.channel import Channel

guitar = Channel("guitar.wav")
guitar.highpass(cutoff_frequency=100, db_per_octave=6)
guitar.eq_band(center_frequency=2000, gain_db=3, q_factor=1)
guitar.lowpass(cutoff_frequency=10000, db_per_octave=12)
guitar.normalize(target_db=-1)
guitar.compressor(threshold_db=-20, compression_ratio=4, attack_ms=50, release_ms=100)
guitar.write("guitar_processed.wav")
```

### Process with a chained channel strip

```python
speech = Channel("speech.wav").highpass(cutoff_frequency=100).lowpass(cutoff_frequency=300)
```

## Plotting

`audio_toolset` provides multiple plotting tools to visualize signals, filters, and dynamics. All plots are generated interactively using [**Plotly**](https://plotly.com) and can be saved as images from the interactive viewer.

### Signal Plots

Use `plot_signal()` to visualize the time-domain and frequency-domain representation of an audio channel.

<img width="1674" height="952" alt="newplot-2" src="https://github.com/user-attachments/assets/c993c26c-4001-4028-82c3-b6419848ba5f" />


### 2. Filter (Bode) Plots

Filter plots show the frequency response (Bode plot) of filters applied using `eq_band(plot_filter_bode=True)`, `highpass(plot_filter_bode=True)`, or `lowpass(plot_filter_bode=True)`.

<img width="1674" height="952" alt="newplot-5" src="https://github.com/user-attachments/assets/53f7c585-34d3-4485-b624-682968d9cab0" />
<img width="1674" height="952" alt="newplot-4" src="https://github.com/user-attachments/assets/b524addc-5e0e-4b44-a0a6-22e68e588924" />


### 3. Dynamics Plots

Dynamics plots visualize the response of compressors and limiters applied to a channel. Generated by `compressor(plot_compressor_response=True)` or `limiter(plot_limiter_response=True)`

<img width="1674" height="952" alt="newplot-6" src="https://github.com/user-attachments/assets/7acf8761-b148-4522-8a65-87c90534f5b7" />

