diff --git a/docs/echonest.rst b/docs/echonest.rst new file mode 100644 index 000000000..4dda925c5 --- /dev/null +++ b/docs/echonest.rst @@ -0,0 +1,112 @@ +Echonest Plugin +=========================== + +Acoustic fingerprinting is a technique for identifying songs from the +way they "sound" rather from their existing metadata. That means that +beets' autotagger can theoretically use fingerprinting to tag files +that don't have any ID3 information at all (or have completely +incorrect data). This plugin uses a fingerprinting technology called +`ENMFP `_ +and its associated Web service, called Echonest `song/identify +`_. + +Turning on fingerprinting can increase the accuracy of the +autotagger---especially on files with very poor metadata---but it +comes at a cost. First, it can be trickier to set up than beets itself +(you need to set up the native fingerprinting library, whereas all of +the beets core is written in pure Python). Also, fingerprinting takes +significantly more CPU and memory than ordinary tagging---which means +that imports will go substantially slower. + +If you're willing to pay the performance cost for fingerprinting, read +on! + +Installing Dependencies +----------------------- + +To get fingerprinting working, you'll need to install two things: +the `ENMFP `_ codegen +command-line tool, and the `pyechonest +`_ Python library. + +First, you will need to install ``ENMFP``, as a command-line tool. +The ``ENMFP`` codegen binary distribution has executables for all +major OSs and architectures. + +Then, install pyechonest itself. You can do this using `pip +`_, like so:: + + $ pip install pyechonest + +Configuring +----------- + +Once you have all the dependencies sorted out, you can enable +fingerprinting by editing your :doc:`configuration file +`. Put ``echonest`` on your ``plugins:`` line. +You'll also need an `API key from Echonest `_. +Then, add the key to your ``config.yaml`` as the value ``apikey`` in a +section called ``echonest`` like so:: + + echonest: + apikey: YOURKEY + +If the ``ENMFP`` binary is not in your path, you'll need to add an +additional key called ``codegen`` under the ``echonest`` section like +so:: + + echonest: + apikey: YOURKEY + codegen: PATH/TO/YOUR/CODEGEN/BINARY + +With that, beets will use fingerprinting the next time you run ``beet +import``. + +If you'd prefer not to run the Echonest plugin importer automatically +when importing, you can shut it off:: + + echonest: + apikey: YOURKEY + codegen: PATH/TO/YOUR/CODEGEN/BINARY + auto: no + +Using +''''' + +The Echonest plugin will automatically fetch and store in the database +(but *not* in the audio file itself) the following audio descriptors: + +- danceability +- duration +- energy +- key +- liveness +- loudness +- mode +- speechiness +- tempo +- time_signature + + +Since most of these fields represent real numbers between 0 and 1, you +will also be able to query inequalities using the range operator +``..``, once it supports doing so in flexattrs, like so:: + + beet ls danceability:0.25...0.75 + beet ls liveness:...0.1 + beet ls speechiness:0.9... + +The above would return all tracks will danceability values in the +range [0.25, 0.75], liveness values less than 0.1, or speechiness +values greater than 0.9. For now, you can sort of get around this +limitation by using regexp queries:: + + beet ls energy::0\.[89] + + +Additionally, the plugin adds a new command, named ``fingerprint``, +which is analogous to the same command provided by ``chroma``. + +TODO +'''' +Provide a command for performing tagging outside of an import stage. diff --git a/docs/plugins/echonest.rst b/docs/plugins/echonest.rst new file mode 100644 index 000000000..799ee646a --- /dev/null +++ b/docs/plugins/echonest.rst @@ -0,0 +1,80 @@ +Echonest Plugin +=============== + +The ``echonest`` plugin will automatically fetch and store the following audio +descriptors from the `EchoNest API`_. All except ``tempo`` will be stored in +flexattrs and *not* in the audio file itself: + +- danceability > echonest_danceability +- energy > echonest_energy +- liveness > echonest_liveness +- loudness > echonest_loudness +- speechiness > echonest_speechiness +- tempo > bpm + +.. _EchoNest API: http://developer.echonest.com/ + +Installing Dependencies +----------------------- + +This plugin requires the pyechonest library in order to talk to the EchoNest +API. At least version 8.0.1 is required. + +There are packages for most major linux distributions, you can download the +library from the Echo Nest, or you can install the library from `pip`_, +like so:: + + $ pip install pyechonest + +To transcode music, this plugin requires the `ffmpeg`_ command-line tool. + +.. _pip: http://pip.openplans.org/ +.. _FFmpeg: http://ffmpeg.org + +To get fingerprinting working, you'll need to install +the `ENMFP `_ codegen +command-line tool. + +You will need to install ``ENMFP``, as a command-line tool. The ``ENMFP`` +codegen binary distribution has executables for all major OSs and +architectures. + +Configuring +----------- + +Beets includes its own Echo Nest API key, but you can `apply for your own`_ for +free from the EchoNest. To specify your own API key, add the key to your +:doc:`configuration file ` as the value for ``apikey`` under +the key ``echonest_tempo`` like so:: + + echonest: + apikey: YOUR_API_KEY + +In addition, the ``auto`` config option lets you disable automatic metadata +fetching during import. To do so, add this to your ``config.yaml``:: + + echonest: + auto: no + +The ``echonest`` plugin tries to upload files to the EchoNest server if it can +not be identified by other means. If you don't want that, disable the +``upload`` config option like so:: + + echonest: + upload: no + +The EchoNest server only supports a limited range of file formats. The +``plugin`` automatically converts unsupported files to ``ogg``. If you don't +want that, disable the ``convert`` config option like so:: + + echonest: + convert: no + +You can enable fingerprinting by editing your :doc:`configuration file +`. If the ``ENMFP`` binary is not in your path, you'll +need to add a key called ``codegen`` under the ``echonest`` section like so:: + + echonest: + codegen: PATH/TO/YOUR/CODEGEN/BINARY + +.. _apply for your own: http://developer.echonest.com/account/register