JFugue

Short description: Audio programming language

JFugue is an open source programming library that allows one to program music in the Java programming language without the complexities of MIDI. It was first released in 2002 by David Koelle. Version 2 was released under a proprietary license. Versions 3 and 4 were released under the LGPL-2.1-or-later license. The current version, JFugue 5.0, was released in March 2015, under the Apache-2.0 license. Brian Eubanks has described JFugue as "useful for applications that need a quick and easy way to play music or to generate MIDI files."

Example

Here's an example Java program that will play the C-major scale in JFugue.

import org.jfugue.player.Player;

public class HelloWorld {
  public static void main(String[] args) {
    Player player = new Player();
    player.play("C D E F G A B");
  }
}

The string passed to JFugue contains a series of musical instructions that JFugue parses and turns into musical events, which by default are rendered in MIDI. This format, called "Staccato," can represent all of the musical features of MIDI and is specifically designed to be easy for people to read and write. While the default use case for JFugue is to convert Staccato to MIDI, the architecture allows it to read and write musical information from and to a variety of formats (e.g., MIDI to MusicXML, Staccato to LilyPond). Below is an example converting a MIDI file to the Staccato format.

MidiParser parser = new MidiParser();
StaccatoParserListener listener = new StaccatoParserListener();
parser.addParserListener(listener);
parser.parse(MidiSystem.getSequence(new File("YourMidiFile.mid"))); // Change to the name of a MIDI file that you own the rights to
Pattern staccatoPattern = listener.getPattern();
System.out.println(staccatoPattern);

JFugue 5.0 contains a set of classes that represent ideas in music theory, including intervals, scales, chords, and chord progressions.

The notion of Patterns is integral to JFugue. Patterns are used to represent phrases of music that can be combined, repeated, and altered using tools that are aware of the musical content of the pattern.

Pattern pattern1 = new Pattern("A B C");
Pattern pattern2 = new Pattern("G F E");
pattern1.add(pattern2).repeat(3);
Player player = new Player();
player.play(pattern1);

JFugue 5.0 makes extensive use of fluent interfaces, also known as method chaining, which lets developers write short, expressive pieces of code like the following:

Chord[] chords = new ChordProgression("I IV V").setRoot("C").getChords();

Advanced Features

JFugue is capable of producing microtonal music by using a Staccato element consisting of the letter 'm' followed by the frequency in Hertz of the desired tone. Like other notes in JFugue, this tone may be followed by a duration (such as 'w' for a whole note or 'q' for a quarter note) and note dynamics (e.g., "note on" and "note off" velocities). JFugue converts the microtone frequency to a sequence of MIDI Pitch Wheel and Note events to achieve the desired tone.

Player player = new Player();
player.play("m440.0q A4q"); // These sound the same
player.play("m568.7w");     // Whole duration note at 568.7 Hertz

JFugue provides an intuitive programming interface for creating beats and rhythms. The characters in the strings below each correspond to a percussion note that is played on the percussive MIDI Channel (the tenth channel); default settings are provided for common sounds (e.g., "O" for "[BASS_DRUM]q"), although any Java Map or Character to String may be passed to the Rhythm constructor.

Rhythm rhythm = new Rhythm()
  .addLayer("O..oO...O..oOO..")
  .addLayer("..S...S...S...S.")
  .addLayer("````````````````")
  .addLayer("...............+");
new Player().play(rhythm.getPattern().repeat(2));

In addition to allowing music to be converted from one music format to another, the architecture of JFugue can be used to create programmatic tools that are capable of both performing computations on incoming music (from any format) and changing incoming music. The example below is a simple tool that keeps track of all instruments used in a musical piece.

public class InstrumentToolDemo {
    public static void main(String[] args) throws InvalidMidiDataException, IOException {
        MidiParser parser = new MidiParser(); // Remember, you can use any Parser!
        InstrumentTool instrumentTool = new InstrumentTool();
        parser.addParserListener(instrumentTool);
        parser.parse(MidiSystem.getSequence(new File("YourMidiFile.mid"))); // Change to a real filename
    
        List<String> instrumentNames = instrumentTool.getInstrumentNames();
        for (String name : instrumentNames) {
            System.out.println(name);
        }
    }
}

class InstrumentTool extends ParserListenerAdapter {
    private List<String> instrumentNames;
    
    public InstrumentTool() {
        super();
        instrumentNames = new ArrayList<String>();
    }
    
    @Override
    public void onInstrumentParsed(byte instrument) {
        String instrumentName = MidiDictionary.INSTRUMENT_BYTE_TO_STRING.get(instrument);
        if (!instrumentNames.contains(instrumentName)) {
            instrumentNames.add(instrumentName);
        }
    }
    
    public List<String> getInstrumentNames() {
        return this.instrumentNames;
    }
}

JFugue provides functionality on top of Java's MIDI Transmitter and Receiver classes to reduce the amount of code that a developer would need to write to connect to external MIDI devices.

Uses in Other Applications

JFugue has been used in a number of applications, including software projects and artistic installations.

• TransProse, which turns classic novels into music, uses JFugue
• The JFugue Music NotePad provides a user interface for composing music
• JFrets is an application for teaching and training guitar tablature
• Log4JFugue is a utility for converting log files created by log4j into musical patterns; this allows one to listen for changes in a log file, which provides a much different experience than reading through the file line-by-line.
• Audovia is a database application for making music using JFugue MusicStrings

JFugue has been used to play music when a software build fails or succeeds.

JFugue is one of the few Java libraries that lets one do something interesting in as little as one or two lines of code. This distinction earned JFugue a place in the book "Groovy in Action"

External links

• JFugue.org—Official JFugue website