tovis 0.1.0__tar.gz

tovis-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johannes Zeitler and Meinard Müller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tovis-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+recursive-include docs/source *.rst *.py .gitkeep
+recursive-include docs/source/_static *.png
+recursive-include tests *.py
+prune docs/build

tovis-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: tovis
+Version: 0.1.0
+Summary: TOVIS: A Python toolbox for tonal visualization of musical audio and annotation data
+Author-email: Johannes Zeitler <johannes.zeitler@audiolabs-erlangen.de>, Meinard Müller <meinard.mueller@audiolabs-erlangen.de>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/groupmm/tovis
+Project-URL: Documentation, https://groupmm.github.io/tovis/
+Project-URL: Repository, https://github.com/groupmm/tovis
+Project-URL: Issues, https://github.com/groupmm/tovis/issues
+Keywords: music,audio,chroma,tonality,visualization,music information retrieval
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+License-File: licenses/countem-upstream.txt
+License-File: licenses/onsets-and-frames-MIT.txt
+License-File: licenses/pytorch-stft-BSD-3-Clause.txt
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+Requires-Dist: pandas
+Requires-Dist: librosa>=0.10
+Provides-Extra: transcription
+Requires-Dist: torch>=2.0; extra == "transcription"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Provides-Extra: notebooks
+Requires-Dist: jupyterlab; extra == "notebooks"
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == "release"
+Requires-Dist: twine>=6; extra == "release"
+Dynamic: license-file
+
+<p align="right">
+  <img src="docs/source/_static/logo_tovis.png" alt="TOVIS logo" width="300">
+</p>
+
+# TOVIS: A Python toolbox for tonal visualization of musical audio and annotation data"
+
+
+© [Johannes Zeitler](https://audiolabs-erlangen.de/fau/assistant/zeitler) and [Meinard Müller](https://www.audiolabs-erlangen.de/fau/professor/mueller), 2026
+
+International Audio Laboratories, Erlangen
+
+TOVIS is a Python toolbox for tonal visualization of musical audio
+and annotation data.
+
+The toolbox includes utilities for:
+
+- chromagram extraction from audio, symbolic note annotations, and transcription output
+- scale-likelihood analysis with configurable templates
+- transposition-invariant self-similarity matrices for structure analysis
+- time/measure conversion using synchronization annotations
+- visualization of chromagrams, scale likelihoods, tempo curves, and structure or measure annotations
+
+Extended documentation available [HERE](https://groupmm.github.io/tovis/).
+
+## Installation
+
+TOVIS requires Python 3.11 or newer. Install from PyPI:
+
+```bash
+python -m pip install tovis
+```
+
+To install from the GitHub repository:
+
+```bash
+git clone https://github.com/groupmm/tovis.git
+cd tovis
+python -m pip install .
+```
+
+Use `python -m pip install -e ".[docs,notebooks]"` for an editable checkout
+with documentation and notebook tools. Neural transcription requires
+`python -m pip install "tovis[transcription]"` and a compatible checkpoint obtained
+separately. You must explicitly set `transcription_checkpoint` to the checkpoint
+file path when using a neural backend; TOVIS searches no default location.
+Direct `tovis.transcription` functions require the `checkpoint` keyword argument.
+Standard chroma backends work without PyTorch or model weights.
+
+## Quick start
+
+This example generates a three-second C-major chord, extracts chroma features,
+compares them with scale templates, and saves `tovis-introduction.png`.
+It needs no audio files, annotations, network access, or neural checkpoints.
+
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+
+import tovis
+from tovis.visualization import plot_chromagram, plot_scale_likelihood
+
+sample_rate = 22050
+time = np.arange(3 * sample_rate) / sample_rate
+frequencies = [261.63, 329.63, 392.00]  # C4, E4, G4
+audio = sum(np.sin(2 * np.pi * f * time) for f in frequencies) / 3
+
+chroma, feature_rate = tovis.compute_chromagram(
+    audio, sample_rate=sample_rate, backend="STFT"
+)
+likelihood = tovis.scale_analysis_templates(chroma, template_version="binary")
+
+fig, axes = plt.subplots(2, 1, figsize=(10, 6))
+plot_chromagram(chroma, feature_rate=feature_rate, ax=axes[0])
+plot_scale_likelihood(likelihood, feature_rate=feature_rate, ax=axes[1])
+fig.tight_layout()
+fig.savefig("tovis-introduction.png", dpi=150)
+plt.close(fig)
+```
+
+To analyze your own audio, replace the synthesis and extraction steps with
+`chroma, feature_rate = tovis.compute_chromagram_from_file("your-audio.wav")`.
+Chroma matrices have shape `(12, n_frames)`; `feature_rate` is frames per second.
+The scale likelihoods compare major-scale templates and are not a definitive
+key estimate.
+
+## Documentation
+
+[Read the documentation](https://groupmm.github.io/tovis/) for the installation
+guide, introduction, and API reference.
+
+Build the installation guide, introduction, and API reference from the checkout:
+
+```bash
+python -m pip install -e ".[docs]"
+python -m sphinx -W -b html docs/source docs/build/html
+```
+
+Open `docs/build/html/index.html` to read the documentation. Generated
+documentation is excluded from version control.
+
+## Development
+
+The conda environment is defined in `environment.yml`. From the checkout, run
+the regression checks with `python -m unittest discover -s tests`.
+
+The demonstration notebooks and their example audio and annotation data are in
+[`scripts/`](https://github.com/groupmm/tovis/tree/master/scripts). Neural
+examples additionally require compatible checkpoints supplied by the user.
+
+## License and attribution
+
+TOVIS is available under the [MIT license](https://github.com/groupmm/tovis/blob/master/LICENSE). It includes code from
+the [count-the-notes project](https://github.com/Yoni-Yaffe/count-the-notes)
+by Jonathan Yaffe, Ben Maman, Meinard Müller, and Amit Bermano (2025), Onsets & Frames code by Jong Wook Kim (2019), and PyTorch STFT code by Prem Seetharaman (2017). Third-party attribution and upstream notices
+are recorded in [THIRD_PARTY_NOTICES.md](https://github.com/groupmm/tovis/blob/master/THIRD_PARTY_NOTICES.md).

tovis-0.1.0/README.md

@@ -0,0 +1,115 @@
+<p align="right">
+  <img src="docs/source/_static/logo_tovis.png" alt="TOVIS logo" width="300">
+</p>
+
+# TOVIS: A Python toolbox for tonal visualization of musical audio and annotation data"
+
+
+© [Johannes Zeitler](https://audiolabs-erlangen.de/fau/assistant/zeitler) and [Meinard Müller](https://www.audiolabs-erlangen.de/fau/professor/mueller), 2026
+
+International Audio Laboratories, Erlangen
+
+TOVIS is a Python toolbox for tonal visualization of musical audio
+and annotation data.
+
+The toolbox includes utilities for:
+
+- chromagram extraction from audio, symbolic note annotations, and transcription output
+- scale-likelihood analysis with configurable templates
+- transposition-invariant self-similarity matrices for structure analysis
+- time/measure conversion using synchronization annotations
+- visualization of chromagrams, scale likelihoods, tempo curves, and structure or measure annotations
+
+Extended documentation available [HERE](https://groupmm.github.io/tovis/).
+
+## Installation
+
+TOVIS requires Python 3.11 or newer. Install from PyPI:
+
+```bash
+python -m pip install tovis
+```
+
+To install from the GitHub repository:
+
+```bash
+git clone https://github.com/groupmm/tovis.git
+cd tovis
+python -m pip install .
+```
+
+Use `python -m pip install -e ".[docs,notebooks]"` for an editable checkout
+with documentation and notebook tools. Neural transcription requires
+`python -m pip install "tovis[transcription]"` and a compatible checkpoint obtained
+separately. You must explicitly set `transcription_checkpoint` to the checkpoint
+file path when using a neural backend; TOVIS searches no default location.
+Direct `tovis.transcription` functions require the `checkpoint` keyword argument.
+Standard chroma backends work without PyTorch or model weights.
+
+## Quick start
+
+This example generates a three-second C-major chord, extracts chroma features,
+compares them with scale templates, and saves `tovis-introduction.png`.
+It needs no audio files, annotations, network access, or neural checkpoints.
+
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+
+import tovis
+from tovis.visualization import plot_chromagram, plot_scale_likelihood
+
+sample_rate = 22050
+time = np.arange(3 * sample_rate) / sample_rate
+frequencies = [261.63, 329.63, 392.00]  # C4, E4, G4
+audio = sum(np.sin(2 * np.pi * f * time) for f in frequencies) / 3
+
+chroma, feature_rate = tovis.compute_chromagram(
+    audio, sample_rate=sample_rate, backend="STFT"
+)
+likelihood = tovis.scale_analysis_templates(chroma, template_version="binary")
+
+fig, axes = plt.subplots(2, 1, figsize=(10, 6))
+plot_chromagram(chroma, feature_rate=feature_rate, ax=axes[0])
+plot_scale_likelihood(likelihood, feature_rate=feature_rate, ax=axes[1])
+fig.tight_layout()
+fig.savefig("tovis-introduction.png", dpi=150)
+plt.close(fig)
+```
+
+To analyze your own audio, replace the synthesis and extraction steps with
+`chroma, feature_rate = tovis.compute_chromagram_from_file("your-audio.wav")`.
+Chroma matrices have shape `(12, n_frames)`; `feature_rate` is frames per second.
+The scale likelihoods compare major-scale templates and are not a definitive
+key estimate.
+
+## Documentation
+
+[Read the documentation](https://groupmm.github.io/tovis/) for the installation
+guide, introduction, and API reference.
+
+Build the installation guide, introduction, and API reference from the checkout:
+
+```bash
+python -m pip install -e ".[docs]"
+python -m sphinx -W -b html docs/source docs/build/html
+```
+
+Open `docs/build/html/index.html` to read the documentation. Generated
+documentation is excluded from version control.
+
+## Development
+
+The conda environment is defined in `environment.yml`. From the checkout, run
+the regression checks with `python -m unittest discover -s tests`.
+
+The demonstration notebooks and their example audio and annotation data are in
+[`scripts/`](https://github.com/groupmm/tovis/tree/master/scripts). Neural
+examples additionally require compatible checkpoints supplied by the user.
+
+## License and attribution
+
+TOVIS is available under the [MIT license](https://github.com/groupmm/tovis/blob/master/LICENSE). It includes code from
+the [count-the-notes project](https://github.com/Yoni-Yaffe/count-the-notes)
+by Jonathan Yaffe, Ben Maman, Meinard Müller, and Amit Bermano (2025), Onsets & Frames code by Jong Wook Kim (2019), and PyTorch STFT code by Prem Seetharaman (2017). Third-party attribution and upstream notices
+are recorded in [THIRD_PARTY_NOTICES.md](https://github.com/groupmm/tovis/blob/master/THIRD_PARTY_NOTICES.md).

tovis-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,44 @@
+# Third-party notices
+
+TOVIS is developed by Johannes Zeitler and Meinard Müller at International
+Audio Laboratories, Erlangen. The root MIT license applies to TOVIS-authored
+code. Bundled third-party code retains its upstream notices and terms.
+
+## Onsets & Frames
+
+The code in `tovis/transcription/onsets_and_frames/` derives from the PyTorch
+implementation of Onsets & Frames by Jong Wook Kim and the CountEM codebase.
+
+- Original implementation: https://github.com/jongwook/onsets-and-frames
+- Copyright 2019 Jong Wook Kim; MIT license, reproduced in
+  `licenses/onsets-and-frames-MIT.txt`.
+- The underlying Onsets and Frames architecture was introduced by Hawthorne
+  et al., *Onsets and Frames: Dual-Objective Piano Transcription* (2018).
+
+## CountEM / Count the Notes
+
+TOVIS includes code from the count-the-notes project (CountEM), including the
+`CountEMModel` Hugging Face wrapper in `hf_model.py` and extensions to the
+Onsets & Frames implementation.
+
+- Source: https://github.com/Yoni-Yaffe/count-the-notes
+- Authors: Jonathan Yaffe, Ben Maman, Meinard Müller, and Amit Bermano (2025).
+- Project: *Count the Notes: Histogram-Based Supervision for Automatic Music
+  Transcription*.
+- Upstream license notice: `licenses/countem-upstream.txt`, reproduced as
+  published in the upstream `LICENSE.md`.
+
+Model weights are not included in the TOVIS distributions.
+
+## PyTorch STFT
+
+The STFT implementation in `tovis/transcription/onsets_and_frames/mel.py`
+is adapted from Prem Seetharaman's PyTorch STFT implementation.
+
+- Source: https://github.com/pseeth/pytorch-stft (now `pseeth/torch-stft`).
+- Copyright (c) 2017, Prem Seetharaman; BSD 3-Clause license, reproduced in
+  `licenses/pytorch-stft-BSD-3-Clause.txt`.
+
+TOVIS integrates these components into its package and transcription wrapper;
+the bundled copies may differ from upstream. Existing upstream model metadata
+and source credits are retained.

tovis-0.1.0/docs/source/_examples/introduction.py

@@ -0,0 +1,22 @@
+import matplotlib.pyplot as plt
+import numpy as np
+
+import tovis
+from tovis.visualization import plot_chromagram, plot_scale_likelihood
+
+sample_rate = 22050
+time = np.arange(3 * sample_rate) / sample_rate
+frequencies = [261.63, 329.63, 392.00]  # C4, E4, G4
+audio = sum(np.sin(2 * np.pi * f * time) for f in frequencies) / 3
+
+chroma, feature_rate = tovis.compute_chromagram(
+    audio, sample_rate=sample_rate, backend="STFT"
+)
+likelihood = tovis.scale_analysis_templates(chroma, template_version="binary")
+
+fig, axes = plt.subplots(2, 1, figsize=(10, 6))
+plot_chromagram(chroma, feature_rate=feature_rate, ax=axes[0])
+plot_scale_likelihood(likelihood, feature_rate=feature_rate, ax=axes[1])
+fig.tight_layout()
+fig.savefig("tovis-introduction.png", dpi=150)
+plt.close(fig)

tovis-0.1.0/docs/source/_static/.gitkeep

@@ -0,0 +1 @@
+

tovis-0.1.0/docs/source/_templates/.gitkeep

@@ -0,0 +1 @@
+

tovis-0.1.0/docs/source/api.rst

@@ -0,0 +1,55 @@
+API Reference
+=============
+
+This section is generated from the docstrings in the TOVIS toolbox code.
+
+Feature
+------------------
+
+.. automodule:: tovis.feature
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Scale
+--------------
+
+.. automodule:: tovis.scale
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Structure
+------------------
+
+.. automodule:: tovis.structure
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Utilities
+---------
+
+.. automodule:: tovis.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Visualization
+-------------
+
+.. automodule:: tovis.visualization
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Transcription
+-------------
+
+These helpers require the optional transcription dependencies and compatible
+model checkpoints at runtime; see :doc:`installation`.
+
+.. automodule:: tovis.transcription
+   :members:
+   :undoc-members:
+   :show-inheritance:

tovis-0.1.0/docs/source/attribution.rst

@@ -0,0 +1,25 @@
+License and attribution
+=======================
+
+TOVIS is developed by Johannes Zeitler and Meinard Müller at International
+Audio Laboratories, Erlangen. TOVIS is distributed under the
+MIT license in the repository's ``LICENSE`` file.
+
+The bundled transcription code includes contributions from:
+
+* `Onsets & Frames <https://github.com/jongwook/onsets-and-frames>`_,
+  the PyTorch implementation by Jong Wook Kim, copyright 2019, under MIT.
+* The `count-the-notes project (CountEM) <https://github.com/Yoni-Yaffe/count-the-notes>`_,
+  by Jonathan Yaffe, Ben Maman, Meinard Müller, and Amit Bermano (2025),
+  whose code is included in TOVIS.
+* `PyTorch STFT <https://github.com/pseeth/torch-stft>`_ by Prem Seetharaman,
+  copyright 2017, under BSD 3-Clause. The STFT code in ``mel.py`` is adapted
+  from this implementation.
+
+The Onsets and Frames architecture was introduced by Hawthorne et al.,
+*Onsets and Frames: Dual-Objective Piano Transcription* (2018).
+
+Upstream notices and terms are included in ``THIRD_PARTY_NOTICES.md`` and
+``licenses/`` in the repository and in the package's distribution license
+files. Bundled third-party code retains its upstream terms.
+

tovis-0.1.0/docs/source/conf.py

@@ -0,0 +1,33 @@
+"""Sphinx configuration for the TOVIS documentation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import sys
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(PROJECT_ROOT))
+
+project = "TOVIS"
+author = "Johannes Zeitler and Meinard Müller"
+copyright = "2026, Johannes Zeitler and Meinard Müller"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+]
+
+autodoc_typehints = "description"
+autodoc_member_order = "bysource"
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_logo = "_static/logo_tovis.png"
+html_theme_options = {"logo_only": True}

tovis-0.1.0/docs/source/index.rst

@@ -0,0 +1,31 @@
+TOVIS Documentation
+===================
+
+.. image:: _static/logo_tovis.png
+   :alt: TOVIS logo
+   :width: 400px
+
+TOVIS is a Python toolbox for **TO**\ nal **VIS**\ ualization of musical audio,
+symbolic annotations, chromagrams, scale likelihoods, and formal structure.
+
+Johannes Zeitler and Meinard Müller
+
+International Audio Laboratories, Erlangen
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   installation
+   introduction
+   api
+   attribution
+
+Indices
+=======
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

tovis-0.1.0/docs/source/installation.rst

@@ -0,0 +1,94 @@
+Installation
+============
+
+TOVIS requires Python 3.11 or newer. Its Python package and distribution name
+is ``tovis``. Use a virtual environment or the supplied conda environment to
+keep dependencies separate from other projects.
+
+Install from PyPI
+-----------------
+
+.. code-block:: bash
+
+   python -m pip install tovis
+
+Install from source
+-------------------
+
+.. code-block:: bash
+
+   git clone https://github.com/groupmm/tovis.git
+   cd tovis
+   python -m pip install .
+
+Check the installation with:
+
+.. code-block:: bash
+
+   python -c "import tovis; from importlib.metadata import version; print(version('tovis'))"
+
+Optional dependencies
+---------------------
+
+Install optional dependencies for documentation, notebooks, or neural
+transcription with:
+
+.. code-block:: bash
+
+   python -m pip install "tovis[docs]"
+   python -m pip install "tovis[notebooks]"
+   python -m pip install "tovis[transcription]"
+
+``docs`` installs Sphinx and the documentation theme. ``notebooks`` installs
+JupyterLab. ``transcription`` installs PyTorch for neural inference with
+user-supplied model checkpoints. Multiple
+extras can be combined, for example ``"tovis[docs,notebooks]"``. For a source
+checkout, replace ``tovis`` with ``.`` in these commands.
+
+The STFT, CQT, VQT, and IIR chroma backends need no neural checkpoints or
+PyTorch. Neural backends additionally require a compatible checkpoint, which
+is obtained separately and not included in the distribution.
+You must configure the checkpoint path explicitly for every
+neural transcription call. TOVIS searches no default checkpoint location.
+For the feature-extraction functions, set ``transcription_checkpoint``:
+
+.. code-block:: python
+
+   from tovis import compute_chromagram_from_file
+
+   chroma, feature_rate = compute_chromagram_from_file(
+       "your-audio.wav",
+       backend="ONSETS_AND_FRAMES",
+       transcription_checkpoint="/path/to/checkpoint_OnsetsAndFrames.pt",
+       transcription_device="cpu",
+   )
+
+For Deep Chroma use ``backend="DEEP_CHROMA"`` and a compatible Deep Chroma
+checkpoint. Direct calls to functions in ``tovis.transcription`` require the
+``checkpoint`` keyword argument. Missing or empty paths are rejected, and
+paths must point to existing files before audio loading or neural inference.
+
+These backends expect different model formats; arbitrary upstream
+weights are not interchangeable. Use checkpoints from a trusted source:
+the Onsets & Frames loader deserializes a Python model object.
+
+Development and documentation
+-----------------------------
+
+For editable installation and a local documentation build:
+
+.. code-block:: bash
+
+   python -m pip install -e ".[docs,notebooks]"
+   python -m unittest discover -s tests
+   python -m sphinx -W -b html docs/source docs/build/html
+
+Open ``docs/build/html/index.html`` in a browser. Generated documentation is
+excluded from version control. The conda environment in ``environment.yml``
+is an alternative for local development; install TOVIS in that environment
+with ``python -m pip install -e .``.
+
+The demonstration notebooks and their example audio and annotation data are
+in ``scripts/`` in the source repository. Neural examples additionally require
+compatible checkpoints supplied by the user. The :doc:`introduction` provides
+a self-contained example using synthesized audio.

tovis-0.1.0/docs/source/introduction.rst

@@ -0,0 +1,66 @@
+Introduction
+============
+
+TOVIS turns musical audio or note annotations into chroma features, compares
+those features with scale templates, and visualizes tonal and formal structure.
+
+A runnable example
+------------------
+
+Install TOVIS as described in :doc:`installation`, then run the following code
+in Python. It synthesizes a three-second C-major chord, extracts an STFT
+chromagram, computes scale likelihoods, and saves ``tovis-introduction.png``
+in the current directory. No datasets, audio downloads, or model checkpoints
+are needed. Saving the plot also works without a graphical desktop.
+
+.. literalinclude:: _examples/introduction.py
+   :language: python
+
+Reading the results
+-------------------
+
+``chroma`` has shape ``(12, n_frames)``. Its rows represent pitch classes
+ordered C, C-sharp, D, ..., B; columns represent successive audio frames.
+``feature_rate`` is measured in frames per second, so frame ``n`` corresponds
+to time ``n / feature_rate``. A C-major chord emphasizes C, E, and G.
+
+``likelihood`` compares each chroma frame with twelve transposed major-scale
+templates. The default scale labels describe each scale's position on the
+circle of fifths relative to C. These values describe template agreement;
+they are not calibrated probabilities or a definitive key estimate.
+
+Use your own audio
+------------------
+
+Replace the synthesis and chromagram extraction in the example with:
+
+.. code-block:: python
+
+   chroma, feature_rate = tovis.compute_chromagram_from_file("your-audio.wav")
+
+The default backend is CQT. STFT, CQT, VQT, and IIR are available without
+neural models. See :doc:`installation` for the additional requirements of
+the neural backends.
+
+Use note annotations
+--------------------
+
+For symbolic input, provide note start and end times in seconds and MIDI
+pitch numbers in a DataFrame:
+
+.. code-block:: python
+
+   import pandas as pd
+
+   notes = pd.DataFrame({
+       "start": [0.0, 0.0, 0.0],
+       "end": [3.0, 3.0, 3.0],
+       "pitch": [60, 64, 67],
+   })
+   chroma, feature_rate = tovis.compute_chromagram_from_annotations(
+       notes, feature_rate=10.0
+   )
+
+This returns a ``(12, 30)`` matrix at ten frames per second. It can be used
+with the same scale-analysis and visualization functions. See :doc:`api`
+for smoothing, normalization, synchronization, and structure-analysis options.