User Guide

This software is a set of command line tool and programming API, simple to use, that aims to become an open source alternative to Chord Pulse (commercial product) or MMA (open source software).

1.1. JChordBox description

JChordBox is a software written in java 1.7. It is platform independant and should work at least on windows, MAC and Linux or any platform that supports java. It uses XML and MIDI technology. XML is a simple text based file format. MIDI is a binary file format (SMF: Standard Midi File) widely used by music industry.

JChordBox generates a backing track from a chord progression and a musical style (containing music templates also called grooves).

Songs are stored in file with .jcb-song extension and styles are stored in file with .jcb-style extension.

The user can easily define its own music style by putting markers in the MIDI file to delimit grooves. It can then generates a style file (.jcb-style) with CreateStyleFromMidiFile process (see CreateStyleFromMidiFile for more information).

The music style XML format stores logic informations about play unit. The notes and rhythm are stored in MIDI file format that you can edit with your favorite sequencer.

GenerateSong process outputs a MIDI file with the resulting song (see GenerateSong for more information)..

1.2. Licence and version

JChordBox is licensed under GPL. The complete licence text can be found in the JChordBox distribution package.

JChordBox is in beta stage. the documentation may contains errors and needs your help and comments to be improved.

1.2.1. Version 0.1

Initial version

1.2.2. Version 0.2

Enhancements

NEW : add <tracks-def/> to <template-source/> : rhythm, default and chords track types. See The XML tag <template-source/> for more information.
NEW : automatically create tetrad template-riff from triad template-riff when it does not exist. This is a runtime behavior (does not modify the style file).
NEW : allow any single duration for chords
NEW : add windows and unix shell scripts
NEW : org.jchordbox.process.CreateStyleFromMidiFile : add -createmarker option with a chord argument. See CreateStyleFromMidiFile for more information.

1.2.3. Version 0.3

Enhancements

NEW: marker policy : extend Random Pattern marker policy to add weight parameter (see Create a Pattern with random alternatives for more information).
NEW: Can add a chords track even if it doesn't exist in the template source MIDI file (see The inner xml tag <chords-track/> type for more information)
NEW: Add ConcatenateMidiFile command line that allow to concatenate two or more MIDI files with various options (see ConcatenateMidiFile (since 0.3) for more information)
NEW: Add NormalizeMidiFile command line that allow to do various operations on a MIDI file (set track names, erase existing markers, change resolution) (see NormalizeMidiFile (since 0.3) for more information)
NEW: Add some new chords (see Chords syntax for more information)
NEW: Extend chord progression grammar (see Chord progression grammar for more information)
NEW: Change Song structure in order to define sections and musical form (see The XML tag <section/> and The XML tag <musical-form/> for more information)

Defects fixed

BUG: on MIDI sequence generation with <template-riff/> that own class attribute to 'window' value.
BUG: character encoding for French translation.
BUG: length of extracted sequence when sequence is made of multiple measures.
BUG: when you use multiple <apply-groove/> chord sequence in a song file, the generated MIDI file is broken.

1.2.4. Version 0.4

Enhancements

NEW: An interactive console mode (run in terminal) song player has been developped. (see SongPlayer (since 0.4) for more information). It is set to the default jar application.
NEW: add keynote option to GenerateSong process. When this option is set, markers with time signature and chord are added to the MIDI file (see GenerateSong for more information).
NEW: GenerateSong process now generates the MIDI file in the current directory when -outfile option is not set (see GenerateSong for more information).
NEW: GenerateSong process can now use URL for -songfile and -stylefile options. You must set the -useurl option (see GenerateSong for more information).
NEW: GenerateSong can now change the pitch of the generated MIDI file without changing chord names (see GenerateSong for more information).
NEW: Style and Song have now a verbose information section. (see Common XML rules for more information).
NEW: JChordBox now manages modes in addition to the chords.
NEW: Add Song and Style examples in the distribution package (example directory).

Defects fixed

BUG: In CreateStyleFromMidiFile: Error on default Style filename generation when the input MIDI filename doesn't end with ".mid".
BUG: In GenerateSong: error on default MIDI filename generation when Song filename doesn't end with ".jcb-song".
BUG: Tempo setting didn't work. The tempo is always 120. Tempo in .jcb-song file is no longer needed. This allow to set the tempo to the preferred tempo of the style (see The XML tag <tempo/> for more information).
BUG: Problem with PATH setting. You must now set the PATH variable manually. (see Windows 7 : set JAVA_HOME and PATH variable)

1.2.5. Version 0.5b

Enhancements

NEW: Implements the bash completion. (see Set environment for more information)
NEW: GenerateSong has now two more options: -songname and -stylename. It is now possible to call a song or a style using his information name tag. Song and Style name are searched in PATH variables. (see GenerateSong for more information).
NEW: add command line synopsis to each command line help.

1.3. JChordBox Homepage

Visit the JChordBox homepage. The homepage contains links to download all JChordBox software versions and to get help. This project is hosted by www.sourceforge.net.

1.4. Help Wanted

If you find JChordBox useful, please consider to help us improving this software. You can report bugs, discuss the software on JChordBox forum or mailing list. You can also translate it to your foreign language.

All these tools (tracker, forum, mailing list) are accessible from JChordBox Home page

If you like it, please, talk about JChordBox on your blog, your site, on twitter, on facebook ...

If you don't like it, and have constructive remarks, you can also let me know by sending an email to eleandar (at) gmail (dot) com.

1.5. Contributors

Main developper and project maintainer : Laurent Schwartz
Logo designer : Thomas Saliba

1.6. About this manual

This manual describes how to install, configure and run JChordBox.

It is written using the standard docbook 4.5 (XML format).

1.7. JChordBox Installation

JChordBox is a software that needs JAVA 1.7. If not yet done, you will have to download Java software (JRE 7).

