::

   _____                 _                   
  |_   _|__   ___  _ __ | | ___   ___  _ __  
    | |/ _ \ / _ \| '_ \| |/ _ \ / _ \| '_ \ 
    | | (_) | (_) | | | | | (_) | (_) | |_) |
    |_|\___/ \___/|_| |_|_|\___/ \___/| .__/ 
                                      |_|    
  
Toonloop is a live animation software. It aims to show the creation process to the audience as well as the result of the creation. Frame by frame animation clips can made by adding images one by one. 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 NEWS file for its history and 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
ctrl-e             : export the current clip as a movie file
Tab                : change the playback direction
r                  : clear the current clip
Caps Lock          : toggle video grabbing
period             : toggle the layout
F1                 : show help

See the toonloop(1) man page, or press F1 for all the key controls.

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

Versioning
----------

Toonloop uses the common "Linux kernel" versioning system, where even-numbered minor versions are stable and odd-numbered minor versions are development snapshots.

The micro version indicates the origin of the release: even micro numbers are only used for released archives; odd micro numbers are only used on the Git repository.

A stable series means that the command-line options and the interactive keyboard controls should not change much for all tags whose version number start with the same major-minor numbers. Some new features might be developped in that branch, but each release should be backward-compatible with their ancestor. Releases from a stable series should be use for production. 

In contrast, unstable branches consist of tags which are developer snapshots. They are not expected to be compatible with any other version. Some features might change between different stable branches.


Known Bugs
----------

Here is a list of known bugs. See also the TODO file. That is what we mainly use to manage issues, rather than a Web application. Please read and write on the mailing list if you encounter some issues with Toonloop.

 * The portrait layout doesn't look nice: both images overlap when not in 4:3 ratio.
 * If you run toonloop from a directory in your home (not in /usr/local) it might use the midi.xml file in /usr/local, unless you are in the same directory as the executable. Be careful.


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

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

 sudo apt-get install 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 many versions of Debian and Ubuntu. It should not currently build on Mac OS X and Windows, but the idea is to port it eventually to many platforms.

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

 sudo apt-get install ffmpeg gettext gstreamer0.10-ffmpeg gstreamer0.10-plugins-bad gstreamer0.10-plugins-base gstreamer0.10-plugins-good gstreamer0.10-plugins-ugly gstreamer0.10-x help2man libasound-dev libavc1394-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 libgdk-pixbuf-dev libglew1.5-dev libglib2.0-dev libglu1-mesa-dev libgstreamer-plugins-base0.10-dev libgstreamer0.10-dev libraw1394-dev libstk0-dev libxml2-dev libxv-dev mencoder mscgen


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

Here is how to build it::

 ./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`)

If you want to install the bash completion script, you should set the sysconfdir command-line option given to ./configure to "/etc". Here is an example::

 ./configure --sysconfdir=/etc

Be warned that the command above would overwrite the default Toonloop config files installed by your package manager, if any. 

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

You can try you r V4L2 camera with many different tools::

  vlc v4l2:///dev/video0

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

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


Copyright and license
---------------------

Toonloop

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