Audio Cat (Beautiful Audio Editor)

Overview

This audio editor runs in a web browser and uses the Web Audio API. Chi made some efforts to embed it within a web view and make it an Android app, but halted after facing memory issues.

This project uses Google Closure, which encompasses a javascript compiler, library, Google Stylesheets (GSS - which lets us compile CSS), and soy templates (for structuring pieces of HTML). Closure standardizes javascript. For instance, it introduces private/protected variables, normal (non-prototypical) inheritance like java, and compile-time error checking.

This is not an official Google product. Chi just thought that the Chrome Web Store needed a nimble audio editing tool, both before and after Android apps can run on Chromebooks.

Setup

1. Install java.

2. Give Google Closure build tools relevant execute permissions:

chmod a+x third_party/closure_library/closure/bin/build/closurebuilder.py
chmod a+x third_party/closure_library/closure/bin/build/depswriter.py
chmod a+x third_party/closure_templates/SoyToJsSrcCompiler.jar
chmod a+x third_party/closure_stylesheets/closure-stylesheets-20111230.jar

Building

The project uses a python script (do.py) for building, which is kind of simple. We're open to using more robust build systems such as bazel or gulp.

Some uses:

Compile the javascript (including soy templates) and CSS, which is outputted into the build directory:

python do.py

Lint the javascript. In other words, find style violations:

python do.py lint

Running the Editor

To run the editor, start up a web server in the home repository directory. For example, in the repository directory, run

python -m SimpleHTTPServer

to start a local server on port 8000.

You can then view the compiled editor at http://localhost:8000/build/compiled.html

You can view the uncompiled editor at http://localhost:8000/build/uncompiled.html

While developing, you don't have to recompile to view changes in the uncompiled version. However, you have to recompile to see changes if you made changes to the dependency graph (altered calls to goog.require), made any stylesheet changes (changes to GSS files), or altered soy templates (which generate javascript files upon template compilation).

Coding Guidelines

This project currently uses Google's javascript style guide.

To help check for style throughout the project, run python do.py lint in the home audio-cat directory.

Code Organization

Location

Source code is located in the src folder.

• src/js/original contains hand-written source code.
• src/js/auto_generated contains javascript generated by tools such as the soy template compiler, which compiles .soy files into javascript classes.
• src/js/test contains code related to testing. When coding a complex object like a volume envelope, it helps to write the test first and then code up a class that adheres to the test.

Documentation

Soon, each folder will have a README describing its contents. Each javascript file also contains a block comment describing it. TODO(chihuahua): uh... do that. write those readmes.

Organization of JavaScript Classes

In broad strokes, this project's javascript classes fall into 5 categories:

src/js/original/state

This folder contains files that maintain the state of individual audio projects. For instance, audioCat.state.Track maintains information about the sections within a track. audioCat.state.Section contains information about an individual section. audioCat.state.Clip encapsulates information about an individual clip within a section.

Classes in this folder typically dispatch events when their states change, notifying other entities such as audio-play-related and UI entities of changes in state.

For instance, when a new track is added, the audioCat.state.TrackManager fires an event notifying the audio graph to play the track as well as the UI (audioCat.ui.TrackListingManager) to visualize the track.

src/js/original/audio

This folder contains classes related to playing audio and hooking up with the Web Audio API. For instance, audioCat.audio.play.PlayManager maintains the current play status. audioCat.audio.AudioGraph maintains the connections between junctions in the audio graph.

Files in this directory heed events dispatched by entities within src/js/original/state as well as fires its own events for the UI to listen to. For instance, when playing starts, the UI responds by switching the play icon to a pause icon.

src/js/original/ui

This folder contains files that updates the UI. Classes in this folder typically encapsulate state and audio play. When the user interacts with the UI, classes in this folder directly modify the state objects. The state then fires events that update the UI.

src/js/original/app

The files in this directory hook up the whole app together. app.js for instance is a megamoth file that instantiates the whole app.

src/js/original/action

This folder contains Action objects that perform a certain action. Each action object can be retreived from the ActionManager by a specific key. We can invoke actions based on various interactions.

src/js/original/utility

This folder is a collection of convenience classes that are used throughout the project. For instance, audioCat.utility.IdGenerator generates IDs unique throughout the application used by many types of objects.

src/js/original/android

This folder contains code that allows the editor to be embedded within an Android web view. Efforts towards making a mobile app were abandoned after the decision to keep the editor a web app. This folder is basically a noop.

Testing

Unit tests currently use Google Closure's junit library. To add a unit test,

1. Code up a _test.js and _test.html file. See id-generator_test for an example.
2. Run python do.py to aggregate all tests into auto_generated/all_tests.js.

Unit tests for certain javascript classes can be run by starting a web server in the home repository directory, again with say

python -m SimpleHTTPServer

and then visiting say (for port 8000 on localhost):

http://localhost:8000/src/js/test/tests.html

Click Start to run tests.

We currently lack integration tests with say web driver, Selenium, or Google Telemetry.