USTREAMER(1)

NAME
ustreamer - stream MJPEG video from any V4L2 device to the network

SYNOPSIS
ustreamer [OPTIONS]

DESCRIPTION
µStreamer (ustreamer) is a lightweight and very quick server to stream MJPEG video from any V4L2 device to the network. All new browsers have native support of this video format, as well as most video players such as mplayer, VLC etc. µStreamer is a part of the PiKVM project designed to stream VGA and HDMI screencast hardware data with the highest resolution and FPS possible.

USAGE
Without arguments, ustreamer will try to open /dev/video0 with 640x480 resolution and start streaming on http://127.0.0.1:8080. You can override this behavior using parameters --device, --host and --port. For example, to stream to the world, run: ustreamer --device=/dev/video1 --host=0.0.0.0 --port=80 Please note that since µStreamer v2.0 cross-domain requests were disabled by default for security reasons. To enable the old behavior, use the option --allow-origin=\*. For example, the recommended way of running µStreamer with TC358743-based capture device on a Raspberry Pi is: ustreamer \
    --format=uyvy \ # Device input format
    --encoder=m2m-image \ # Hardware encoding with V4L2 M2M intraface
    --workers=3 \ # Maximum workers for V4L2 encoder
    --persistent \ # Suppress repetitive signal source errors (for example when HDMI cable was disconnected)
    --dv-timings \ # Use DV-timings
    --drop-same-frames=30 # Save the traffic

Please note that to use --drop-same-frames for different browsers you need to use some specific URL /stream parameters (see URL / for details).

You can always view the full list of options with ustreamer --help. Some features may not be available on your platform. To find out which features are enabled, use ustreamer --features.

OPTIONS

  Capturing options

-d /dev/path, --device /dev/path
    Path to V4L2 device. Default: /dev/video0.

-i N, --input N
    Input channel. Default: 0.

-r WxH, --resolution WxH
    Initial image resolution. Default: 640x480.

-m fmt, --format fmt
    Image format. Available: YUYV, YVYU, UYVY, YUV420, YVU420, RGB565, RGB24, JPEG; default: YUYV.

-a std, --tv-standard std
    Force TV standard. Available: PAL, NTSC, SECAM; default: disabled.

-I method, --io-method method
    Set V4L2 IO method (see kernel documentation). Changing of this parameter may increase the performance. Or not. Available: MMAP, USERPTR; default: MMAP.

-f N, --desired-fps N
    Desired FPS. Default: maximum possible.

-z N, --min-frame-size N
    Drop frames smaller then this limit. Useful if the device produces small-sized garbage frames. Default: 128 bytes.

-T, --allow-truncated-frames
    Allows to handle truncated frames. Useful if the device produces incorrect but still acceptable frames. Default: disabled.

-n, --persistent
    Suppress repetitive signal source errors. Default: disabled.

-t, --dv-timings
    Enable DV-timings querying and events processing to automatic resolution change. Default: disabled.

-b N, --buffers N
    The number of buffers to receive data from the device. Each buffer may processed using an independent thread. Default: 2 (the number of CPU cores (but not more than 4) + 1).

-w N, --workers N
    The number of worker threads but not more than buffers. Default: 1 (the number of CPU cores (but not more than 4)).

-q N, --quality N
    Set quality of JPEG encoding from 1 to 100 (best). Default: 80. Note: If HW encoding is used (JPEG source format selected), this parameter attempts to configure the camera or capture device hardware's internal encoder. It does not re-encode MJPEG to MJPEG to change the quality level for sources that already output MJPEG.

-c type, --encoder type
    Use specified encoder. It may affect the number of workers. CPU ─ Software MJPEG encoding (default). HW ─ Use pre-encoded MJPEG frames directly from camera hardware. M2M-VIDEO ─ GPU-accelerated MJPEG encoding. M2M-IMAGE ─ GPU-accelerated JPEG encoding.

-g WxH,..., --glitched-resolutions WxH,...
    It doesn't do anything. Still here for compatibility.

-k path, --blank path
    It doesn't do anything. Still here for compatibility.

-K sec, --last-as-blank sec
    It doesn't do anything. Still here for compatibility.

-l, --slowdown
    Slowdown capturing to 1 FPS or less when no stream or sink clients are connected. Useful to reduce CPU consumption. Default: disabled.

--device-timeout sec
    Timeout for device querying. Default: 1.

--device-error-delay sec
    Delay before trying to connect to the device again after an error (timeout for example). Default: 1.

--m2m-device /dev/path
    Path to V4L2 mem-to-mem encoder device. Default: auto-select.

  Image control options

--image-default
    Reset all image settings below to default. Default: no change.

--brightness N, auto, default
    Set brightness. Default: no change.

--contrast N, default
    Set contrast. Default: no change.

--saturation N, default
    Set saturation. Default: no change.

--hue N, auto, default
    Set hue. Default: no change.

--gamma N, default
    Set gamma. Default: no change.

--sharpness N, default
    Set sharpness. Default: no change.

--backlight-compensation N, default
    Set backlight compensation. Default: no change.

--white-balance N, auto, default
    Set white balance. Default: no change.

--gain N, auto, default
    Set gain. Default: no change.

--color-effect N, default
    Set color effect. Default: no change.

--flip-vertical 1, 0, default
    Set vertical flip. Default: no change.

--flip-horizontal 1, 0, default
    Set horizontal flip. Default: no change.

  HTTP server options

-s address, --host address
    Listen on Hostname or IP. Default: 127.0.0.1.

