[DESCRIPTION]
Toonloop is a live stop motion animation software. It aims to show the creation process to the audience as well as the result of the creation. The frame by frame animation is made by adding frames one by one to a clip made of many frames. Clips are displayed in a never ending loop. Toonloop can also grab video images continuously.

Toonloop is a great tool for teaching new medias to children. It can also be used as a professional software for movie creators, though it is mainly intended to be used in a live kiosk of show. In the left window, you can see what is seen by the live camera. In the right window, it is the result of the stop motion loop. To add an image to the current clip, simply press the space bar.

Toonloop can be controlled using MIDI input, or the Open Sound Control protocol. (OSC) Images are saved to the disk in the JPEG format, and the clips are saved using the photo-JPEG video codec. (using mencoder)

[SYNOPSIS]
toonloop [options]

[EXAMPLES]
Choosing the video input can be tricky. The name of the GStreamer video source element is guessed from the \-\-video-source option. (its short form is \-d) If it's "/dev/video0" or "/dev/video1", Toonloop will use the v4l2src element. (a Video4Linux 2 video device) 

To use a V4L2 video camera:

 toonloop \-d /dev/video0

To display some color bars:

 toonloop \-d test

To continuously grab screeshots from X11: (very slow)

 toonloop \-d x

Note that if Toonloop crashes at startup, you should verify that your camera /dev/video0 is really a V4L2 camera, and that it is present. The default width and height are 640x480. You might try to change those using the \-\-width and \-\-height options. You can use tools such as ivtv\-utils, gst\-launch, gst\-inspect or xawtv to investigate about your video devices under GNU/Linux.

Some Toonloop features are enabled only when a value is given for their option. It is the case for MIDI, OSC sending and OSC receiving.
 - MIDI is enabled if the user specifies a \-\-midi-input
 - OSC sending is enabled if the user specifies a \-\-osc-send-port
 - OSC receiving is enabled if the user specifies a \-\-osc-receive-port

Here is how to launch a fullscreen timelapse:

 toonloop \-\-enable-intervalometer \-\-intervalometer\-rate 0.1 \-\-playhead\-fps 60 \-\-max\-images\-per\-clip 600 \-\-remove\-deleted\-images \-\-fullscreen \-\-layout 2 \-\-verbose


[INTERACTIVE USAGE]
Toonloop is an interactive software. While it runs, the user can control it using keyboard keys. Here is the list of keystrokes to control Toonloop.

Toonloop interactive keyboard controls :
 - Space: Grab a single image.
 - Escape: Switch fullscreen mode.
 - Delete: Erase the last captured frame.
 - Ctrl-q: Quit.
 - Page-down: Switch to the next clip.
 - Page-up: Switch to the previous clip.
 - Number from 0 to 9: Switch to a specific clip.
 - Ctrl-number: Switch to a specific layout.
 - s: Save the current clip as a movie file.
 - period (.): Toggle the layout.
 - Tab: Change the playback direction.
 - r: Clear the current clip.
 - Caps lock: Toggle video grabbing.
 - a: Toggle on/off the intervalometer.
 - k: Increase the intervalometer interval by 1 second.
 - j: Decrease the intervalometer interval by 1 second.
 - Right: Move writehead to the next image.
 - Left: Move writehead to the previous image.
 - Return: Move writehead to the last image.
 - semicolon (;): Move writehead to the first image.
 - o: Enable/disable onion skinning.
 - (): Decrease/increase frame blending in playback layout.
 - []: Increase/decrease opacity of the live input image in the overlay layout.
 - F1: Show help.

[OSC INTERFACE]
Toonloop can send and receive messages using the Open Sound Protocol. 

Messages Toonloop can receive:

 - /ping: Answer with /pong
 - /pong: Do nothing.
 - /toon/quit: Quit
 - /toon/frame/add: Grab a frame
 - /toon/frame/remove: Remove a frame

Toonloop sends the following OSC messages:

 - /pong
 - /toon/clip/cleared i:clip_number
 - /toon/clip/fps i:clip_number i:fps
 - /toon/clip/playhead i:clip_number i:image_number s:file_name
 - /toon/clip/saved i:clip_number s:file_name
 - /toon/clip/select i:clip_number
 - /toon/frame/add i:clip_number i:frame_number
 - /toon/frame/remove i:clip_number i:frame_number
 - /toon/playhead/direction i:clip_number s:direction
 - /toon/playhead/none

[MIDI INTERFACE]
Toonloop can be used with MIDI control devices. Here is the list of controls it supports: 

 - 64: (sustain pedal) Grab a still image
 - 80: Grab video
 - Program change: choose a clip
 - 7: (main volume) change playback speed

The sustain pedal controls single-image grabbing, the pedal control number 80 toggles video recording on and off, the volume pedal controls the playback speed and the 10 program changes select the clip that is currently edited and played back. 

The Roland GFC-50 Foot Controller is a nice MIDI device that is useful to control Toonloop. 

[AUTHOR]
Alexandre Quessy, Tristan Matthews and Vasilis Liaskovitis.

[HISTORY]
2008 - Version 0.x written by Alexandre Quessy in Processing/Java

2008 - Version 1.x written by Alexandre Quessy with contributions from Tristan Matthews and Arjan Scherpenisse in Python

2010 - Version 2.x written by Alexandre Quessy with contributions from Tristan Matthews and Vasilis Liaskovitis in C++ 

Contributers include Tristan Matthews, Vasilis Liaskovitis, mose, Arjan Scherpenisse and the Society for Arts and Technology.

Toonloop is an idea of Alexandre Quessy, and is his research project for his master at UQAM. It is similar to the live animation work of Pierre Hebert, Frédéric Back and other artists. Toonloop is released under the GNU GPL. 

[REPORTING BUGS]
See http://www.toonloop.com for the URL of the Toonloop mailing list.

[COPYRIGHT]
Copyright 2010 Alexandre Quessy
<alexandre@quessy.net>

Toonloop is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

Toonloop is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the gnu general public license
along with Toonloop.  If not, see <http://www.gnu.org/licenses/>.

[SEE ALSO]
gstreamer\-properties(1), gst\-inspect(1), mencoder(1)
