ERROR(1)

NAME
ERROR - The Toonloop Live Animation Performance Tool

SYNOPSIS
toonloop [options]

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)

ERROR (std::logic_error): basic_string::_S_construct null not valid

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 use a DV video Firewire camera:

 toonloop -d dv

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.
 - Ctrl-e: Save the current clip as a movie file.
 - Ctrl-s: Save the whole project.
 - 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
 - /toon/clip/select i:clip_number : Selects a clip
 - /toon/clip/save_current : Saves the currently selected clip
 - /toon/clip/import_image s:file_name : Imports an image from the filesystem

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. The MIDI bindings are configurable by editing an XML file. This way, anyone can decide how to control Toonloop with any different MIDI controller.

The default presets are set so that the sustain pedal controls single-image grabbing, and program change controls clip selection.

To customize the MIDI binding rules, one must copy the midi.xml that comes with Toonloop (typically installed in /usr/share/toonloop/presets/midi.xml) into ~/.toonloop/midi.xml. The syntax of that MIDI rules file is pretty straightforward. For example, the following rule makes it so that pressing the note 60 down selects clip number 19. (60 is the central C note on a piano)

 <note_on number="60" action="select_clip" args="19" />

Other possible actions include setting the value of a float or int property of the main Toonloop controller. The following rule specifies that pressing the sustain pedal down grabs and image.

  <control_on number="64" action="add_image" />

See the documentation for the MidiBinder class for more about MIDI rules. Run Toonloop with the --print-properties option to list the properties you can change using the "control_map" rule and the "set_float" or "set_int" action.

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.

AUTHOR
Alexandre Quessy, Tristan Matthews and Vasilis Liaskovitis.

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

COPYRIGHT
Copyright (c) 2010 Alexandre Quessy <alexandre@quessy.net> Copyright (c) 2010 Tristan Matthews <le.businessman@gmail.com>

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)