1.7.1. Installation on Ubuntu 12.04

Java Runtime Environment

To install and set java 7 on ubuntu 12.04, use the following command lines :

$ sudo apt-get install openjdk-7-jre
$ sudo update-alternatives --config java

The update-alternatives command is used when you have more than one JRE installed on your system. It allows you to set the default JRE.

Linux Sound Configuration

To allow java to connect to MIDI software synthesizer, you need to upload snd-virmidi kernel module. This module installs virtual MIDI ports. find your modules file configuration (/etc/modules) and add on a new line:

snd-virmidi enable=1

Once your module added, reboot your system.
Start your java application.
Select a VirMIDI output port.
Connect your VirMIDI port to fluidsynth (using qjackctl or aconnect).
And you're done !

Otherwise, you can try to load a SF2 sound library into SongPlayer process to improve the sound playing (see SongPlayer (since 0.4) for more information).'

Unzip distribution package and install

$ unzip jchordbox-0.2.zip
$ cd jchordbox-0.2
$ ./install.sh

These commands unzip the jchordbox package in a folder named "jchordbox-0.2" and create a bin directory with unix shell scripts that are wrapper to java command line. Each JChordBox process has a dedicated shell command.

Set environment

add to your ~/.bashrc the following line:

source /fullpath/to/jchordbox/bin/env.sh

If you don't want to set your profile, you can source the env.sh script to set the environment locally.

$ source /fullpath/to/jchordbox/bin/env.sh

If you source env.sh, completion will be added. (since 0.5b)

1.7.2. Installation on Windows

Java Runtime Environment

Download java 7 (JRE) and install it from Oracle site.

Unzip distribution package and install

You can use 7 zip open source software to unzip the distribution package

Double click on install.bat to run the batch file.

This will create a bin directory with Windows BATCH command that are wrapper to java command line. Each JChordBox process has a dedicated BATCH file.

Windows 7 : set JAVA_HOME and PATH variable

Computer from the Start menu
Choose System Properties from the context menu
Click Advanced system settings > Advanced tab
Click on Environment Variables, under User Variables, set the JAVA_HOME variable. Example : JAVA_HOME=C:\Program Files\Java\jre7

add JChordBox bin directory (ex: c:\jchordbox-0.4\bin) to the PATH variable. Add a semi-colon at the end of the PATH variable content if any and add the JChordBox bin directory.

1.7.3. Installation on MAC

To be done ...

1.8. Useful application

1.8.1. On Ubuntu 12.04

You can use a sequencer like rosegarden and a MIDI events monitor like kmidimon.

$ sudo apt-get install rosegarden kmidimon

1.9. Run JChordBox

JChordBox package distribution comes with several command line process. See Use the command line section for more details.

The JChordBox application center is a text mode user interface called org.jchordbox.process.SongPlayer See SongPlayer (since 0.4) section for more details.

It can be loaded as a jar application

java -jar /path/to/jchordbox.jar

Or simply click on the jar file to load application.

You will find in the package distribution under the example directory some files to be used with SongPlayer (AllBlues.jcb-song, Rock50.jcb-style, Rock50.mid...).

Chapter 2. XML Structure

Table of Contents

2.1. Common XML rules

2.1.1. 'id' and '*refid' attributes
2.1.2. <information/> element

2.2. Song file

2.2.1. The XML tag <use-style/>
2.2.2. The XML tag <tempo/>
2.2.3. The XML tag <section/>
2.2.4. The XML tag <musical-form/>
2.2.5. Chord progression grammar
2.2.6. Chords syntax

2.3. Music style (accompaniement)

2.3.1. The XML tag <preferred-tempo/>
2.3.2. The XML tag <template-source/>
2.3.3. The XML tag <groove/>
2.3.4. The XML tag <pattern/>
2.3.5. The XML tag <template-riff/> (also named Riff)

JChordBox defines two file types:

*.jcb-song : song file that contains information about chord progression, sets the music style to use and the tempo.
*.jcb-style : music style file that contains informations about musical accompaniement unit.

2.1. Common XML rules

The JChordBox XML format uses some common rules to the Style and Song files.

2.1.1. 'id' and '*refid' attributes

The id attribute is a unique key that identifies an XML element.

Example:

	<groove id="jazzrock">

If the attributes ended with "refid", then it is a reference to an XML element identified by a key attribute "id".

Example:

	<apply-groove groove-refid="jazzrock">

2.1.2. <information/> element

The XML information element <information/> are common to the Song and Style file. It defines several optional inner tag element.

    <information>
        <author>
            <name>Laurent Schwartz</name>
            <email>eleandar@gmail.com</email>
        </author>
        <author>
            <name>Another author</name>
        </author>
        <homepage href="http://jchordbox.sourceforge.net"/>
        <name>song name</name>
        <version>1.1</version>
        <creation-date day="18" month="01" year="2013"/>
        <genre>rock</genre>
        <description kind="long">This song allows to easily test all style.
        The song will be set with the style's prefered-tempo.
        </description>
    </information>

2.2. Song file

Example:

<?xml version="1.0" standalone="no"?>
<song-chords>   
    <information/>
    <use-style>../style/import_gm/Rock_1.Alternative.080_Alternative_03a.jcb-style</use-style>
    <body>
        <tempo>114</tempo>
        <section label="A">
            <apply-groove class="main">
               D#m7 | G#7 | C#M7 | % 
            </apply-groove>
        </section>
        <section label="C">
            <apply-groove class="main">
               2/4:-Am7 2/4:+CM7
            </apply-groove>
        </section>
        <section label="B">
            <apply-groove class="main">
               FM7 | G7 | CM7 | % 
            </apply-groove>
        </section>
        <musical-form>A C B</musical-form>
    </body>
</song-chords>

2.2.1. The XML tag `<use-style/>`

