Read Me

-----------------------------------------------------------------------------------------
                                   CODESOUNDING PROJECT
-----------------------------------------------------------------------------------------
CodeSounding is an open source sonification framework which makes possible to hear how any existing Java program "sounds like", by assigning instruments and pitches to code statements (if, for, etc) and playing them as they are executed at runtime. In this way the flowing of execution is played as a flow of music and its rhythm changes depending on user interaction. 

For latest informations please visit http://www.codesounding.org and http://sourceforge.net/apps/wordpress/codesounding.


 TABLE OF CONTENTS
 *****************

1. Requirements
2. Compiling
3. License
4. Usage
5. Examples
6. Contact Email


1. Requirements
---------------
Compiling CodeSounding requires a Java 1.5 or later compatible virtual machine for your operating system.


2. Compiling
---------------
Checkout the source code:
svn co https://codesounding.svn.sourceforge.net/svnroot/codesounding/CodeSounding/trunk CodeSounding

From the source root folder run:
#ant

To compile the java2demo example:
#ant -buildfile build_java2demo.xml


3. License
---------------
All CodeSounding code is licensed under GPLv3. JSyn is covered by its SDK's free license (http://www.softsynth.com/jsyn/developers/jsyn_sdk_license.txt) so CodeSounding's JSyn-dependent code is covered by an "Additional permission under GNU GPL version 3 section 7".

Since my copy of JSyn jar file was licensed from Mobileer Inc I can exceptionally distribute it here, thanks to Phil Burk. Check out http://www.jsyn.com.


4. Usage
---------------
Post-process your source java files with the script "sonify.sh", a wrapper of 
codesounding.cl.ApplyTemplate class. Its usage is:

codesounding.cl.ApplyTemplate -d <arg> [-f <arg>] [-h] -s <arg> [-t <arg>]
 -d <arg>   Destination root dir. Where rewritten files are copied
 -f <arg>   File containing a list of file to whom apply the template.
            Each line is a relative path to the source directory set by -s option. If
            omitted, the list of file is read from standard input
 -h         Print help for this application
 -s <arg>   Source root dir. Paths specified with -f option are relative
            to this directory
 -t <arg>   ANTLR template file; default (embedded in the jar) is
            basicProcessor.stg
 
Examples:
$ java codesounding.cl.ApplyTemplate -s src -d srcRewritten -f list.txt
$ cat list.txt | java codesounding.cl.ApplyTemplate -s src -d srcRewritten
$ find . -name "*.java" | java codesounding.cl.ApplyTemplate -s ../src -d ../srcRewritten

Post-processing can be done by an ANT task, after adding codesounding-embedded.jar to the classpath:

<target name="sonifier" depends="jar.codesounding">
    <taskdef name="sonify" classpathref="cp.test.grammar" classname="codesounding.ant.TaskTemplateApplier"/>
    <sonify destDir="srcRewritten">
        <fileset dir="src" includes="**/*.java" excludes="**/antlr/**" />
    </sonify>
</target>

An online tutorial is available on this topic:
http://codesounding.wiki.sourceforge.net/ShortTutorial

After post-processing your source files, compile them, having codesounding-embedded.jar into the classpath.

Finally, run your classes / jars, for example:
java -DCONFIG_FILE=./jmusic.properties -Xbootclasspath/a:"./codesounding-embedded.jar" -jar ./java2demo.jar

For a deep explanation of runtime configuration (like 'CONFIG_FILE' option) see USAGE.html file.


5. Examples
---------------
Several demo scripts are contained in the Linux packages provided by the OpenSuse Build Service (https://build.opensuse.org/project/show?project=home%3Arobermann79%3Acodesounding):
 * /usr/share/codesounding-*/samples/plain_abc.sh: writes an ABC file
 * /usr/share/codesounding-*/samples/sound_abc.sh: creates and plays MIDI files
 * /usr/share/codesounding-*/samples/sound_jjack.sh: enables the communication with a JACK audio server
 * /usr/share/codesounding-*/samples/sound_jmusic.sh: dinamically plays MIDI instruments
(They are also included in the source folder named "packaging".)

A jMusic-based live demo is provided as a Java Web Start application on http://www.codesounding.org/java2demo.jnlp. This sonifies several BSD licensed Sun Microsystems's files (they should be in $JAVA_HOME/demo/jfc/Java2D/src): they compile into a java 2D demo application: while seeing its 2D magics, you are able to hear its source code in action.

An example of Max/MSP interaction (http://sourceforge.net/projects/codesounding/files/codesounding/codesounding_maxmsp.zip/download):
* java2demo.jar, for every instruction executed, will send an UDP message to the patch, which will trigger several oscillators (see a live on http://www.youtube.com/watch?v=8v9qCnaPwgw).
Also, Max/MSP enabled the auralization of several sorting algorithmís execution path: every instruction triggers an oscillator, tuned to a specific pitch: http://www.youtube.com/watch?v=ol5ml9e2THw

Several JSyn examples (http://sourceforge.net/projects/codesounding/files/codesounding/codesounding_jsyn_examples.zip/download):
 * GrainScaledSkipperProcessor: Every thousandth Java istruction the class triggers an enveloped oscillation (of 50 ms), with each instruction having a different frequency. They are finally added and reverberated. Faders enable you to change the oscillators's frequencies, how many instructions are skipped and the grains's envelope. Furthermore the skipped instructions scale the amplitude of each oscillator.
 * GrainSkipperProcessor: An implementation similar to GrainScaledSkipperProcessor, with a larger envelope and without scaling.
 * OneSampleProcessor: Every Java instruction queues just one sample. Every 200s they are played by a sampler. A fader enables the change of the sampling frequency.
 * OctaveProcessorWithFilter: Similar to GrainScaledSkipperProcessor, here the output is band-pass filtered in a bank tuned to MIDI's C60, ..., F77 pitches.
 * InstrumentProcessor: Here I'm just joking with instruments exported from SoftSynth's Wire; the same effects (that is, skipping instructions and playing them with short, equal tempered notes) can be obtained through mere MIDI - see for example the JMusic based SynthSyncopate.java class.
 * JaVoiceProcessor: The Java trace is translated into an "image", then converted into sound. The core algorithm is quite the same as hificode.c's, published in JavOICe (http://www.seeingwithsound.com/javoice.htm). The audio is rendered by JSyn.


6. Contact
----------------
Roberto Mannai  <robermann@gmail.com>