yaafe

Audio features extraction

https://github.com/yaafe/yaafe

Repository

Audio features extraction

README.rst

=======
 Yaafe
=======

Yet Another Audio Feature Extractor
+++++++++++++++++++++++++++++++++++


Build status
============
- Branch **master** : |travis_master|
- Branch **dev** : |travis_dev|
- Anaconda : |anaconda_build|

.. |travis_master| image:: https://travis-ci.org/Yaafe/Yaafe.svg?branch=master
    :target: https://travis-ci.org/Yaafe/Yaafe

.. |travis_dev| image:: https://travis-ci.org/Yaafe/Yaafe.svg?branch=dev
    :target: https://travis-ci.orgYaafe/Yaafe

.. |anaconda_build| image:: https://anaconda.org/yaafe/yaafe/badges/installer/conda.svg
   :target: https://anaconda.org/yaafe/yaafe/builds


Install
=======

Conda
-----

.. |conda| image:: https://anaconda.org/yaafe/yaafe/badges/installer/conda.svg
   :target: https://anaconda.org/conda-forge/yaafe

|conda|

Yaafe can be easily install with `conda `_. To install this package with conda run::

  conda install -c conda-forge yaafe


Docker
------

.. |docker| image:: https://badge.imagelayers.io/yaafe/yaafe:latest.svg
   :target: https://imagelayers.io/?images=yaafe/yaafe:latest

|docker|

Yaafe can also be install through `Docker `_.

Get the official *Yaafe* image from `Yaafe repository on Docker Hub `_::

  docker pull yaafe/yaafe
  docker tag yaafe yaafe/yaafe

or build it from the sources directory::

    docker build --tag=yaafe .

Following both of the method above, you then have a docker image tagged as *yaafe*.
The ``yaafe`` command is the entrypoint for that docker image so you can run 'yaafe' from the command line through `docker run yaafe`. For example::

    docker run -it yaafe --help
    docker run -it yaafe --volume=$(pwd):/wd  --workdir=/wd -c resources/featureplan -r 16000 --resample resources/yaafe_check.wav

On Linux, it can be usefull to create an ``alias`` for it::

  alias yaafe='docker run -it --rm=true --volume=$(pwd):/wd  --workdir=/wd yaafe'

You could then simply run::

  yaafe --help
  yaafe -l

et voilà !

If you need to set the docker user as the current user on the host, you could try to run docker with the  ``-u $(id -u):$(id -g)`` option ::

    docker run -it --rm=true --volume=$(pwd):/wd  --workdir=/wd -u $(id -u):$(id -g) yaafe -c resources/featureplan -o h5 -r 16000 --resample resources/yaafe_check.wav

Last but not least, the entry-point for the *yaafe* docker image is smart :

- every command that start with a dash ``-`` will be pass as options to the ``yaafe`` command inside the docker container
- every command that does not start with a dash will be treated as a regular command. For example::

    docker run -it yaafe /bin/bash

will give you access to a bash terminal inside the docker. And ::

    docker run -it yaafe yaafe-engine --help

