====== User guide ======

===== Basic concepts =====

Duga reads video frames from pipe as raw RGB24 bitmaps (i.e., each pixel is represented by 3 uint8_t) and audio as int16_t (a.k.a. PCM S16_LE) samples. It combines them and outputs RGB24 and PCM stream.

The intended usage is to have several ffmpeg (and maybe arecord for audio) processes that eat from various sources (V4L2, files, network streams, wireless microphones…) and one ffmpeg process that reads the output, encodes it to something sane and feeds it to your favorite streaming server (VLC, ffserver…).

Configuration is solely by commands. Commands can be read from a rc file (which is the only command line argument) during startup or from stdin afterwards.

===== Installation =====

For duga, only C++11 compiler is required. However, you will probably need ffmpeg and vlc binaries to do something useful.

Just run "make".

===== Supported commands =====

Some example usage is in the default rc file. It opens your camera, a video file and an image and starts streaming in FLV format.

==== set <variable> <value> ====

Sets variable in global configuration.

Variables are:
  * vrate <n> - video frame rate
  * arate <n> - audio sample rate
  * ores <x> <y> - output video resolution
  * bufsize <n> - number of frames to buffer
  * videopipe <path> - output video is written here
  * audiopipe <path> - output audio is written here
  * streamer <string> - this command is executed upon startup, it should open videopipe and audiopipe and do something with the data

==== run ====

Starts the processing (duga will start outputting black video and silent audio).

==== import <video name> <audio name> <video resolution x> <video resolution y> <video pipe> <audio pipe> <framedrop/noframedrop> <command> ====

Add a stream.

  * name - some human-readable handle
  * resolution - obvious
  * pipe - this will be opened and data will be read from it
  * (no)framedrop - if we are reading for example from a camera and its clock is unstable (faster than in your computer), it will produce frames faster than we read them and finally some buffer on the way will overflow (really observed with one cheap camera that had the exact frame rate 25.01 FPS). With framedropping enabled, we detect this situation and drop some frames. However, if you are reading from a file (e.g. you are broadcasting a pre-recorded thing), we will detect this as a really fast camera, but you really don't want to have frames dropped. So set this to noframedrop if the source is file, and to framedrop, if the source is a real camera.

If you have only audio or only video, put "none" as the name.

==== static <name> <resolution x> <resolution y> <filename> ====

Import an image, e.g. a logo. The file in RGBA format (alpha ~ 0xFF - full opacity, 0x00 - full transparency) can be obtained for example with
<code>convert image.png image.rgba</code>

==== transform <parameter> <value> ====

Manipulate existing stream. Parameters are:

  * pos <x> <y> - move the video
  * scale <factor> - downscale video by this factor (default: 1)
  * scale <factor> - if this is audio, set volume (default: 100)
  * brightness <n> - shift black level (default: 0)
  * contrast <n> - scale dynamic range (default: 255)
  * zindex <n> - when several images overlay, the one with higher z-index will be shown

==== enable <name> ====

Enable a source.

==== disable <name> ====

Disable a source (it will just stop showing it, but all the processing still runs).

==== destroy <name> ====

Destroy a source (it will close the pipe - which will probably mean that your program will receive SIGPIPE and gracefully end).

==== show ====

Show which sources are currently configured.

==== audiopeak ====

Show peak audio level since the time this command was last run. The number is in range [0, 2^15] as we are using signed 16-bit PCM.