This tag declare the use of a music style file. It's location can be absolute (absolute path) or relative to the Song file.

2.2.2. The XML tag `<tempo/>`

The tempo tag defines the tempo for the whole song. It is optional. If it is omitted, then the style tempo is used instead (since 0.4).

It is possible to override the song tempo by setting the command line -tempo parameter.

2.2.3. The XML tag `<section/>`

The <section/> element defines a section of the song. The section can be call in the tag <musical-form/>. Each section has a label which is an upper case letter or an upper case letter plus a digit. (look at the example above).

Each section contains <keynote> (optional) and <apply-groove/> element(s).

The XML tag `<keynote/>` (since 0.4)

Default mode is assigned to each chord family. If you want to associate another mode than default setting (see Chords definition for more information), you must use the <key-note/> tag:

        <section label="A">
            <key-note chord="FM7" set-mode="lydian"/>
            <key-note chord="m7" set-mode="dorian"/>
            <apply-groove class="main">
               2/4:-Am7 2/4:+CM7
            </apply-groove>
        </section>

The <key-note/> tag element is a <section/> inner tag.

The previous <section/> definition assign lydian mode for all F major seventh chord and dorian mode for all minor seventh chord. (see Modes definition for more information)

The XML tag `<apply-groove/>`

The XML tag <apply-groove/> allows to apply a groove to a given chord progression (see Chord progression grammar for more information).

A Groove can be referenced with an id (attribute 'groove-refid'). It can also be referenced using a class (intro, ending, main, ...) (attribute 'class') and a variant number (if 'variant' attribute is ommit it is assume to be 1). (see The XML tag <groove/> for more details). A generic approach is to set groove-refid and class attributes.

<apply-groove groove-refid="Rock" class="main" variant="1">
    FM7 | G7 | CM7 | % 
</apply-groove>

or

<apply-groove groove-refid="Rock">
    FM7 | G7 | CM7 | % 
</apply-groove>

or 
<apply-groove class="main" variant="1">
    FM7 | G7 | CM7 | % 
</apply-groove>

or

<apply-groove class="main">
    FM7 | G7 | CM7 | % 
</apply-groove>

2.2.4. The XML tag `<musical-form/>`

The <musical-form> element defines the song form (or structure). Each section label is replaced by the corresponding <section/>. (look at the example above).

2.2.5. Chord progression grammar

A chord progression is a list of bar (|), % and chords.

The % sign repeat the preceding chord declaration.

Example:

Dm7 | % | G7 | CM7 | %

The bars are only used for readability.

You can add a time signature to the chord. For example, if your pattern length is 4/4 and you want a chord for 2 beats then you can use :

2/4:Dm7

Even more, you can tie Chords sequence.

CM7_ | _1/4:CM7 3/4:G7 |

The two CM7 chords are tied.

Another example:

3/4:Dm7 1/4:G7_ | _G7_ | _1/4:G7 3/4:CM7 |

The three G7 chords are tied.

2.2.6. Chords syntax

Notes : A B C D E F G
add # (sharp) or b (flat)
Chord type:
- Tetrad : m7|m7b5|m7#5|M6|m6|dim7|7|7b5|7#5|M7|M7b5|M7#5|m7M|7sus4|7sus2
- Triad : Maj|min|aug|dim|sus4|sus2

C#7sus4  
Dbm7
Gm7M
...

(see Chords definition for more information)

2.3. Music style (accompaniement)

A music style (ex: rock, jazz, blues, pop, funk ...) is described using two files:

*.jcb-style : music style file that contains informations about musical accompaniement unit.
*.mid : MIDI file that contains information about notes and rhythm.

A music style defines some Grooves. A Groove is an abstract unit that contains element defining its behaviors when it comes to transpose (to a given chord) or to cut the music (one or more beats).

A Groove is defined using Patterns and they are defined using Riffs. Riffs refers to concrete MIDI file part or chunk.

2.3.1. The XML tag `<preferred-tempo/>`

This XML element defines the preferred tempo for this music style. If tempo is not set in the song file or set at command line then the preferred tempo is applied.

2.3.2. The XML tag `<template-source/>`

<template-source file="style-example.mid">
     <tracks-def>
	    <rhythm-track trackname="Drums" tracknum="1"/>
	    <default-track trackname="Acoustic Bass" tracknum="2"/>
	    <default-track trackname="Electric Piano 1" tracknum="3"/>
	    <default-track trackname="Nylon-String Guitar" tracknum="4"/>
	    <chords-track start-block-length="45" end-block-length="45" trackname="Acoustic Grand Piano" tracknum="5"/>
	    <chords-track start-block-length="45" end-block-length="45" trackname="Warm Pad" tracknum="6"/>
	</tracks-def>
</template-source>

This tag refers to a MIDI file. The MIDI file contains the note and rhythms of the current style. The inner <tracks-def/> defines the behavior of each track.

Each track type tag defines the track number and the track name. The track 0 is a special track containing MIDI meta events. The instrument track starts at 1.

The inner xml tag `<default-track/>` type

This XML tag defines a default track. Nothing special is done.

The inner xml tag `<rhythm-track/>` type

This XML tag defines a rhythm track. This kind of track is used for Drum tracks. When you define short Riff in a Pattern, sometimes you want to have a continuous rhythm part. If you set a rhythm track then the rhythm part from the longest Riff of the Pattern will be copied into the shorter Riffs in order to have a continuous rhythm part.

The inner xml tag `<chords-track/>` type

This XML tag defines a chords track. This kind of track has special behavior. It defines a starting MIDI events block (that raise the chord) and an ending MIDI events block (that ends the chord, can be empty). The attributes start-block-length and end-block-length are expressed in tick.

The block should be shorter than a single beat. For example: let say that 1/4 is equal to 480 ticks. The start-block-length plus the end-block-length must be less than a 480 ticks.

