Data loader / more example tracks (#1150)

* implemented pooch loader, starts #952 * added librosa data cache to travis config * deprecated example audio file * added license + metadata display * updated examples * updated beat tracking doc examples * updated decompose examples * more docstring example updates * more docstring example updates * more docstring example updates * updated feature examples * updated examples except cqt * fixed clicks docstring example * added tests for data loader * fixed load-resample tests * fixed example-list test * cache the appveyor cache * updated cache documentation * fixing windows backslashing silliness * removed waller * removed waller * updated data path * added another example, revised advanced example gallery * updated pcen example to match sampling rate correctly * updated librosa data path * updated docs to describe example files * updated docstrings examples for cqt/vqt
librosa · Jun 19, 2020 · 3cab0b6 · 3cab0b6
1 parent c2417c1
commit 3cab0b6
Show file tree

Hide file tree

Showing 48 changed files with 625 additions and 392 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -3,6 +3,8 @@ cache:
   directories:
   - $HOME/env
   - $HOME/Library/Caches/Homebrew
+  - $HOME/.cache
+  - $HOME/Library/Caches/librosa
 
 language: python
 

diff --git a/appveyor.yml b/appveyor.yml
@@ -8,6 +8,7 @@ environment:
 
 cache:
     - "%MINICONDA%\\envs -> appveyor.yml, setup.py"
+    - "%HOMEPATH%\\AppData\\Local"
 
 init:
   - "ECHO %PYTHON_VERSION% %MINICONDA%"

diff --git a/docs/conf.py b/docs/conf.py
@@ -73,7 +73,8 @@
             '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/'
+            'samplerate': 'https://python-samplerate.readthedocs.io/en/latest/',
+            'pooch': 'https://www.fatiando.org/pooch/latest/'
         }
     }
 

diff --git a/docs/examples/audio/BFJazz_-_Stargazer_from_Texas.mp3 b/docs/examples/audio/BFJazz_-_Stargazer_from_Texas.mp3
diff --git a/docs/examples/audio/Cheese_N_Pot-C_-_16_-_The_Raps_Well_Clean_Album_Version.mp3 b/docs/examples/audio/Cheese_N_Pot-C_-_16_-_The_Raps_Well_Clean_Album_Version.mp3
diff --git a/docs/examples/audio/Karissa_Hobbs_-_09_-_Lets_Go_Fishin.mp3 b/docs/examples/audio/Karissa_Hobbs_-_09_-_Lets_Go_Fishin.mp3
diff --git a/docs/examples/audio/Kevin_MacLeod_-_Camille_Saint-Sans_Danse_Macabre_-_Sad_Part.mp3 b/docs/examples/audio/Kevin_MacLeod_-_Camille_Saint-Sans_Danse_Macabre_-_Sad_Part.mp3
diff --git a/docs/examples/audio/README.md b/docs/examples/audio/README.md
@@ -2,9 +2,4 @@
 
 The licenses and the origins of the audio files are as follows:
 
-* http://freemusicarchive.org/music/We_Is_Shore_Dedicated/Smiley/12_Sometimes_With_Friends
-* http://freemusicarchive.org/music/Karissa_Hobbs/Age_of_Flowers/09_Lets_Go_Fishin
-* http://freemusicarchive.org/music/Kevin_MacLeod/Classical_Sampler/Danse_Macabre_-_Sad_Part
-* https://www.jamendo.com/track/1316074/stargazer-from-texas
-* http://freemusicarchive.org/music/Cheese_N_Pot-C/The_Raps_Well/16_-_The_Raps_Well_Clean_Album_Version
 * `sir_duke_slow.mp3` and `sir_duke_fast.mp3` were recorded by Stefan Balke and are released under CC BY 4.0.
diff --git a/docs/examples/audio/We_Is_Shore_Dedicated_-_12_-_12_Sometimes_With_Friends.mp3 b/docs/examples/audio/We_Is_Shore_Dedicated_-_12_-_12_Sometimes_With_Friends.mp3
diff --git a/docs/examples/plot_chroma.py b/docs/examples/plot_chroma.py
@@ -38,7 +38,8 @@
 
 #######################################################################
 # We'll use a track that has harmonic, melodic, and percussive elements
-y, sr = librosa.load('audio/Karissa_Hobbs_-_09_-_Lets_Go_Fishin.mp3')
+#  Karissa Hobbs - Let's Go Fishin'
+y, sr = librosa.load(librosa.ex('fishin'))
 
 
 #######################################

diff --git a/docs/examples/plot_hprss.py b/docs/examples/plot_hprss.py
@@ -23,8 +23,8 @@
 import librosa.display
 
 ########################
