Metadata-Version: 2.4
Name: sms-tools
Version: 1.2
Summary: Sound analysis/synthesis tools for music applications
Author-email: "Music Technology Group, Universitat Pompeu Fabra" <mtg-info@upf.edu>
Project-URL: Homepage, https://github.com/mtg/sms-tools
Project-URL: Issues, https://github.com/mtg/sms-tools/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS
Requires-Dist: matplotlib
Requires-Dist: numpy<2.0.0
Requires-Dist: scipy
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-cov>=5.0; extra == "test"
Requires-Dist: hypothesis; extra == "test"
Dynamic: license-file

sms-tools
========= 

Sound analysis/synthesis tools for music applications written in python.

The package includes the following sound analysis/synthesis models:

* dftModel.py: models based on the Discrete Fourier Transform
* stft.py: models based on the Short-Time Fourier Transform
* sineModel.py: models based on a Sinusoidal Model
* harmonicModel.py: models based on a Harmonic Model
* stochasticModel.py: models based on a Stochastic Model
* sprModel.py: models based on a Sinusoidal plus Residual Model
* spsModel.py: models based on a Sinusoidal plus Stochastic Model
* hprModel.py: models based on a Harmonic plus Residual Model
* hpsModel.py: models based on a Harmonic plus Stochastic Model


Installation
------------

Install using pip:

    pip install sms-tools


When installing via pip, the Cython extension is built automatically if a compatible compiler and Python environment are available. This provides significant speedups for core routines.

    pip install sms-tools

If you are developing locally or want to ensure the Cython extension is built, you can run:

    pip install sms-tools
    python setup.py build_ext --inplace

If you encounter issues with the Cython extension, ensure you have Cython, setuptools, and a C compiler installed. The extension is optional; sms-tools will fall back to pure-Python routines if unavailable.

You can verify which backend is active at runtime:

    python - <<'PY'
    from smstools.models import utilFunctions as UF
    print("Using Cython backend:", UF.UF_C is not None)
    print("Backend module:", getattr(UF.UF_C, "__file__", None))
    PY

Binary packages are available for Linux, macOS (Intel & Apple Silicon) and Windows (64 bit) on all recent python versions.

For details about automatic Cython acceleration and fallback behavior, see the
"Cython backend" section below.

To build and install the package locally you can use the python packaging tools:

    pip install build
    python -m build


Cython backend
--------------

sms-tools includes a compiled Cython extension for selected core routines.
When available, it is used automatically for better performance.
If it cannot be imported, sms-tools falls back to pure-Python implementations
with the same public behavior (typically slower).

You can verify which backend is active at runtime:

    python - <<'PY'
    from smstools.models import utilFunctions as UF
    print("Using Cython backend:", UF.UF_C is not None)
    print("Backend module:", getattr(UF.UF_C, "__file__", None))
    PY

Testing
-------

To install test dependencies and run the test suite, use:

    pip install .[test]
    pytest

You can run a specific test file with:

    pytest -v tests/test_cython_vs_python.py

This will execute all tests and print detailed output.

sms-tools-materials repository
-------

There is a separate repository containing teaching materials, example notebooks, and exercises used in courses that use the sms-tools package. It includes Jupyter notebooks, audio examples, and practical guides to help students and researchers learn about sound analysis, synthesis, and transformation with sms-tools.

For more information and resources, see: https://github.com/MTG/sms-tools-materials

License
-------

sms-tools is made available under the terms of the Affero GPL license (http://www.gnu.org/licenses/agpl-3.0.en.html). 