Even if the chords track does not exist in the MIDI file, you can add a chords track extracted from another MIDI file. If you want to use the JChordBox default chords track then use the following declaration:

<chords-track trackname="Warm Pad" tracknum="-1"/>

The important thing to note is that the tracknum is define as -1 value.

If you want to use your own MIDI file that contains your own chords track sequence please adapt to your need the following declaration:

<chords-track 
                    trackname="Electric Guitar"
                    tracknum="-1"
                    start-block-length="60" 
                    end-block-length="60" 
                    sequence-file="mychords-electricguitar.mid" 
                    sequence-keynote="CM7"
/>

You may notice that the keynote of the MIDI sequence has to be set. The start-block-length and end-block-length has to be adapt to your MIDI sequence.

To have information on your MIDI file, I suggest to use kmidimon on Linux. It is a MIDI event monitor simple to use. Beware ! The track are numbered from 1 (1 = meta events track). In JChordBox they are numbered from 0 (0 = meta events track).

2.3.3. The XML tag `<groove/>`

A Groove defines a music accompaniement style. Several Grooves can be defined in a single Style file

A Groove has a unique attribute key named id. It is referenced by the <apply-groove/> XML element (in Song file) with the groove-refid attribute.

A Groove can also be referenced and defined using a class attribute and optionnally a variant attribute (a number) in addition to the id attribute. The class is a groove category. It can take several value: intro, end, main, verse, chorus, bridge.

Example:

<groove id="rhumba" class="main" variant="1">
  <main-pattern pattern-refid="p-rhumba"/>
</groove>

A Groove declare the use of a main Pattern.

2.3.4. The XML tag `<pattern/>`

A Pattern is defined with Riffs which refers to MIDI chunk. A Pattern is a logical unit that can defines static Pattern or Random Pattern

Exemple of static pattern:

<pattern id="p-verse">
  <template-riff key-note="CM7" class="normal" >
    <from measure="1"/>
    <to measure="1"/> 
    <measures-time-signature>4/4</measures-time-signature>           
  </template-riff>                             
</pattern>

See The XML tag <template-riff/> (also named Riff) for more details about <template-riff/> tag.

Exemple of random pattern:

<pattern id="p-verse">
  <random>
    <on-pattern pattern-refid="p-verse-alt1" weight="2"/>
    <on-pattern pattern-refid="p-verse-alt2" weight="4"/>
    <on-pattern pattern-refid="p-verse-alt3" weight="2"/>
  </random>               
</pattern>

This example defines a pattern that choose randomly at generation time the real pattern to apply. The weight are summed. The pattern p-verse-alt1 has 2/8 chance to occur, the pattern p-verse-alt2 has 4/8 chance to occur and the pattern p-verse-alt3 has 2/8 chance to occur.

2.3.5. The XML tag `<template-riff/>` (also named `Riff`)

  <template-riff key-note="CM7" class="normal" >
    <from measure="1"/>
    <to measure="1"/> 
    <measures-time-signature>4/4</measures-time-signature>           
  </template-riff>               

  <template-riff key-note="CM7" class="window" >
    <from measure="1"/>
    <to measure="3"/>
    <measures-time-signature>4/4</measures-time-signature>         
  </template-riff>

A Riff refers to a concrete MIDI file chunk. It is a musical repeating chunk.

A Riff has a chord that covers the note used in the MIDI sequence. The chord can be a triad or a tetrad.

In addition to the chord, you can assign a mode (since 0.4) (see Modes definition for more information). When using modes, you can use any notes in your template-riff.

  <template-riff key-note="FM7" set-mode="lydian" class="normal" >

The Riff has a time signature. It can be compose of several measures.

A Riff is a repeating MIDI sequence. The extraction of the corresponding MIDI sequence is done from the <from/> pointer to the <to/> pointer.

A Riff can be of class attribute normal or window: This example defines two Riff :

class="normal" : define a normal Riff (of <measures-time-signature/> length).
class="window" : define a window Riff. A window Riff is a long sequence with a moving window (of <measures-time-signature/> length). Let's say the long sequence is 2 * 4/4 bar long and the window is 4/4 length.The first bar is played, then the second bar is played, then we replay the first one ...

The pointer <from/> and <to/> do not support beat attribute for this class of template-riff

Chapter 3. How does it work ?

Table of Contents

3.1. Chord and mode transposition

3.1.1. Note transposition with chord
3.1.2. Note transposition with mode

3.2. Selection Riff along its length

3.3. Selection Riff along its chord category

3.4. Riff selection in a Random Pattern

3.5. Long sequence Riff with a moving window

A Riff is identified by two elements:

The key note (a chord) : The chord that covers all notes used in the Riff. It can be a triad or a tetrad chord. If you want to use notes that are not in the chord, you can assign a mode giving you more intervals to work with (since 0.4).

For example: CM7 or Cmin.
The time signature : The time signature of the Riff

For example: 4/4 (one measure length) or 3/4 4/4 (Two measures length, it can be more)

3.1. Chord and mode transposition

Chords used in JChordBox have 3 degrees (triad) or four degrees (tetrad).

Modes used in JChordBox have 7 degrees.

3.1.1. Note transposition with chord

Let's say we set a Template Riff keynote to CM7 (the source chord). The CM7 chord has 4 degree:

degree 1: root (0 semi-tons)
degree 2: major third (4 semi-tons)
degree 3: perfect fifth (7 semi-tons)
degree 4: major seventh (11 semi-tons)

now we use the Template Riff with a dim chord (the target chord).

Fdim chord has 3 degrees:

degree 1: root (0 semi-ton)
degree 2: minor third (3 semi-tons)
degree 3: diminished fifth (6 semi-tons)

The source chord is a tetrad (CM7) while the target chord (Fdim) is a triad.

