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

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

dvswitch is a basic video mixer designed for the needs of DebConf.  It
may suit the needs of other conferences that require live mixing for
streams and/or recording.

Currently dvswitch can combine audio from one source with video from
another and can combine two video streams with a picture-in-picture
effect.  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-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, 48 or 44.1 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.

Home page
---------

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.

Operating system configuration
------------------------------

CPU frequency scaling should be disabled on the host running the mixer
because it seems to make the mixer's timing irregular, leading to
dropped and duplicated frames.

Socket buffers should be allowed to grow to at least one DV frame
size (144000 or 120000 bytes depending on the video system).  On
Linux 2.6 this happens automatically.

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 an 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 with a film strip and
speaker symbol respectively.

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
R               start/stop recording (in English locales)
T               cut recording (in English locales)
Return/Enter    apply effect
Escape          cancel area selection
Ctrl-Q          quit

Video and audio sources can also be selected using the buttons beneath
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 the only mixing effect is picture-in-picture.  To apply this
effect:

1. Select the primary video source by pressing its number key or
   clicking the 'A' button under its thumbnail
2. Select the secondary video source by pressing Alt and its number
   key or clicking the 'B' button under 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.
