Merge 4f61e97 into f0d4853

docs/conf.py

@@ -63,14 +63,14 @@
 sphinx_gallery_conf = {
         'examples_dirs': 'examples/',
         'gallery_dirs': 'auto_examples',
-        'backreferences_dir': False,
+        'backreferences_dir': None,
         'reference_url': {
             'sphinx_gallery': None,
-            'numpy': 'http://docs.scipy.org/doc/numpy/',
-            'np': 'http://docs.scipy.org/doc/numpy/',
+            'numpy': 'http://numpy.org/doc/stable/',
+            'np': 'http://numpy.org/doc/stable/',
             'scipy': 'http://docs.scipy.org/doc/scipy/reference',
             'matplotlib': 'https://matplotlib.org/',
-            'sklearn': 'https://scikit-learn.org/stable',
+            'sklearn': 'https://scikit-learn.org/stable/',
             'resampy': 'https://resampy.readthedocs.io/en/latest/',
             'pyrubberband': 'https://pyrubberband.readthedocs.io/en/stable/',
             'samplerate': 'https://python-samplerate.readthedocs.io/en/latest/',
@@ -138,16 +138,15 @@
 numpydoc_show_class_members = False
 
 intersphinx_mapping = {'python': ('https://docs.python.org/3', None),
-                       'numpy': ('https://docs.scipy.org/doc/numpy/', None),
-                       'np': ('https://docs.scipy.org/doc/numpy/', None),
+                       'numpy': ('https://numpy.org/doc/stable/', None),
+                       'np': ('https://numpy.org/doc/stable/', None),
                        'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
                        'matplotlib': ('https://matplotlib.org/', None),
                        'sklearn': ('https://scikit-learn.org/stable/', None),
                        'resampy': ('https://resampy.readthedocs.io/en/latest/', None),
                        'soundfile': ('https://pysoundfile.readthedocs.io/en/latest', None),
-                       'pyrubberband': ('https://pyrubberband.readthedocs.io/en/stable/', None),
+                       'pyrubberband': ('https://pyrubberband.readthedocs.io/en/stable/', None)}
 
-                       'librosa_gallery': ('https://librosa.github.io/librosa_gallery/', None)}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -163,23 +162,16 @@
 
 # General information about the project.
 project = u'librosa'
-copyright = u'2013--2019, librosa development team'
+copyright = u'2013--2020, librosa development team'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 
-if sys.version_info.major == 2:
-    import imp
-
-    librosa_version = imp.load_source('librosa.version',
-                                      '../librosa/version.py')
-else:
-    from importlib.machinery import SourceFileLoader
-
-    librosa_version = SourceFileLoader('librosa.version',
-                                       '../librosa/version.py').load_module()
+from importlib.machinery import SourceFileLoader
+librosa_version = SourceFileLoader('librosa.version',
+                                   '../librosa/version.py').load_module()
 
 # The short X.Y version.
 version = librosa_version.short_version

docs/index.rst

@@ -38,7 +38,6 @@ API documentation
     beat
     decompose
     effects
-    output
     segment
     sequence
     util

docs/tutorial.rst

@@ -75,8 +75,9 @@ Before diving into the details, we'll walk through a brief example program
     from __future__ import print_function
     import librosa
 
-    # 1. Get the file path to the included audio example
-    filename = librosa.util.example_audio_file()
+    # 1. Get the file path to an included audio example
+    filename = librosa.example('nutcracker')
+
 
     # 2. Load the audio as a waveform `y`
     #    Store the sampling rate as `sr`
@@ -93,12 +94,10 @@ Before diving into the details, we'll walk through a brief example program
 
 The first step of the program::
 
-    filename = librosa.util.example_audio_file()
+    filename = librosa.example('nutcracker')
 
-gets the path to the audio example file included with *librosa*.  After this step,
+gets the path to an audio example file included with *librosa*.  After this step,
 ``filename`` will be a string variable containing the path to the example audio file.
-The example is encoded in OGG Vorbis format, so you will need the appropriate codec
-installed for `audioread <https://github.com/sampsyo/audioread>`_.
 
 The second step::
 
@@ -151,7 +150,7 @@ multiple spectral features, and beat-synchronous feature aggregation.
     import librosa
 
     # Load the example clip
-    y, sr = librosa.load(librosa.util.example_audio_file())
+    y, sr = librosa.load(librosa.ex('nutcracker'))
 
     # Set the hop length; at 22050 Hz, 512 samples ~= 23ms
     hop_length = 512

librosa/core/audio.py

@@ -825,7 +825,8 @@ def lpc(y, order):
     >>> import scipy
     >>> y, sr = librosa.load(librosa.ex('trumpet'), duration=0.020)
     >>> a = librosa.lpc(y, 2)
-    >>> y_hat = scipy.signal.lfilter([0] + -1*a[1:], [1], y)
+    >>> b = np.hstack([[0], -1 * a[1:]])
+    >>> y_hat = scipy.signal.lfilter(b, [1], y)
     >>> plt.figure()
     >>> plt.plot(y)
     >>> plt.plot(y_hat, linestyle='--')

librosa/core/spectrum.py

@@ -207,8 +207,14 @@ def stft(y, n_fft=2048, hop_length=None, win_length=None, window='hann',
 
     # Pad the time series so that frames are centered
     if center:
+        if n_fft > y.shape[-1]:
+            warnings.warn('n_fft={} is too small for input signal of length={}'.format(n_fft, y.shape[-1]))
+
         y = np.pad(y, int(n_fft // 2), mode=pad_mode)
 
+    elif n_fft > y.shape[-1]:
+        raise ParameterError('n_fft={} is too small for input signal of length={}'.format(n_fft, y.shape[-1]))
+
     # Window the time series.
     y_frames = util.frame(y, frame_length=n_fft, hop_length=hop_length)
 

librosa/onset.py

@@ -185,7 +185,6 @@ def onset_strength(y=None, sr=22050, S=None, lag=1, max_size=1,
                    ref=None,
                    detrend=False, center=True,
                    feature=None, aggregate=None,
-                   centering=None,
                    **kwargs):
     """Compute a spectral flux onset strength envelope.
 
@@ -231,7 +230,9 @@ def onset_strength(y=None, sr=22050, S=None, lag=1, max_size=1,
         Filter the onset strength to remove the DC component
 
     center : bool [scalar]
-        Shift the onset function by `n_fft / (2 * hop_length)` frames
+        Shift the onset function by `n_fft / (2 * hop_length)` frames.
+        This corresponds to using a centered frame analysis in the short-time Fourier
+        transform.
 
     feature : function
         Function for computing time-series features, eg, scaled spectrograms.
@@ -446,7 +447,9 @@ def onset_strength_multi(y=None, sr=22050, S=None, n_fft=2048, hop_length=512,
         Filter the onset strength to remove the DC component
 
     center : bool [scalar]
-        Shift the onset function by `n_fft / (2 * hop_length)` frames
+        Shift the onset function by `n_fft / (2 * hop_length)` frames.
+        This corresponds to using a centered frame analysis in the short-time Fourier
+        transform.
 
     feature : function
         Function for computing time-series features, eg, scaled spectrograms.

tests/test_core.py

@@ -238,6 +238,18 @@ def test_stft(infile):
     assert np.allclose(D, DATA["D"].conj())
 
 
+@pytest.mark.xfail(raises=librosa.ParameterError)
+def test_stft_toolong_left():
+    y = np.zeros((128,))
+    librosa.stft(y, n_fft=2048, center=False)
+
+
+def test_stft_toolong_center():
+    y = np.zeros((128,))
+    with pytest.warns(UserWarning):
+        librosa.stft(y, n_fft=2048, center=True)
+
+
 def test_stft_winsizes():
     # Test for issue #1095
     x = np.empty(1000000)