Instructions for awesome-audio-cnn

I recently made public a github repository I was working on called 'awesome-audio-cnn'. The code for the project is at github at https://github.com/radiodee1/awesome-audio-cnn . Below are the instructions that go with the project.

INSTRUCTIONS

This is a complex project. There are several steps required for a full implementation of this project. Some of the steps require resources not available to everyone. The ultimate goal is the implementation of a music server that employs a neural network to help it select which songs to play. It might be possible to implement only part of the project and render for the user a server that plays music, but without the neural network, to play selected albums in their entirety. This latter option has not been explored in this document. Finally, this project pre-supposes that the user is serving up their own music in their own house. The project is not for any sort of distribution of music, and is scaled to operate with a small library of personal selections.

1. Arrange your music in the predetermined format. Music for this project must be in the mp3 format and must be arranged in the following manner. All songs are sorted by album and are stored in folders with the artist and album title as the folder's name. These album folders are all stored in a single larger folder, usually called 'Music' or 'music'. There is generally a jpg image in each folder for the album's cover image. This file is called 'cover.jpg'. Song files that are simply dropped in the 'Music' folder without an album directory will not be recognized. Furthermore all mp3 songs should be tagged using the id3 tag system. Good tools for using mp3 files are: picard, soundjuicer, and soundconverter.
2. Download the sources for the server project. The project is currenly hosted on github and is called awesome-audio-cnn. Make a folder in your work area (or 'workspace' in eclipse terminology) for your neural network training data. You will use this folder later. For example, mine is at ~/workspace/ACNN/.
3. Install the necessary supporting software. This may include, but may not be limited to, java8, libchromaprint-tools, tomcat8, activemq, and maven. For an IDE the developer used the Intellij IDEA Community Eddition. The IDE is used for syntax verification, and the mvn command line tools are actually used for building the project.
4. Build the server and the desktop versions of the project. You can use the command ./make_music_for_war.sh /path/to/Music to set up the xml files in the project repository. You can also mount the music directory at the location /mnt/acnn/Music/ and leave the shell script unused. This mounting can be accomplished by modifying your fstab file. Use the command ./get_all.sh to see if your build environment is up to date. If the second script works you will have two files in your awesome-audio-cnn folder, one, the war file, called audio.war, and the other one called acnn-desktop.jar, the jar file.
5. Use the desktop version to setup the working environment for training the neural network. You should start the desktop version with the command java -jar acnn-desktop.jar -train. The various peices of information are stored in the user's home folder in a folder named .acnn. You need several thousand songs for this training to go well. Identify the location of the music folder to the desktop version of the software. You must also identify the folder that will hold the training data that you work with. On my computer this folder is called ~/workspace/ACNN/. It could be called anything and could be located anywhere in the user's home area. If at any time you want to start over with the training, one of the things you should do is to erase the contents of the folder ~/.acnn.
6. Use the desktop version to create the training 'csv' file. Originally the file is called 'myfile_1.csv' but you can change the name by clicking buttons on the desktop user interface. After you have set up all the directories and the filenames you should click the Make List button. This makes the csv list of your songs that is used in neural network training.
7. Begin training your neural network. Training is an iterative process and requires the /usr/bin/fpcalc program installed with libchromaprint-tools. You press the buttons on the interface in a certain order and you watch the terminal that you started the interface in. Basically you press the Train button and watch the screen. When a certian time has expired you press the Clear-Break button. Wait for the neural network model software to save the model. Then press the Test button to evaluate your progress. Wait while the testing software goes through the test set. At the end of the test phase you end up with a score. The score starts out at something like 0.5 but will improve with extensive periods of training. Repeat this process (#7) until you get a testing score between '0.85' and '0.95'. I stopped at a '0.94' score. Two files are created in this process. They are named (originally) fp-test.bin and fp-test.updater.bin. The base of the name ('fp-test') can be changed to anything you like during training, but must have the name 'fp-test' when the web site is launched.
8. Prepare to deploy the war file. This is one of the areas where the requirements of the project are very specific. The audio.war file is meant to reside on a tomcat8 server that is connected by a dedicated IP address to a wifi router. The server is connected by cat cable. This way anyone in the area of the router can access the server via the IP address and play the music stored there. The server is meant for private use. The war file expects to find your two neural network files in the folder /opt/acnn/. Here it will setup another folder /opt/acnn/.acnn/ which is in most ways identical to the one that the desktop jar file creates in your home folder. The /opt/acnn/ folder should contain the two neural network '.bin' files and also the file myfile.id3tag.csv. If this csv file is not present the program will try to create it. Maintaining this file is covered in the next step.
9. Whenever you change the contents of your music file, and when you first setup your server, you must supply the audio.war file with a new copy of the myfile.id3tag.csv file. Start the desktop version of the program with the command java -jar acnn-desktop.jar -id3. After a few minutes the program will exit, leaving a new copy of the file in the training data folder. On my computer this would be in the ~/workspace/ACNN/ folder. Copy this file to the server computer and put it (with the permissions that will allow it to be read universally) in the /opt/acnn/ folder. There should be one entry in this csv file for every mp3 file that the server has access to.
10. Go through the README.md document and make sure that you have edited all the tomcat and activemq configuration files to allow the server to do its job. For activemq type the following.
    $ cd /etc/activemq/instances-enabled
$ sudo ln -s ../instances-available/main .
    For the tomcat8 server you must specify memory sizes for startup of the catatlina engine. Add the following line to the beginning of the catalina.sh file at the location /usr/share/tomcat8/bin/.
    export CATALINA_OPTS="$CATALINA_OPTS -Xms1024m -Xmx4g"
    For the tomcat8 admin interface, change the following to allow larger files to be processed. The web manager upload size must be changed. /user/share/tomcat8-admin/manager/WEB-INF/web.xml needs to have the following code:
    <multipart-config>
<!-- 52MB max -->
<max-file-size>52428800</max-file-size>
<max-request-size>52428800</max-request-size>
<file-size-threshold>0</file-size-threshold>
</multipart-config>
    I added a zero to both 'max' numbers mentioned above.
11. Set up the mysql database. To do this you should have root privileges. Type mysql -u root -p. When prompted enter the root password. Then type this:
    mysql> create database acnn;
mysql> grant all on acnn.* to 'testuser'@'localhost' identified by 'fpstuff';
12. Stop the tomcat8 webserver on the server computer. This can be achieved by typing sudo /etc/init.d/tomcat8 stop. Copy the audio.war file to the directory /var/lib/tomcat8/webapps/. Restart the server with the command sudo /etc/init.d/tomcat8 restart. Navigate to the server with your favorite browser on your favorite device and listen to your music.