 _____                 _                   
|_   _|__   ___  _ __ | | ___   ___  _ __  
  | |/ _ \ / _ \| '_ \| |/ _ \ / _ \| '_ \ 
  | | (_) | (_) | | | | | (_) | (_) | |_) |
  |_|\___/ \___/|_| |_|_|\___/ \___/| .__/ 
                                    |_|    

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 professionnal 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.

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

See the RELEASE file for up-to-date information about this version of Toonloop.

Most of the information on how to use it is in the toonloop(1) man page.

How to use Toonloop
-------------------

To make it short, press space to capture an image, it will be recorded 
in your default directory (~/Documents/toonloop/default/) under jpg format.

space              : capture an image
delete             : remove last captured image
esc                : switch fullscreen
ctrl-q             : quit
Page down          : next clip
Page up            : previous clip
Number from 0 to 9 : switch to a specific clip
s                  : saves the current clip as a movie file
Tab                : changes the playback direction
r                  : clear the current clip
Caps Lock          : toggle video grabbing
a                  : Toggles on/off the intervalometer
k                  : increase intervalometer interval by 1 second
j                  : decrease intervalometer interval by 1 second
period             : Toggles the layout
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

Toonloop saves the clip in its project directory. The default project directory is the ~/Documents/toonloop/default/ directory, where "~" is your HOME directory. 


Basic Tools for Compiling
-------------------------

To build applications such as Toonloop, you should have the following packages installed on your system:

 automake,
 bison,
 build-essential,
 flex,
 libtool

These instructions are for Ubuntu GNU/Linux - and should work on Debian GNU/Linux as well. Toonloop should build on other platforms too. Please help us improving this documentation if you get it to work on other operating systems.


Dependencies
------------

Toonloop 1.9.x has been built successfully on Debian squeeze and Ubuntu 10.04 Lucid Lynx. It should build on Mac OS X and Windows too, but that might require some modifications. 

Here is the list of Debian package that you will need to build Toonloop 2.x. 

 ffmpeg,
 gettext,
 gstreamer0.10-alsa,
 gstreamer0.10-ffmpeg,
 gstreamer0.10-plugins-bad,
 gstreamer0.10-plugins-base,
 gstreamer0.10-plugins-good,
 gstreamer0.10-plugins-ugly (>= 0.10.14),
 gstreamer0.10-pulseaudio,
 gstreamer0.10-x,
 help2man,
 libasound-dev,
 libboost-program-options-dev,
 libboost-filesystem-dev,
 libboost-thread-dev,
 libboost-date-time-dev,
 libboost-signals-dev,
 libboost-system-dev,
 liblo-dev,
 libclutter-1.0-dev,
 libclutter-gst-0.10-dev,
 libclutter-gtk-0.10-dev,
 libglew1.5-dev,
 libglib2.0-dev,
 libglu1-mesa-dev,
 libgstreamer-plugins-base0.10-dev,
 libgstreamer0.10-dev (>= 0.10.23),
 libgtk2.0-dev,
 libstk0-dev,
 libxml2-dev,
 libxv-dev,
 mencoder

The packages listed below are not used yet, but we plan to use them 
soon.

 libxml++2.6-2,
 libxml++2.6-dev,

How to build Toonloop
---------------------

 ./autogen.sh
 ./configure
 make
 sudo make install

There is also the handy ./one_click_build.sh that does it in a single script. (except the `sudo make install`)


How to run Toonloop
-------------------

Note that you need to have the GLX acceleration set up in order to use Clutter, and therefore Toonloop. 

Here is how to lauch Toonloop using the default V4L2 video input: 

 toonloop -d /dev/video0

You can also try the "test" and "x" video sources:

 toonloop -d test
 toonloop -d x

See the toonloop(1) man page for details.


DEVELOPERS DOCUMENTATION
------------------------

To build the HTML documentation, make sure you have doxygen installed, then:

 make html

See the CONTRIBUTING file.


Additional Configuration Notes
------------------------------

You might need to properly configure your V4L2 video device::

  sudo apt-get install ivtv-utils
  v4l2-ctl --set-input=1
  v4l2-ctl --set-standard=ntsc
  v4l2-ctl --set-fmt-video=width=768,height=480
  v4l2-ctl --set-ctrl=saturation=65535,contrast=32768

If you use two displays, you might want to use 2 separate X screens::

  sudo nvidia-settings
  DISPLAY=:0.1 toonloop --fullscreen