-# Load the example clip.
-y, sr = librosa.load('audio/Karissa_Hobbs_-_09_-_Lets_Go_Fishin.mp3', offset=40, duration=10)
+# Load an example clip with harmonics and percussives
+y, sr = librosa.load(librosa.ex('choice'))
 
 
 ###############################################

diff --git a/docs/examples/plot_pcen_stream.py b/docs/examples/plot_pcen_stream.py
@@ -27,7 +27,8 @@
 
 ######################################################################
 # First, we'll start with an audio file that we want to stream
-filename = librosa.util.example_audio_file()
+# We'll use an example track at 44.1 KHz
+filename = librosa.ex('brahms', hq=True)
 
 #####################################################################
 # Next, we'll set up the block reader to work on short segments of 

diff --git a/docs/examples/plot_presets.py b/docs/examples/plot_presets.py
@@ -58,7 +58,7 @@
 
 ######################################################################
 # Now we can load in a file and do some analysis with the new defaults
-filename = 'audio/Karissa_Hobbs_-_09_-_Lets_Go_Fishin.mp3'
+filename = librosa.ex('fishin')
 
 y, sr = librosa.load(filename, duration=5, offset=35)
 

diff --git a/docs/examples/plot_segmentation.py b/docs/examples/plot_segmentation.py
@@ -36,7 +36,7 @@
 
 #############################
 # First, we'll load in a song
-y, sr = librosa.load('audio/Karissa_Hobbs_-_09_-_Lets_Go_Fishin.mp3')
+y, sr = librosa.load(librosa.ex('fishin'))
 
 
 ##############################################

diff --git a/docs/examples/plot_superflux.py b/docs/examples/plot_superflux.py
@@ -28,7 +28,7 @@
 # noticeable vocal vibrato.
 # The method works fine for longer signals, but the
 # results are harder to visualize.
