veejay/veejay-current/veejay-server/man/veejay.1

.TH "veejay" 1
.SH NAME
veejay - a visual (video) instrument and video sampler for GNU/Linux
.SH SYNOPSIS
.B veejay [options] Videofile1 [Videofile2 ... VideofileN]
.SH DESCRIPTION
.B Veejay
is a visual instrument and realtime video sampler. It allows you
to "play" the video like you would play a Piano.

While playing, you can record the resulting video directly to disk (video sampling). Veejay keeps audio in sync and pitches when needed through trickplay (slow , faster, reverse, loop) and delivered to JACK for possible further processing.

Veejay can be operated live by using the keyboard (which is 100% user definable)
and remotely over network (both unicast and multicast) using an inhouse message
system that allows mapping of various protocols on top of it, including OSC.

Veejay is beeing developed in the hope it will be usefull for VJ's, media artists
theathers and other interested users that want to use Free Software for their
performances and/or video installations.


.TP
.SH Supported video containers
.TP
AVI , QuickTime, DVVideo
.TP
.SH Supported video codecs/formats
* MJPEG AVI / Quicktime (fourcc: mjpg,mjpb,mjpa,jfif)

* Lossless JPEG AVI (fourcc: ljpg)

* Quasar DV codec (NTSC/PAL) AVI / Quicktime (fourcc: dv,dvhd,dvp,dvcp)

* YUV4MPEG (chroma 4:2:0 jpeg/mpeg2, chroma 4:2:2) AVI / Y4M

* Motion PNG (fourcc: mpng, png)

* RAW YUV 4:2:2 planar JPEG/JFIF (sample range 0-255,8 bit, 3 planes) (fourcc: vj22,vj20)

* RAW YUV 4:2:2 planar  Rec. 601 (Y’CbCr) (sample range 16-235 Y, 16-240 UV, 8 bit, 3 planes)

