Debian Codegraph @

doc/bino-manual.md

raw
1 ---
2 title: Bino
3 header: Version 2.6
4 date: November 9, 2025
5 section: 1
6 ---
7
8 # Overview
9
10 Bino is a video player with a focus on 3D and Virtual Reality:
11
12 - Support for stereoscopic 3D videos in various formats
13
14 - Support for 360° and 180° surround videos, with and without stereoscopic 3D
15
16 - Support for Virtual Reality environments, including SteamVR,
17 CAVEs, powerwalls, and other multi-display / multi-GPU / multi-host systems
18
19 # Invocation
20
21 `bino` [*options*] *URL*...
22
23 - `-h`, `--help`
24
25 Displays help on command line options.
26
27 - `--help-all`
28
29 Displays help including Qt specific options.
30
31 - `-v`, `--version`
32
33 Displays version information.
34
35 - `--log-level` *level*
36
37 Set log level (fatal, warning, info, debug, firehose).
38
39 - `--log-file` *file*
40
41 Set log file.
42
43 - `--read-commands` *script*
44
45 Read commands from a script file. See [Scripting].
46
47 - `--disable-stereo`
48
49 Disable OpenGL quad-buffered stereo support. This is a workaround for broken
50 drivers, mostly the NVIDIA proprietary drivers on Linux.
51
52 - `--opengles`
53
54 Use OpenGL ES instead of Desktop OpenGL.
55
56 - `--vr`
57
58 Start in Virtual Reality mode instead of GUI mode. See [Virtual Reality].
59
60 - `--vr-screen` *screen*
61
62 Set VR screen geometry, either as the special values 'united' or 'intersected', or as a comma-separated list of nine
63 values representing three 3D coordinates that define a planar screen (bottom left, bottom right, top left), or as a an
64 aspect ratio followed by the name of an OBJ file that contains the screen geometry with texture coordinates (example:
65 '16:9,myscreen.obj').
66
67 - `--capture`
68
69 Capture audio/video input from microphone and camera/screen/window.
70
71 - `--list-audio-outputs`
72
73 List audio outputs.
74
75 - `--list-audio-inputs`
76
77 List audio inputs.
78
79 - `--list-video-inputs`
80
81 List video inputs.
82
83 - `--list-screen-inputs`
84
85 List screen inputs.
86
87 - `--list-window-inputs`
88
89 List window inputs.
90
91 - `--audio-output` *ao*
92
93 Choose audio output via its index.
94
95 - `--audio-input` *ai*
96
97 Choose audio input via its index. Can be empty.
98
99 - `--video-input` *vi*
100
101 Choose video input via its index.
102
103 - `--screen-input` *si*
104
105 Choose screen input via its index.
106
107 - `--window-input` *wi*
108
109 Choose window input via its index.
110
111 - `--list-tracks`
112
113 List all video, audio and subtitle tracks in the media.
114
115 - `--preferred-audio` *lang*
116
117 Set preferred audio track language (en, de, fr, ...).
118
119 - `--preferred-subtitle` *lang*
120
121 Set preferred subtitle track language (en, de, fr, ...). Can be empty.
122
123 - `--video-track` *track*
124
125 Choose video track via its index.
126
127 - `--audio-track` *track*
128
129 Choose audio track via its index.
130
131 - `--subtitle-track` *track*
132
133 Choose subtitle track via its index. Can be empty.
134
135 - `-p`, `--playlist` *file*
136
137 Load playlist.
138
139 - `-l`, `--loop` *mode*
140
141 Set loop mode (off, one, all).
142
143 - `-w`, `--wait` *mode*
144
145 Set wait mode (off, on).
146
147 - `-i`, `--input` *mode*
148
149 Set input mode (mono, top-bottom, top-bottom-half, bottom-top,
150 bottom-top-half, left-right, left-right-half, right-left, right-left-half,
151 alternating-left-right, alternating-right-left).
152
153 - `-o`, `--output` *mode*
154
155 Set output mode (left, right, stereo, alternating, hdmi-frame-pack,
156 left-right, left-right-half, right-left, right-left-half, top-bottom,
157 top-bottom-half, bottom-top, bottom-top-half, even-odd-rows,
158 even-odd-columns, checkerboard, red-cyan-dubois, red-cyan-full-color,
159 red-cyan-half-color, red-cyan-monochrome, green-magenta-dubois,
160 green-magenta-full-color, green-magenta-half-color, green-magenta-monochrome,
161 amber-blue-dubois, amber-blue-full-color, amber-blue-half-color,
162 amber-blue-monochrome, red-green-monochrome, red-blue-monochrome).
163
164 - `--surround` *mode*
165
166 Set surround mode (360, 180, off).
167
168 - `--surround-vfov` *degrees*
169
170 Set surround vertical field of view (default 50, range 5-115).
171
172 - `-S`, `--swap-eyes`
173
174 Swap left/right eye.
175
176 - `-f`, `--fullscreen`
177
178 Start in fullscreen mode.
179
180 # Output modes
181
182 Most output modes should be self explanatory, but there are some exceptions:
183
184 - `stereo` requires OpenGL quad-buffered stereo support, typically limited to
185 high-end graphics cards.
186 - `alternating` tries to mimic stereo mode by displaying the left and right
187 frames alternating, ideally at display speed. This is unreliable since Bino
188 has no way of making sure that its output frames actually correspond to
189 display output frames, but it might work, depending on your hardware and
190 system setup.
191 - `hdmi-frame-pack` is a special mode supported by some 3D TVs via HDMI 1.4a,
192 where the left view is placed in the top part of a frame and the right view
193 in the bottom part, and both parts are separated by a blank area that takes
194 1/49 of the vertical space. To use this mode, force your display output
195 resolution into either 1280x1470 (720p 3D: 720+30+720=1470; 1470/49=30) or
196 1920x2205 (1080p 3D: 1080+45+1080=2205; 2205/49=45).
197 - `even-odd-rows`, `even-odd-columns` and `checkerboard` are for (older) 3D
198 TVs.
199
200 # File Name Conventions
201
202 Bino currently cannot detect the stereoscopic layout or the surround video mode
203 from metadata because Qt does not provide that information. It therefore has to
204 guess.
205
206 Bino recognizes the following hints at the last part of the file name, just
207 before the file name extension (.ext):
208
209 - `*-tb.ext`, `*-ab.ext`: Input mode `top-bottom`
210 - `*-tbh.ext`, `*-abq.ext`: Input mode `top-bottom-half`
211 - `*-bt.ext`, `*-ba.ext`: Input mode `bottom-top`
212 - `*-bth.ext`, `*-baq.ext`: Input mode `bottom-top-half`
213 - `*-lr.ext`: Input mode `left-right`
214 - `*-lrh.ext`, `*-lrq.ext`: Input mode `left-right-half`
215 - `*-rl.ext`: Input mode `right-left`
216 - `*-rlh.ext`, `*-rlq.ext`: Input mode `right-left-half`
217 - `*-2d.ext`: Input mode `mono`
218
219 Additionally, if the number `180` or `360` is part of the file name and separated
220 by neighboring digits or letters by other characters, then the corresponding surround
221 mode is assumed.
222
223 # Scripting
224
225 Bino can read commands from a script file and execute them via the option
226 `--read-commands` *scriptfile*. This works both in GUI mode and in Virtual
227 Reality mode.
228
229 The script file can also be a named pipe so that you can have arbitrary remote
230 control interfaces write commands into it as they come in.
231
232 Empty lines and comment lines (which begin with `#`) are ignored.
233 The following commands are supported:
234
235 - `open` `[--input` *mode*`]` `[--surround` *mode*`]` `[--video-track` *vt*`]` `[--audio-track` *at*`]` `[--subtitle-track` *st*`]` *URL*
236
237 Open the URL and start playing. The options have the same meaning as the corresponding command line options.
238
239 - `capture` `[--audio-input` *ai*`]` `[--video-input` *vi*`]` `[--screen-input` *si*`]` `[--window-input` *wi*`]`
240
241 Start capturing camera and microphone. The options have the same meaning as the corresponding command line options.
242
243 - `play`
244
245 Start playing.
246
247 - `pause`
248
249 Pause.
250
251 - `toggle-pause`
252
253 Switch between pause and play.
254
255 - `stop`
256
257 Stop playing.
258
259 - `playlist-load` *playlist.m3u*
260
261 Load the playlist.
262
263 - `playlist-next`
264
265 Switch to next playlist entry.
266
267 - `playlist-prev`
268
269 Switch to previous playlist entry.
270
271 - `playlist-wait` *mode*
272
273 Set wait mode (off, on).
274
275 - `playlist-loop` *mode*
276
277 Set loop mode (off, one, all).
278
279 - `quit`
280
281 Quit Bino.
282
283 - `set-position` *p*
284
285 Set the video position to *p*, where *p*=0 is the beginning and *p*=1 is the end.
286
287 - `seek` *seconds*
288
289 Seek the given amounts of seconds forward or, if the number of seconds is negative, backwards.
290
291 - `wait` `stop`|*seconds*
292
293 Wait until the video stops, or wait for the given number of seconds, before executing the next command.
294
295 - `set-mute` `on`|`off`
296
297 Set the volume mute status.
298
299 - `toggle-mute`
300
301 Switch between mute and unmute.
302
303 - `set-volume` *vol*
304
305 Set the volume level to *vol* (between 0 and 1).
306
307 - `adjust-volume` *offset*
308
309 Adjust the volume by the given amount (the final volume is clamped between 0 and 1).
310
311 - `set-output-mode` *mode*
312
313 Set the given output mode. See the command line option `--output` for a list of modes.
314
315 - `set-surround-vfov` *degrees*
316
317 Set surround vertical field of view (default 50, range 5-115).
318
319 - `set-swap-eyes` `on`|`off`
320
321 Set left/right eye swap.
322
323 - `toggle-swap-eyes`
324
325 Toggle left/right eye swap.
326
327 - `set-fullscreen` `on`|`off`
328
329 Set fullscreen mode.
330
331 - `toggle-fullscreen`
332
333 Toggle fullscreen mode.
334
335 # Slideshows
336
337 You can play slideshows of images (or videos) simply by making a playlist and
338 switching on its *wait* status. This is the default whenever one or more of the
339 files you open are images instead of videos; this works from the command line
340 as well as from the GUI.
341
342 With *wait* enabled, the next media in the playlist will only be displayed after
343 you press the N key, or choose Playlist/Next from the menu.
344
345 For automatic media switching based on predefined presentation times, use the
346 scripting mode as in the following example:
347 ```
348 set-fullscreen on
349 playlist-load my-slideshow.m3u
350 playlist-loop on
351 playlist-wait on
352 playlist-next
353 wait 4
354 playlist-next
355 wait 7
356 playlist-next
357 wait 5
358 quit
359 ```
360
361 # Virtual Reality
362
363 Bino supports all sorts of Virtual Reality environments via [QVR](https://marlam.de/qvr):
364
365 - When QVR is compiled just with Qt6, CAVEs and powerwalls and similar
366 multi-display setups are supported, including multi-GPU and multi-host
367 rendering.
368
369 - When QVR is compiled with [VRPN](https://github.com/vrpn/vrpn),
370 all sorts of tracking and interaction hardware for such systems are
371 additionally supported.
372
373 - When QVR is compiled with [OpenVR](https://github.com/ValveSoftware/openvr),
374 SteamVR is additionally supported and automatically detected (e.g. HTC Vive).
375
376 To start Bino in VR mode, use the option `--vr`.
377 Bino will then display a screen in the virtual world, and the video will be
378 displayed on that screen, unless the input is a surround video (360° or 180°),
379 which will of course be displayed all around the viewer.
380
381 The default is a 16:9 screen in a few meters distance from the viewer, but you
382 can use the `--vr-screen` option to either define arbitrary planar screens via
383 their bottom left, bottom right and top left corners, or to load arbitrary
384 screen geometry from an OBJ file. The latter case is useful e.g. if you want
385 Bino's virtual screen to coincide with a curved physical screen.
386
387 The `--vr-screen` option also accepts the special values `united` and
388 `intersected`. This will unite (or intersect) the 2D geometries of all VR windows
389 at runtime. For example, use `--vr-screen=united --qvr-config=two-screen-stereo.qvr`
390 for a two-screen stereo setup, where the left view goes on the first screen and
391 the right view goes on the second screen.
392
393 Bino uses QVRs default navigation, which may be based on autodetected
394 controllers such as the HTC Vive controllers, or on tracking and interaction
395 hardware configured via QVR for your VR system, or on the mouse and WASDQE keys
396 if nothing else is available.
397
398 Additional interaction in VR mode is currently limited to the same keyboard
399 shortcuts that also work in GUI mode. That means you currently must specify the
400 video to play on the command line, and have no way to pause, skip or seek with
401 VR controllers. This will be added in a future version.