Advanced how-to

Here are more informations on how to use Toonloop 1.x.

WARNING: These notes are for Toonloop 1.x, not Toonloop 2.x. As we do not support anymore Toonloop 1.x, one should read the manual page for Toonloop, and read its source code, in order to know how to use it as an advanced user. In the Developers section, there is a link to the auto-generated documentation of the C++ code.

Using Toonloop with a gamepad

It is possible to control Toonloop with a USB gamepad. We suggest the Logitech Precision USB gamepad. Here is the list of gamepad controls:

Button 1: Remove an image
Button 2: Play back and forth
Button 3: Add an image
Button 4: Toggle onion skinning
Button 5: Add an image
Button 6: Add an image
Button 7: Add an image
Button 8: Add an image
Button 9: Save as a clip
Button 10: Erase all images
Up: Faster
Down: Slower
Left: Play backward
Right: Play forward

You will need to launch Toonloop with the --enable-joystick option. To do so, you will need to start it using the terminal.

Starting Toonloop from the terminal

On Ubuntu, the Terminal is an application located in the Application - Accessories menu. You can launch Toonloop from there, and specify arguments and options to customize how the software behaves. Try entering the following command, and press "enter".

toonloop -v

You should see a lot of text in the terminal window. Toonloop should be running.

The Toonloop Man Page

Like most GNU/Linux applications, Toonloop comes with a manual that can be read in the terminal. To read it, simply type "man toonloop" in your terminal window and press enter.

Use the up and down arrow keys to scroll the text. Press Q to quit.

Custom Options

The --option command line option allows one to specify specific keyword identified by a keyword. Their type can be integer, float, string of boolean. Boolean options can be given using integer of python-style boolean string. A true value can be specified as True, or 1. A false value is set as 0 or False.

You can launch Toonloop with a whole bunch of options. Options are set
using the -o flag :

toonloop -o toonloop_home ~/Public/toonloop -o project_name hello -o intervalometer_enabled False -o bgimage_glob_enabled True -o image_flip_horizontal True -o chromakey_on True -o chromakey_on True -o chromakey_r 0.2 -o chromakey_g 0.9 -o chromakey_b 0.0 -o chromakey_thresh 0.5 -o chromakey_slope 0.2 -o fudi_enabled True -w 320 -v

Once Toonloop has been started by some keyword config options, those options can be saved to the ~/.toonloop.json configuration file. Next time Toonloop is launched, those configuration options will be read from that file. If Toonloop behaves strangely, you should try deleting that file.

Here is the list of options with their default values:

-o autosave_enabled True
-o autosave_on False
-o autosave_rate_seconds 600.0
-o bgcolor_b 0.2
-o bgcolor_g 0.8
-o bgcolor_r 1.0
-o bgimage [toonloop package data path]/bgimage_05.jpg
-o bgimage_enabled False
-o bgimage_glob
-o bgimage_glob_enabled False
-o config_file ~/.toonloop.json
-o delete_jpeg False
-o display_height 480
-o display_width 640
-o framerate_max 30
-o framerate_min 1
-o fudi_enabled False
-o fudi_receive_port 15555
-o fudi_send_host localhost
-o fudi_send_port 17777
-o fx_white_flash True
-o fx_white_flash_alpha 0.5
-o image_flip_horizontal False
-o image_height 240
-o image_width 320
-o intervalometer_enabled True
-o intervalometer_on False
-o intervalometer_rate_seconds 30.0
-o max_num_clips 10
-o midi_enabled False
-o midi_input_id -1
-o midi_note_play 62
-o midi_note_record 60
-o midi_pedal_control_id 64
-o midi_verbose True
-o onionskin_enabled True
-o onionskin_on False
-o onionskin_opacity 0.3
-o osc_enabled False
-o osc_listen_port 7772
-o osc_send_host localhost
-o osc_send_port 7770
-o project_name new_project
-o toonloop_home ~/Documents/toonloop
-o verbose False
-o video_device 0
-o web_enabled False
-o web_server_port 8000



Toonloop sends the following OSC messages :

* /toon/framerate i
* /toon/writehead i
* /toon/playhead i
* /toon/clip/index i
* /sampler/play/start i
* /sampler/play/stop i
* /sampler/record/start i
* /sampler/record/stop i

Toonloop listens for the following OSC messages :

* /toon/frame/add
* /toon/frame/remove
* /toon/playhead i
* /toon/osc/subscribe s i 
* /toon/clip/select i
* /toon/clip/save


Toonloop can be controlled using a MIDI keyboard. It is best used with a sustain pedal. Control #64 seems to be consistantly mapped to the sustain pedal and is set up to add a frame to the current clip. This can be changed using the keyword configuration options which start with "midi".

Application Notes

Using The Chroma Key Effect

Chroma key is a technique for mixing two images or frames together in which a color from one image is made transparent, revealing another image behind it. The background wall should be of a color such as light green and be evenly lit. See the [[|Wikipedia Chroma key page]] for more informations. For a green background, Toonloop should be launched with a command line like this.

toonloop -o toonloop_home ~/Public/toonloop -o project_name hello -o intervalometer_enabled False \
-o  bgimage_glob_enabled  True  -o  image_flip_horizontal True -o fudi_enabled True -w 320 -v