Preparation

These steps are required for building JJazzlab, both from the command line or from Netbeans:

• Clone the repository from https://github.com/jjazzboss/JJazzLab (or download and extract the source files)

• There is a file too big for git, you have to download it from https://archive.org/download/jjazz-lab-sound-font/JJazzLab-SoundFont.sf2 and move it to plugins/FluidSynthEmbeddedSynth/src/main/soundfont

In Linux & MacOS, install fluidsynth package

On both Linux and MacOS, you also need the native fluidsynth package. Check if it is installed with fluidsynth --version . If it's not yet there, install it with:

• sudo apt-get install fluidsynth on Debian based distributions,

• brew install fluidsynth for Homebrew users on MacOS,

• for other Linux distributions and other MacOS installation options see https://github.com/FluidSynth/fluidsynth/wiki/Download

Build from the command line

With the preparation done, you only need to execute the build and run the application:

• In the project root, run mvn clean install

• Go to app/application and run mvn nbm:cluster-app nbm:run-platform

The application should open up, the output of the application will be visible in the terminal that launched the app.

Build from Netbeas IDE

Because JJazzlab uses Apache Netbeans Platform, Netbeans IDE is preferred for development. Follow these steps to build and run the application:

• Go to File menu, Open project and point to the folder with JJazzlab source code

• You will see a project named JJazzLab parent [master] , right click it and select build

• Expand JJazzLab parent / modules using the > symbol on the left, and locate the module called JJazzLab App

• Open that module by either double clicking on it or using right click and Open Project

• Scroll up on the projects panel and locate JJazzLab App [master]

• Right click the project name and use Run

The application should open up, the output of the application will be visible in the output panel in the IDE.

Troubleshooting

If the instructions don't work as expected, consider creating an issue in github JJazzLab repository or asking in jjazzlab forums.

Let's first create a new module to hold our code. In the Netbeans IDE, follow these steps:

1. Open JJazzLab Parent and expand its contents

2. Right click JJazzLab Parent / Modules and use Create New Module...

3. Select Java with Maven as category and Netbeans Module as project

4. Enter a name for the module, this guide uses "Reharmonize"

5. Click next and finish in the next step

You new module will appear in the JJazzLab modules list, but Netbeans will also open the module. If you expand all the module's contents you should have something like this:

Create an action

We want to create a "Reharmonize" action which should be callable from the chord symbol popup menu, and should operate on the chord symbols currently selected.

The best way to start is to look for a similar action and copy the code. Actions classes are mainly found in the following modules:

• CL_Editor module : Chord Leadsheet editor actions such as insert bar, transpose chord symbols, etc

• SS_Editor module : Song Structure editor actions such as delete song part, change rhythm, etc

• MixConsole module : save default rhythm mix, mute all, etc

• module: play, stop, etc

• module: new song, open song, duplicate song, etc

The chord leadsheet editor action TransposeDown is enabled when user has selected one or more chord symbols, which makes it perfect to base our code on. Let's reuse it in our module:

1. Open the CL_EditorImpl module, navigate to Source Packages > org.jjazz.cl_editorimpl.actions and copy TransposeDown.java (copy the file in the projects panel, not its contents!)

2. Open the Reharmonize module, select the org.myself.reharmonize package, and choose Paste > Refactor Copy... (Ctrl+V triggers Refactor Copy in Netbeans)

3. A dialog appears, set the new name to Reharmonize and press Refactor

The new Reharmonize class will be created in the module, but it will show many errors due to missing dependencies.

There are several ways of fixing the dependencies, for brevity let's just copy the ones from CL_EditorImpl:

1. Go to Reharmonize > Project Files, open the pom.xml file and delete the whole <dependencies> element

2. Go to CL_EditorImpl > Project Files, open the pom.xml file and copy the entire <dependencies> element

3. Switch back to the pom.xml from the Reharmonize module, paste the <dependencies> element after the <build> element and save the file

Open the Reharmonize class again or switch back to that tab in the editor. The errors in the import statements should be gone now! Not all problems are solved yet though...

Action annotations

Now you should have only one error in the file:

Netbeans uses annotations to facilitate action declaration. There are separate annotations to regulate different aspects of how the action will integrate with the application:

• @ActionID is used to identify the action, its required properties category & id are used to locate this action from other modules (e.g. see Actions#forID)

• @ActionRegistration registers the action, making it available to other modules. The displayName property determines the text this action will show in the UI. If that name starts with a # symbolit means the actual text will be obtained from a Bundle.properties localization file instead

• puts a reference to this action in the Netbeans virtual file system (created at runtime), in the Actions/ChordSymbol directory. When user right clicks a chord symbol, JJazzLab uses all action references in that directory to create the related menu entries, using the position value to order them

You only need a few changes to correctly show the action, most of them in the Java code. A few changes are also required in other files.

The necessary changes for Reharmonize.java are:

1. In the @ActionID declaration, replace the id by org.myself.reharmonize (or a string of your choice)

2. In the @ActionRegistration, change the displayName to #CTL_TransposeDown

3. There should be a use of the String literal "CTL_TransposeDown", as a parameter to ResUtil#getString. Change it to "CTL_TransposeDown" (notice there's no # at the start for this use)

4. In @ActionReference, change the value of position from 410 to 415, this way the new action will appear in the popup menu after the TransposeDown action.

A couple of changes are needed in other files:

1. Edit Reharmonize > Other Sources > src/main/resources > org.jjazzlab.reharmonize > Bundle.properties by adding a line with CTL_Reharmonize=Reharmonize chord progression

2. Open JJazzLab App > Project Files > pom.xml and add a dependency on the new module. Go to the end of the <dependencies> and add:

You should be able to build the new module. Right click the Reharmonize module then Build from the popup menu. Run JJazzLab by right clicking JJazzLab App and selecting Run from the menu.

JJazzLab will open, running with the new module. In any song (open one or create a new one), select a chord symbol and show the popup menu: our action should be there, as shown below. If you select it it will transpose down the chords symbols, as we have not yet changed the action code itself.

Action code

The two important methods for this guide are:

• selectionChange() which is called each time selection has changed (e.g. user has selected or unselected bars/chord symbols/sections) with a selection context parameter. This is used to enable or disable the action depending on the selection

• actionPerformed(), which performs the action. This can be triggered in several ways

The automatic selection change mechanism in the active Chord leadsheet editor is provided by the CL_ContextActionSupport helper class. This mechanism is based on the powerful Netbeans global Lookup mechanism, which is a out of scope of this tutorial.

Below is a sketch of a possible Reharmonize action implementation. If you are a music enthusiast, you probably know reharmonization is a complex topic, the strategy used in this code is a risky one: replace the selected chords by randomly generated chords!

Although there is a non-zero chance of this code offering a good reharmonization, the strategy is not recommended at all! A proper implementation is outside the scope of this tutorial.

Now you know:

• How to create a new module and add it to JJazzLab

• How to add new actions (and where to look for examples of existing actions)