====================
       MixVis
====================

ABOUT
====================
MixViz is an audio production tool that help users visualize potential problem areas in an audio mix that are preventing sounds in the mix from coming through clearly.

Frequently a high level goal that a user has when mixing audio is to make each sound they put into the mix sound as clear and distinct as possible in the final mix. However, when you start mixing many sounds together, they inevitably begin to interfere with each other and cause auditory masking. When two sounds contain strong energy in overlapping frequency bands, one of the sounds may become muddied or masked in those frequency ranges. This is usually undesirable in an audio mix.

How does a user mixing audio identify masked frequency bands? It typically takes an expert audio engineer to find the muddied tracks and correct them. We believe that a tool should exist to make this process more intuitive, so we created MixViz.

MixViz presents the user with a two-dimensional visualization where the x-axis is spatial location and the y-axis is frequency. Each sound source is assigned a color hue. All sound sources are analyzed for masking using a model of human audition and masked regions and displayed as white in the visualization.


PREREQUISITES
====================
- Linux OS (Currently only tested on Ubuntu 14.04 LTS)
- Ardour digital audio workstation (I'm using 3.5.403)
- JACK Audio Connection Kit (http://jackaudio.org/) (I'm using 1.9.10)
- FFTW3 fft libraries (http://www.fftw.org/)
- loudness modeling library (https://github.com/jondavidford/loudness)
- Some third party DAW that is compatible with JACK (Ardour works)
- Various dev libraries. the required packages for Ubuntu are
  - g++
  - libjack-jackd2-dev
  - mesa-common-dev
  - libgl1-mesa-dev
  - libasound2-dev
  - libfreetype6-dev
  - libxinerama-dev
  - libxcursor-dev
  - freeglut3-dev


INSTALLATION
====================
1. Pull down the code from repository
2. Go into the Builds/Linux directory and run "make"
  - If the project fails to compile due to a missing header, use 'apt-file search "example-header.h"' and install a dev library with the header in it via apt-get. Let me know which library you had to install.
  - If the project fails to link due to a missing library, try doing a google search for that file and install the dev library that you find via apt-get.
3. The executable MixVis should now be in Builds/Linux/build


RUNNING THE VISUALIZER
====================
1. Start jackd (the jackd server) via QjackCtl
2. Start up the visualizer (./Builds/Linux/build/Mixvis). You must be in the directory Builds/Linux so that MixViz can find the required filter files.
3. Start up your third party audio application. I have been using Ardour which seems to play very nicely with Jack.
4. Make the appropriate connections via the Jack Audio Connection Kit patchbay. The outputs from your third party application should be routed to the inputs on the device "MixVisJACK". in_1 of MixVisJack corresponds track_1/audio_out 1, in_2 corresponds track_1/audio_out 2 and so on. Currently up to EIGHT stereo tracks are supported. The names of the output sockets in the patchbay will be pulled into MixViz when the Load Tracks Button is used to load a file, so name them appropriately. The names of the input sockets MUST BE LEFT AS THE DEFAULT 'Input Socket n'. After you've created the patchbay definition, save it and you can load the names within MixViz by using the Load Tracks Button. In order to use with mono tracks, set your mono tracks to have stereo output in your third party application.

USING THE VISUALIZER
====================
First, select the audio buffer size you are currently using with Jack (found in Setup->Frames/Period). Use the Load Tracks Button and select the .xml file generated when you saved the Jack patchbay definition to load tracks into MixViz. Move tracks around to different groups as desired. Play audio through your third party application and it should be visualized. White areas represent potential problem areas, or masking. Adjust slider settings as desired, their effects are displayed in tooltips if you hover over the slider label.