DVswitch: a basic video mixer for live DV streams
=================================================

Introduction
------------

DVswitch is a basic video mixer designed for the needs of low-budget
technical conferences that require live mixing for streams and/or
recording.

Currently DVswitch can combine audio from one source with video from
another, can combine two video streams with a picture-in-picture
effect, and can apply a fading transition from one video stream to
another.  Further mixing effects are planned.  It works solely with the
DV format since almost all camcorders support this and it allows for low
latency display and cutting.

Since DV cameras must be connected to computers via Firewire cables of
limited length, DVswitch is divided into several different programs
that can run on different computers on a TCP/IP network:

- dvswitch: the mixer GUI and network server
- dvsource-firewire: source that connects to a DV camera via Firewire
- dvsource-v4l2-dv: source that connect to a DV camera via V4L2, useful for USB
- dvsource-command: source from any V4L2 device, via e.g. ffmpeg -target pal-dv.
- dvsource-file: source that reads a raw DV (DIF) file
- dvsource-alsa: source that captures audio through ALSA
- dvsink-files: sink that writes the mixed stream to raw DV files
- dvsink-command: sink that runs a command with the mixed stream as
  its standard input

It is important to make sure all DV sources use the same video system
(PAL or NTSC), aspect ratio (16:9 or 4:3) and audio sample rate
(32 or 48 kHz).  Mixing input format will produce bogus output.
DVswitch automatically detects the format used by its first source and
will show warnings for any sources that don't match it.

Web resources
-------------

The project home page is <http://dvswitch.alioth.debian.org>.  This
has links to the download page, bug tracker, source repository, and
mailing list.

System requirements
-------------------

DVswitch is developed and tested under Linux 2.6, and may not work on
earlier versions of Linux or other Unix-like systems.  In particular,
dvsource-firewire uses dvgrab which only runs on Linux.

The sources and sinks have low processor and memory requirements.  The
dvswitch mixer should be able to run on an x86 or x86-64 processor
with a 1 GHz or faster clock, but will need a somewhat faster
processor to update the display at full frame rate.  On other
architectures it is less efficient as the DV decoder only has
optimisations for these two architectures.  It currently requires
about 40 MB memory in addition to whatever the underlying operating
system requires.

The dvswitch mixer requires an X display of at least 1024x768 pixels
that supports the X video extension (aka XVideo or Xv).  XVideo is
available in most modern X display drivers but was not implemented in
older versions of fglrx.

A DV stream has a fixed bandwidth of about 36 Mbit/s and it is
doubtful that current wireless networks can reliably provide this
bandwidth.  We recommend use of a 100 or 1000 Mbit/s switched Ethernet
network between the hosts running the DVswitch system.

Configuration
-------------

All programs read the configuration files /etc/dvswitchrc and
~/.dvswitchrc.  These files can specify the following options:

MIXER_HOST - the hostname (or IP address) on which the mixer listens
             (no default)
MIXER_PORT - the port on which the mixer listens (no default)
FIREWIRE_CARD - number of the Firewire card that dvsource-firewire
                should read through (default: use first which appears
                to have a camera attached)

The mixer hostname and port can also be specified using the -h and
-p command-line options.  A Firewire card number for dvsource-firewire
can be specified using the -c option.

Starting the mixer
------------------

Run dvswitch, and you will initially see a mostly empty window.  You
then need to connect some sources to it (see below).

Once sources are connected, you will see the mixed output at full
resolution (slightly higher, in fact, since the video pixels are not
square).  Below it, you will see all the sources at lower resolution
in greyscale.  (This allows dvswitch to display many sources without
requiring a very fast processor.)  Each is numbered and the active
sources for video and audio are indicated by the buttons beside them.

In the main display, a 10% border on each side of the frame is shaded.
This indicates approximately the area of the picture that may not be
visible on a TV.  Everything that viewers need to see should be framed
within these borders (the "title-safe" area).

There are currently a small number of commands, available through
keystrokes:

