1USTREAMER(1) General Commands Manual USTREAMER(1)
2
6 ustreamer - stream MJPEG video from any V4L2 device to the network
7
10 ustreamer [OPTIONS]
11
14 µStreamer (ustreamer) is a lightweight and very quick server to stream
15 MJPEG video from any V4L2 device to the network. All new browsers have
16 native support of this video format, as well as most video players such
17 as mplayer, VLC etc. µStreamer is a part of the PiKVM project designed
18 to stream VGA and HDMI screencast hardware data with the highest reso‐
19 lution and FPS possible.
20
23 Without arguments, ustreamer will try to open /dev/video0 with 640x480
24 resolution and start streaming on http://127.0.0.1:8080. You can over‐
25 ride this behavior using parameters --device, --host and --port. For
26 example, to stream to the world, run: ustreamer --device=/dev/video1
27 --host=0.0.0.0 --port=80
28 Please note that since µStreamer v2.0 cross-domain requests were dis‐
30 abled by default for security reasons. To enable the old behavior, use
31 the option --allow-origin=\*.
32 For example, the recommended way of running µStreamer with Auvidea B101
34 on a Raspberry Pi is:
35 ustreamer \
37 --format=uyvy \ # Device input format
38 --encoder=m2m-image \ # Hardware encoding with V4L2 M2M intraface
39 --workers=3 \ # Maximum workers for V4L2 encoder
40 --persistent \ # Don´t re-initialize device on timeout (for example when HDMI cable was disconnected)
41 --dv-timings \ # Use DV-timings
42 --drop-same-frames=30 # Save the traffic
43 Please note that to use --drop-same-frames for different browsers you need to use some specific URL /stream parameters (see URL / for details).
45 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.
47
50 Capturing options
51 -d /dev/path, --device /dev/path
52 Path to V4L2 device. Default: /dev/video0.
53 -i N, --input N
55 Input channel. Default: 0.
56 -r WxH, --resolution WxH
58 Initial image resolution. Default: 640x480.
59 -m fmt, --format fmt
61 Image format. Available: YUYV, UYVY, RGB565, RGB24, JPEG; de‐
62 fault: YUYV.
63 -a std, --tv-standard std
65 Force TV standard. Available: PAL, NTSC, SECAM; default: dis‐
66 abled.
67 -I method, --io-method method
69 Set V4L2 IO method (see kernel documentation). Changing of this
70 parameter may increase the performance. Or not. Available:
71 MMAP, USERPTR; default: MMAP.
72 -f N, --desired-fps N
74 Desired FPS. Default: maximum possible.
75 -z N, --min-frame-size N
77 Drop frames smaller then this limit. Useful if the device pro‐
78 duces small-sized garbage frames. Default: 128 bytes.
79 -n, --persistent
81 Don't re-initialize device on timeout. Default: disabled.
82 -t, --dv-timings
84 Enable DV-timings querying and events processing to automatic
85 resolution change. Default: disabled.
86 -b N, --buffers N
88 The number of buffers to receive data from the device. Each buf‐
89 fer may processed using an independent thread. Default: 2 (the
90 number of CPU cores (but not more than 4) + 1).
91 -w N, --workers N
93 The number of worker threads but not more than buffers. De‐
94 fault: 1 (the number of CPU cores (but not more than 4)).
95 -q N, --quality N
97 Set quality of JPEG encoding from 1 to 100 (best). Default: 80.
98 Note: If HW encoding is used (JPEG source format selected), this
99 parameter attempts to configure the camera or capture device
100 hardware's internal encoder. It does not re-encode MJPEG to
101 MJPEG to change the quality level for sources that already out‐
102 put MJPEG.
103 -c type, --encoder type
105 Use specified encoder. It may affect the number of workers.
106 CPU ─ Software MJPEG encoding (default).
108 HW ─ Use pre-encoded MJPEG frames directly from camera hardware.
110 M2M-VIDEO ─ GPU-accelerated MJPEG encoding.
112 M2M-IMAGE ─ GPU-accelerated JPEG encoding.
114 NOOP ─ Don't compress MJPEG stream (do nothing).
116 -g WxH,..., --glitched-resolutions WxH,...
118 It doesn't do anything. Still here for compatibility.
119 -k path, --blank path
121 Path to JPEG file that will be shown when the device is discon‐
122 nected during the streaming. Default: black screen 640x480 with
123 'NO SIGNAL'.
124 -K sec, --last-as-blank sec
126 Show the last frame received from the camera after it was dis‐
127 connected, but no more than specified time (or endlessly if 0 is
128 specified). If the device has not yet been online, display 'NO
129 SIGNAL' or the image specified by option --blank. Note: cur‐
130 rently this option has no effect on memory sinks. Default: dis‐
131 abled.
132 -l, --slowdown
134 Slowdown capturing to 1 FPS or less when no stream or sink
135 clients are connected. Useful to reduce CPU consumption. De‐
136 fault: disabled.
137 --device-timeout sec
139 Timeout for device querying. Default: 1.
140 --device-error-delay sec
142 Delay before trying to connect to the device again after an er‐
143 ror (timeout for example). Default: 1.
144 --m2m-device /dev/path
146 Path to V4L2 mem-to-mem encoder device. Default: auto-select.
147 Image control options
150 --image-default
151 Reset all image settings below to default. Default: no change.
152 --brightness N, auto, default
154 Set brightness. Default: no change.
155 --contrast N, default
157 Set contrast. Default: no change.
158 --saturation N, default
160 Set saturation. Default: no change.
161 --hue N, auto, default
163 Set hue. Default: no change.
164 --gamma N, default
166 Set gamma. Default: no change.
167 --sharpness N, default
169 Set sharpness. Default: no change.
170 --backlight-compensation N, default
172 Set backlight compensation. Default: no change.
173 --white-balance N, auto, default
175 Set white balance. Default: no change.
176 --gain N, auto, default
178 Set gain. Default: no change.
179 --color-effect N, default
181 Set color effect. Default: no change.
182 --flip-vertical 1, 0, default
184 Set vertical flip. Default: no change.
185 --flip-horizontal 1, 0, default
187 Set horizontal flip. Default: no change.
188 HTTP server options
191 -s address, --host address
192 Listen on Hostname or IP. Default: 127.0.0.1.
193 -p N, --port N
195 Bind to this TCP port. Default: 8080.
196 -U path, --unix path
198 Bind to UNIX domain socket. Default: disabled.
199 -D, --unix-rm
201 Try to remove old unix socket file before binding. default: dis‐
202 abled.
203 -M mode, --unix-mode mode
205 Set UNIX socket file permissions (like 777). Default: disabled.
206 -S, --systemd
208 Bind to systemd socket for socket activation. Required WITH_SYS‐
209 TEMD feature. Default: disabled.
210 --user name
212 HTTP basic auth user. Default: disabled.
213 --passwd str
215 HTTP basic auth passwd. Default: empty.
216 --static path
218 Path to dir with static files instead of embedded root index
219 page. Symlinks are not supported for security reasons. Default:
220 disabled.
221 -e N, --drop-same-frames N
223 Don't send identical frames to clients, but no more than speci‐
224 fied number. It can significantly reduce the outgoing traffic,
225 but will increase the CPU loading. Don't use this option with
226 analog signal sources or webcams, it's useless. Default: dis‐
227 abled.
228 -R WxH, --fake-resolution WxH
230 Override image resolution for the /state. Default: disabled.
231 --tcp-nodelay
233 Set TCP_NODELAY flag to the client /stream socket. Only for TCP
234 socket. Default: disabled.
235 --allow-origin str
237 Set Access-Control-Allow-Origin header. Default: disabled.
238 --instance-id str
240 A short string identifier to be displayed in the /state handle.
241 It must satisfy regexp ^[a-zA-Z0-9./+_-]*$. Default: an empty
242 string.
243 --server-timeout sec
245 Timeout for client connections. Default: 10.
246 JPEG sink options
249 With shared memory sink you can write a stream to a file. See us‐
250 treamer-dump(1) for more info.
251 --sink name
253 Use the specified shared memory object to sink JPEG frames. De‐
254 fault: disabled.
255 --sink-mode mode
257 Set JPEG sink permissions (like 777). Default: 660.
258 --sink-rm
260 Remove shared memory on stop. Default: disabled.
261 --sink-client-ttl sec
263 Client TTL. Default: 10.
264 --sink-timeout sec
266 Timeout for lock. Default: 1.
267 H264 sink options
270 --h264-sink name
271 Use the specified shared memory object to sink H264 frames. De‐
272 fault: disabled.
273 --h264-sink-mode mode
275 Set H264 sink permissions (like 777). Default: 660.
276 --h264-sink-rm
278 Remove shared memory on stop. Default: disabled.
279 --h264-sink-client-ttl sec
281 Client TTL. Default: 10.
282 --h264-sink-timeout sec
284 Timeout for lock. Default: 1.
285 --h264-bitrate kbps
287 H264 bitrate in Kbps. Default: 5000.
288 --h264-gop N
290 Intarval between keyframes. Default: 30.
291 --h264-m2m-device /dev/path
293 Path to V4L2 mem-to-mem encoder device. Default: auto-select.
294 Process options
298 --exit-on-parent-death
299 Exit the program if the parent process is dead. Required
300 HAS_PDEATHSIG feature. Default: disabled.
301 --exit-on-no-clientssec
303 Exit the program if there have been no stream or sink clients or
304 any HTTP requests in the last N seconds. Default: 0 (disabled).
305 --process-name-prefix str
307 Set process name prefix which will be displayed in the process
308 list like 'str: ustreamer --blah-blah-blah'. Required WITH_SET‐
309 PROCTITLE feature. Default: disabled.
310 --notify-parent
312 Send SIGUSR2 to the parent process when the stream parameters
313 are changed. Checking changes is performed for the online flag
314 and image resolution. Required WITH_SETPROCTITLE feature.
315 GPIO options
318 Available only if WITH_GPIO feature enabled.
319 --gpio-device /dev/path
321 Path to GPIO character device. Default: /dev/gpiochip0.
322 --gpio-consumer-prefix str
324 Consumer prefix for GPIO outputs. Default: ustreamer.
325 --gpio-prog-running pin
327 Set 1 on GPIO pin while µStreamer is running. Default: disabled.
328 --gpio-stream-online pin
330 Set 1 while streaming. Default: disabled.
331 --gpio-has-http-clients pin
333 Set 1 while stream has at least one client. Default: disabled.
334 Logging options
337 --log-level N
338 Verbosity level of messages from 0 (info) to 3 (debug). Enabling
339 debugging messages can slow down the program. Available levels:
340 0 (info), 1 (performance), 2 (verbose), 3 (debug). Default: 0.
341 --perf Enable performance messages (same as --log-level=1). Default:
343 disabled.
344 --verbose
346 Enable verbose messages and lower (same as --log-level=2). De‐
347 fault: disabled.
348 --debug
350 Enable debug messages and lower (same as --log-level=3). De‐
351 fault: disabled.
352 --force-log-colors
354 Force color logging. Default: colored if stderr is a TTY.
355 --no-log-colors
357 Disable color logging. Default: ditto.
358 Help options
361 -h, --help
362 Print this text and exit.
363 -v, --version
365 Print version and exit.
366 --features
368 Print list of supported features.
369
372 ustreamer-dump(1)
373
376 Please file any bugs and issues at https://github.com/pikvm/us‐
377 treamer/issues
378
381 Maxim Devaev <mdevaev@gmail.com>
382
385 https://pikvm.org/
386
389 GNU General Public License v3.0
390November 2020 version 5.37 USTREAMER(1)