Otogranulator 1.0

What is Otogranulator?

	Otogranulator is a simple VJing tool based on the idea of "video
	granulation". It has been developed during my stay in Croatia,
	mostly on the Island of Vis during a camp called "Otokultivator 2".
	
	Otogranulator takes a live video feed (from a camera or VCR),
	and analyzes the overall motion in it to determine starting points
	for recording short "Video Granules" (clips of up to 4 seconds)
	to memory. Up to five of these clips are held at the same time
	and can be triggered by pressing keys on the keyboard. When a clip
	is playing, it will ping-pong forwards-backwards, and if the key
	is pressed again, it will restart from the beginning. This way,
	the VJ can easily transform the rhytmic audio processed by his
	ears into rhytmic video on the beamer.
	The "Gamba Feature", named after the guy who had the idea, allows
	the live feed to be overlayed over the clip on nine rectangular
	areas.
	
	
Requirements and Installation

	Otogranulator, while being a simple tool, is a relatively complex
	system to install. It requires BeOS 5 and a MediaKit-compatible
	video input (usually a cheap Bt848 TV card), and a little application
	called "hey" (available on BeBits). Otogranulator is made up of the 
	following components:
	  - FDifference, a video filter node that compares consecutive
	    video frames and calculates the overall motion.
	  - FGranularVideo, a MediaNode that makes up most of the program
	    and will open a small window for information and receiving key
	    presses (see "Usage", below).
	  - FCrop, which is actually a video filter that will crop the image
	    but is being used in Otogranulator because it copies the video
	    frame buffers received from the video in, and as a side effect
	    this eliminates possible overwrites of the buffer data from the
	    video in node ahead of time, which would result in stupid errors.
	  - libFMedia, a shared library used by all these three nodes.
	  - MediaControl, my commandline interface to the BeOS MediaKit, 
	    for easy starting up.
	    
	To install Otogranulator,
	  - place "mc" and "hey" from the bin/ subdirectory into
	    /boot/home/config/bin
	  - place "libFMedia.so" from lib/ into /boot/home/config/lib/
	  - place "FCrop", "FDifference" and "FGranularVideo" from addons/
	    into /boot/home/addons/media/
	
	Then, you should be able to launch the "otogranulator.mc" script,
	usually using Terminal (because it is easier to stop then :).
	
	
Usage
	The otogranulator.mc script will try to set up the required nodes
	in the MediaKit and start the whole system. Using "hey", it will
	resize the video output window to 640x480. The FGranularVideo node
	will open a small window on the top left corner of your screen
	(the "control window"). This window will repeatedly make itself
	the active window, every second or so. While this is somehow annoying
	it is necessary to prevent loss of control when someone clicks
	the mouse on the video output image during your performance.
	
	The control window is made up of 7 squares displaying various information:
	- the first five squares represent the five video granules in memory,
	  when they're gray they are not yet filled, when they're blue they are
	  "new", when white they are filled and have been played. The green
	  one is currently being played. You can trigger the clips with the
	  1 to 5 number keys. By pressing 0, the live feed will be featured.
	  Whenever a new clip is recorded, the one of the five that you did
	  not use for the longest time will get replaced (and the respective
	  square marked blue). There will only be one new clip at a time. You
	  have to use it at least shortly to get another new one.
	- the 6th square displays what areas of the screen will be filled with
	  the currently played clip and which ones will feature the live feed.
	  The screen is cut into 3 by 3 rectangular areas which can be toggled
	  live/clip with the following keys:
	  	U	I	O
		J	K	L
		M	,	.
	  I hope this works for most keyboard mappings. if not, go to the source
	  code and adapt to your needs :)
	- the 7th square, finally, shows wether the current motion is over the
	  threshold (red) or below (gray). You can modify the threshold value
	  via up and down cursor keys in steps of 0.5.

Quitting
	Exiting Otogranulator is somewhat of a hassle. You can close the
	control window with Alt-Q to get full control over your focus again.
	I usually switch workspaces then and use Deskbar to close all Terminal
	windows (Otogranulator has to be started from a Terminal for this to
	work, though).
	
Credits
	Oli and Astrid for the discussion that brought up the idea for video
	  granulation
	Klub Mama, Zagreb (and temporarily Vis), for support, especially
	  Zeljko for bringing me to Croatia
	  Slipke for patient camera lending
	  Danijel for equipment support
	  Gamba for discussion and ideas
	Maia and Maia for dancing to some other stuff and thereby providing
	  testing material
	The Linux/320x240 room on otokultivator for waking me up before
	  end of breakfast
	All other friends and short encounters during DigiDU, Otokultivator
	  and EASA
	Be, Inc. (RIP) for a great OS and the MediaKit

Author
	Daniel Fischer
	dan@f3c.com