USTREAMER(1)

📦
version 6.12 · 4 versions
, in fedora 43, fedora 44

💖 USTREAMER(1) 💖

okay so welcome bestie, you've just opened the USTREAMER(1) page from the General Commands Manual section and honestly? you're about to have a great time 🦋✨

✨ NAME ✨

ustreamer — stream MJPEG video from any V4L2 device to the network 🌈

🎀 SYNOPSIS 🎀

ustreamer [OPTIONS]

💅 DESCRIPTION 💅

µStreamer</purl> (ustreamer) is a lightweight and very quick server that streams MJPEG video from any V4L2 device straight to the network. no cap. 🔥

And the best part? Every new browser has native support for this video format, plus most video players like mplayer, VLC etc. So like… no plugin drama, no weird codec chaos, it just works 💖

µStreamer is part of the PiKVM project 👑 and it was designed to stream VGA and HDMI screencast hardware data at the highest resolution and FPS possible. main character energy fr fr.

🌸 USAGE 🌸

okay so if you run it with zero arguments, ustreamer will try to open /dev/video0 at a 640x480 resolution and start streaming on http://127.0.0.1:8080. that's the default vibe 🎀

You can override this behavior using the 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 a 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). iykyk 🫶

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 👑

and bestie… there's more coming, don't go anywhere 💖

✨ OPTIONS ✨

okay bestie, this is the big one. grab a snack, hydrate, stretch, we're going in 🍓

🎥 Capturing options

these are the ones that talk to your actual camera hardware, the moment of truth fr fr

  • -d /dev/path, --device /dev/path — the path to your V4L2 device, i.e. where your camera lives. Default is /dev/video0 🎀
  • -i N, --input N — which input channel to use. Default: 0.
  • -r WxH, --resolution WxH — the image resolution you start out with. Default: 640x480.
  • -m fmt, --format fmt — the image format, the whole vibe of your pixels. Available: YUYV, VYVU, UYVY, RGB565, RGB24, JPEG; default is YUYV ✨
  • -a std, --tv-standard std — force a TV standard, like the old-school days. Available: PAL, NTSC, SECAM; default: disabled.
  • -I method, --io-method method — set the V4L2 IO method (go peek at the kernel docs if you want the lore). Changing this may boost performance. Or not. no promises 💀 Available: MMAP, USERPTR; default: MMAP.
  • -f N, --desired-fps N — your desired FPS. Default: maximum possible, go fast.
  • -z N, --min-frame-size N — drop any frames smaller than this limit. Super handy when your device spits out tiny garbage frames. Default: 128 bytes.
  • -n, --persistent — suppress those repetitive signal source errors. Default: disabled.
  • -t, --dv-timings — enable DV-timings querying and events processing so the resolution can change automatically. Default: disabled.
  • -b N, --buffers N — how many buffers to receive data from the device. Each buffer may be 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 never more than buffers. Default: 1 (the number of CPU cores (but not more than 4)).
  • -q N, --quality N — set the 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 the specified encoder. Heads up, this can 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. it's giving haunted heirloom 🙈
  • -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 — slow the capturing down to 1 FPS or less whenever no stream or sink clients are connected. Great for saving CPU. Default: disabled.
  • --device-timeout sec — the timeout for device querying. Default: 1.
  • --device-error-delay sec — how long to wait before trying to reconnect to the device after an error (a timeout, for example). Default: 1.
  • --m2m-device /dev/path — the path to your V4L2 mem-to-mem encoder device. Default: auto-select.

🌸 Image control options

your glow-up menu, we're adjusting the camera's whole aesthetic

  • --image-default — reset every image setting below back 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

where your stream gets served, the main character entrance 💅

  • -s address, --host address — listen on this 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 a UNIX domain socket. Default: disabled.
  • -D, --unix-rm — try to remove the old unix socket file before binding. Default: disabled.
  • -M mode, --unix-mode mode — set the UNIX socket file permissions (like 777). Default: disabled.
  • -S, --systemd — bind to the systemd socket for socket activation. Requires the 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 a dir with static files instead of the 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 never more than the number you specify. It can significantly reduce outgoing traffic, but it will increase CPU load. Don't use this with analog signal sources or webcams, it's useless there. Default: disabled.
  • -R WxH, --fake-resolution WxH — override the image resolution for the /state. Default: disabled.
  • --tcp-nodelay — set the TCP_NODELAY flag on the client /stream socket. Only for TCP sockets. Default: disabled.
  • --allow-origin str — set the 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 a shared memory sink you can write a stream to a file. go read ustreamer-dump(1) for the deets 🫶

  • --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 the 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. Requires the HAS_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). (yes bestie, the manpage really does spell that option name like that, we do not make the rules 🙈)
  • --process-name-prefix str — set a process name prefix which will be displayed in the process list, like str: ustreamer --blah-blah-blah. Requires the 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. Requires the WITH_SETPROCTITLE feature.

🔌 GPIO options

available only if the WITH_GPIO feature is enabled 🎀

  • --gpio-device /dev/path — path to the GPIO character device. Default: /dev/gpiochip0.
  • --gpio-consumer-prefix str — consumer prefix for GPIO outputs. Default: ustreamer.
  • --gpio-prog-running pin — set 1 on a 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 the stream has at least one client. Default: disabled.

📝 Logging options

  • --log-level N — verbosity level of messages from 0 (info) to 3 (debug). Heads up, enabling debugging messages can slow the program down. 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 the list of supported features.

👀 SEE ALSO

ustreamer-dump(1)

🐛 BUGS

please file any bugs and issues at https://github.com/pikvm/ustreamer/issues — they want to hear from you fr fr

✍️ AUTHOR

Maxim Devaev <mdevaev@gmail.com>

🏠 HOMEPAGE

https://pikvm.org/

GNU General Public License v3.0

and that's the whole page bestie 🫶 this one's from November 2020, version 6.12, and it lives under the name USTREAMER(1). slay, go stream something iconic 💖✨

📦 where this page comes from