To transpose the Template Riff from CM7 to Fdim, we compute the source degree of each note in the MIDI sequence. Each note is then transpose to the same degree in the target chord (if it exists otherwise the note is ignored).

3.1.2. Note transposition with mode

The same algorithm as above is used with modes transposition.

Except that if a note is not an exact degree, then the number of semitones between the note and the nearest source degree is calculated and added to the target degree to compute the target note.

3.2. Selection `Riff` along its length

The longest Riff defines the parent pattern time signature.

Riff can be defined shorter than the parent Pattern (or the Pattern longest Riff). It allows to define a custom behavior when the groove is splitted into several chords sequence.

For example:

 
1/4:CM7 2/4:Dm7 1/4:G7
            
The CM7 and the G7 uses the same Riff defined with 1/4 time signature.
The Dm7 uses a Riff defined with 2/4 time signature.

If a Riff of the requested time signature does not exist, then the main Riff (the longest Pattern's Riff) is splitted.

3.3. Selection `Riff` along its chord category

Sometimes we want a different melody for triad and tetrad chords. A Riff can be defined with a tetrad keynote or a triad keynote.

A tetrad Riff can generate a tetrad and a triad chord sequence. A triad Riff can also generate a tetrad chord sequence (since 0.2).

3.4. `Riff` selection in a `Random Pattern`

All pattern referenced by a random sequence must be of the same time signature. As well as their inner Riff

3.5. Long sequence `Riff` with a moving window

Sometime define normal Riff can be frustrating because we want variation to append every 4 bars for example.

This kind of behavior can be defined with a special Riff that declares an inner window sequence block.

<pattern id="p-main">
  <template-riff 
        key-note="CM7" 
        class="window">
    <from measure="1"/>
    <to measure="4"/>
    <measures-time-signature>4/4</measures-time-signature>
  </template-riff>
</pattern>

This example declares a "window sequence" from measure 1 to measure 4 of the MIDI file and declares a window with 4/4 time signature.

That means that the long sequence will be splitted into 4/4 chunk and each chunk will be played sequentially. Once the last chunk is played, then the first chunk is played again etc.

Chapter 4. Use the command line

Table of Contents

4.1. GenerateSong

4.1.1. songname option (since 0.5b)
4.1.2. stylename option (since 0.5b)

4.2. CreateStyleFromMidiFile

4.2.1. Marker policy

4.3. SongPlayer (since 0.4)

4.4. NormalizeMidiFile (since 0.3)

4.5. ConcatenateMidiFile (since 0.3)

The JChordBox comes with several command line program. The command line arguments for each program are explained in this section

4.1. `GenerateSong`

SYNOPSIS: org.jchordbox.process.GenerateSong 
    [ [ -stylename {stylename} ] |[ -stylefile {stylefile} ] ]
    [ -useurl ][ -valid ][ -check ][ -debug ][ -tempo {tempo} ][ -xmlout ]
    [ -chunk ][ -color ][ -outfile {outfile} ][ -keynote ][ -pitch {pitch} ]
    ( -songname {songname} | -songfile {songfile} )

usage: org.jchordbox.process.GenerateSong
 -check                   check the consistency of the JChordBox Song file
                          and the JChordBox Style file. [Optional]
 -chunk                   Generate a MIDI file for each <template-riff/>
                          declared. [Optional]
 -color                   Activate the color if ANSI codes are supported
                          on the current terminal. [Optional]
 -debug                   Activate debug mode. [Optional]
 -keynote                 Add markers in the generated MIDI file with
                          keynote. [Optional]
 -outfile <outfile>       Output the MIDI generated file to <outfile>.
                          [Optional]
 -pitch <pitch>           Change the pitch by n semi-tons. (n is an
                          integer) [Optional]
 -songfile <songfile>     JChordBox Song file (XML file) to process.
                          [Optional]
 -songname <songname>     The Song name to use. The song is searched in
                          directory found in jcb.song.path java system
                          property. [Optional]
 -stylefile <stylefile>   JChordBox Style file (XML file) to use.
                          Overrides the <use-style/> XML element.
                          [Optional]
 -stylename <stylename>   The Style name to use. The style is searched in
                          directory found in jcb.style.path java system
                          property. Overrides the <use-style/> XML
                          element. [Optional]
 -tempo <tempo>           fix the tempo for the entire song. Tempo must be
                          in the interval [40 .. 260] [Optional]
 -useurl                  Use URLs instead of files for -songfile and
                          -stylefile options. [Optional]
 -valid                   validate the xml of the JChordBox Song file and
                          the JChordBox Style file used according to the
                          schema. [Optional]
 -xmlout                  display of the (internal) JChordBox Song file
                          and the (internal) JChordBox Style file after
                          being processed. [Optional]

The simplest command line to generate MIDI song file from JChordBox song file is:

$ java -cp /path/to/jchordbox.jar org.jchordbox.process.GenerateSong -songfile /path/to/your/song.jcb-song

This command line generates a MIDI file in current directory with the name song.mid.

When you set -debug option, markers are added to the generated MIDI file with the chord name and the pattern used.

4.1.1. songname option (since 0.5b)

The songname option search on disk in jcb.song.path java system variable.

The first song file that contains a name tag (see <information/> element for more information) with the required value is returned.

The environment variable used by shell wrapper for song search is JCBSONGPATH.

Example:

$ java -cp path/to/jchordbox.jar -Djcb.song.path=$JCBSONGPATH org.jchordbox.process.GenerateSong -songname AllBlues

4.1.2. stylename option (since 0.5b)

The stylename option search on disk in jcb.style.path java system variable.

The first style file that contains a name tag (see <information/> element for more information) with the required value is returned.

The environment variable used by shell wrapper for style search is JCBSTYLEPATH.

Example:

$ java -cp path/to/jchordbox.jar -Djcb.style.path=$JCBSTYLEPATH org.jchordbox.process.GenerateSong -songfile AllBlues.jcb-song -stylename Rock50

4.2. `CreateStyleFromMidiFile`

SYNOPSIS: org.jchordbox.process.CreateStyleFromMidiFile 
    [ -help ][ -color ][ -debug ][ -author {arg} ][ -name {arg} ][ -version {arg} ]
    [ -outstylefile {outstylefile} ][ -printxml ][ -createmarker {createmarker} ]
    [ -blocklength {blocklength} ][ -addchords ] 
    -inmidifile {inmidifile}

usage: org.jchordbox.process.CreateStyleFromMidiFile
 -addchords                     Add a new track with generated chords
                                (default instrument is Warm Pad)
                                [Optional].
 -author <arg>                  Set the author of the music style.
                                [Optional]
 -blocklength <blocklength>     Activate Chords Track search: Define the
                                length of starting and ending block for
                                Chords Track support. [Optional]
 -color                         Activate the color if ANSI codes are
                                supported on the current terminal.
                                [Optional]
 -createmarker <createmarker>   Add a marker to the MIDI sequence before
                                processing. Useful for quick style
                                integration of a MIDI file. The argument
                                is the MIDI chord. [Optional]
 -debug                         Activate debug mode. [Optional]
 -help                          Print this help. [Optional]
 -inmidifile <inmidifile>       Midi filename to read to create the music
                                style.  [Required]
 -name <arg>                    Set the name of the music style.
                                [Optional]
 -outstylefile <outstylefile>   Filename of the music style to create.
                                [Optional]
 -printxml                      Print the XML Style file to standard
                                output. [Optional]
 -version <arg>                 Set the version of the music style.
                                [Optional]

The CreateStyleFromMidiFile process a MIDI file and extract all MIDI markers to auto-create a music style (e.g the Grooves / Patterns and Riffs).

The simplest command line for creating a music style from a MIDI file is

$ java -cp /path/to/jchordbox.jar org.jchordbox.process.CreateStyleFromMidiFile -inmidifile mystyle.mid

This command line assumes that there are some markers in the MIDI file and create a file mystyle.jcb-style from the MIDI file mystyle.mid.

$ java -cp /path/to/jchordbox.jar org.jchordbox.process.CreateStyleFromMidiFile -inmidifile mystyle.mid -createmarker CMaj

This command line add a marker with the given chord (e.g. CMaj) to the MIDI sequence (without modifying the MIDI file on disk) and create a file mystyle.jcb-style from the MIDI file mystyle.mid.

4.2.1. Marker policy

The marker name has policy to guide the process through the music style creation.

Each marker must have a unique name and must start or end on a measure.

In the next sections, we use some keywords:

{GrooveId} : it is the groove identifier that owns the Riff. The Groove Id implies the class attribute. If it contains the string "intro", "end", "verse", "chorus" or "bridge", the groove takes the corresponding class otherwise it is set as main class. The variant attribute is incremented for each class.
{KeyNote} : it represents the chord that covers the notes used in the MIDI Riff.
{SetMode} (since 0.4) : it represents the mode used in addition to the chord thus allowing to use any note in the MIDI Riff.

Create normal `Riff` associated to a `Pattern`

The name of the marker must be as follow :

(start|end)-{GrooveId}-{KeyNote}(/{SetMode})?
example: start-Jazz-CM7
or       end-Jazz-CM7
or       start-Jazz-CM7/lydian

The "start" means that the marker starts a new Riff and ended previous Riff if any.

The "end" means that the marker ends the corresponding "start" marker's Riff.

Create a `Pattern` with random alternatives

(start|end)-{GrooveId}-{KeyNote}(/{SetMode})?-alt{Number}
example: start-Jazz-CM7-alt1
or       end-Jazz-CM7-alt1
or       start-Jazz-CM7/lydian-alt1

Since 0.3, you can add a weight to the marker name:

(start|end)-{GrooveId}-{KeyNote}(/{SetMode})?-alt{Number}-{Weight} 
example: start-Jazz-CM7-alt1-5
or       end-Jazz-CM7-alt1-5
or       start-Jazz-CM7/lydian-alt1-5

Each alternate pattern, should have a different number ("alt1", "alt2", ...). The whole marker must have a unique name.

Create a `Riff` with a long sequence and set a moving window

(start|end)-{GrooveId}-{KeyNote}(/{SetMode})-{Window}
example: start-Jazz-CM7-4/4
or       end-Jazz-CM7-4/4
or       start-Jazz-CM7/lydian-4/4

The long sequence is extracted from the start marker to the next marker. We append to the default marker name, the time signature of the moving window.

4.3. `SongPlayer` (since 0.4)

SYNOPSIS: org.jchordbox.process.SongPlayer 
    [ -file {file} ][ -stylefile {stylefile} ]
    [ -debug ][ -help ][ -port {arg} ][ -listport ][ -play ][ -loop ][ -nogui ]
    [ -color ][ -loadsf2 {loadsf2} ][ -jnlp ]

usage: org.jchordbox.process.SongPlayer
 -color                   Activate the color if ANSI codes are supported
                          on the current terminal. [Optional]
 -debug                   Set Debug mode [Optional]
 -file <file>             Load a file (Can be a MIDI file or a JChordBox
                          Song). [Optional]
 -help                    Print this help [Optional]
 -jnlp                    not documented. [Optional]
 -listport                List all the available output midi ports
                          [Optional]
 -loadsf2 <loadsf2>       Load SF2 library file. [Optional]
 -loop                    Loop the given file (with -file option)
                          [Optional].
 -nogui                   Don't load the console mode GUI (user interface)
                          [Optional].
 -play                    Start Playing the given file (with -file option)
                          [Optional].
 -port <arg>              Set the output MIDI port to use [Optional].
 -stylefile <stylefile>   Choose a style to apply to a loaded JChordBox
                          Song. [Optional]

The SongPlayer process can be loaded as a text user interface and gives quick and easy access to some JChordBox command lines.

It can select the output MIDI port or default java synthesizer.
It can load a MIDI file or a JChordBox Song as a MIDI sequence.
It can play/stop/pause/rewind/forward/loop MIDI sequence.
It displays the chords and bar/beat
It can change the Style applied to the loaded JChordBox Song thus recomputing the resulting MIDI sequence.
It can create Style from a MIDI file with various options.
It can mute and soloing tracks.

To list the available MIDI ports with SongPlayer, use the -listport option. This option force the process loading in non-interactive mode.

$ java -jar path/to/jchordbox.jar -listport

To load the GUI with a minimal set of options or simply click on the jar file to execute:

$ java -jar /path/to/jchordbox.jar

The SongPlayer process can load a SoundFont 2 library:

$ java -jar /path/to/jchordbox.jar -loadsf2 /path/to/sf2file

The SongPlayer process can be load in non interactive mode (-nogui option).

To play a file (MIDI or JChordBox Song) and loop until Ctrl^C is pressed:

$ java -jar path/to/jchordbox.jar -nogui -file path/to/file -play -loop

4.4. `NormalizeMidiFile` (since 0.3)

SYNOPSIS: org.jchordbox.process.NormalizeMidiFile 
    [ -newresolution {newresolution} ][ -settrack {settrack ... } ]
    [ -debug ][ -color ][ -help ][ -erasemarkers ] 
    -infile {infile} -outfile {outfile}

usage: org.jchordbox.process.NormalizeMidiFile
 -color                           Activate the color if ANSI codes are
                                  supported on the current terminal.
                                  [Optional]
 -debug                           Activate debug mode. [Optional]
 -erasemarkers                    Erase all markers from the MIDI file.
                                  [Optional]
 -help                            Print this help. [Optional]
 -infile <infile>                 Input MIDI Filename. [Required]
 -newresolution <newresolution>   new MIDI file resolution. [Optional]
 -outfile <outfile>               Output MIDI filename. [Required]
 -settrack <settrack>             Overwrite or create the given tracknames
                                  in the MIDI file. The list of tracknames
                                  must be ordered. [Optional]

Ex:

$ java -cp /path/to/jchordbox.jar org.jchordbox.process.NormalizeMidiFile -infile example.mid -settrack Drum WarmPad -outfile result.mid

In this example, the file 'example.mid' is read as input file. The track names are changed. First instrument track is set to "Drum" and second instrument track to "WarmPad". The resulting MIDI sequence is write to 'result.mid'.

4.5. `ConcatenateMidiFile` (since 0.3)

SYNOPSIS: org.jchordbox.process.ConcatenateMidiFile 
    [ -debug ][ -color ][ -help ][ -newresolution {newresolution} ]
    [ -createmarker {createmarker} ] -infiles {infiles ... } -outfile {outfile}

usage: org.jchordbox.process.ConcatenateMidiFile
 -color                           Activate the color if ANSI codes are
                                  supported on the current terminal.
                                  [Optional]
 -createmarker <createmarker>     Add a marker to the MIDI sequence before
                                  processing. Useful for quick style
                                  integration of a MIDI file. The argument
                                  is the MIDI chord. [Optional]
 -debug                           Activate debug mode. [Optional]
 -help                            Print this help. [Optional]
 -infiles <infiles>               Input MIDI Filenames. [Required]
 -newresolution <newresolution>   new MIDI file resolution. [Optional]
 -outfile <outfile>               Output MIDI filename. [Required]

Ex:

$ java -cp /path/to/jchordbox.jar org.jchordbox.process.ConcatenateMidiFile -newresolution 960 -createmarker CM7 -infiles example1.mid example2.mid -outfile result.mid

In this example, the files 'example1.mid' and 'example2.mid' are read as input files. Their resolution are changed to 960 tick. For each input file, a marker is added on the first measure of the MIDI sequence the keynote is set to CM7 (for all markers). Then they are concatenate in the same order they are input. The resulting MIDI sequence is write to 'result.mid' file.

Chapter 5. Appendix

Table of Contents

5.1. Chords definition
5.2. Modes definition

5.1. Chords definition

The following items defines the chord families defined by JChordBox and their corresponding default mode setting:

Tetrad chords category (four degrees):

M7 : (intervals: 1 3 5 7) (default mode: 'ionian')
M7#5 : (intervals: 1 3 5# 7) (default mode: 'ionian 5#')
M7b5 : (intervals: 1 3 5b 7) (default mode: 'lydian 2#')
m7 : (intervals: 1 3b 5 7b) (default mode: 'aeolian')
m7#5 : (intervals: 1 3b 5# 7b) (default mode: 'aeolian')
m7b5 : (intervals: 1 3b 5b 7b) (default mode: 'locrian')
m7M : (intervals: 1 3b 5 7) (default mode: 'minor harmonic')
7 : (intervals: 1 3 5 7b) (default mode: 'mixolydian')
7sus4 : (intervals: 1 4 5 7b) (default mode: 'mixolydian')
7sus2 : (intervals: 1 2 5 7b) (default mode: 'mixolydian')
7#5 : (intervals: 1 3 5# 7b) (default mode: 'super locrian')
7b5 : (intervals: 1 3 5b 7b) (default mode: 'lydian 7b')
dim7 : (intervals: 1 3b 5b 7bb) (default mode: 'super locrian')
M6 : (intervals: 1 3 5 6) (default mode: 'ionian')
m6 : (intervals: 1 3b 5 6) (default mode: 'aeolian')

Triad chords category (three degrees):

Maj : (intervals: 1 3 5) (default mode: 'ionian')
min : (intervals: 1 3b 5) (default mode: 'aeolian')
aug : (intervals: 1 3 5#) (default mode: 'ionian 5#')
dim : (intervals: 1 3b 5b) (default mode: 'locrian')
sus4 : (intervals: 1 4 5) (default mode: 'mixolydian')
sus2 : (intervals: 1 2 5) (default mode: 'mixolydian')

5.2. Modes definition

The following items are the modes defined by JChordBox. They all have 7 degrees:

The major modes:

'ionian' : 1 2 3 4 5 6 7
'dorian' : 1 2 3b 4 5 6 7b
'phrygian' : 1 2b 3b 4 5 6b 7b
'lydian' : 1 2 3 4# 5 6 7
'mixolydian' : 1 2 3 4 5 6 7b
'aeolian' : 1 2 3b 4 5 6b 7b
'locrian' : 1 2b 3b 4 5b 6b 7b

The Minor Harmonic modes:

'minor harmonic' : 1 2 3b 4 5 6b 7
'locrian 6' : 1 2b 3b 4 5b 6 7b
'ionian 5#' : 1 2 3 4 5# 6 7
'dorian 4#' : 1 2 3b 4# 5 6 7b
'super phrygian' : 1 2b 3 4 5 6b 7b
'lydian 2#' : 1 2# 3 4# 5 6 7
'super locrian 7bb' : 1 2b 3b 4b 5b 6b 6

The Minor Melodic modes:

'minor melodic' : 1 2 3b 4 5 6 7
'dorian 2b' : 1 2b 3b 4 5 6 7b
'lydian 5#' : 1 2 3 4# 5# 6 7
'lydian 7b' : 1 2 3 4# 5 6 7b
'mixolydian 6b' : 1 2 3 4 5 6b 7b
'locrian 2' : 1 2 3b 4 5b 6b 7b
'super locrian' : 1 2b 3b 4b 5b 6b 7b

User Guide

Laurent Schwartz

Chapter 1. Introduction

1.1. JChordBox description

1.2. Licence and version

1.2.1. Version 0.1

1.2.2. Version 0.2

Enhancements

1.2.3. Version 0.3

Enhancements

Defects fixed

1.2.4. Version 0.4

Enhancements

Defects fixed

1.2.5. Version 0.5b

Enhancements

1.3. JChordBox Homepage

1.4. Help Wanted

1.5. Contributors

1.6. About this manual

1.7. JChordBox Installation

1.7.1. Installation on Ubuntu 12.04

Java Runtime Environment

Linux Sound Configuration

Unzip distribution package and install

Set environment

1.7.2. Installation on Windows

Java Runtime Environment

Unzip distribution package and install

Windows 7 : set JAVA_HOME and PATH variable

1.7.3. Installation on MAC

1.8. Useful application

1.8.1. On Ubuntu 12.04

1.9. Run JChordBox

Chapter 2. XML Structure

2.1. Common XML rules

2.1.1. 'id' and '*refid' attributes

2.1.2. <information/> element

2.2. Song file

2.2.1. The XML tag <use-style/>

2.2.2. The XML tag <tempo/>

2.2.3. The XML tag <section/>

The XML tag <keynote/> (since 0.4)

The XML tag <apply-groove/>

2.2.4. The XML tag <musical-form/>

2.2.5. Chord progression grammar

2.2.6. Chords syntax

2.3. Music style (accompaniement)

2.3.1. The XML tag <preferred-tempo/>

2.3.2. The XML tag <template-source/>

The inner xml tag <default-track/> type

The inner xml tag <rhythm-track/> type

The inner xml tag <chords-track/> type

2.3.3. The XML tag <groove/>

2.3.4. The XML tag <pattern/>

2.3.5. The XML tag <template-riff/> (also named Riff)

Chapter 3. How does it work ?

3.1. Chord and mode transposition

3.1.1. Note transposition with chord

3.1.2. Note transposition with mode

3.2. Selection Riff along its length

3.3. Selection Riff along its chord category

3.4. Riff selection in a Random Pattern

3.5. Long sequence Riff with a moving window

Chapter 4. Use the command line

4.1. GenerateSong

4.1.1. songname option (since 0.5b)

4.1.2. stylename option (since 0.5b)

4.2. CreateStyleFromMidiFile

4.2.1. Marker policy

Create normal Riff associated to a Pattern

Create a Pattern with random alternatives

Create a Riff with a long sequence and set a moving window

4.3. SongPlayer (since 0.4)

4.4. NormalizeMidiFile (since 0.3)

4.5. ConcatenateMidiFile (since 0.3)

Chapter 5. Appendix

5.1. Chords definition

5.2. Modes definition

2.2.1. The XML tag `<use-style/>`

2.2.2. The XML tag `<tempo/>`

2.2.3. The XML tag `<section/>`

The XML tag `<keynote/>` (since 0.4)

The XML tag `<apply-groove/>`

2.2.4. The XML tag `<musical-form/>`

2.3.1. The XML tag `<preferred-tempo/>`

2.3.2. The XML tag `<template-source/>`

The inner xml tag `<default-track/>` type

The inner xml tag `<rhythm-track/>` type

The inner xml tag `<chords-track/>` type

2.3.3. The XML tag `<groove/>`

2.3.4. The XML tag `<pattern/>`

2.3.5. The XML tag `<template-riff/>` (also named `Riff`)

3.2. Selection `Riff` along its length

3.3. Selection `Riff` along its chord category

3.4. `Riff` selection in a `Random Pattern`

3.5. Long sequence `Riff` with a moving window

4.1. `GenerateSong`

4.2. `CreateStyleFromMidiFile`

Create normal `Riff` associated to a `Pattern`

Create a `Pattern` with random alternatives

Create a `Riff` with a long sequence and set a moving window

4.3. `SongPlayer` (since 0.4)

4.4. `NormalizeMidiFile` (since 0.3)

4.5. `ConcatenateMidiFile` (since 0.3)