-p N, --port N
    Bind to this TCP port. Default: 8080.

-U path, --unix path
    Bind to UNIX domain socket. Default: disabled.

-D, --unix-rm
    Try to remove old unix socket file before binding. default: disabled.

-M mode, --unix-mode mode
    Set UNIX socket file permissions (like 777). Default: disabled.

-S, --systemd
    Bind to systemd socket for socket activation. Required WITH_SYSTEMD feature. Default: disabled.

--user name
    HTTP basic auth user. Default: disabled.

--passwd str
    HTTP basic auth passwd. Default: empty.

--static path
    Path to dir with static files instead of embedded root index page. Symlinks are not supported for security reasons. Default: disabled.

-e N, --drop-same-frames N
    Don't send identical frames to clients, but no more than specified number. It can significantly reduce the outgoing traffic, but will increase the CPU loading. Don't use this option with analog signal sources or webcams, it's useless. Default: disabled.

-R WxH, --fake-resolution WxH
    Override image resolution for the /state. Default: disabled.

--tcp-nodelay
    Set TCP_NODELAY flag to the client /stream socket. Only for TCP socket. Default: disabled.

--allow-origin str
    Set Access-Control-Allow-Origin header. Default: disabled.

--instance-id str
    A short string identifier to be displayed in the /state handle. It must satisfy regexp ^[a-zA-Z0-9./+_-]*$. Default: an empty string.

--server-timeout sec
    Timeout for client connections. Default: 10.

  JPEG sink options
With shared memory sink you can write a stream to a file. See ustreamer-dump(1) for more info.

--jpeg-sink name
    Use the specified shared memory object to sink JPEG frames. The name should end with a suffix ".jpeg" or ":jpeg". Default: disabled.

--jpeg-sink-mode mode
    Set JPEG sink permissions (like 777). Default: 660.

--jpeg-sink-rm
    Remove shared memory on stop. Default: disabled.

--jpeg-sink-client-ttl sec
    Client TTL. Default: 10.

--jpeg-sink-timeout sec
    Timeout for lock. Default: 1.

  H264 sink options

--h264-sink name
    Use the specified shared memory object to sink H264 frames. The name should end with a suffix ".h264" or ":h264". Default: disabled.

--h264-sink-mode mode
    Set H264 sink permissions (like 777). Default: 660.

--h264-sink-rm
    Remove shared memory on stop. Default: disabled.

--h264-sink-client-ttl sec
    Client TTL. Default: 10.

--h264-sink-timeout sec
    Timeout for lock. Default: 1.

--h264-bitrate kbps
    H264 bitrate in Kbps. Default: 5000.

--h264-gop N
    Interval between keyframes. Default: 30.

--h264-m2m-device /dev/path
    Path to V4L2 mem-to-mem encoder device. Default: auto-select.

  RAW sink options

--raw-sink name
    Use the specified shared memory object to sink RAW frames. The name should end with a suffix ".raw" or ":raw". Default: disabled.

--raw-sink-mode mode
    Set RAW sink permissions (like 777). Default: 660.

--raw-sink-rm
    Remove shared memory on stop. Default: disabled.

--raw-sink-client-ttl sec
    Client TTL. Default: 10.

--raw-sink-timeout sec
    Timeout for lock. Default: 1.

  Process options

--exit-on-parent-death
    Exit the program if the parent process is dead. Required WITH_PDEATHSIG feature. Default: disabled.

--exit-on-no-clientssec
    Exit the program if there have been no stream or sink clients or any HTTP requests in the last N seconds. Default: 0 (disabled).

--process-name-prefix str
    Set process name prefix which will be displayed in the process list like 'str: ustreamer --blah-blah-blah'. Required WITH_SETPROCTITLE feature. Default: disabled.

--notify-parent
    Send SIGUSR2 to the parent process when the stream parameters are changed. Checking changes is performed for the online flag and image resolution. Required WITH_SETPROCTITLE feature.

  GPIO options
Available only if WITH_GPIO feature enabled.

--gpio-device /dev/path
    Path to GPIO character device. Default: /dev/gpiochip0.

--gpio-consumer-prefix str
    Consumer prefix for GPIO outputs. Default: ustreamer.

--gpio-prog-running pin
    Set 1 on GPIO pin while µStreamer is running. Default: disabled.

--gpio-stream-online pin
    Set 1 while streaming. Default: disabled.

--gpio-has-http-clients pin
    Set 1 while stream has at least one client. Default: disabled.

  Logging options

--log-level N
    Verbosity level of messages from 0 (info) to 3 (debug). Enabling debugging messages can slow down the program. Available levels: 0 (info), 1 (performance), 2 (verbose), 3 (debug). Default: 0.

--perf
    Enable performance messages (same as --log-level=1). Default: disabled.

--verbose
    Enable verbose messages and lower (same as --log-level=2). Default: disabled.

--debug
    Enable debug messages and lower (same as --log-level=3). Default: disabled.

--force-log-colors
    Force color logging. Default: colored if stderr is a TTY.

--no-log-colors
    Disable color logging. Default: ditto.

  Help options

-h, --help
    Print this text and exit.

-v, --version
    Print version and exit.

--features
    Print list of supported features.

SEE ALSO
ustreamer-dump(1)

BUGS
Please file any bugs and issues at https://github.com/pikvm/ustreamer/issues

AUTHOR
Maxim Devaev <mdevaev@gmail.com>

HOMEPAGE
https://pikvm.org/

COPYRIGHT
GNU General Public License v3.0