0.10.0rc0 release prep (#1653)

* updated changelog and authors for 0.10

* fixing warnings

* converting .format into f-strings for aesthetics

* updating version checker and f-strings

* f-stringing

* blacked

* update dates

* fixed typo in f-stringing

* updated advanced examples for citation and modernization

* more documentation updates

* added troubleshooting section for numba cache issue

* updated changelog

* bumped release date for rc0 [ci skip]

AUTHORS.md

@@ -96,6 +96,11 @@ Contributors
 * Zvi Baratz <https://github.com/ZviBaratz>
 * Alexandre Chabot-Leclerc <https://github.com/achabotl>
 * Steve Kowalik <https://github.com/s-t-e-v-e-n-k>
+* Tom Xi <https://github.com/tomxi>
+* Matan Gover <https://github.com/matangover>
+* Fabian Keller <https://github.com/bluenote10>
+* BdeGraff <https://github.com/BdeGraff>
+* Jon Petter Åsen <https://github.com/jpaasen>
 
 Some feature extraction code was based on <https://github.com/ronw/frontend> by Ron Weiss.
 

docs/changelog.rst

@@ -7,29 +7,36 @@ v0.10
 
 v0.10.0
 -------
-*In development*
+*rc0: 2023-02-07*
 
 New features
 
-    - `#1485`_ Added support for `"h"` (hours) and `"m"` (minutes) in `TimeFormatter`.  *Vincent Lostanlen*
-    - `#1529`_ Accelerated utility functions for squared magnitude `util.abs2` and `util.phasor`. *Brian McFee*
+    - `#1485`_ Added support for `"h"` (hours) and `"m"` (minutes) in `librosa.display.TimeFormatter`.  *Vincent Lostanlen*
+    - `#1495`_ Expanded options for bandwidth calculation in `librosa.segment.recurrence_matrix` and `librosa.segment.cross_similarity`. *Tom Xi*
+    - `#1529`_ Accelerated utility functions for squared magnitude `librosa.util.abs2` and `librosa.util.phasor`. *Brian McFee*
     - `#1514`_ `librosa.stft` support for pre-allocated output arrays.  *Brian McFee*
-    - `#1533`_ Accelerated `util.localmax` and `util.localmin`. *Brian McFee*
-    - `#1552`_ **EXPERIMENTAL** Support for just-intonation based variable-Q transforms and functional just system (FJS) notation. *Brian McFee*
+    - `#1533`_ Accelerated `librosa.util.localmax` and `librosa.util.localmin`. *Brian McFee*
+    - `#1552`_ **EXPERIMENTAL** Support for just-intonation based variable-Q transforms `librosa.vqt` and functional just system (FJS) notation. *Brian McFee*
     - `#1579`_ Imports are now done lazily, significantly reducing startup time. It is not longer necessary to explicitly `import librosa.display`. *Brian McFee*
-    - 
+    - `#1587`_, `#1632`_, `#1637`_ Type annotations. *Matan Gover, Brian McFee, Fabian Keller*
+    - `#1647`_ Harmonic spectrum interpolation `librosa.f0_harmonics` and tempogram ratio features `librosa.feature.tempogram_ratio`. *Brian McFee*
 
 Bug fixes
 
     - `#1560`_ Corrected an error in bandwidth estimation for window functions that take on negative sample values. *Brian McFee*
     - `#1571`_ Fixed rounding error in multirate filterbank calculation of sampling rates. *Brian McFee*
     - `#1594`_ Fixed incorrect use of deprecated numpy numerical types. *Mattia Di Gangi*
+    - `#1596`_ Fixed harmonic interpolation for recent scipy releases. *Brian McFee*
 
 
 API changes
 
     - `#1561`_ `librosa.resample` now supports `axis=` for all sample rate conversion backends. *Brian McFee*
-    - `#1572`_ Notation conversion (e.g., `midi_to_note`) now vectorizes operations, and produces `numpy.ndarray` outputs rather than `list` when given iterable inputs. *Brian McFee*
+    - `#1572`_ Notation conversion (e.g., `librosa.midi_to_note`) now vectorizes operations, and produces `numpy.ndarray` outputs rather than `list` when given iterable inputs. *Brian McFee*
+    - `#1625`_ Deprecations now raise `FutureWarning` instead of `DeprecationWarning`.
+    - `#1625`_ `librosa.get_duration` parameter `filename` has been renamed to `path`. *Brian McFee*
+    - `#1643`_ Removed support for `threshold=None` in `librosa.zero_crossings`. *Brian McFee*
+
 
 
 Documentation
@@ -38,35 +45,49 @@ Documentation
     - `#1531`_ Updated LICENSE.md documentation. *Anton Kostin*
     - `#1536`_ Added keyword argument (`kwargs`) definitions to docstrings. *Emily Halvachs*
     - `#1537`_ Improvements to CONTRIBUTING.md. *Juanita Gomez*
-    - `#1545`_ Correction to docstring for `note_to_midi`. *Helmin Jinoz*
-    - `#1563`_ Improved `specshow` documentation to explain `cmap=` parameter. *Kian Eliasi*
+    - `#1545`_ Correction to docstring for `librosa.note_to_midi`. *Helmin Jinoz*
+    - `#1563`_ Improved `librosa.display.specshow` documentation to explain `cmap=` parameter. *Kian Eliasi*
+    - `#1573`_ Improved documentation for `librosa.filters.semitone_filterbank`. *BdeGraff*
     - `#1586`_ Fixed figure layout in documentation builds. *Brian McFee*
     - `#1592`_ Fixed incorrect link to the documentation badge in README. *Zvi Baratz*
+    - `#1614`_ Improved documentation for resampling. *Jon Petter Åsen*
 
 
 Deprecations
 
     - `#1521`_ Removed backward compatibility support for positional arguments that are now keyword-only. *Brian McFee*
     - `#1577`_ Removed official support for python 3.6. *Brian McFee*
+    - `#1625`_ The `audioread` backend is now deprecated and will be removed in a future release. *Brian McFee*
 
 
 Other changes
 
-    - `#1501`_ Infer square / equal plot dimensions for compatible x/y axes.  *Kian Eliasi*
+    - `#1501`_ Infer square / equal plot dimensions for compatible x/y axes in `librosa.display.specshow`.  *Kian Eliasi*
     - `#1535`_ Standardized integer type checks throughout the library. *Alexandre Chabot-Leclerc*
-    - `#1539`_ Refactored `AdaptiveWaveplot` to allow callback disconnection. *Brian McFee*
+    - `#1539`_ Refactored `librosa.display.AdaptiveWaveplot` to allow callback disconnection. *Brian McFee*
     - `#1548`_ Removed deprecated `'hanning'` window specification from tests. *Brian McFee*
     - `#1551`_ Removed dependency on `contextlib2`. *Steve Kowalik*
-    - `#1565`_ Efficiency improvements to `autocorrelate`. *Brian McFee*
+    - `#1565`_ Efficiency improvements to `librosa.autocorrelate`. *Brian McFee*
     - `#1566`_ Changed the default sample rate conversion method from `kaiser_best` (resampy) to `soxr_hq` (soxr). *Brian McFee*
     - `#1581`_ Updated tests for numpy 1.23 compatibility. *Brian McFee*
+    - `#1617`_ Accelerated `librosa.yin` implementation. *Brian McFee*
+    - `#1640`_ Updated display module dependencies to require matplotlib >= 3.3. *Brian McFee*
+    - `#1643`_ Accelerated `librosa.zero_crossings` implementation. *Brian McFee*
+    - `#1646`_ Added support for transposed (vertical) display of waveforms. *Brian McFee*
+
+
 
 .. _#1485: https://github.com/librosa/librosa/issues/1485
+.. _#1495: https://github.com/librosa/librosa/issues/1495
 .. _#1529: https://github.com/librosa/librosa/issues/1529
 .. _#1514: https://github.com/librosa/librosa/issues/1514
 .. _#1533: https://github.com/librosa/librosa/issues/1533
 .. _#1552: https://github.com/librosa/librosa/issues/1552
 .. _#1579: https://github.com/librosa/librosa/issues/1579
+.. _#1637: https://github.com/librosa/librosa/issues/1637
+.. _#1632: https://github.com/librosa/librosa/issues/1632
+.. _#1587: https://github.com/librosa/librosa/issues/1587
+.. _#1647: https://github.com/librosa/librosa/issues/1647
 .. _#1560: https://github.com/librosa/librosa/issues/1560
 .. _#1571: https://github.com/librosa/librosa/issues/1571
 .. _#1594: https://github.com/librosa/librosa/issues/1594
@@ -80,6 +101,7 @@ Other changes
 .. _#1563: https://github.com/librosa/librosa/issues/1563
 .. _#1586: https://github.com/librosa/librosa/issues/1586
 .. _#1592: https://github.com/librosa/librosa/issues/1592
+.. _#1596: https://github.com/librosa/librosa/issues/1596
 .. _#1521: https://github.com/librosa/librosa/issues/1521
 .. _#1577: https://github.com/librosa/librosa/issues/1577
 .. _#1501: https://github.com/librosa/librosa/issues/1501
@@ -90,6 +112,14 @@ Other changes
 .. _#1565: https://github.com/librosa/librosa/issues/1565
 .. _#1566: https://github.com/librosa/librosa/issues/1566
 .. _#1581: https://github.com/librosa/librosa/issues/1581
+.. _#1625: https://github.com/librosa/librosa/issues/1625
+.. _#1643: https://github.com/librosa/librosa/issues/1643
+.. _#1573: https://github.com/librosa/librosa/issues/1573
+.. _#1614: https://github.com/librosa/librosa/issues/1614
+.. _#1617: https://github.com/librosa/librosa/issues/1617
+.. _#1640: https://github.com/librosa/librosa/issues/1640
+.. _#1643: https://github.com/librosa/librosa/issues/1643
+.. _#1646: https://github.com/librosa/librosa/issues/1646
 
 
 

docs/conf.py

@@ -97,7 +97,6 @@
     + """
 import matplotlib
 import librosa
-import librosa.display
 matplotlib.rcParams['figure.constrained_layout.use'] = True
 """
 )

