Metadata-Version: 2.4
Name: dstft
Version: 3.0.0
Summary: Differentiable Short-Time Fourier Transform (DSTFT) for PyTorch
Author: Maxime Leiber
License-Expression: MIT
Project-URL: Homepage, https://github.com/maxime-leiber/dstft
Project-URL: Documentation, https://dstft.readthedocs.io
Project-URL: Issues, https://github.com/maxime-leiber/dstft/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.1
Requires-Dist: matplotlib
Requires-Dist: torchaudio
Provides-Extra: dev
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: interrogate>=1.7; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Requires-Dist: nbsphinx>=0.9; extra == "docs"
Requires-Dist: ipython>=8.0; extra == "docs"
Dynamic: license-file

# DSTFT

[![PyPI Version](https://img.shields.io/pypi/v/dstft.svg)](https://pypi.org/project/dstft/)
[![Python Versions](https://img.shields.io/pypi/pyversions/dstft.svg)](https://pypi.org/project/dstft/)
[![Documentation Status](https://readthedocs.org/projects/dstft/badge/?version=latest)](https://dstft.readthedocs.io/en/latest/?badge=latest)
[![CI](https://github.com/maxime-leiber/dstft/actions/workflows/ci.yml/badge.svg)](https://github.com/maxime-leiber/dstft/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/maxime-leiber/dstft/branch/main/graph/badge.svg)](https://codecov.io/gh/maxime-leiber/dstft)
[![License](https://img.shields.io/github/license/maxime-leiber/dstft.svg)](LICENSE)
[![IEEE TSP](https://img.shields.io/badge/IEEE_TSP-DSTFT-00629B?logo=ieee&logoColor=white)](https://ieeexplore.ieee.org/abstract/document/11220928)

**DSTFT** (Differentiable Short-Time Fourier Transform) is a PyTorch module for a differentiable short-time Fourier transform, supporting learnable/adaptive parameters.

---

<!-- For GitHub -->
<img src="docs/_static/opt.gif" alt="Optimization demo" width="600"/>

Gradient-based optimization of DSTFT parameters (example: window length).

---

## Features

- Differentiable STFT (learnable window lengths, and hop lengths)
- FFT for DSTFT, DFT for adaptive DSTFT, inverse DSTFT

## Installation

### pip/venv

Create and activate a virtual environment, then install in editable mode:

```bash
python -m venv venv
source venv/bin/activate
pip install -U pip
pip install -e .
```

### Conda/Mamba + uv

Create a new environment:

```bash
mamba create -n dstft python=3.11 pip
mamba activate dstft
pip install -U uv
```

Install the package:

```bash
uv pip install -e .
```

Install optional dependencies:

```bash
uv pip install -e ".[dev,docs]"
```

For development tools:

```bash
pip install -e ".[dev]"
```

For documentation dependencies:

```bash
pip install -e ".[docs]"
```

## Usage example

```python
import torch

from dstft import DSTFT

torch.manual_seed(0)
x = torch.randn(1, 1024)

dstft = DSTFT(
    n_fft=256,
    hop_length=64.0,
    win_length=256.0,
    window_mode="constant",
)
dstft.initialize(x)

spec, stft = dstft(x)
```


## License

This project is licensed under the terms of the MIT License. See the
[LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please open issues or pull requests for bug fixes,
improvements, or new features.

## Releasing

The package version is derived automatically from git tags (via
`setuptools-scm`) — it is never edited by hand in `pyproject.toml`. To cut a
release:

```bash
git tag v3.0.1
git push origin v3.0.1
```

Then build and publish as usual (`python -m build && twine upload dist/*`).
A tag on a commit with no uncommitted local changes produces an exact version
(`3.0.1`); any other commit gets an automatic `.devN+g<hash>` suffix.

## Citation

Please cite this repository if you use it in your scientific work:

```bibtex
@ARTICLE{11220928,
  author={Leiber, Maxime and Marnissi, Yosra and Barrau, Axel and Meignen, Sylvain and Massoulié, Laurent},
  journal={IEEE Transactions on Signal Processing},
  title={Optimal Adaptive Time-Frequency Representation via Differentiable Short-Time Fourier Transform},
  year={2025},
  volume={73},
  number={},
  pages={5047-5059},
  keywords={Windows;Time-frequency analysis;Optimization;Spectrogram;Computational efficiency;Tuning;Signal resolution;Neural networks;Discrete Fourier transforms;Backpropagation;Short-time Fourier transform;spectrogram;differentiable STFT;learnable STFT parameters;adaptive time-frequency representation},
  doi={10.1109/TSP.2025.3624477}}
@inproceedings{leiber2022differentiable,
  title={A differentiable short-time Fourier transform with respect to the window length},
  author={Leiber, Maxime and Barrau, Axel and Marnissi, Yosra and Abboud, Dany},
  booktitle={2022 30th European Signal Processing Conference (EUSIPCO)},
  pages={1392--1396},
  year={2022},
  organization={IEEE}
}
@inproceedings{leiber2023differentiable,
  title={Differentiable adaptive short-time Fourier transform with respect to the window length},
  author={Leiber, Maxime and Marnissi, Yosra and Barrau, Axel and El Badaoui, Mohammed},
  booktitle={ICASSP 2023-2023 IEEE International Conference on Acoustics, Speech and Signal Processing (ICASSP)},
  pages={1--5},
  year={2023},
  organization={IEEE}
}
@inproceedings{leiber2023differentiable,
  title={Differentiable short-time Fourier transform with respect to the hop length},
  author={Leiber, Maxime and Marnissi, Yosra and Barrau, Axel and El Badaoui, Mohammed},
  booktitle={2023 IEEE Statistical Signal Processing Workshop (SSP)},
  pages={230--234},
  year={2023},
  organization={IEEE}
}
```

[![IEEE TSP](https://img.shields.io/badge/IEEE_TSP-DSTFT-00629B?logo=ieee&logoColor=white)](https://ieeexplore.ieee.org/abstract/document/11220928)
[![EUSIPCO](https://img.shields.io/badge/EUSIPCO-2208.10886-B31B1B?logo=arxiv&logoColor=white)](https://arxiv.org/abs/2208.10886)
[![ICASSP](https://img.shields.io/badge/ICASSP-2506.21440-B31B1B?logo=arxiv&logoColor=white)](https://arxiv.org/abs/2308.02418)
[![SSP Workshop](https://img.shields.io/badge/SSP_Workshop-2308.02418-B31B1B?logo=arxiv&logoColor=white)](https://arxiv.org/abs/2308.02421)