-y, sr = librosa.load('audio/Karissa_Hobbs_-_09_-_Lets_Go_Fishin.mp3',
+y, sr = librosa.load(librosa.ex('fishin', hq=True),
                      sr=44100,
                      duration=5,
                      offset=35)

diff --git a/docs/examples/plot_viterbi.py b/docs/examples/plot_viterbi.py
@@ -24,7 +24,7 @@
 
 #############################################
 # Load an example signal
-y, sr = librosa.load('audio/sir_duke_slow.mp3')
+y, sr = librosa.load(librosa.ex('trumpet'))
 
 
 # And compute the spectrogram magnitude and phase

diff --git a/docs/examples/plot_vocal_separation.py b/docs/examples/plot_vocal_separation.py
@@ -31,7 +31,7 @@
 
 #############################################
 # Load an example with vocals.
-y, sr = librosa.load('audio/Cheese_N_Pot-C_-_16_-_The_Raps_Well_Clean_Album_Version.mp3', duration=120)
+y, sr = librosa.load(librosa.ex('fishin'), duration=120)
 
 
 # And compute the spectrogram magnitude and phase

diff --git a/docs/index.rst b/docs/index.rst
@@ -54,6 +54,7 @@ Advanced topics
     cache
     ioformats
     advanced
+    recordings
 
 Reference
 ---------

diff --git a/docs/recordings.rst b/docs/recordings.rst
@@ -0,0 +1,56 @@
+Example files
+^^^^^^^^^^^^^
+
+*librosa* includes a small selection of example recordings which are primarily used
+to demonstrate different functions of the library.
+Beginning with version 0.8, these examples are automatically retrieved from a remote
+server upon request.
+Example recordings are cached locally after the first request, so each file should
+only be downloaded once.
+
+
+Downloading files directly
+--------------------------
+
+If you want to ensure that example data are always present on your computer, you can
+clone the data repository directly::
+
+    $ git clone https://github.com/librosa/data.git /path/to/librosa-data
+
+To ensure that *librosa* can find the example files, you can set the
+`LIBROSA_DATA_DIR` environment variable prior to importing *librosa*::
+
+    $ export LIBROSA_DATA_DIR=/path/to/librosa-data/audio
+    $ python my_librosa_script.py
+
+or, directly in Python::
+
+    >>> import os
+    >>> os.environ['LIBROSA_DATA_DIR'] = '/path/to/librosa-data/audio'
+    >>> import librosa
+    
+This will bypass any remote network access and use the local copies of the data
+files directly.
+
+
+Description of examples
+-----------------------
+
+The function `librosa.util.list_examples()` provides a brief description of each
+track, and `librosa.util.example_info()` will provide some metadata and licensing
+information for a given track.
+
+The following table describes in more detail what the recordings are, and how they
+are mainly used in the documentation.
+`Key` indicates the descriptor used to identify the track when calling `librosa.example()`.
+
+==========  =========================================== ============================================================================
+Key         Full name                                   Description
+==========  =========================================== ============================================================================
+brahms      Brahms - Hungarian Dance #5                 A short performance of this piece, with soft note onsets and variable tempo.
+choice      Admiral Bob - Choice                        A short drum and bass loop, good for demonstrating decomposition methods.
+fishin      Karissa Hobbs - Let's Go Fishin'            A folk/pop song with verse/chorus/verse structure and vocals.
+nutcracker  Tchaikovsky - Dance of the Sugar Plum Fairy Orchestral piece included to demonstrate tempo and harmony features.
+trumpet     Mihai Sorohan - Trumpet loop                Monophonic trumpet recording, good for demonstrating pitch features.
+vibeace     Kevin Macleod - Vibe Ace                    A vibraphone, piano, and bass combo. Previously the only included example.
+==========  =========================================== ============================================================================
diff --git a/librosa/__init__.py b/librosa/__init__.py
@@ -23,5 +23,9 @@
 # Exporting exception classes at the top level
 from .util.exceptions import *  # pylint: disable=wildcard-import
 
+# Exporting data loader at the top level
+from .util.files import example, ex
+
+
 # Exporting all core functions is okay here: suppress the import warning
 from .core import *  # pylint: disable=wildcard-import
diff --git a/librosa/beat.py b/librosa/beat.py
@@ -108,28 +108,35 @@ def beat_track(y=None, sr=22050, onset_envelope=None, hop_length=512,
     --------
     Track beats using time series input
 
-    >>> y, sr = librosa.load(librosa.util.example_audio_file())
+    >>> y, sr = librosa.load(librosa.ex('choice'))
 
     >>> tempo, beats = librosa.beat.beat_track(y=y, sr=sr)
     >>> tempo
-    64.599609375
+    135.99917763157896
 
 
-    Print the first 20 beat frames
+    Print the frames corresponding to beats
 
-    >>> beats[:20]
-    array([ 320,  357,  397,  436,  480,  525,  569,  609,  658,
-            698,  737,  777,  817,  857,  896,  936,  976, 1016,
-           1055, 1095])
+    >>> beats
+    array([   3,   21,   40,   59,   78,   96,  116,  135,  154,  173,
+            192,  211,  230,  249,  268,  287,  306,  325,  344,  363,
+            382,  401,  420,  439,  458,  476,  495,  515,  534,  553,
+            572,  591,  610,  629,  647,  667,  686,  705,  724,  743,
+            762,  780,  799,  819,  838,  857,  876,  895,  914,  933,
+            951,  971,  990, 1008])
 
 
     Or print them as timestamps
 
-    >>> librosa.frames_to_time(beats[:20], sr=sr)
-    array([  7.43 ,   8.29 ,   9.218,  10.124,  11.146,  12.19 ,
-            13.212,  14.141,  15.279,  16.208,  17.113,  18.042,
-            18.971,  19.9  ,  20.805,  21.734,  22.663,  23.591,
-            24.497,  25.426])
+    >>> librosa.frames_to_time(beats, sr=sr)
+    array([ 0.07 ,  0.488,  0.929,  1.37 ,  1.811,  2.229,  2.694,
+            3.135,  3.576,  4.017,  4.458,  4.899,  5.341,  5.782,
+            6.223,  6.664,  7.105,  7.546,  7.988,  8.429,  8.87 ,
+            9.311,  9.752, 10.194, 10.635, 11.053, 11.494, 11.958,
+           12.399, 12.841, 13.282, 13.723, 14.164, 14.605, 15.023,
+           15.488, 15.929, 16.37 , 16.811, 17.252, 17.694, 18.112,
+           18.553, 19.017, 19.458, 19.9  , 20.341, 20.782, 21.223,
+           21.664, 22.082, 22.547, 22.988, 23.406])
 
 
     Track beats using a pre-computed onset envelope
@@ -139,11 +146,14 @@ def beat_track(y=None, sr=22050, onset_envelope=None, hop_length=512,
     >>> tempo, beats = librosa.beat.beat_track(onset_envelope=onset_env,
     ...                                        sr=sr)
     >>> tempo
-    64.599609375
-    >>> beats[:20]
-    array([ 320,  357,  397,  436,  480,  525,  569,  609,  658,
-            698,  737,  777,  817,  857,  896,  936,  976, 1016,
-           1055, 1095])
+    135.99917763157896
+    >>> beats
+    array([   3,   21,   40,   59,   78,   96,  116,  135,  154,  173,
+            192,  211,  230,  249,  268,  287,  306,  325,  344,  363,
+            382,  401,  420,  439,  458,  476,  495,  515,  534,  553,
+            572,  591,  610,  629,  647,  667,  686,  705,  724,  743,
+            762,  780,  799,  819,  838,  857,  876,  895,  914,  933,
+            951,  971,  990, 1008])
 
 
     Plot the beat events against the onset strength envelope
@@ -158,7 +168,6 @@ def beat_track(y=None, sr=22050, onset_envelope=None, hop_length=512,
     ...            linestyle='--', label='Beats')
     >>> plt.legend(frameon=True, framealpha=0.75)
     >>> # Limit the plot to a 15-second window
-    >>> plt.xlim(15, 30)
     >>> plt.gca().xaxis.set_major_formatter(librosa.display.TimeFormatter())
     >>> plt.tight_layout()
     >>> plt.show()
@@ -262,34 +271,32 @@ def tempo(y=None, sr=22050, onset_envelope=None, hop_length=512, start_bpm=120,
     Examples
     --------
     >>> # Estimate a static tempo
-    >>> y, sr = librosa.load(librosa.util.example_audio_file())
+    >>> y, sr = librosa.load(librosa.ex('nutcracker'))
     >>> onset_env = librosa.onset.onset_strength(y, sr=sr)
     >>> tempo = librosa.beat.tempo(onset_envelope=onset_env, sr=sr)
     >>> tempo
-    array([129.199])
+    array([143.555])
 
     >>> # Or a static tempo with a uniform prior instead
     >>> import scipy.stats
     >>> prior = scipy.stats.uniform(30, 300)  # uniform over 30-300 BPM
     >>> utempo = librosa.beat.tempo(onset_envelope=onset_env, sr=sr, prior=prior)
     >>> utempo
-    array([64.6])
+    array([161.499])
 
     >>> # Or a dynamic tempo
     >>> dtempo = librosa.beat.tempo(onset_envelope=onset_env, sr=sr,
     ...                             aggregate=None)
     >>> dtempo
-    array([ 143.555,  143.555,  143.555, ...,  161.499,  161.499,
-            172.266])
+    array([ 89.103,  89.103,  89.103, ..., 123.047, 123.047, 123.047])
 
     >>> # Dynamic tempo with a proper log-normal prior
     >>> prior_lognorm = scipy.stats.lognorm(loc=np.log(120), scale=120, s=1)
     >>> dtempo_lognorm = librosa.beat.tempo(onset_envelope=onset_env, sr=sr,
     ...                                     aggregate=None,
     ...                                     prior=prior_lognorm)
     >>> dtempo_lognorm
-    array([ 86.133,  86.133, ..., 129.199, 129.199])
-
+    array([ 89.103,  89.103,  89.103, ..., 123.047, 123.047, 123.047])
 
     Plot the estimated tempo against the onset autocorrelation
 
@@ -322,7 +329,7 @@ def tempo(y=None, sr=22050, onset_envelope=None, hop_length=512, start_bpm=120,
     >>> plt.figure()
     >>> tg = librosa.feature.tempogram(onset_envelope=onset_env, sr=sr,
     ...                                hop_length=hop_length)
-    >>> librosa.display.specshow(tg, x_axis='time', y_axis='tempo')
+    >>> librosa.display.specshow(tg, x_axis='time', y_axis='tempo', cmap='magma')
     >>> plt.plot(librosa.times_like(dtempo), dtempo,
     ...          color='w', linewidth=1.5, label='Tempo estimate (default prior)')
     >>> plt.plot(librosa.times_like(dtempo_lognorm), dtempo_lognorm,
@@ -434,7 +441,7 @@ def plp(y=None, sr=22050, onset_envelope=None, hop_length=512,
     Visualize the PLP compared to an onset strength envelope.
     Both are normalized here to make comparison easier.
 
-    >>> y, sr = librosa.load(librosa.util.example_audio_file())
+    >>> y, sr = librosa.load(librosa.ex('brahms'))
     >>> onset_env = librosa.onset.onset_strength(y=y, sr=sr)
     >>> pulse = librosa.beat.plp(onset_envelope=onset_env, sr=sr)
     >>> # Or compute pulse with an alternate prior, like log-normal
@@ -466,7 +473,7 @@ def plp(y=None, sr=22050, onset_envelope=None, hop_length=512,
     ...          label='Predominant local pulse (PLP)')
     >>> plt.title('Log-normal tempo prior, mean=120')
     >>> plt.legend()
-    >>> plt.xlim([30, 35])
+    >>> plt.xlim([5, 20])
     >>> plt.tight_layout()
     >>> plt.show()
 
@@ -493,7 +500,7 @@ def plp(y=None, sr=22050, onset_envelope=None, hop_length=512,
     ...            linestyle='--', label='PLP Beats')
     >>> plt.legend(frameon=True, framealpha=0.75)
     >>> plt.title('librosa.beat.plp')
-    >>> plt.xlim(30, 35)
+    >>> plt.xlim([5, 20])
     >>> ax.xaxis.set_major_formatter(librosa.display.TimeFormatter())
     >>> plt.tight_layout()
     >>> plt.show()