#+TITLE: Rusty Microphone

[[https://travis-ci.org/JWorthe/rusty_microphone][https://travis-ci.org/JWorthe/rusty_microphone.svg?branch=master]]

* Summary

The goal of this project is to create a dashboard for real-time
feedback to musicians while they are practicing. This is a personal
needs project, and so will at least initially focus only on the
trumpet and working on my intonation.

More information on how the project works can be read [[https://www.worthe-it.co.za/programming/2017/08/14/rusty-microphone.html][here]].

[[https://www.worthe-it.co.za/rusty-microphone/][Live demo]]

* Getting started

** Environment Setup

This is a Rust project. The latest version of the Rust compiler and
Cargo are available from your system's package manager, or from
https://www.rust-lang.org/.

The project depends on two native libraries: GTK and
Portaudio. These need to be preinstalled.

On OSX, this can be done with Homebrew using

#+BEGIN_SRC sh
brew install pkg-config
brew install gtk+3
brew install portaudio
#+END_SRC

On Ubuntu, you can skip the portaudio install since it can be compiled
as part of the build process. You still need to install GTK though,
like so:

#+BEGIN_SRC sh
apt-get install libgtk-3-bin libgtk-3-dev libpango1.0-0
#+END_SRC

On Fedora

#+BEGIN_SRC sh
yum install gtk3-devel portaudio-devel
#+END_SRC

** Compiling and running

To compile the project:

#+BEGIN_SRC sh
cargo build
#+END_SRC

To compile and run:

#+BEGIN_SRC sh
cargo run
#+END_SRC

To compile and run unit tests. Use this as the CI build command if
setting up a CI server.

#+BEGIN_SRC sh
cargo test
#+END_SRC

** WebAssembly

This project also supports WebAssembly as a compilation target. To
start, you need to install the nightly rust compiler toolchain and
~wasm32-unknown-unknown~ target. If you installed Rust using Rustup,
then you can do this with

#+BEGIN_SRC sh
rustup toolchain install nightly
rustup target add wasm32-unknown-unknown --toolchain nightly
#+END_SRC

You can then compile the project with Make.

#+BEGIN_SRC sh
make build-web
#+END_SRC

If you choose not to use Make, you can look in ~Makefile~ for the
instructions that ~make build-web~ is actually an alias for.

After compiling, open ~target/site/index.html~ in any modern web
browser.

* Project structure
** File Structure

- Dependencies are declared in ~Cargo.toml~
- The project main function for the project executable is in
  ~src/main.rs~. This should only be an entry point. Any actual
  functionality should be part of the library build.
- The other files to be included in the build are declared in
  ~src/lib.rs~.
- Unit tests are kept in the same files as the units they are testing.
- The main function will launch the GUI in ~src/gui.rs~. From here,
  the GUI can call out to the other parts of the library as required.

** General Architectural Guidelines

- Try to keep functions pure when possible. If not possible, try to
  isolate the impure parts.
- Split functionality into files based on their logical separation of
  concerns. Try to keep mathematical processing separate from
  presentation logic, so that the processing can be reused
  independently.

* System Requirements

I have tested this project and found it to be working on a Linux
system. It should also work under MacOS.

Unfortunately, Windows is not currently supported. If you wish to
contribute to adding Windows support, the most useful approach would
be to take a look at the [[https://github.com/RustAudio/rust-portaudio/issues/71][open issue in rust-portaudio]] for supporting
Windows in their build script.