Running Juggling Lab from the command line

To use Juggling Lab from the command line, download and expand the CLtools.zip file from the Download section. This file contains command-line scripts for running Juggling Lab on a variety of platforms.

Windows: The batch file jlab.bat runs Juggling Lab from the command line. It looks for the Juggling Lab executable at its usual install location at C:\Program Files\Juggling Lab\Juggling Lab.exe.

macOS: The script file jlab runs Juggling Lab on macOS using the application Juggling Lab.app. Make sure that Juggling Lab.app is either in the same directory as jlab, or in the /Applications directory.

Debian Linux: The script file jlab runs Juggling Lab on Debian using the application installed at /opt/juggling-lab/bin/Juggling Lab.

Other Unix systems: The same script file jlab runs on other Unix systems too, but since there is no Java runtime bundled with Juggling Lab on these systems you will need to have Java 11 or later installed on your computer. The script jlab expects to find JugglingLab.jar in the same directory as the script.

Once the script is in place, run it with no arguments to print out a help message. If this works then it is finding the Juggling Lab executable correctly:

    jlab

Features available from the command line

    jlab start

Launches the application.

    jlab open <file1.jml> <file2.jml> ...

Launches the application and opens the listed JML files.

    jlab anim <pattern> [-prefs <prefs>]

Opens a window with an animation of the given pattern, using the given (optional) animation preferences.

    jlab gen <number> <max throw> <period> [-options] [-out <path>]

Runs the siteswap generator and prints a list of patterns, using the given set of generator options to define the number of objects, etc. Type jlab gen with no options for a help message. The output may optionally be written to a file.

    jlab trans <pattern A> <pattern B> [-options] [-out <path>]

Runs the siteswap transition-finder and prints a list of transitions from pattern A to pattern B. Type jlab trans for a help message. The output may optionally be written to a file.

    jlab togif <pattern> [-prefs <prefs>] -out <path>

Saves a pattern animation to a file as an animated GIF, using the given (optional) animation preferences. If fps is not specified in the animation preferences, Juggling Lab saves with a default of 33.3 frames per second.

    jlab tojml <pattern> [-out <path>]

Converts a pattern to JML notation, Juggling Lab's internal XML-based pattern description. This may optionally be written to a file.

    jlab verify <file1.jml> <file2.jml> ... [-out <path>]

Checks the validity of the listed JML files. For pattern list files, the validity of each line within the list is verified. The output may optionally be written to a file.

<pattern> format: For the <pattern> inputs above, this can take any of three formats:

  1. A pattern in siteswap notation, for example 771 or (6x,4)(4,6x).
  2. A siteswap pattern annotated with additional settings, in a semicolon separated format. These settings are identical in format to that used in the pattern entry panel.
  3. A JML pattern read in from a file, using the format '-jml <path>'.

<prefs> format: The <prefs> is always optional, and is used to override Juggling Lab's default animation preferences. These are given in a semicolon-separated format, identical in format to the animation preferences variables recognized by the GIF server.

Important note: The command line environments on both Windows and Unix treat certain characters in special ways. To avoid confusion, on Windows use double-quotes ("like this") around any command line parameters with non-alphanumeric characters, as in the examples below. On macOS, Linux, and other Unix systems use single quotes ('like this').

Examples:

    jlab anim "(6x,4)*"
    jlab togif "pattern=3;dwell=1.0;bps=4.0;hands=(-30)(2.5).(30)(-2.5).(-30)(0)." -out mills.gif
    jlab anim -jml my_favorite_pattern.jml
    jlab anim 771 -prefs "stereo=true;width=800;height=600"
    jlab anim 5B -prefs "bouncesound=true"
    jlab gen 5 7 5

Running the siteswap generator

Command-line access is especially useful for running the siteswap generator, where there are no limits on execution time or number of patterns generated as there are in the application version. All of the features in the siteswap generator UI have corresponding options from the command line. (Type "jlab gen" for a summary.) For example you can experiment with these:

    jlab gen 5 7 5
    jlab gen 5 7 5 -g
    jlab gen 5 7 5 -g -n
    jlab gen 5 7 5 -g -no
    jlab gen 5 7 5 -ng -se
    jlab gen 5 7 5 -x 2 3
    jlab gen 5 7 5 -x 23
    jlab gen 5 7 18 -prime
    jlab gen 3 7 27- -prime -n
    jlab gen 4 - 3 -f -rot -se -n

Generating synchronous patterns:

    jlab gen 4 6 6 -s -g

Multiplexing has a number of options designed to filter out less interesting patterns:

    jlab gen 5 6 4 -m 2 -g
    jlab gen 5 6 4 -m 2 -g -mt

Here are some examples involving more than one juggler:

    jlab gen 6 4 1 -j 2
    jlab gen 6 4 2 -j 2 -g -jp -m 2 -d 1 -l 1

Experiment and see what you can discover! The number of possible siteswap patterns is vast, so it's easy to find patterns that have never been tried or even seen before. If you give jlab a task that takes too long to complete, stop it with control-c on the keyboard.