docs/examples/plot_audio_playback.py

@@ -19,7 +19,6 @@
 # sphinx_gallery_thumbnail_path = '_static/playback-thumbnail.png'
 
 import librosa
-import librosa.display
 
 # We'll need IPython.display's Audio widget
 from IPython.display import Audio

docs/examples/plot_chroma.py

@@ -31,7 +31,6 @@
 import matplotlib.pyplot as plt
 
 import librosa
-import librosa.display
 
 
 #######################################################################

docs/examples/plot_display.py

@@ -21,7 +21,6 @@
 import matplotlib.pyplot as plt
 
 import librosa
-import librosa.display
 
 # %%
 # First, we'll load in a demo track

docs/examples/plot_hprss.py

@@ -21,7 +21,6 @@
 from IPython.display import Audio
 
 import librosa
-import librosa.display
 
 ########################
 # Load an example clip with harmonics and percussives

docs/examples/plot_music_sync.py

@@ -8,7 +8,7 @@
 which is implemented in `librosa`.
 
 We assume that you are familiar with the algorithm and focus on the application. Further information about
-the algorithm can be found in the literature, e. g. [1].
+the algorithm can be found in the literature, e. g. [1]_.
 
 Our example consists of two recordings of the first bars of the famous
 brass section lick in Stevie Wonder's rendition of "Sir Duke".
