Package: wavescapes
wavescapesWavescapes are plots that can visually represent measurements of regularity in music. Those measurements are represented by colors, which are ordered in a hierarchical manner allowing all possible subsections of a musical piece to have their measurement being displayed on the plot. The regularity is measured through the Discrete Fourier Tansform (DFT). Interpretation of the different components outputed by the DFT with respect to the soure musical piece allow high-level analysis of the tonality in the hierarchy of the piece.Here is the paper published by Musicae Scientiae describing the methodology and some case studies of this novel method of visualisation.InstallationTo install this package the following command has to be issued on a terminal prompt:pipinstallwavescapesDepending on which default python distribution you have,pip3instead ofpipmight be used. This library only works with a version of python that is 3.6 or higher.The current version of the library has a dependency that is sometimes tricky to install, if during installation from pip, you encounter several warning messages ending with the following two lines:ERROR: Could not find a version that satisfies the requirement madmom (from wavescapes) (from versions: 0.12, 0.12.1, 0.13, 0.13.1, 0.13.2, 0.14, 0.14.1, 0.15, 0.15.1, 0.16, 0.16.1)
ERROR: No matching distribution found for madmomYou can resolve the issue by installing cython (pip install cython) and then restart the intallation of wavescapes. More information on the matterin this issue.Below is the list of packages required in order for this library to work. Link to the package's official webpage, and a short description of its usage in this project is specified. Explanations on how to install each of these can be found on each package's hyperlink.numpyused for vector operations, the DFT operations, and in order to model the wavescapes as a matrix of colored values.music21used to parse MIDI files and get temporal and pitch informations from them.pretty_midionly used in order to remove percussive tracks for MIDI files.matplotlibthe main graphic library.madmomused to produce chromagrams (i.e. pitch class distributions) from real audio.(Optional)ffmpegmadmom supports only audio files in WAV formats, to enable support for most common audio formats such asmp3,oggoraif, you needffmpegwhich can be used internally by madmom.Documentation & How to useThe library is small and lightweight as there are only three functions useful for plotting and understanding wavescapes. However, we do provide a lot of customizations through the means of optional parameters for each functions. This is why we have designed a thorough tutorial on how to use the library and manipulate all the options available. The tutorial consists of a single jupyter notebook located in thenotebookfolder. You can read the tutorial on your browser by following the link below, but we strongly recommand you to clone this repository and to run the tutorials notebook on your own. You can then try to change the parameters and experiment with the different customizations options proposed, or use the notebooks as a base for generating your own wavescapes.Link to a notebook viewer of the tutorialNo official documentation is provided, however most of the functions from this package have been described by python docstring you may find in the source code (wavescapesfolder).QuickstartIf all functions and classes from this package are correctly imported, the short function call below is an example on how to generate a wavescape plot from a MIDI file and then save it as a PNG file.fromwavescapesimportsingle_wavescapesingle_wavescape(filepath='Bach Prelude in C Major (BWV 846).mid',#plot's width in pixelsindividual_width=500,#length of the shortest segments of the wavescapes in terms of quarter noteaw_size=1.,#the coefficient to be displayedcoefficient=3,#amount of segments per tick drawn on the horizontal axisaw_per_tick=4,#no offset introduced for the position of the ticks, the value 0 also indicates the tick numbers have to start at 1 and not 0.tick_offset=0,#saves the figure drawn as a PNG image.save_label='bach_3rd_coeff_wavescape.png')