will launch the  ``yaafe-engine` batch processing tool.



From sources
------------

*Yaafe* source code should compile on *linux* and *MacOsX* platform, and uses CMake as compilation tool.
Yaafe requires third-party libraries to enable specific features. Some of these libraries may already be available on your system.

The `argtable `_ library is required.

The `eigen `_  library is also required. You could either installed it through your regular packages manager (e.g. `libeigen3-dev `__ on Debian) and then pass the ``-DWITH_EIGEN_LIBRARY=ON`` option flag to ``ccmake``. 
Or you can use the source code provided through the git submodule included in the Yaafe git repository and which you can get with the ``git submodule update --init`` command. *If you used ``git clone --recursive`` to clone Yaafe, you don't need this.*


Depending on optional features you want to use, other librairies may be used:

* `libsndfile `_: enable reading WAV files format (highly recommanded)
* `libmpg123 `_: enable reading MP3 audio files
* `HDF5 `_ >= 1.8: enable H5 output format
* `liblapack `_: enable some audio features (LSF)
* `FFTW3 `_: use FFTW instead of Eigen for FFT computations (pay attention to licensing issues when linking with the GPL FFTW3 library).

To use the *yaafe* script you need Python >= 2.5, and the numpy package.

Once previous libraries are installed (some may have been locally installed in ),
you can compile with the following steps: ::

 mkdir build
 cd build
 ccmake -DCMAKE_PREFIX_PATH= -DCMAKE_INSTALL_PREFIX= ..
 make
 make install

If you use an external eigen library (and not the one provided by git submodule), don't forget to add the  flag: ::

 ccmake -DCMAKE_PREFIX_PATH= -DCMAKE_INSTALL_PREFIX= -DWITH_EIGEN_LIBRARY=ON ..


Several options can control Yaafe compilation. More details can be found at:
	http://yaafe.sourceforge.net/manual/install.html


Environment
~~~~~~~~~~~

To easily use Yaafe, you should set the following environment vars::

 export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$DEST_DIR/lib

On MacOSX replace ``LD_LIBRARY_PATH`` by ``DYLD_FALLBACK_LIBRARY_PATH``

The output of ``make install`` should give you the INSTALL_DIR path (defaults to ``/usr/local``). The python files are installed in ``/usr/local/lib/python2.7/site-packages``, which is *not* by default in the python path on MacOSX.
The consequence is the error ``ERROR: cannot load yaafe packages:  No module named yaafelib``.
There are 3 ways to solve this problem :

* The simplest way is to add the line ``sys.path.append("/usr/local/lib/python2.7/site-packages")`` in ``/usr/local/bin/yaafe`` after ``from optparse import OptionParser``, but it won't let you use the yaafelib unless you add this line (and import sys) before each import of yaafelib.

* You can use ``export PYTHONPATH=/usr/local/lib/python2.7/site-packages:$PYTHONPATH`` or add it to your ~/.bash_profile, but this will affect other versions of python.
* You can move the files to a site-package folder that is in your PYTHONPATH:
	* if you use Python 2: ``mv /usr/local/lib/python2.7/site-packages/yaafefeatures.py /usr/local/lib/python2.7/site-packages/yaafelib `python -c 'import sys, re ; print next(i for i in sys.path if re.match(".*site-packages$", i))'``
	* if you use Python 3: ``mv /usr/local/lib/python2.7/site-packages/yaafefeatures.py /usr/local/lib/python2.7/site-packages/yaafelib `python3 -c 'import sys, re ; print(next(i for i in sys.path if re.match(".*site-packages$", i)))'``

If you use Matlab, you can set your MATLABPATH var::

 export MATLABPATH=$MATLABPATH:$DEST_DIR/matlab


Documentation
=============

Documentation is also available online: http://yaafe.github.io/Yaafe/ (mirror:  http://yaafe.sourceforge.net/)

To build documentation, you need Sphinx.
Before building documentation, you should set your environment correctly so that sphinx builds documentation
with automatic features documentation.

To build documentation, just run ``make doc_python`` in the ``build`` directory. Documentation is built in ``doc/doc_python/html``.

License
=======

YAAFE is released under the version 3 of the GNU Lesser General Public License. Read COPYING and COPYING.LESSER for
more details. The user should also read DISCLAIMER before linking with optional libraries which have different license policy.

Support
=======

To get help with YAAFE, use the mailing-list yaafe-users@lists.sourceforge.net (registration
at https://lists.sourceforge.net/lists/listinfo/yaafe-users ).


Credits
=======

Yaafe was first developed at `Telecom Paristech / AAO Team `_. It uses several great open-source projects like `Eigen `_, `Smarc `_, `libsndfile `_, `mpg123 `_, `HDF5 `_.

If you want to cite Yaafe in a publication, please see `CITATION `_.

Citation (CITATION.rst)

Citation
========
If you are using *Yaafe* in research work for publication,
please cite:

    "*YAAFE, an Easy to Use and Efficient Audio Feature Extraction Software.*",

    Mathieu, B., Essid, S., Fillon, T., Prado, J. & Richard, G.,

    In Proceedings of the 11th International Society for Music Information Retrieval Conference. Utrecht, The Netherlands. August 9-13 2010, pp. 441--446.

`Download PDF <http://ismir2010.ismir.net/proceedings/ismir2010-75.pdf>`_


BibTex
======
BibTeX entry for LaTeX users is:
::

  @InProceedings{MathieuEtAl_2010_YaafAnEasyTo,
	author = "Mathieu, Benoit and Essid, Slim and Fillon, Thomas and Prado, Jacques and Richard, Gaël",
	title = {YAAFE, an Easy to Use and Efficient Audio Feature Extraction Software},
	year = 2010,
	address = "Utrecht, The Netherlands",
	pages = "441--446",
	month = "August 9-13",
	booktitle = "Proceedings of the 11th International Society for Music Information Retrieval Conference",
	note = {\url{http://ismir2010.ismir.net/proceedings/ismir2010-75.pdf}}
  }

GitHub Events

Committers

Last synced: over 3 years ago

Issues and Pull Requests

Last synced: almost 3 years ago

Packages