1 to 9          select the video source
Alt-1 to Alt-9  select the audio source
P               picture-in-picture (in English locales)
D               enable fade transition (in English locales)
R               start/stop recording (in English locales)
T               cut recording (in English locales)
Return/Enter    apply effect
Escape          cancel any (pending) effects
Ctrl-Q          quit

Video and audio sources can also be selected using the buttons beside
their thumbnails.

Connecting sources and sinks
----------------------------

Run dvsource-file to stream a DV file to the mixer.  It takes a single
filename.  Normally it plays the file once and then exits.  You can
enable looping of the file with the -l option.

Run dvsource-firewire to stream from a DV device (camera or VCR)
connected by Firewire.

Run dvsource-v4l2-dv to stream from a DV device that has a
Video4Linux2 driver.  This includes most USB DV cameras if you have
the uvcvideo driver installed.

Run dvsink-files to save the mixer's output to files.  It takes a
filename pattern which may include formatting sequences as used by
strftime(3) so that files are named according to the time when they
are created.  It will open a new file every time you start recording
and every time you cut in the mixing window.  If the name pattern does
not end with the suffix ".dv", this will be added.  Finally, a hyphen
and a number will be added before the ".dv" if necessary to avoid
filename collisions.

Run dvsink-command to send the mixer's output to the standard input of
a command.  For example, to send a downscaled Theora stream over
Icecast, run:
    dvsink-command -- \
    ffmpeg2theora -o - -f dv -x 320 -y 240 --aspect 4:3 --deinterlace - \
    | oggfwd <icecast-hostname> <icecast-port> <password> <path>

dvsink-command provides a continuous stream which is not affected by
the recording commands.

Applying effects
----------------

Currently two effects are implemented: picture-in-picture, and a
time-based fading transition.

To apply the picture-in-picture effect:

1. Select the primary video source by pressing its number key or
   clicking the 'A' button next to its thumbnail
2. Select the secondary video source by clicking the 'B' button next
   to its thumbnail
3. Press P
4. Drag to mark the area the secondary video source should overlay in
   the main display, using mouse button 1 (normally left).  You can
   also extend the selection using mouse button 2 (normally middle).
   You can also cancel selection by pressing Escape.
5. Press Return/Enter

To cancel the effect, press Escape.

For fading:

1. Select the video source to transition from by pressing its number key
   or clicking the 'A' button next to its thumbnail
2. Enable the fade effect by pressing D
3. Select a timeout for the fade effect by using the slider below the
   fade button. This slider has a millisecond resolution, but note that
   of course the effect has a resolution of one frame. The default
   timeout is set to two seconds.
4. Select the video source to transition to by pressing its number key
   or clicking the 'A' button next to its thumbnail

The fade effect will remain active until the 'No effect' button is
activated (either by using the mouse or by hitting 'Escape'), or the
picture-in-picture effect is enabled.

It is not currently possible to combine effects; if a fading transition
is started while the picture-in-picture effect is active, then the
latter will be disabled when the fading transition is started.

Remote Control
--------------

dvswitch can be remote-controlled via OpenSoundControl. To activate
the remote-control interface, dvswitch needs to be started with the
-o <port-number> option. Basically all control messages are equivalent
to functionality otherwise accessible via GUI interaction.

OSC-msg              | var | description
---------------------+-----+--------------------------------------------
/dvswitch/src/pri    |  i  | select primary video-input [0..]
/dvswitch/src/sec    |  i  | select secondary video-input [0..]
/dvswitch/src/snd    |  i  | select audio-input [0..]
/dvswitch/rec/start  | --- | send record-start command
/dvswitch/rec/stop   | --- | send record-stop command
/dvswitch/rec/cut    | --- | send record-cut command
/dvswitch/fx/overlay |  i  | set A/B overlay [0..255];
                     |     |  0: source A, 255: source B
/dvswitch/fx/fade    |  i  | switch to A->A' fade-effect [50..15000]ms;
                     |     |  0:cancel-effect