* MLZO (YUV 4:2:2 planar compressed with OberHumer's LZO real-time data compression library) (fourcc: mlzo)

* FFmpeg RAW format
.TP
.SH Audio
.TP
Veejay uses Jack, a low latency audio server, to transport (playback) audio in sync with video. This allows you to process veejay's audio output in another sound processing application.
.TP
.SH General Usage (How to work with veejay)
.TP
Veejay has a console and a video window.

* The console is used for displaying messages only.

* If the mouse is moved over to the video window, you can use the keyboard like a piano to play/manipulate the video.
.TP
You can start veejay with multiple files, video files and/or Mjpegtools' EditList files. Upon startup, veejay creates a new EditList in memory containing all the files you have loaded. As a result, all files will appear as a single large video file. Next you can start making selections (samples) of your EditList. These samples will be placed in a slot in a so called 'sample banks' and they can be triggered for continue or playback by combining the F-keys (1 to 12) with SHIFT. You can select a sample bank holding SHIFT and pressing a number 1 to 9.
.TP
Note that if you change the EditList (for example, when deleting portions of your editlist) you should save your editlist as well as your samplelist.
.TP
You can select effects to put on your samples by pressing the cursor keys up and down, once you have found an effect you would like to use, press ENTER and it will be added to the current chain entry. The current chain entry can be changed with the PLUS and MINUS key on your numeric keyboard. Look at the KEYBINDINGS in this manual page to see what other possibilities you could have. 
.TP
.SH Interactive camera/projection system
.TP
You can use veejay to calibrate a camera (or another input source) against a projector screen to map a physical position to veejay's projection. To use this feature, you can press CTRL\-s to activate the projection/camera calibration setup. This will render a graphical OSD on top of the video.Next, you need to play the live input source in order to find veejay's projection in the camera image. Set the points to the edges of the screen and right-click. Now press CTRL\-s or the middle mouse button to leave setup. Press CTRL-i to enable transforming the camera input and press CTRL-p to bring the projection screen in front.
.TP
.SH Interoperability
.TP
Using the OpenSoundControl (OSC) veejay can be used with a great number of sound and video processing applications.
.TP
Veejay can record video data to the yuv4mpeg format (mjpegtools), or stream uncompressed video over the network (uni - and multicast)
.TP
The power come with VIMS, Veejay's IMS (Internal Message System). With sayVIMS; a command line utility; you can control mainly all veejay's function on the fly, headless. You can scripts your performance / video installation, you can even plug them with the real world ...!
.SH OPTIONS
.TP
.B \-w/--output-width <num>
Specify video output width
.TP
.B \-h/--output-height <num>
Specify video output height
.TP
.B \-p/--port <num>
TCP port offset for communication with clients like 'reloaded' , 'sayVIMS' or sendVIMS for PD (default 3490)
.TP
.B \-O/--output [0..6]
Specify video output 0 = SDL (default) 1 = DirectFB 2 = SDL and DirectFB 3 = Open GL (requires ARB fragment shader), 4 = Y4M Stream 4:2:0, 5 = VLOOPBACK, 6 = Y4M Stream 4:2:2
(options 4, 5 and 6 require --output-file)
.TP
.B \-o/--output-file [file]
Write to file (for use with -O/--output)
.TP
.B \-s/--size WxH
Scaled video dimensions for SDL video output (Width x Height)
.TP
.B \-a/--audio [0-1]
Play audio 0 = off , 1 = on (default)
.TP
.B \-r/--audiorate <num>
Set audio rate (defaults to 48Khz)
.TP
.B \--pace-correction [ms]
Set audio pace correction in milliseconds.
.TP
.B \-c/--synchronization [0-1]
Sync correction off/on (default on)
.TP
.B \-P/--preverse-pathnames
Do not 'canonicalise' pathnames in editlists
.TP
.B \-v/--verbose 
Verbosity on/off (default off)
.TP
.B \-t/--timer [0-1]
Timer to use 0=none, 1=default timer (default=1)
.TP
.B \-f/--fps <num>
Override framerate of video. Disables audio when used. (default: read from first loaded file)
.TP
.B \-x/--geometry-x <num>
Geometry x offset for SDL video window
.TP
.B \-y/--geometry-y <num>
Geometry y offset for SDL video window
.TP
.B \--no-keyboard
Disable keyboard for SDL video window
.TP
.B \--no-mouse
Disable mouse for SDL video window
.TP
.B \--show-cursor
Show mouse cursor in SDL video window
.TP
.B \-F/--action-file <filename>
Configuration File to load at initialization.
The configuration file stores custom keybindings, custom bundles, available VIMS events, editlist,samplelist,streamlist
and commandline options.
.TP
.B \-l/--sample-file <filename>
Load a sample list file at startup.
The sample list file store your project. Samples load in sample bank (based on .edl files), effects in fx chain, loop and play mode,
sample currently playing, sequencer information...
.TP
.B \-b/--bezerk
Bezerk mode, if enabled it allows you to change input channels on the fly (without restarting the samples)      
.TP
.B \-g/--clip-as-sample
Load every file on the commandline as a new sample
.TP
.B \-q/--quit
Quit at end of the file
.TP
.B \-n/--no-color
Dont use colored text in console output
.TP
.B \-u/--dump-events
Dump veejay's documentation to stdout
.TP
.B \-m/--memory [0..100]
Frame cache size in percentage of total system RAM 
.TP
.B \-j/--max_cache [0..100]
Maximum number of samples to cache
.TP
.B \-B/--features
Show compiled in options
.TP
.B \-Y/--yuv [0-1]
Force YCbCr (defaults to YUV). Use 0 for YUV 4:2:2 Rec 601 or 1 for YUV 4:2:2 JPEG/JFIF
.TP
.B \-e/--swap-range [0..3]
Swap YUV range [0..255] <-> [16..235] on videofiles (0 = YUV 4:2:0 Planar,
1 = YUV 4:2:2 Planar (default),2 = YUV 4:2:0 Planar full range, 3 = YUV 4:2:2 Planar full range)
.TP
.B \-I/--deinterlace
Deinterlace video if it is interlaced
.TP
.B \-d/--dummy
Start veejay with no video files (dummy mode). By default it will play black video (Stream 1 [F1])
.TP
.B \-W/--width <num>
Specify width of dummy video
.TP
.B \-H/--height <num>
Specify height of dummy video
.TP
.B \-N/--norm [0..2]
Set video norm of dummy video [0=PAL, 1=NTSC, 2=SECAM (defaults to PAL)]
.TP
.B \-M/--multicast-osc <address>
Starts OSC receiver in multicast mode
.TP
.B \-T/--multicast-vims <address>
Setup additional multicast frame sender / command receiver.
The frame sender transmits on port offset + 3, send commands to port offset + 4, 
.TP
.B \-A/--all
Start with all capture devices active as streams
.TP
.B \-Z/--load-generators <num>
Load and instantiate all plugins of type generator and start playing <num>
.TP
.B \-D/--composite
Do not start with camera/projection calibration viewport.
.TP
.B \--qrcode-connection-info
Encode veejay server IP and port number in QR code image (available if build with qrcode support)
.TP
.B \-S/--scene-detection <threshold>
Create new samples based on scene detection threshold.
.TP
.B \-M/--dynamic-fx-chain
Do not keep the fx chain buffers in RAM. Specify this option if you prefer dynamic allocation instead (slower, but no RAM is reserved)
.TP
.B \--split-screen
Load split screen configuration
.TP
.B \--fx-custom-default-values
Read FX custom default values from ~/.veejay/[livido,frei0r]
.TP
.B \--benchmark NxN
Benchmark veejay's core functions (multi-thread vs single thread model) using a specific resolution NxN
.TP
.B \-?
Print veejay's options to stdout and quit
.TP
.SH Environment variables
.TP
.B VEEJAY_SUBSAMPLE_MODE
Selects a sampling method for up-and down sampling of UV data (drop,average,bilinear,mitchell)
.TP
.B VEEJAY_NUM_DECODE_THREADS
Set the number of MJPEG decode threads you would like to spaw. 
.TP
.B VEEJAY_MULTITHREAD_TASKS
You can set this environment variable to the number of threads you would like to spawn for veejay's pixel tasks. This option is automatically enabled if you run high resolution video.
.TP
.B VEEJAY_AUTO_SCALE_PIXELS
Tell veejay to automatically convert between CCIR 601 and JPEG
pixels - hence, it scales YUV values from 0 - 255 to YCbCr 16-235/16-240
and vice versa. Use "0" to disable this behaviour, "1" to enable.
.TP
.B SDL_VIDEO_HWACCEL
Set to 1 to use SDL video hardware accel (default=on)
.TP
.B VEEJAY_PERFORMANCE
Set to "quality" or "fastest" (default is fastest)
.TP
.B VEEJAY_AUTO_SCALE_PIXELS
Set to 1 to convert between CCIR 601 and JPEG automatically (default=dont care,white != white)
.TP
.B VEEJAY_INTERPOLATE_CHROMA
Set to 1 if you wish to interpolate every chroma sample when scaling (default=0)
.TP
.B VEEJAY_SDL_KEY_REPEAT_INTERVAL
Interval of key pressed to repeat while pressed down.
.TP
.B VEEJAY_SDL_DRIVER
Tells SDL which video driver to use
.TP
.B VEEJAY_SDL_HINT_RENDER_DRIVER
Set a hint before creating the SDL driver (e.g: opengl)
.TP
.B VEEJAY_SDL_HINT_FRAMEBUFFER_ACCELERATION
Enable or disable SDL hardware acceleration (0,1,2)
.TP
.B VEEJAY_PLAYBACK_CACHE   
Sample cache size in MB - by default, veejay will consume up to 30% of your total RAM to cache video samples.
.TP
.B VEEJAY_SDL_KEY_REPEAT_DELAY
Delay key repeat in ms
.TP
.B VEEJAY_FULLSCREEN 
Fullscreen (1) or windowed (0) mode
.TP
.B VEEJAY_DESKTOP_GEOMETRY
Specify the desktop geometry for veejay to position the video window. Use this feature to specificy where a video window appears in TwinView or One Big Desktop
.TP
.B VEEJAY_VIDEO_SIZE
Specify the size of the video window (inside VEEJAY_DESKTOP_GEOMETRY)
.TP
.B VEEJAY_VIDEO_POSITION
Specify the position of the video window (inside VEEJAY_DESKTOP_GEOMETRY)
.TP
.B VEEJAY_DEFAULT_CHANNEL
Specify the default video4linux channel id
.TP
.B VEEJAY_SWAP_RGB
Capture in RGB or BGR (Video4Linux)
.TP
.B VEEJAY_MMAP_PER_FILE
MMap size per loaded video file
.TP
.B VEEJAY_RUN_MODE
Set this to "CLASSIC" if you want to startup in low resolution
.B Examples
.TP
.B VEEJAY_DESKTOP_GEOMETRY=2624x1024+1600x0
The video window will be displayed on the second screen, first screen is 1600 pixels wide. Specify this and VEEJAY_VIDEO_SIZE to create a borderless video window for use on one of your monitors in TwinView or One Big Desktop mode.
.TP
.B VEEJAY_VIDEO_SIZE=1024x768
The second screen is 1024x768, the video window will appear fullscreen 
.TP
.B VEEJAY_DEFAULT_CHANNEL
Set the Video4Linux Channel ID for veejay to use by default.
.TP
.B VEEJAY_SHMID
Set SHMID by environment variable (slave mode)
.TP
.B VEEJAY_PAUSE_EVERYTHING
Pause behaviour; Set to 0 to pause only top sample (and keep playing FX chain) or to 1 to pause everything (default).
.TP
.B VEEJAY_MAX_FILESIZE
Set the maximum file size in bytes. This option influences the maximum file size of recorded AVI files.
.TP
.B VEEJAY_MEMSET_METHOD
Set a preferred memset method. A list of memset methods is printed when an invalid value is given.
.TP
.B VEEJAY_MEMCPY_METHOD
Set a preferred memcpy method. A list of memcpy methods is printed when an invalid value is given.
.TP
.SH Home directory
.TP
Veejay creates a new directory in your $HOME , ".veejay".
You must put a TrueType font file in $HOME/.veejay/fonts for veejay's OSD functionality.
.TP
.B .veejay/recovery
If veejay stops unexpectedly, it will try to save your samplelist and editlist before aborting. Most of the time, veejay will be able to fully recover.
.TP
.B .veejay/plugins.cfg
If you want to load frei0r or freeframe plugins , set the paths
to the .so files in the plugins.cfg file. Only support for single
channel plugins.  
.TP
.SH ENVIRONMENT VARIABLES FOR V4L2 CAPTURE
.TP
.B VEEJAY_V4L2_GREYSCALE_ONLY
Use '1' to capture in greyscale only
.TP
.B VEEJAY_V4L2_PREFER_JPEG
Use '1' to set preferred capture format to (M)JPEG
.TP
.B VEEJAY_V4L2_CAPTURE_METHOD
Capturing method. Use 0 for read/write, 1 for memory mapping.
.TP
.B VEEJAY_V4L2_MAX_RETRIES
Maximum number of attempts before giving up on capture device
.TP
.B VEEJAY_V4L2_NO_THREADING
Do not start a seperate thread for capturing. Use '1' to disable threads.
.TP
.SH INTERFACE COMMANDS (STDIN)
When you are running veejay with a SDL window you can use keybindings for
realtime interaction. See 
.B KEYBINDINGS
for details.
.SH KEYBINDINGS
.TP
.B [Keypad *]
Switch loop mode ("Normal" or "Ping Pong")
.TP
.B [SHIFT] + [Keypad *]
Switch random loop mode ("Play once and keep playing last frame" or "Random")
.TP
.B [Keypad 1]
Goto start of sample
.TP
.B [Keypad 2]
Go back 25 frames
.TP
.B [Keypad 3]
Goto end of sample
.TP
.B [Keypad 4]
Play backward
.TP
.B [Keypad 5]
Pause
.TP
.B [Keypad 6]
Play forward
.TP
.B [Keypad 7]
Goto previous frame
.TP
.B [Keypad 8]
Go forward 25 frames
.TP
.B [Keypad 9]
Goto next frame
.TP
.B [Keypad /]
Switch to Plain video playback mode (from Sample or Tag mode)
.TP
.B [LEFT BRACKET]
Set sample start
.TP
.B [RIGHT BRACKET]
Set sample end and create new sample
.TP
.B [ALT] + [LEFT BRACKET]
Set marker start
.TP
.B [ALT] + [RIGHT BRACKET]
Set marker end and activate marker
.TP
.B [Backspace]
Delete current marker 
.TP
.B [a,s,d,f,g,h,j,k,l]
Set playback speed to 1,2,3,4,5,6,7,8, or 9
.TP
.B [ALT] + [a|s|d|f|g|h|j|k|l]
Adjust frame duplicator to 1,2,3,4,5,6,7,8 or 9. Interpolates missing frames.
.TP
.B [1..9]
Quick jump into sample position : 10%, 20%, 30% etc.
.TP
.B [SHIFT] + [1..9]
Sample bank selection: range [0-12], [12-24], [24-36] etc.
.TP
.B [ALT] + [1..9]
Change the channel ID 1-9, depending on sample range
.TP
.B [SHIFT] + [a,s,d,f,g,h,j,k,l]
Set current mixing channel speed to 1,2,3,4,5,6,7,8, or 9
.TP
.B [SHIFT] + [ALT] + [a|s|d|f|g|h|j|k|l]
Adjust current mixing channel frame duplicator to 1,2,3,4,5,6,7,8 or 9. Interpolates missing frames.
.TP
.B [F1..F12]
Select and play sample bank 1 .. 12
.TP
.B [SHIFT] + [F1..F12]
Select and resume sample bank 1 .. 12
.TP
.B [ESC]
Switch between Plain -> Tag or Sample playback mode
.TP
.B [SHIFT] + [t]
Toggle transitions between samples
.TP
.B [RETURN | ENTER]
Add selected effect from list to sample effect chain
.TP
.B [DELETE]
Delete effect from selected chain entry
.TP
.B [UP]
Go up 1 position in the effect list
.TP
.B [DOWN]
Go down 1 position in the effect list
.TP
.B [Keypad -]
Decrease selected effect chain entry
.TP
.B [Keypad +]
Increase selected effect chain entry
.TP
.B [-]
Decrease mixing channel ID
.TP
.B [=]
Increase mixing channel ID
.TP
.B [/]
Toggle mixing source between Clips and Streams
.TP
.B [END]
Enable/Disable Effect Chain
.TP
.B [Left ALT] + [END]
Enable/Disable Video on selected Entry
.TP
.B [LCTRL] + [END]
Enable/Disable Video on selected Entry
.TP
.B [PgUp]
Increase parameter 0 of selected effect
.TP
.B [PgDn]
Decrease parameter 0 of selected effect
.TP
.B [Keypad 0]
Decrease parameter 1 of selected effect
.TP
.B [Keypad .]
Increase parameter 1 of selected effect
.TP
.B [.]
Increase parameter 2 of selected effect
.TP
.B [,]
Decrease parameter 2 of selected effect
.TP
.B [q]
Decrease parameter 3 of selected effect
.TP
.B [w]
Increase parameter 3 of selected effect
.TP
.B [e]
Decrease parameter 4 of selected effect
.TP
.B [r]
Increase parameter 4 of selected effect
.TP
.B [t]
Decrease parameter 5 of selected effect
.TP
.B [y]
Increase parameter 5 of selected effect
.TP
.B [u]
Decrease parameter 6 of selected effect
.TP
.B [i]
Increase parameter 6 of selected effect
.TP
.B [o]
Decrease parameter 7 of selected effect
.TP
.B [p]
Increase parameter 7 of selected effect
.TP
.B [SHIFT] + [Spacebar]
Start keystroke recorder. The keystroke recorder
records most of the received VIMS messages and plays them
back in order and on the position you have pressed them.
Instead of using the keyboard, you can also use 'Reloaded',
and record the buttons pressed. However, some VIMS messages
are excluded from the keystroke recorder for safety reasons. 
.TP
.B [Spacebar]
(re)play recorded VIMS messages. The keystroke recorder
will jump to the starting position and replay all
recorded VIMS messages. 
.TP
.B [CTRL] + [Spacebar]
Clear recorded keystrokes. This clears all VIMS messages
in the current selected macro slot.
.TP
.B [Spacebar] (CAPS-LOCK on)
Plays the next sample in queue (in playing direction)
.TP
.B [CTRL] + [ F1 - F12 ]
Select a slot to record keystrokes to (default=0)
Use this if you want to record multiple keystrokes. You
can switch slots while in keystroke playback.
.TP
.B [ALT] + [b]
Take a snapshot of a video frame and put it in a seperate
buffer (used by some effects like Difference Overlay)
.TP
.B [CTRL] + [s]
Show/hide interactive camera/projector calibration setup
.TP
.B [CTRL] + [p]
Focus on front (primary output) or back (secundary input) projection
.TP
.B [CTRL] + [i]
Toggle current playing sample/stream as input source to be transformed
.TP
.B [CTRL] + [v]
Toggle grayscale/color mode
.TP
.B [CTRL] + [h]
Toggle OSD help for camera/projector setup
.TP
.B [CTRL] + [o]
Toggle OSD help for general status messages and mouse coordinates
.TP
.B [CTRL] + [d]
Toggle rendering of single source FX on underlying samples
.TP
.B [CTRL] + [r]
Start recording
.TP
.B [CTRL] + [t]
Stop recording
.TP
.B [CTRL] + [f]
Toggle fullscreen / windowed mode
.TP
.B [Home]
Print sample/tag information
.SH EXAMPLES
.TP
.B veejay -u |less
Startup veejay and list all events (VIMS/OSC) and effect descriptions
.TP
.B veejay -p 4000 ~/my_video1.avi
Startup veejay listening on port 4000 (use this to use multiple veejays)
.TP
.B veejay -d -W 352 -H 288 -N 0 -a 0
Startup veejay using dummy video, dimensions 352x288, using PAL and no audio.
.TP
.B veejay movie1.avi -M 224.0.0.50 -p 5000 -n -v
Startup veejay, using osc multicast protocol on port 5000 and no colored but verbose output
.TP
.B veejay -g movie1.avi movie2.avi movie3.avi --output 5 --output-file /dev/video1
Startup veejay headless and use given clip as sample, the video output is writen
to /dev/video1 (a video loopback device)

You will need something like v4l2looback kernel module to setup the video loopback.

Only the video channel is writen to the loopback device! audio, if any, still goes to jack
.TP
.B veejay movie1.avi --output 4 --output-file /tmp/video-yuv4mpeg.pipe
Startup veejay headless and write yuv4mpeg video to a named fifo pipe.

Only video channel goes to the pipe! the audio still goes to jack

Dues how pipe works, audio and video could lost synchro
.TP
.SH REFERENCES
.TP
.I http://veejayhq.net
.TP
.SH BUGS
.TP
See
.I https://github.com/c0ntrol/veejay/issues
.SH AUTHOR
This man page was written by Niels Elburg.

If you have questions, remarks or you just want to
contact the developers, the main mailing list for this
project is: 
.I http://groups.google.com/group/veejay-discussion/post?hl=en

For more info see the website at
.I http://veejayhq.net
.SH "SEE ALSO"
.B veejay sayVIMS reloaded