@@ -26,7 +26,6 @@
 import matplotlib.pyplot as plt
 
 import librosa
-import librosa.display
 
 
 ############################################################
@@ -137,5 +136,5 @@
 # Literature
 # ----------
 #
-# [1] Meinard Müller, Fundamentals of Music Processing — Audio, Analysis, Algorithms, Applications.
-# Springer Verlag, 2015.
+# .. [1] Meinard Müller, Fundamentals of Music Processing — Audio, Analysis, Algorithms, Applications.
+#     Springer Verlag, 2015.

docs/examples/plot_pcen_stream.py

@@ -24,8 +24,7 @@
 
 import soundfile as sf
 
-import librosa as librosa
-import librosa.display as display
+import librosa
 
 
 ######################################################################

docs/examples/plot_presets.py

@@ -19,9 +19,7 @@
 # Import the Preset class
 from presets import Preset
 
-
 # To use presets, we'll make a dummy import of librosa
-# and the display submodule here.
 import librosa as _librosa
 
 #########################################################################

docs/examples/plot_rainbowgram.py

@@ -6,7 +6,11 @@
 
 This notebook demonstrates how to use "Rainbowgrams" to simultaneously 
 visualize amplitude and (unwrapped) phase (differential) as demonstrated in the
-`NSynth paper <https://proceedings.mlr.press/v70/engel17a/engel17a.pdf>`_.
+`NSynth paper <https://proceedings.mlr.press/v70/engel17a/engel17a.pdf>`_ [1]_.
+
+.. [1] Engel, Jesse, Cinjon Resnick, Adam Roberts, Sander Dieleman, Mohammad Norouzi, Douglas Eck, and Karen Simonyan.
+    "Neural audio synthesis of musical notes with wavenet autoencoders."
+    In International Conference on Machine Learning, pp. 1068-1077. PMLR, 2017.
 
 """
 # Code source: Brian McFee
@@ -18,7 +22,6 @@
 import matplotlib.pyplot as plt
 import librosa
 
-import librosa.display
 
 ############################################# 
 # We implemented a stft method to visualize the rainbowgram and demonstrated the result with a chirp signal.

docs/examples/plot_segmentation.py

@@ -30,7 +30,6 @@
 import sklearn.cluster
 
 import librosa
-import librosa.display
 
 #############################
 # First, we'll load in a song
@@ -169,7 +168,7 @@
 #############################################################
 # Let's use these k components to cluster beats into segments
 # (Algorithm 1)
-KM = sklearn.cluster.KMeans(n_clusters=k)
+KM = sklearn.cluster.KMeans(n_clusters=k, n_init="auto")
 
 seg_ids = KM.fit_predict(X)
 

docs/examples/plot_superflux.py

@@ -5,10 +5,16 @@
 ================
 
 This notebook demonstrates how to recover the Superflux onset detection algorithm of
-`Boeck and Widmer, 2013 <http://dafx13.nuim.ie/papers/09.dafx2013_submission_12.pdf>`_
+`Boeck and Widmer, 2013
+<http://dafx13.nuim.ie/papers/09.dafx2013_submission_12.pdf>`_ [1]_
 from librosa.
 
 This algorithm improves onset detection accuracy in the presence of vibrato.
+
+.. [1] Böck, Sebastian, and Gerhard Widmer. 
+    Maximum filter vibrato suppression for onset detection.
+    In Proc. of the 16th Int. Conf. on Digital Audio Effects (DAFx).
+    Maynooth, Ireland (Sept 2013), vol. 7, p. 4. 2013.
 """
 
 # Code source: Brian McFee
