Metadata-Version: 2.4
Name: fluxion-dsp
Version: 0.3.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Scientific/Engineering
Requires-Dist: numpy>=1.23
Requires-Dist: pyarrow>=14 ; extra == 'dataset'
Requires-Dist: safetensors>=0.4 ; extra == 'interop'
Requires-Dist: jax>=0.4 ; extra == 'jax'
Requires-Dist: pytest>=7 ; extra == 'test'
Requires-Dist: scipy ; extra == 'test'
Requires-Dist: array-api-strict ; extra == 'test'
Requires-Dist: array-api-compat ; extra == 'test'
Requires-Dist: pyarrow>=14 ; extra == 'test'
Requires-Dist: torch>=2.0 ; extra == 'torch'
Provides-Extra: dataset
Provides-Extra: interop
Provides-Extra: jax
Provides-Extra: test
Provides-Extra: torch
License-File: LICENSE
Summary: GPU-accelerated, differentiable audio DSP — Python bindings
Keywords: audio,dsp,differentiable,gpu,realtime
Home-Page: https://github.com/matteospanio/fluxion
Author: Matteo Spanio
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/matteospanio/fluxion
Project-URL: Repository, https://github.com/matteospanio/fluxion

# fluxion

GPU-accelerated, differentiable audio DSP — Python bindings for [Fluxion](https://github.com/matteospanio/fluxion).

Build effect chains out of `fluxion.filter` / `fluxion.effect` classes, compose them with `|`
(series) and `+` (parallel), and apply them to a `Wave` or to any NumPy / PyTorch / JAX CPU array
(zero-copy via DLPack when it's already `float32` + contiguous). The differentiable SOS primitives
expose fluxion's analytic gradients to `torch.autograd` and `jax.custom_vjp`, so filter
coefficients train inside your model.

Every op has the same name here, in the Rust library, in the CLI and in the browser — they come
from one registry. The chain can also be written as text and passed between them:
`fluxion.chain("highpass(80, 4) | gain(-3dB)")`.

## Install

```bash
pip install fluxion-dsp               # CPU wheel (numpy only); the module is `import fluxion`
pip install 'fluxion-dsp[torch]'      # + the torch.autograd adapter
pip install 'fluxion-dsp[jax]'        # + the jax.custom_vjp adapter
pip install 'fluxion-dsp[interop]'    # + safetensors, for load_flamo_sos
pip install 'fluxion-dsp[dataset]'    # + pyarrow, for the Parquet dataset IO
```

The default wheel is CPU-only. A CUDA build (the "GPU wheel", extra batch kernels behind
`fluxion.cuda_available()`) is published as a separate `+cu12` local-version artifact — it is not on
PyPI (local versions can't be uploaded); grab it from the project's GitHub releases.

## Quick start

**A file in, a file out** — `Wave` carries the sample rate, so it stays out of your code:

```python
import fluxion as fx

wave = fx.Wave.from_file("in.wav")
(wave | fx.filter.Highpass(80, order=4) | fx.effect.Gain(fx.db(-3))).save("out.wav")
```

**Arrays** — for notebooks and batch jobs, a chain is simply callable:

```python
import numpy as np
import fluxion as fx

x = np.random.default_rng(0).standard_normal(48_000).astype(np.float32)
chain = fx.filter.Lowpass(2000.0, order=4) | fx.effect.Gain(0.8)   # series
y = chain(x, fs=48_000)                                            # (T,) float32 out
batch = chain.process_batch(np.stack([x, x]), fs=48_000)           # (B, T) batched CPU path
```

**Trainable filter** — a designed cascade as a torch `nn.Module`:

```python
import torch
import fluxion as fx
import fluxion.torch as fxt

m = fxt.SosModule.from_chain(fx.filter.Lowpass(2000.0, 4), fs=48_000)  # seed from a design
y = m(torch.randn(512))            # differentiable; m.coeffs is an nn.Parameter
y.pow(2).sum().backward()          # gradients flow through fluxion's analytic IIR adjoint
```

**Augmentation** — stochastic, reproducible transforms:

```python
import numpy as np
import fluxion as fx
from fluxion.augment import Compose, RandomChain

aug = Compose([
    RandomChain(fx.filter.Lowpass, cutoff=(500.0, 8000.0), order=4, p=0.5, rng=0),
    fx.effect.Gain(0.9),
])
y = aug(np.random.default_rng(0).standard_normal(1000).astype(np.float32), fs=48_000)
```

**Dataset IO** — Parquet audio datasets (extra `fluxion[dataset]`), the same on-disk schema as the
Rust `fluxion_io::arrow` side, so files interoperate. Streams both ways, so augmenting a whole
dataset is bounded-memory:

```python
from fluxion.dataset import iter_parquet, write_parquet
write_parquet("out.parquet", ((aug(x, fs), fs) for x, fs in iter_parquet("in.parquet")))
```

Import a FLAMO/DDSP biquad checkpoint into fluxion's SOS path with
`fluxion.interop.load_flamo_sos(...)` (see its docstring for supported layouts).

## License

MIT — see [LICENSE](LICENSE).

