Merge pull request #56 from MTG/dev

Added essentia.js-model add-on module and changes related to 0.1.1 release

AUTHORS.md

@@ -0,0 +1,19 @@
+# Essentia.js developers & contributors
+
+## Developers
+
+- [Albin Correya](https://albincorreya.github.io/) 
+  - Main author of the Essentia.js project, API, add-on modules and build scripts. Currently a maintainer/contributor.
+- [Jorge Marcos](https://github.com/jmarcosfer) 
+  - Current developer/maintainer of Essentia.js. Developed real-time examples, tutorials etc.
+- [Dmitry Bogdanov](https://dbogdanov.com/) 
+  - Supervision, PR review and main developer/maintainer of the upstream Essentia library.
+- [Pablo Alonso](https://palonso.github.io/)
+  - Essentia Tensorflow models for TensorFlow.js. Co-developer of upstream Essentia library.
+- [Luis Joglar-Ongay](http://www.luisjoglar.com) 
+  - Benchmarking of Essentia.js and audio problem detection applciation use-case example.
+- [Next-Awesome-Person?](./CONTRIBUTING.md)
+
+## Contributors
+
+- [Next-Awesome-Person?](./CONTRIBUTING.md)

CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.1] - 2021-06-20
+
+### Added
+
+- Added `essentia.js-model` add-on module to facilitate the end-to-end use of a collection of pre-trained tensorflow.js audio ML models.
+- Added both realtime and offline use-case examples for using essentia.js and tensorflow.js along with documentation.
+
+
+### Changes
+
+- Changed namespaces in node.js entrypoint. ie. Now, all the add-on modules are also exposed in the node.js import (see #50).
+- Re-organized the directory structure of the source code and related scripts in terms of category of the module.
+- Essentia WASM backend sync build files are now distributed as both UMD and ES6 compatiable formats (`essentia-wasm.umd.js` and `essentia-wasm.es.js`).
 
 ## [0.1.0] - 2020-09-14
 

CONTRIBUTING.md

@@ -1,8 +1,12 @@
-# Contribute to `essentia.js`
+# How to contribute to Essentia.js?
 
-You are more than welcome to collaborate and submit your contributions to `Essentia.js`. The best practice of submitting your code is by creating pull requests to our GitHub [repository](https://github.com/MTG/essentia.js) following our contribution policy. 
+Everyone is welcome to contribute, and we value everybody's contribution. Code is thus not the only way to help the community. Answering questions, filling issues, feature requests, helping others, reaching out and improving the documentations are immensely valuable to the community. It also helps us if you spread the word thorugh reference of the library in your projects or shout-out on Twitter.
 
-By submitting your code you authorize that it complies with the Developer's Certificate of Origin.
+Whichever way you choose to contribute, please be mindful to respect our [code of conduct](https://berlincodeofconduct.org/).
+
+## Code contribution
+
+The best practice of submitting code is by creating pull requests to the [dev branch](https://github.com/MTG/essentia.js/tree/dev) our GitHub [repository](https://github.com/MTG/essentia.js) following the contribution policy. By submitting your code you authorize that it complies with the Developer's Certificate of Origin.
 
 > ### Developer’s Certificate of Origin
 
@@ -17,7 +21,3 @@ By submitting your code you authorize that it complies with the Developer's Cert
 > (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
 
 Based on https://gcc.gnu.org/contribute.html and http://elinux.org/Developer_Certificate_Of_Origin
-
-We encourage sharing with us any ideas on how we can improve Essentia.js and the best way to do this is by creating github issues for bug reports, feature requests and improvement ideas.
-
-You are also more than welcome to suggest any improvements, including proposals for new algorithms, etc.

Dockerfile

@@ -1,4 +1,4 @@
-ARG EMSCRIPTEN_VERSION=latest
+ARG EMSCRIPTEN_VERSION=1.39.19
 FROM emscripten/emsdk:${EMSCRIPTEN_VERSION}
 
 ENV LANG C.UTF-8
@@ -8,7 +8,7 @@ RUN apt-get update \
     && apt-get install -y cmake curl nano python-dev python-numpy-dev libpython2.7 python-pip libeigen3-dev \
     && mkdir /essentia && cd /essentia && git clone https://github.com/MTG/essentia.git \
     && cd /essentia/essentia/packaging/debian_3rdparty \
-    && bash -C "./build_eigen3.sh" && cd ../../ \
+    && bash -C "./build_eigen3.sh" && cd ../../  && chmod +x waf \
     && emconfigure sh -c './waf configure --prefix=$EMSCRIPTEN/system/local/ --build-static --fft=KISS --emscripten --static-dependencies' \
     && emmake ./waf && emmake ./waf install \
     &&  apt-get remove -y python-dev libeigen3-dev \

Makefile.essentiajs

@@ -1,8 +1,8 @@
-ESSENTIAJS_VERSION=0.1.0-dev
+ESSENTIAJS_VERSION=0.1.1
 ## Path to libs for Emscripten
 LIB_DIR_ESSENTIA=$(EMSCRIPTEN)/system/local/lib
 EIGEN_PATH=/usr/local/include/eigen3
-## pass custom build and dist directories using system environment variables
+## Pass custom build and dist directories using system environment variables
 BUILD_DIR_ES := $(or $(ESSENTIAJS_WASM_BUILDS_DIR),builds)
 DIST_DIR_ES := $(or $(ESSENTIAJS_BUILDS_DIR),dist)
 ## C++ source code for Essentia.js
@@ -12,10 +12,13 @@ INCLUDE_ESSENTIAJS=src/cpp/includes/essentiajs.cpp
 ESSENTIA_JS_WEB=$(BUILD_DIR_ES)/essentia-wasm.web.js
 ESSENTIA_JS_WEB_WASM=$(BUILD_DIR_ES)/essentia-wasm.web.wasm
 ESSENTIA_JS_MODULE=$(BUILD_DIR_ES)/essentia-wasm.module.js
+ESSENTIA_WASM_UMD_MODULE=$(BUILD_DIR_ES)/essentia-wasm.umd.js
+ESSENTIA_WASM_ES6_MODULE=$(BUILD_DIR_ES)/essentia-wasm.es.js
 ## Path to custom --pre-js and --post-js files for Emscripten
 PRE_JS_WASM=src/js/wasm.module.pre.js
 POST_JS_WEB_WASM=src/js/wasm.webmodule.post.js
 POST_JS_ES6_WASM=src/js/wasm.es6module.post.js
+POST_JS_UMD_WASM=src/js/wasm.umd.post.js
 
 codegen:
 	@echo "Generating cpp source code from essentia python bindings ..."
@@ -58,12 +61,21 @@ build:
 
 	@cat $(PRE_JS_WASM) $(ESSENTIA_JS_WEB) > $$.tmp && mv $$.tmp $(ESSENTIA_JS_WEB)
 	@cat $(PRE_JS_WASM) $(ESSENTIA_JS_MODULE) > $$.tmp && mv $$.tmp $(ESSENTIA_JS_MODULE)
-	@cat $(POST_JS_ES6_WASM) >> $(ESSENTIA_JS_MODULE)
+
+	@cp -f $(ESSENTIA_JS_MODULE) $(ESSENTIA_WASM_ES6_MODULE)
+	@cat $(POST_JS_ES6_WASM) >> $(ESSENTIA_WASM_ES6_MODULE)
+
+	@cp -f $(ESSENTIA_JS_MODULE) $(ESSENTIA_WASM_UMD_MODULE)
+	@cat $(POST_JS_UMD_WASM) >> $(ESSENTIA_WASM_UMD_MODULE)
+
+	@rm -f $(ESSENTIA_JS_MODULE)
 
 	@mkdir -p $(DIST_DIR_ES)
 	@cp -f $(ESSENTIA_JS_WEB) $(DIST_DIR_ES)/
 	@cp -f $(ESSENTIA_JS_WEB_WASM) $(DIST_DIR_ES)/
-	@cp -f $(ESSENTIA_JS_MODULE) $(DIST_DIR_ES)/
+	@cp -f $(ESSENTIA_WASM_UMD_MODULE) $(DIST_DIR_ES)/
+	@cp -f $(ESSENTIA_WASM_ES6_MODULE) $(DIST_DIR_ES)/
+
 	@echo "Done ..."
 
 	@echo "Removing unnecessary files ..."

README.md

@@ -6,19 +6,34 @@
 [![npm version](https://badge.fury.io/js/essentia.js.svg)](https://badge.fury.io/js/essentia.js)
 [![](https://data.jsdelivr.com/v1/package/npm/essentia.js/badge)](https://www.jsdelivr.com/package/npm/essentia.js)
 
-A JavaScript library for music/audio signal analysis and processing for both real-time and offline use-cases. The core of [`essentia.js`](/) is powered by [Essentia C++ library](https://essentia.upf.edu) back-end using [WebAssembly](https://webassembly.org/) along with a high-level Typescript API and add-on utility modules. ie, Now you can run a extensive collection of music/audio processing and analysis algorithms on your web-browser or Node.js applications with ease-of-use. [`essentia.js`]() also provides additional modules for easy-to-use configurable feature extractors for some selected features and helper classes for visualizing common music processing features directly into your HTML web page using [Plotly.js](https://plotly.com/javascript/) library.
+
+`Essentia.js` is a JavaScript (JS) library for music/audio signal analysis and processing developed at the [Music Technology Group, UPF, Barcelona](https://www.upf.edu/web/mtg/). The core of library is powered by [Essentia C++ library](https://essentia.upf.edu) back-end using [WebAssembly](https://webassembly.org/) built via [Emscripten](https://emscripten.org/) along with a high-level JS and TypeScript API and add-on utility modules. ie, You can run an extensive collection of music/audio processing and analysis algorithms/models on your web browser or Node.js runtime applications. It supports both real-time and offline audio analysis use-cases.  
+
+The packaged add-on modules includes configurable feature extractors for some selected features, interface for feature extraction and inference of a collection of pre-trained audio ML models using [Tensorflow.js](https://www.tensorflow.org/js), some helper classes for visualizing common music processing features directly into your HTML web page using [Plotly.js](https://plotly.com/javascript/) library.
+
+- License: [https://essentia.upf.edu/licensing_information.html](https://essentia.upf.edu/licensing_information.html)
 
 - Repository: [https://github.com/MTG/essentia.js](https://github.com/MTG/essentia.js)
 
 - Releases: [https://github.com/MTG/essentia.js/releases](https://github.com/MTG/essentia.js/releases)
 
-- License: [https://essentia.upf.edu/licensing_information.html](https://essentia.upf.edu/licensing_information.html)
+
+- Live demos: [https://mtg.github.io/essentia.js/examples](https://mtg.github.io/essentia.js/examples)
+
 
 - Documentation: [https://mtg.github.io/essentia.js/docs/api](https://mtg.github.io/essentia.js/docs/api/)
-
-- Examples: [https://mtg.github.io/essentia.js/examples](https://mtg.github.io/essentia.js/examples)
 
+- Tutorials: [https://mtg.github.io/essentia.js/docs/api/list_tutorial.html](https://mtg.github.io/essentia.js/docs/api/list_tutorial.html)
+
 
 You are also most welcome to [contribute](CONTRIBUTING.md) to `essentia.js`. 
 
-> NOTE: Currently under active-development, some of the algorithms are not yet manually tested on the JavaScript front. Please submit the issues at https://github.com/MTG/essentia.js/issues.
+> NOTE: Essentia.js is currently under rapid development. This means that APIs and features will evolve. It is recommended that devs who adopt essentia.js today upgrade their installation as new releases become available, as backwards compatibility is not yet guaranteed. Some of the algorithms are not yet manually tested on the JavaScript front. Please submit the issues at https://github.com/MTG/essentia.js/issues.
+
+## Citing essentia.js
+If you want to cite essentia.js in a scholarly work, please use the following reference.
+
+
+> Albin Correya, Dmitry Bogdanov, Luis Joglar-Ongay, Xavier Serra. “Essentia.js: A JavaScript Library for Music and Audio Analysis on the Web”, 21st International Society for Music Information Retrieval Conference, Montréal, Canada, pp. 605-612. 2020.
+
+

build-docs.sh

@@ -1,11 +1,16 @@
 #!/usr/bin/env bash
 set -e -x
 
-tsc src/typescript/core_api.ts || exit 1
-tsc src/typescript/extractor.ts || exit 1
-tsc src/typescript/plot.ts || exit 1
+tsc --lib ES2015,DOM src/typescript/core_api.ts || exit 1
+tsc --lib ES2015,DOM src/typescript/extractor/extractor.ts || exit 1
+tsc --lib ES2015,DOM src/typescript/display/plot.ts || exit 1
+tsc --lib ES2015,DOM src/typescript/machinelearning/index.ts || exit 1
+tsc --lib ES2015,DOM src/typescript/machinelearning/tfjs_input_extractor.ts || exit 1
+tsc --lib ES2015,DOM src/typescript/machinelearning/tfjs_models.ts || exit 1
 
-echo "Generating js docs"
+rm -rf docs/api
+
+echo "Generating JS docs"
 node node_modules/jsdoc/jsdoc.js \
     -c jsdoc.config.json -t node_modules/foodoc/template \
     -R docs/index.md -u docs/tutorials . || exit 1
@@ -14,4 +19,4 @@ mkdir -p docs/api
 cp -rf out/. docs/api/
 rm -rf out
 
-find src/typescript/ -maxdepth 1 -type f -name "*.js" -delete 
+find src/typescript/ -maxdepth 2 -type f -name "*.js" -delete 

build-libs.sh

@@ -21,6 +21,9 @@ $NPM_PATH install
 # Build essentia.js JS API and add-on modules
 $NPM_PATH run build-js-api
 
+# Minified build of JS API and add-on modules
+$NPM_PATH run build-js-api rollup.config.min.js
+
 # Run tests
 echo "Running tests ..."
 $NPM_PATH test