@@ -20,7 +26,6 @@
 import matplotlib.pyplot as plt
 
 import librosa
-import librosa.display
 
 ######################################################
 # The method works fine for longer signals, but the
@@ -100,12 +105,12 @@
 
 
 ax[0].plot(frame_time, odf_default, label='Spectral flux')
-ax[0].vlines(onset_default, 0, odf_default.max(), label='Onsets')
+ax[0].vlines(onset_default, 0, odf_default.max(), color='r', label='Onsets')
 ax[0].legend()
 ax[0].label_outer()
 
 ax[1].plot(frame_time, odf_sf, color='g', label='Superflux')
-ax[1].vlines(onset_sf, 0, odf_sf.max(), label='Onsets')
+ax[1].vlines(onset_sf, 0, odf_sf.max(), color='r', label='Onsets')
 ax[1].legend()
 ax[0].label_outer()
 

docs/examples/plot_viterbi.py

@@ -19,8 +19,6 @@
 import matplotlib.pyplot as plt
 import librosa
 
-import librosa.display
-
 #############################################
 # Load an example signal
 y, sr = librosa.load(librosa.ex('trumpet'))

docs/examples/plot_vocal_separation.py

@@ -11,17 +11,31 @@
     This example is primarily of historical interest, and we do not recommend
     this as a competitive method for vocal source separation.
     For a more recent treatment of vocal and music source separation, please
