SendVIMS is a Puredata external written
by Niels Elburg and Tom Schouten. It is a control interface to veejay,
a realtime video processing package. VIMS stands for 'Veejay's Internal
Messaging System.
I have been working with veejay
for a long time now so I took my knowledge of what it could do and
built a few paches that will demonstrate the power of building
interactive controls for veejay. This might be interesting for the
newcomers to linux video, but also for the experienced who want to know
more about veejay, and puredata although it is not intended as step by
step guide on how to use PureData or veejay( Especially since I'm
rather new to PureData), but I will try to explain some basics on how
to get this working.
This document is Copyright © 104-10-09 M. van Henten. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
Use the information in this document at your own risk. I disavow any potential liability for the contents of this document. Use of the concepts, examples, and/or other content of this document is entirely at your own risk.
All copyrights are owned by their owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark.
Naming of particular products or brands should not be seen as endorsements.
You are strongly recommended to take a backup of your system before major installation and backups at regular intervals.
9-10-2004 Started Writing first draft to this howto, after finishing up on some basic patches.
Many thanks to of course to Tom Schouten en Niels Elburg for creating this tool, thanks to Niels for creating veejay after numerous sessions of feature dreaming, and continue working on it to create more then we ever fantasized about.
Also, much obliged to the people in te PureData community, who helped me getting started in the first place.Thanks to Derek Holzer, who introduced me to PD and showed me how easy and fun PD was.
A thankyou should be in place for the people at BEK ( http://www.bek.no) Who brought a lot of video guys in the OS world together, and made this collaboration possible in the first place.
2.1 Expected Skills
I assume that you know how to work with the linux commandline.
Veejay is ( up to this date) mainly a console application ( besides the
video bit of course) and you need to type stuff to get it working. If this is all
too strange for you, I would advice you to get know a bit more of linux
first, by reading some magazines, and some howto's ( the linux documentation project has a
lot of howto's) like the windows/dos
to linux howto.
2.2 Veejay
First of all, you need to download and install a later version of
veejay. In this document, I used veejay-0.6.2. Any version before
0.5.9 will not work as expected, or not at all together with SendVims.
Veejay sources are located http://veejay.sourceforge.net,
or go directly to the sourceforge
download area.
Installation is standard: open a shell, or terminal, unpack the package
somehwere, go into the newly created directory, and type:
./configure
when configure has finished, something like:
veejay 0.6.2 build
configuration :
Build
configuration:
MMX
enabled
: true
MMX2
enabled
: false
SSE
enabled
: true
3DNow
enabled
: false
CMOV
enabled
: true
glibc support for >2GB files : true
Required
dependencies:
POSIX Threads (pthread)
: true
video4linux recording/playback : true
Simple Direct Media Layer : true
XML C library for Gnome libxml2 : true
libJPEG
: true
Optional
dependencies:
libDV (digital
video)
: true
Jack Audio Connection Kit : true
DirectFB
support
: false
2.2 PureData
PureData is a whole story upon itself. Please read the installation
notes and documentation on http://www.puredata.org.
You can verify if everything works by just running pd, goto help en
check out some of the example paches. Using the documentation
from within pd you should at least get some basic understanding.
2.3 SendVims
In this document I used sendVIMS-0.1.
This is compied from the README in sendVIMS-0.1.tar.gz :
sendVIMS
- very simple VeeJay client for pure data
(C) 2002-2004 Niels Elburg <elburg@hio.hen.nl>
(C) 2004 Tom Schouten <doelie@zzz.kotnet.org>
This is free
software covered under the terms of the
GNU GPL. See
the file COPYING for details.
building:
./configure
&& make && make install
'make
install' copies these files to your pd directory:
<prefix>/lib/pd/extra/sendVIMS.pd_linux
<prefix>/lib/pd/doc/5.reference/help-sendVIMS.pd
the default
<prefix> is /usr/local
running:
if the module
is in your pd path it will be loaded automaticly.
3.1 Get veejay running
To start veejay, you need to start it with a video file. Veejay only
plays avi files, so no quicktime, or mpeg movies.
Veejay only knows of two types of video codecs: mjpeg and DV type 2.0.
So to get veejay running, you need at least one mjpeg or DV type 2.0
.avi file. These formats were chosen with some reasons, explained in
the veejay-howto. Converting into codecs and other formats is a whole
science upon itself, and I do intend to write a crash course into video
and linux in the future. For creating mjpeg avi's I use the lavtools and mplayer, and veejay itself.
You can grab a one
second mjpeg avi from here.
This is copyright free material I transcoded out of a movie from archive.org
Start veejay by opening up a terminal window such as xterm and type:
veejay mymovie.avi
If you used the example one second avi, it will briefly play the
whole movie and stop at the last frame. Move your mouse into the video
window. As long as the mouse pointer is inside the video window, you
can use the built in keyboard controls. press keypad-5, this pauzes
playback. now press keypad-1, to skip to the start of your movie. press
the [ key, this marks 'clip start', press keypad-3, to skip to the end
of the movie, and press the ] key, this marks the 'clip end'. You can
now sellect your clip by pressing the F1 key. the movie will
automatically keep looping. you can alterate loopmode by pressing
keypad-*. try some other keypad keys to see what they do. See 'man
veejay' for the other controls.
3.2 Running PD/SendVIMS
Open up a terminal window such as xterm and type:
pd
You'll need the terminal to get some feedback from pd. From the file
menu of pd, choose 'new'. In the new window, choose 'put > object'.
A rectangular object appears under your mousepointer. Click somewhere
in the white area of the window, and type "sendVIMS" inside the object.
If you installed the sendVIMS external properly, you should read
in the terminal:
sendVIMS:
version 0.1
sendVIMS: (c)
2004 Niels Elburg & Tom Schouten
sendVIMS:
connected to localhost:3490
That's it! you should now be able to right-click on the sendVIMS
object, and choose 'help' from the popup window.
You are now properly set up to use sendVIMS and veejay. Please refer to
some of the examples I provide under 'examples' for more information.
You should note that my examples will work right away, even without
understanding PD in the first place, but they are not intended as a
tutorial on how to use PD. you should see the 'help' menu and various
resources around the web for that!.
4.1 Veejay doesn't start!
You need to start veejay from a terminal, using a proper encoded avi
file. you can use the demo
file if you don't have one.
Please refer to veejay documentation and maillinglist.
4.2 SendVIMS doesn't work, PD tells
me it can't create sendvims.
The sendVIMS-0.1 external is not installed. please install the
external and restart PD.
4.3 I have a different problem,
please help me.
If the problem is relevant to this document please mail me and I'll add it here. Try the
PD and veejay maillinglist otherwise.
5.1 HOWTO's and documentation
The veejay howto can be found here: http://veejay.sourceforge.net/veejay-HOWTO.html
PureData documentation is here: http://www.puredata.org
I have have been working on some more patches besides the ones in
the examples, they're on my personal homepage:
http://cola.looze.net/sendvims/
5.2 Email, Mailinglists
Please post your questions to the veejay mailinglist, you can
subscribe here.
6.1 Basic Example: play, play
backwards.
In PD, you send a message by creating a message object, type the
message into that object, and connect the output of the message to the
sendVIMS object.
In this example, I used PD aliasses: video.play.forward, and
video.play.backward. Normally, most VIMS messages are represented as
numbers, preceded by a 'p', for example, p100 stands for 'select and
play sample' followed by an argument. In the following example, you can
select different clips to play in veejay by changing the number inside
the number box. ( you can make diferent clips in veejay when in 'plain
video' mode, by pressing keypad '/'. Use keypad play controls to select
different frame positions, use the [ and ] keys to mark in and
outpoints of clips, use the function keys to select samples with the
keyboard controls).
6.2 Set the playing clip with an argument.
The $1 takes the number from the number box, and together with the
p100 message it gives the command "select and play sample $1" to
veejay. Note, that since PD doesn't know how many clips we have here,
we can select non-existing clips. We can give negative numbers. veejay
will give an error message.
6.3 Getting status output from
veejay.
This example shows how to get information you need from veejay: for
example the current frame.
Now, there are two number boxes. When playing clips, the first
number box will display the current frame, but when playing in plain
video, the second box outputs the current frame. Veejay sends it's
status in one big string of numbers, seperated by spaces. all
information comes in at the same time. You can use the 'unpack' object
to split the information in smaller chunks. notice how many outputs it
has - there are lots of status messages to be read. I have made a patch
that helps me remember what goes where, and I include it as a subpatch
when working with sendVIMS. You can find it on my personal weppage: http://cola.looze.net/sendvims.
6.4 Controlling video effects.
Veejay has many video effects. you can find out what kind of effects
on veejay's homepage, in the gallery section. For this next example,
you need two different clips. Assuming that you are working with the
example movie, press Keypad-5 for pauze, and Keypad-1 to go to the
start of the movie. Mark the beginning of your first clip here. Now, we
gently scrub to frame 12 in the movie using Keypad-9 - it skips one
frame ahead at a time - and mark the end of the first clip, and, on the
same frame, the beginning of the second clip, and at the last frame of
the movie, the end of the second clip( HINT: you could use the
"video.set.frame <frame>" message here instead).
You should have two samples now, which you can select with the F1 and
F2 keys. Lets start with selecting the first clip and have a look at
the example:
The first message sets up the effect chain. Veejay can chain
multiple effects on top of eachother, like layers in an image editing
program. In this example, it sets effect 4 on current playing sample (
the number zero in the VIMS messages that control effects always stands
for the current playing clip, as a convenience. you could also replace
the number with a variable, and read it from veejay's output to know
the current clip).
Effect 4 is the "Normal Overlay" effect, it simply mixes two video like
a videomixer.
The second message controls the clip the overlay effect mixes with.
Put it to 2 to mix with our second clip.
The third message is a PD message, that controls the boundaries of the
slider. Normally, sliders have value 0 to 127 by default. the overlay
effect has only one controll, opacity, and it is mesured in value 0 to
255, so I want the slider to have boundaries ranging 0 to 255.
The slider is connected to the third message: control parameter 0 of
the effect on chain-entry 3 of the current playing clip.
The order of these values is typical: first, tell which sample to
select. second, what effect chain entry, third, which control
parameter, and last, the value of that parameter.
You can make a dump of the effects numbers and the VIMS messages by
running:
veejay
--dump-events -d > veejay-events.txt
The last message, "connect localhost 3490" actually (re)connects the
sendVIMS object to veejay if not already connected. You can use the
message "disconnect" and "quit", too, have a look at the sendVIMS
helpfile.
6.5 More advanced playback control:
scrubbing.
This example shows two things: One slider can be used to set a new
play position in a clip, the other shows the play position in the
current clip.
Both sliders get their boundaries updated with the starting position of
the clip and the ending position. This only works in the 'clip' mode,
not when playing in plain video.
From the status, the starting frame and the end frame of the current
playing clip are read, which sets the boundaries of both sliders. The
slider in the top of the patch controls message p089: set frame $1, the
slider in the bottom gets updated with the 'current frame of clip'
information.
However, when switching from clip to plain video mode, this will no
longer work as the outputs get different status updates. Switching
between clips wil work perfectly however.
More advanced combinations are possible. PD offers a lot of
functionality, such as MIDI, joystick controls and controlling things
through sound. Some more examples of my work are on my personal
website.