{% extends "layout.html" %}
{% set title = 'Overview' %}
{% block body %}
  <h1>Essentia {{version}} Documentation</h1>



  <div class="section" id="what-is-essentia">
    <h2>What is Essentia?<a class="headerlink" href="#what-is-essentia" title="Permalink to this headline">¶</a></h2>

    <p>Essentia is an open-source C++ library for <strong>audio analysis and audio-based music information retrieval</strong> released
    under the <strong><a href="http://tldrlegal.com/license/gnu-affero-general-public-license-v3-%28agpl-3.0%29#summary">Affero GPLv3
    license</a></strong> (also available under proprietary license upon request). It contains an <strong><a href="{{ pathto("algorithms_overview") }}">
    extensive collection of reusable algorithms</a></strong> which implement audio input/output functionality, standard digital signal processing
    blocks, statistical characterization of data, and a large set of spectral, temporal, tonal and high-level music descriptors.
    In addition, Essentia can be <strongs>complemented</strong> with <strong><a href="https://github.com/MTG/gaia">Gaia</a></strong>, a
    C++ library with python bindings which implement similarity measures and classification on the results of audio analysis, and generate
    <strong><a href="{{ pathto("installing") }}#using-pre-trained-high-level-models-in-essentia">classification
    models</a></strong> that Essentia can use to compute high-level description of music (same license terms apply).</p>

    <p>Essentia is not a framework, but rather a collection of algorithms (plus some infrastructure) wrapped in a library.
    It does not provide common high-level logic for descriptor computation (so you aren’t locked into a certain way of doing things). It
    rather focuses on the <strong>robustness</strong>, <strong>performance </strong>and <strong>optimality </strong>of the <strong>provided
    algorithms</strong>, as well as ease of use. The flow of the analysis is decided and implemented by the user, while Essentia is taking
    care of the implementation details of the algorithms being used. There is a special <strong>streaming mode</strong> in which it is possible to connect
    algorithms and run them automatically (similarly to PureData or Max/MSP) instead of specifying explicitly the order of execution with an
    advantage of less boilerplate code and less memory consumption. A number of predefined executable extractors are provided with the library
    as examples, however they should not be considered as the only correct way of doing things.</p>

    <p>Currently the following algorithms are included (among others):</p>

    <ul class="simple">
      <li><strong>Audio file input/output:</strong> ability to read and write nearly all audio file formats (wav, mp3, ogg, flac, etc.)</li>
      <li><strong>Standard signal processing blocks:</strong> FFT, DCT, frame cutter, windowing, envelope, smoothing</li>
      <li><strong>Filters (FIR &amp; IIR):</strong> low/high/band pass, band reject, DC removal, equal loudness</li>
      <li><strong>Statistical descriptors:</strong> median, mean, variance, power means, raw and central moments, spread, kurtosis, skewness, flatness</li>
      <li><strong>Time-domain descriptors:</strong> duration, loudness, LARM, Leq, Vickers' loudness, zero-crossing-rate, log attack time and other signal envelope descriptors</li>
      <li><strong>Spectral descriptors:</strong> Bark/Mel/ERB bands, MFCC, GFCC, LPC, spectral peaks, complexity, rolloff, contrast, HFC, inharmonicity and dissonance</li>
      <li><strong>Tonal descriptors</strong> Pitch salience function, predominant melody and pitch, HPCP (chroma) related features, chords, key and scale, tuning frequency</li>
      <li><strong>Rhythm descriptors</strong> beat detection, BPM, onset detection, rhythm transform, beat loudness</li>
      <li><strong>Other high-level descriptors:</strong> danceability, dynamic complexity, audio segmentation, SVM classifier</li>
    </ul>

    <p>The library is<strong> cross-platform</strong> and currently supports <a href="{{ pathto("installing") }}"><strong>Linux</strong>, <strong>Mac OS X</strong>, and partially <strong>Windows</strong>,
    <strong>iOS</strong> and <strong>Android</strong></a> systems. It can also be cross-compiled to <strong><a href="https://github.com/MTG/essentia/blob/master/FAQ.md#compiling-essentia-to-javascript-with-emscripten">JavaScript</a></strong> to be used on the web.</p>

    <p>The library is wrapped in <strong>Python</strong> (Linux and OSX) and includes a number of predefined <strong><a href="{{ pathto("extractors_out_of_box") }}">
    command-line extractors for music descriptors</a></strong> (Linux, OSX and Windows), which facilitates its use for fast prototyping and allows setting up
    research experiments very rapidly. Furthermore, it includes a <a href="http://essentia.upf.edu/documentation/vamp_plugins"><strong>Vamp plugin</strong></a>
    (Linux and OSX) that can be used with Sonic Visualiser for visualization purposes. There have been developed a number of third-party extensions to Essentia
    that allow its use within the frameworks of <a href="http://mtg.upf.edu/technologies/EssentiaRT~"><strong>PureData</strong> and
    <strong>Max/MSP</strong></a>, <a href="https://github.com/leozimmerman/ofxAudioAnalyzer"><strong>openFrameworks</strong></a>, and
    <a href="https://github.com/MTG/matlab-c-tools"><strong>Matlab</strong></a>.</p>

    <p>Essentia is designed with a focus on the robustness of the provided music descriptors and is optimized in terms of the computational
    cost of the algorithms and low memory usage. The provided functionality, specifically the music descriptors included in-the-box and signal
    processing algorithms, is <strong>easily expandable</strong> and allows for both research experiments and development of large-scale
    industrial applications. Large part of Essentia's algorithms is well-suited for
    <a href="https://github.com/MTG/essentia/blob/master/FAQ.md#using-essentia-real-time"><strong>real-time</strong></a> applications.</p>


    <h2>Crediting Essentia<a class="headerlink" href="#crediting-essentia" title="Permalink to this headline">¶</a></h2>
    <p>Please credit properly your use of Essentia! If you use the Essentia library in your software please
    acknowledge it and specify its origen as <a>http://essentia.upf.edu</a>. If you do some research and publish an article,
    cite both the Essentia paper [1] and the specific references mentioned in the documentation of the algorithms used.
    We would be also very grateful if you let us know how you use Essentia by sending an email to <a
    href="mailto:mtg@upf.edu">mtg@upf.edu</a>
    </p>

    <p>[1] Bogdanov, D., Wack N., Gómez E., Gulati S., Herrera P., Mayor O., et al. (2013).  <a
    href="http://mtg.upf.edu/node/2793">ESSENTIA: an Audio Analysis
    Library for Music Information Retrieval.</a> International Society for Music Information Retrieval Conference
    (ISMIR'13). 493-498.</p>
  </div>

  <div class="section" id="contents">

  <h2>Contents<a class="headerlink" href="#contents" title="Permalink to this headline">¶</a></h2>

  <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Contents and search</a><br/>
      <span class="linkdescr">For a complete overview of the documentation</span></p>

  <p class="biglink"><a class="biglink" href="{{ pathto("algorithms_reference") }}">Algorithm reference</a><br/>
    <span class="linkdescr">The detailed documentation for all the algorithms</span></p>

  <p class="biglink"><a class="biglink" href="doxygen/index.html">Doxygen C++ documentation</a><br/>
      <span class="linkdescr">The documentation for the base classes used in Essentia</span></p>

  <h2>Getting started</h2>
      
  <p class="biglink"><a class="biglink" href="{{ pathto("introduction") }}">Introduction</a><br/>
      <span class="linkdescr">An introduction to Essentia's main concepts</span></p>

  <p class="biglink"><a class="biglink" href="{{ pathto("installing") }}">Building and installing Essentia</a><br/>
      <span class="linkdescr">Instructions to get Essentia running on your computer</span></p>

  <p class="biglink"><a class="biglink" href="{{ pathto("algorithms_overview") }}">Algorithms overview</a><br/>
     <span class="linkdescr">A quick description of the main algorithms</span></p>

  <p class="biglink"><a class="biglink" href="{{ pathto("python_tutorial") }}">Python tutorial for beginners</a><br/>
     <span class="linkdescr">A hands-on introduction to Essentia</span></p>

  <p class="biglink"><a class="biglink" href="{{ pathto("extractors_out_of_box") }}">Using extractors out-of-box</a><br/>
     <span class="linkdescr">Quick results with no programming required</span></p>

  <p class="biglink"><a class="biglink" href="{{ pathto("FAQ") }}">Frequently asked questions</a><br/>
     <span class="linkdescr">Various tips on how to build and use Essentia</span></p>


  <h2>Using Essentia</h2>

  <p class="biglink"><a class="biglink" href="{{ pathto("design_overview") }}">Design overview</a><br/>
      <span class="linkdescr">An explanation of Essentia's basic types and classes</span></p>

  <p class="biglink"><a class="biglink" href="{{ pathto("howto_standard_extractor") }}">Using standard mode</a><br/>
      <span class="linkdescr">Learn how to write a "standard" extractor</span></p>

  <p class="biglink"><a class="biglink" href="{{ pathto("howto_streaming_extractor") }}">Using streaming mode</a><br/>
      <span class="linkdescr">Learn how to write a "streaming" extractor</span></p>

  <p class="biglink"><a class="biglink" href="{{ pathto("streaming_architecture") }}">Streaming mode architecture</a><br/>
      <span class="linkdescr">A description of how the "streaming" mode works</span></p>


  <h2>Extending Essentia</h2>

  <p class="biglink"><a class="biglink" href="{{ pathto("extending_essentia") }}">Standard algorithms</a><br/>
      <span class="linkdescr">How to write new "standard" algorithms for Essentia</span></p>

  <p class="biglink"><a class="biglink" href="{{ pathto("extending_essentia_streaming") }}">Streaming algorithms</a><br/>
      <span class="linkdescr">How to write new "streaming" algorithms for Essentia</span></p>

  <p class="biglink"><a class="biglink" href="{{ pathto("composite_api") }}">AlgorithmComposite algorithms</a><br/>
      <span class="linkdescr">The inner workings of the composite algorithms</span></p>

  <p class="biglink"><a class="biglink" href="{{ pathto("execution_network_algorithm") }}">Streaming network execution</a><br/>
      <span class="linkdescr">How Essentia's streaming scheduler works</span></p>

  <p class="biglink"><a class="biglink" href="{{ pathto("coding_guidelines") }}">Coding guidelines</a><br/>
      <span class="linkdescr">Good practices to follow when developing new algorithms</span></p>

  </div>
<!--
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
</div>

<div class="section" id="get-essentia">
<h2>Get Essentia<a class="headerlink" href="#get-essentia" title="Permalink to this headline">¶</a></h2>
<p>You can download precompiled packages for Essentia from the
<a class="reference external" href="http://static.mtg.upf.edu/mir-dev-download/essentia/">TODO download page</a></p>
<p>The code can be found in a Github repository, at <tt class="docutils literal"><span class="pre">https://github.com/MTG/essentia.git</span></tt>.</p>
<p>(Please refer to <a class="reference external" href="https://help.github.com/articles/set-up-git">this page</a>
for instructions on how to setup Git)</p>
</div>
-->

{% endblock %}