-    refer to `Open Source Tools & Data for Music Source Separation <https://source-separation.github.io/tutorial/landing.html>`_
-    (Manilow, Seetharaman, and Salamon 2020).
+    refer to `Open Source Tools & Data for Music Source Separation
+    <https://source-separation.github.io/tutorial/landing.html>`_ [1]_.
 
 This is based on the "REPET-SIM" method of `Rafii and Pardo, 2012
-<http://www.cs.northwestern.edu/~zra446/doc/Rafii-Pardo%20-%20Music-Voice%20Separation%20using%20the%20Similarity%20Matrix%20-%20ISMIR%202012.pdf>`_, but includes a couple of modifications and extensions:
+<http://www.cs.northwestern.edu/~zra446/doc/Rafii-Pardo%20-%20Music-Voice%20Separation%20using%20the%20Similarity%20Matrix%20-%20ISMIR%202012.pdf>`_
+[2]_, but includes a couple of modifications and extensions:
 
     - FFT windows overlap by 1/4, instead of 1/2
     - Non-local filtering is converted into a soft mask by Wiener filtering.
       This is similar in spirit to the soft-masking method used by `Fitzgerald, 2012
-      <http://arrow.dit.ie/cgi/viewcontent.cgi?article=1086&context=argcon>`_,
+      <http://arrow.dit.ie/cgi/viewcontent.cgi?article=1086&context=argcon>`_
+      [3]_,
       but is a bit more numerically stable in practice.
+
+.. [1] Manilow, Ethan, Prem Seetharman, and Justin Salamon.
+    "Open source tools & data for music source separation."
+    2020.
+
+.. [2] Rafii, Zafar, and Bryan Pardo.
+    "Music/Voice Separation Using the Similarity Matrix."
+    In ISMIR, pp. 583-588. 2012.
+
+.. [3] FitzGerald, Derry.
+    "Vocal separation using nearest neighbours and median filtering."
+    23rd IET Irish Signals and Systems Conference, Maynooth.  (2012): 98-98.
 """
 
 # Code source: Brian McFee
@@ -35,8 +49,6 @@
 
 import librosa
 
-import librosa.display
-
 #############################################
 # Load an example with vocals.
 y, sr = librosa.load(librosa.ex('fishin'), duration=120)

docs/troubleshooting.rst

@@ -18,7 +18,7 @@ message::
     AttributeError: module 'librosa' has no attribute 'display'
 
 
-it is because the `librosa.display` submodule needs to be imported explicitly in librosa versions
+it is because the `librosa.display` submodule needed to be imported explicitly in librosa versions
 earlier than 0.10.
 This is because `matplotlib` is an optional dependency for librosa, so we do not
 assume that all users have it installed, or want plotting capability.
@@ -31,7 +31,7 @@ To fix the problem, add the line
 
 to the beginning of your program.
 
-**NOTE**: this is no longer necessary beginning with the 0.10 release, but it won't hurt to include
+**NOTE**: this is no longer a problem since librosa 0.10, but it won't hurt to include
 the explicit import statement.
 
 PySoundFile failed
@@ -49,3 +49,25 @@ This warning is most often triggered by loading files encoded with `mp3` format,
 which are not supported by `libsndfile` prior to version 1.1.
 When this situation is detected, librosa falls back to use the slower, but more
 flexible `audioread`-based file loader.
+
+
+`import librosa` hangs indefinitely
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you are trying to execute `import librosa` in either a script or interactive
+environment, and it "stalls" or fails to complete, the problem is most likely
+that `numba` is trying to compile librosa functions for more efficient execution,
+and is unable to write the compiled functions to disk for later usage.
+(See: `numba caching documentation <https://numba.readthedocs.io/en/stable/developer/caching.html>`_ for more details on this.)
+This might occur if `librosa` was installed by an administrator or super-user,
+and ordinary users (i.e. you) may not have permission to write files in the same folder.
+
+There are two ways to address this issue:
+
+1. Install `librosa` as the same user who will be executing code, e.g., in a
+   virtual environment.
+2. Change the `NUMBA_CACHE_DIR` environment variable to a folder which the
+   user does have write permissions to.  See `numba environment variables <https://numba.readthedocs.io/en/stable/reference/envvars.html#numba-envvars-caching>`_ for details.
+
+Note that in librosa 0.10 and later, you may not encounter this issue when importing the library, but it may arise later when executing functions.
+The solutions above are applicable in either case.