----- {i} '''[[FreejTutoriales|Español]]''' ----- = Freej beginner's tutorial = FreeJ is a vision mixer: a digital instrument for realtime video manipulation used in the fields of dance teather, veejaying, online streaming, medical visualisation and TV. It runs a video engine in which multiple layers can be filtered thru effect chains and then mixed together with images, movies, live cameras, particle generators, text scrollers and vector graphics. All the resulting video mix can be shown on a screen, encoded into a movie and streamed live to the internet. FreeJ can be controlled locally or remotely, and even from multiple places at the same time, using its ascii console interface; operations can be scripted in javascript and triggered live via keyboard, mouse, MIDI controllers, Joysticks, OSC clients, Wiimotes and many other devices. FreeJ's sourcecode is written in portable C and C++ and it works on most platforms supported by the GNU C compiler, including 32bit and 64bit processors, PowerPC and various ARM flavours. FreeJ is released free under the GNU General Public License (v3). [[http://freej.dyne.org/tut/img/00.jpg|{{http://freej.dyne.org/tut/img/00-mini.jpg}}]] == FEATURES == * reads and renders layers from multiple sources: webcams, TV, divx/avi movies, images, txt files and more * can encode in Ogg/Theora video, recording on local file and streaming live to an online Icecast server * can be controlled from remote: VJoE - VeeJay over Ethernet * can be scripted in object oriented javascript * supports frei0r and freeframe video plugins * very efficient video engine with multithreaded layers * Emacs/Vi style console with hotkeys and completion * multiple controllers at the same time (Midi,Joystick etc.) * 100% Free and open source, GCC 4 compliant portable code == HISTORY == This software started being developed as a digital instrument Jaromil used in dance-theater performances. Since 2001 ongoing development took inspiration from various artists and programmers: Andreas Schiffler, Roberto Paci Dalo', Tom Demeyer, Francescopaolo Isidoro, Kentaro Fukuchi, Luigi Pagliarini, Isabella Bordoni, to name just a few. The first motto for this software was "Set the VeeJay Free!" In 2003 Kysucix joined development, contributing the streaming feature and helping to include the javascript parser. He employed FreeJ in interactive installations while working with Studio Azzurro. Since 2004 development has received support from the Netherlands Media Art Insitute. In 2005 Mr.Goil joined development, writing programmable controllers, reviewing the scripting environment and adding more features. In 2007 the Austrian initiative Netculture lab supported Jaromil and Mr.Goil developing the BeTV release: it enhanced scriptability and streaming, with a major cleanup of the code and wider support of video plugins. In 2008 both Jaromil and Mr.Goil were meeting regularly in code sessions which rapidly drove the project towards a stable 1.0 release of FreeJ engine and javascript API. Meanwhile Blender2Crystal developer Caedes is experimenting with python bindings and uses of the FreeJ engine in a 3d environment. For the time being, FreeJ is employed in various video performances, interactive installations and online TV streams, as well used for visualisations in medical analysis. Developers are keen to accept projects and propositions in order to sustain the development activity and involve more developers. Please join our mailing list on http://lists.dyne.org to collaborate and be part of our history :) == GET STARTED == As well as this guide, you can have a look at the README, INSTALL and other files distributed with the package or source code to start rolling with FreeJ. Also, check the online documentation on http://freej.dyne.org Most powerful uses of FreeJ involve scripting for live interaction with devices and video compositing, but a first look at the console controller can give an initial picture of how the software works. Tutorials, examples and scripting reference are available from the website as well along with the distributed sourcecode, in the doc/ and scripts/ directories. GNU/Linux distributions usually ship these files inside /usr/share/freej and /usr/doc/FreeJ* As development continues, suggestions and feedback are welcome. Join us on the freej mailinglist on http://lists.dyne.org and let us know your impressions and ideas. == Target of this manual == In this part you will learn: * installing freej * the basics of using ''freej'' and how its user interface is organized * how to use ''freej'' to show movies and static images * how to use layers, so you can use more than one movie * how to mix layers with each other * how to add visual effects to displayed movies However, we assume that you: * can use a GNU/Linux system (command line) * will really do all the exercises from this tutorial -- if you only read it, you'll learn nothing. You have to be hands on! :) * will let us know about any problems, comments and suggestions, so we can make this tutorial better ---------- == contents == * [[#installation|installation]] * [[#start|the first start]] -- how to start and stop ''freej'' * [[#ui|user interface]] -- what is what in ''freej'' * [[#movies|showing movies with freej]] * [[#layers|using layers]] * [[#mix|mixing two movies]] (fun starts) * [[#alpha|adding transparency]] * [[#effects|using effects]] -- basics * [[#more_on_effects|effects disabling and deleting]] ---------- <> == installation == === requirements === To compile and run FreeJ it is necessary to have: 1. a working GNU/Linux system or Darwin/OSX -> see the documentation in README.OSX 2. SDL libraries http://www.libsdl.org 3. PNG libraries http://www.libpng.org 4. S-LANG libraries http://www.s-lang.org Several other libraries are optional and strongly recommended to benefit from all features implemented in FreeJ, in particular Ogg/Vorbis/Theora libraries available on http://www.xiph.org === how to install === ==== GNU/Linux users ==== On Debian and Ubuntu 'freej' stable packages are ready to install. Release candidates up to date with latest development are also published on: http://launchpad.org/~jaromil/+archive On Gentoo it is also possible to 'emerge freej' ==== Apple/OSX users ==== Binary packages of FreeJ for OSX should be available from the website http://freej.dyne.org, although they might be a bit outdated and limited in features. It is also possible to compile FreeJ from source using XCode, MacPorts and Fink. Follow the instructions in README.OSX. If you are a talented OSX programmer, please consider getting in touch with us and contributing to make this software better on the Apple platform, there isn't much work to do anyway. ==== Windows users ==== There is no version of FreeJ on the M$ platform yet, but there is a quick and easy way to try this software without installing anything. Just boot the dyne:bolic liveCD. [[http://dynebolic.org/|dynebolic live CD]]. {{http://dynebolic.org/img/cd_small.jpg}} ==== Game console users ==== Experimental builds of FreeJ have been successfully run on the GP2X and NintendoDS consoles. It should be also possible to make FreeJ run on other embedded devices and we are very interested in doing so, please contact us if you are as well :) === installing from source code === ''So yo' smart, huh? I thou' yo' head woul' be biggah! (Idiocracy, Mike Judge, 2006)'' ==== x86 PC ==== First, be sure to have: * all the required libraries and tools: ''cdbs, libtool, flex, bison, libsdl-dev, libpng-dev, libfreetype6-dev, libfontconfig-dev, libogg-dev, libvorbis-dev, libjpeg-dev, libslang2-dev, libtheora-dev, libavcodec-dev, libavformat-dev, libswscale-dev, libunicap2-dev, libbluetooth-dev, fftw3-dev, libjack-dev, libasound-dev, libhtml-template-perl, python-dev, swig'' If you're going to create Debian packages, you need also ''debhelper and pkg-config'' ''' PLEASE NOTE: ''automake 1.9'' is REQUIRED - it doesn't work with a different version (we're hardly working to fix this).''' * A working GNU/Linux system with X or framebuffer video * SDL libraries http://www.libsdl.org * PNG library (compile with _ZLIB_ support) http://libpng.org * To have some more assembler mmx optimized filters you need ''NASM'': NASM netwide assembler compiler http://sf.net/projects/nasm then go in the filters/nasm-x86 and type {{{ make }}} copy by hand the *.so filters in a ~/.freej/ directory in your home, and you're ready to rock'n roll! Now, '''download freej latest stable version''' from http://ftp.dyne.org/freej extract the source archive and compile it: {{{ $ tar xvfz freej.tar.gz $ cd freej (if you are reading this file from the sourcecode, start from here) $ ./configure $ make $ sudo make install }}} this will install: * effect plugins into /usr/local/lib/freej/ * freej binary in /usr/local/bin/ (or any other prefix you configured instead of the default /usr/local) To launch it, just type {{{ freej }}} and that's all! ==== Darwin/OSX ==== Please see README.OSX into the tarball. === from debian packages === Assuming you can do {{{ apt-get install freej }}} to have a precompiled FreeJ, to squeeze the best out of your damn box you may want to compile this software with machine specific optimizations! The source configure script guesses the best compiler optimization flags for your CPU. The following commands are then necessary to set your build environment. From inside the freej source directory do: {{{ sudo apt-get install autoconf automake1.9 sudo apt-get build-dep freej dpkg-buildpackage -rfakeroot }}} === INSTALL FROM GIT REPOSITORY === (''I know shit's bad right now with all that starvin' bullshit. And the dust storms. And we runnin' out of French Fries and burrito coverings. But I got a solution.'' - Idiocracy, Mike Judge, 2006) Assuming you have Debian/Ubuntu (for other distro there can be some differences), with all tools needed and all developers lib installed (e.g. build-essential, the libs above etc.: You need git: {{{ apt-get install git-core }}} So, get the code: {{{ git clone git://code.dyne.org/freej.git }}} After this, you will have a "freej" dir. Enter it, and do {{{ ./autogen.sh }}} That will create all the necessary configuration files (It may ask you to install some missing libraries or to install the required automake version 1.9). Then also run the "configure" script. If you need to enable/disable something, relaunch "configure" with your chosen options. When you're satisfied: {{{ make && sudo make install }}} That's all! If you want to experiment with live video, please be sure to have a working camera and to activate it from your BIOS settings (e.g. for eeepc 701), otherwise it will not work! :) ---------- <> == the first start == Create a directory, for example ''freej_tmp''. We will put our images, movies etc in this directory and we will play inside it: {{{ mkdir freej_tmp cd freej_tmp }}} Download [[http://freej.dyne.org/tut/data/ipernav.png|this image]] to ''freej_tmp'' directory. Now start ''freej'': {{{ freej ipernav.png }}} As a result, ''freej'' starts and shows the picture ''ipernav.png''. [[http://freej.dyne.org/tut/img/01.png|{{http://freej.dyne.org/tut/img/01-mini.jpg}}]] ---------- <> == user interface == ''Freej'' consists of two windows: * output window – in this window our movies, pictures etc are shown, * console window – this window is used to interact with ''freej'' – give commands, load new pictures, movies etc, [[http://freej.dyne.org/tut/img/02.jpg|{{http://freej.dyne.org/tut/img/02-mini.jpg}}]] In console window, press ''ctrl-h''. You will see the list of shortcuts. [[http://freej.dyne.org/tut/img/03.png|{{http://freej.dyne.org/tut/img/03.png}}]] As you can see, ''[ctrl+c]'' means ''quit''. Press ''[ctrl+c]''. You are prompted to confirm that you really want to quit ''freej''. Type ''yes [enter]'' [[http://freej.dyne.org/tut/img/04.png|{{http://freej.dyne.org/tut/img/04.png}}]] ---------- <> == some more fun – movies == So far we just used static image – not so much fun. But the very same way we can use a movie. Download [[http://freej.dyne.org/tut/data/kury.avi|this movie]] to ''freej_tmp'' directory. Then start ''freej'': {{{ freej kury.avi }}} As a result, ''freej'' starts and shows the movie ''kury.avi''. [[http://freej.dyne.org/tut/img/05-mini.jpg|{{http://freej.dyne.org/tut/img/05.jpg}}]] quit the ''freej'' (remember? ''[ctrl+c]''). ---------- <> == more layers == We can load both static image and the movie. Start ''freej'' with both movie and static image: {{{ freej kury.avi ipernav.png }}} [[http://freej.dyne.org/tut/img/06.png|{{http://freej.dyne.org/tut/img/06-mini.jpg}}]] As you can see, only chicken movie is visible (and the static image – file ''ipernav.png'' – is invisible). We are going to understand why... Now, when we opened two images (static image and a movie) in ''freej'', we have them on two layers. You can see the list of layers in the console. As you can see, that layers are called ''VID'' (which means: ''video layer'') and ''IMG'' (''static image layer''). [[http://freej.dyne.org/tut/img/06-lista.jpg|{{http://freej.dyne.org/tut/img/06-lista.jpg}}]] The list of layers is also shown in output window. As you can see (below), the video layer is on top of static image layer. This is why we can't see the image. [[http://freej.dyne.org/tut/img/06-output.png|{{http://freej.dyne.org/tut/img/06-output.png}}]] Take a look at the console window. As you can see, one of layers (''VID'') is highlighted. It is the current layer. You can see the detailed information about that layer in the top of console window. You can see there the name of the file (''kury.avi'') and some other info, which we will understand later. Notice that ''current layer'' doesn't mean ''top layer'' or ''the layer which is visible now''. ''Current layer'' means just ''current layer''. [[http://freej.dyne.org/tut/img/06-details.png|{{http://freej.dyne.org/tut/img/06-details.png}}]] While in the console window, you can use left and right arrow keys to change the current layer. Press the ''right arrow key'' to change the current layer to ''IMG'' layer. Notice that now at the top of the console window you can see the details of static image layer. [[http://freej.dyne.org/tut/img/07.png|{{http://freej.dyne.org/tut/img/07.png}}]] While in the console window, you can use ''+'' and ''-'' keys to move the current layer up and down. So now, when the current layer is ''IMG'' layer, press ''+''. As you can see, the static image layer went to the top. Now the static image is visible and the chicken movie became invisible. [[http://freej.dyne.org/tut/img/08.png|{{http://freej.dyne.org/tut/img/08-mini.jpg}}]] Close the ''freej'' (''ctrl+c'', as you remember). ---------- == some words about commands, parameters, completions == Some of the console commands (e.g. CTRL-B, CTRL-E) can accept parameters. To show them, just press TAB. The completion is also working. :) For example, pressing ''CTRL-B'' you have: {{{ [*] select Blit mode for the selected Layer - press TAB for completion: }}} and so, pressing ''TAB'', you obtain: {{{ [*] List available blits starting with "" RGB ADD SUB MEAN ABSDIFF MULT MULTNOR DIV MULTDIV2 MULTDIV4 AND OR XOR RED GREEN BLUE REDMASK GREENMASK BLUEMASK NEG ADDB ADDBH SUBB SHL SHLB SHR MULB BIN SDL ALPHA SRCALPHA CHROMAKEY }}} When choosing something, like a filter (pressing ''CTRL-E''), you can also use ''TAB'' and completion: {{{ [*] add new Effect - press TAB for completion: 3dflippo Brightness bw0r Cartoon Contrast0r delay0r Distort0r Equaliz0r Flippo Gamma Glow Hueshift0r Invert0r Mask0Mate nosync0r pixeliz0r rotozoom Saturat0r scanline0r Sobel Squareblur TehRoxx0r Threshold0r Twolay0r Vertigo Water }}} This also give you a list of all effect. <> == mixing two movies == As we previously told, ''freej'' is about mixing images. Now we will start doing that. Download [[http://freej.dyne.org/tut/data/term.avi|another movie]] to ''freej_tmp'' directory. Then start freej: {{{ freej term.avi kury.avi }}} As a result, ''freej'' starts. ''kury.avi'' is on the top layer, and is visible. ''term.avi'' is on the bottom layer and thus is invisible. [[http://freej.dyne.org/tut/img/09.png|{{http://freej.dyne.org/tut/img/09-mini.jpg}}]] Now press key ''CTRL-B'', and write ''red'' in output window. The effect should look like that: [[http://freej.dyne.org/tut/img/10.png|{{http://freej.dyne.org/tut/img/10-mini.jpg}}]] Doing so, we made ''red blit'' on active layer. You can see it in layer details, in the top of console window. [[http://freej.dyne.org/tut/img/10-info.png|{{http://freej.dyne.org/tut/img/10-info.png}}]] As you know, each picture an a computer screen has three channels: red, green and blue. ''Red blit'' means that now only red channel of the ''kury.avi'' layer is visible. Green and blue channels of this layer became transparent, so now we can see: * the red channel of ''kury.avi'' * the green channel of ''term.avi'' * the blue channel of ''term.avi'' In very similar fashion we can use green blit or blue blit, just choosing ''green'' or ''blue'' as parameter for ''CTRL-B''. You can also try using other blits in the list. Try switching it on and off! ;) ---------- <> == alpha blit == And now let's try ''alpha'' blit! [[http://freej.dyne.org/tut/img/11.png|{{http://freej.dyne.org/tut/img/11-mini.jpg}}]] As you can see, now we use ''alpha'' blit (you can read it in the info on current layer in the console window). With alpha blit, the current layer becames partly transparent. As you can see, now the layer ''kury.avi'' became fully transparent and only ''term.avi'' is visible. This is because alpha parameter is zero: [[http://freej.dyne.org/tut/img/11-alpha.png|{{http://freej.dyne.org/tut/img/11-alpha.png}}]] We can change the alpha parameter from the console window. Just press CTRL-V and you can change the alpha numeric value. Enter a value between 0.0 and 0.1, for instance 0.5 – the current layer becomes half transparent. [[http://freej.dyne.org/tut/img/11_alpha_127.png|{{http://freej.dyne.org/tut/img/11_alpha_127-mini.jpg}}]] ---------- <> == Effects == Start ''freej'' with ''term.avi'': {{{ freej term.avi }}} In console window press ''[ctrl+e]'' (''e'' like ''effect''). You will see the prompt like that: [[http://freej.dyne.org/tut/img/13.png|{{http://freej.dyne.org/tut/img/13.png}}]] So just press ''[tab]'' and you will see the list of available effects: [[http://freej.dyne.org/tut/img/14.png|{{http://freej.dyne.org/tut/img/14.png}}]] Vertigo effect is a nice one. So just type ''vertigo [enter]''. You will see something like that: [[http://freej.dyne.org/tut/img/15.png|{{http://freej.dyne.org/tut/img/15-mini.jpg}}]] ---------- <> == disabling and deleting effects == Take a look at the console window. As you can see, the current layer is video layer with file ''term.avi'': [[http://freej.dyne.org/tut/img/16.png|{{http://freej.dyne.org/tut/img/16.png}}]] You can also see that this current layer has the effect ''vertigo'': [[http://freej.dyne.org/tut/img/16-effect.png|{{http://freej.dyne.org/tut/img/16-effect.png}}]] Press ''down arrow key'' in the console window to see the details on this filter: [[http://freej.dyne.org/tut/img/17.png|{{http://freej.dyne.org/tut/img/17.png}}]] Pressing ''SPACE'' key you can temporarily disable and enable this effect. Press ''[delete]'' to delete the effect from this layer. ---------- == TEAM == * Denis "Jaromil" Rojo - FreeJ author and mantainer * Silvano "Kysucix" Galliani - TXT layer, encoder, streaming * Christoph "Mr.Goil" Rudorff - Scriptability, MIDI and Joystick parts of included code are written by Andreas Schiffler (sdl_gfx), Jan (theorautils), Dave Griffiths (audio bus), Nemosoft (ccvt), Charles Yates (yuv2rgb), Steve Harris (liblo), Sam Lantinga (sdl_*), Jean-Christophe Hoelt (goom), L. Donnie Smith (cwiid), Olivier Debon (flash). documentation, testing and user case studies have bee contributed by Anne-Marie Skriver, Marloes de Valk, Piotr Sobolewski refer to the AUTHORS file for a full list of contributions == DISCUSSION == A mailinglist for further discussion about FreeJ is running on http://lists.dyne.org For chat we hang around the channel #dyne on irc.dyne.org - access is free via SSL on port 9999, connection IP is kept anonymous for your own privacy. If you have problems, you are welcome to ask on the mailinglist for help, there you will probably find some good suggestions Please try to not mix your system's problems with FreeJ's bugs. If you find bugs, you are welcome to report them in the bugtracking system on http://bugs.dyne.org == DISCLAIMER == FreeJ is (c) 2001 - 2008 by Denis Roio (c) 2004 - 2005 by Silvano Galliani (c) 2005 - 2008 by Christoph Rudorff Statically included libraries are copyright of the respective authors. This source code is free software; you can redistribute it and/or modify it under the terms of the GNU Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version. This source code 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. Please refer to the GNU Public License for more details. You should have received a copy of the GNU Public License along with this source code; if not, write to: Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. === about this document === The original document was by Piotr Sobolewski ([[http://www.rozrywka.jawsieci.pl/materialy/index_EN.html]]) It was revised, enlarged and rebuilt at Wintercamp 09 in Amsterdam, by Gabriele ''Asbesto Molesto'' Zaverio. ---- CategoryTemplate