Bino 1.6.5

Next: , Up: (dir)   [Contents]

Bino

This manual was last updated 11 September 2014 for version 1.6.5 of Bino.

Copyright © 2011, 2012, 2013, 2014 Martin Lambers (marlam@marlam.de), Stefan Eilemann (eile@eyescale.ch), Frédéric Devernay (Frederic.Devernay@inrialpes.fr)

Copying and distribution of this file and the accompanying media files, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. These files are offered as-is, without any warranty.

Short Contents:

Table of Contents


Next: , Previous: , Up: Top   [Contents]

1 Introduction

Bino is a 3D video player with multi-display support.

3D videos are more accurately called stereoscopic videos. Such videos have separate views for the left and right eye and thus allow depth perception through stereopsis.

The left and right view of a stereoscopic video can be stored using different layouts. Sometimes the two views are stored as two separate video streams, but most often both views are packed into a single video stream and need to be unpacked by the video player. Bino supports all commonly used layouts. See Input Layouts.

To display a stereoscopic video, the left and right view have to be prepared in a special way so that the left eye sees the left view and the right eye sees the right view. Different display techniques use different approaches to achieve this separation of the two views. Bino supports a wide variety of such techniques. See Output Techniques.


Next: , Previous: , Up: Top   [Contents]

2 Invocation

This section describes the command line interface of Bino.

Synopsis: bino [option…] [file…]

Bino combines all input files into one media source which is then played. This means you can have video, audio, and subtitle streams in separate files. The files are decoded with the FFmpeg libraries, so URLs and other special constructs are supported.

--help

Print help.

--version

Print version.

-n
--no-gui

Do not use the GUI, just play the given input in a plain window using the parameters given on the command line.

--log-file=FILE

Append all log messages to the given file.

-L
--log-level=LEVEL

Select log level: debug, info, warning, error, or quiet.

--list-audio-devices

Print a list of known audio devices and exit.

-A
--audio-device=N

Use audio device number N. N=0 is the default device.

D
--audio-delay=D

Delay audio by D milliseconds. Default is 0.

-V
--audio-volume=V

Set audio volume (0 to 1). Default is 1.

-m
--audio-mute

Mute audio.

--device-type=TYPE

Type of input device: default, firewire, or x11.

--device-frame-size=WxH

If the input is a device, request the given frame size, e.g. 640x480.

--device-frame-rate=N/D

If the input is a device, request the given frame rate, e.g. 25/1.

--device-format=FORMAT

Request format default or mjpeg from device.

--read-commands=FILE

Read commands from file. See Scripting.

--lirc-config=FILE

Use the given LIRC configuration file. This option can be used more than once.

--quality=Q"

Set rendering quality, from 0 (fastest) to 4 (best, default).

-v
--video=STREAM

Select video stream (1-n, depending on the input).

-a
--audio=STREAM

Select audio stream (1-n, depending on the input).

-s
--subtitle=STREAM

Select subtitle stream (1-n, depending on the input).

-i
--input=TYPE

Select input layout. See Input Layouts.

-o
--output=TYPE

Select output technique. See Output Techniques.

-S
--swap-eyes

Swap left/right view.

-f
--fullscreen

Fullscreen.

--fullscreen-screens=[S0[,S1[,…]]]

Use the listed screens S0, …, Sn in fullscreen mode. Screen numbers start with 1. If the list is empty, the primary screen will be used (this is the default).

--fullscreen-flip-left

Flip left view vertically when in fullscreen mode.

--fullscreen-flop-left

Flop left view horizontally when in fullscreen mode.

--fullscreen-flip-right

Flip right view vertically when in fullscreen mode.

--fullscreen-flop-right

Flop right view horizontally when in fullscreen mode.

--fullscreen-3dr-sync

Use DLP® 3-D Ready Sync when in fullscreen mode.

-z
--zoom=Z

Set zoom for videos that are wider than the screen, from 0 (off; show full video width) to 1 (full; use full screen height). The default is 0.

-C
--crop=W:H

Crop the video to the given aspect ratio, to remove borders. 0:0 disables cropping.

-c
--center

Center window on screen.

--subtitle-encoding=ENC

Set subtitle encoding.

--subtitle-font=FONT

Set subtitle font name.

--subtitle-size=N

Set subtitle font size.

--subtitle-scale=S

Set subtitle scale factor.

--subtitle-color=COLOR

Set subtitle color, in [AA]RRGGBB format.

--subtitle-shadow=-1|0|1

Set subtitle shadow, -1=default, 0=off, 1=on.

--subtitle-parallax=VAL

Subtitle parallax adjustment (-1 to +1).

-P
--parallax=VAL

Parallax adjustment (-1 to +1).

--crosstalk=VAL

Crosstalk leak level (0 to 1). Comma-separated values for the R,G,B channels.

--ghostbust=VAL

Amount of crosstalk ghostbusting to apply (0 to 1).

-b
--benchmark

Benchmark mode: no audio, no time synchronization, output of frames-per-second measurements.

--swap-interval=D

Frame rate divisor relative to display refresh rate. The default is 0 for benchmark mode and 1 otherwise.

-l
--loop

Loop the input media.


Next: , Previous: , Up: Top   [Contents]

3 Input Layouts

3.1 Overview

The left and right view of a stereoscopic video can be stored using different layouts. Sometimes they are stored in separate files, sometimes in separate streams inside the same file, and often they are packed into a single video on top of each other or next to each other, with or without a reduction of resolution.

By default, Bino autodetects the input layout from meta data stored in the file (for example, the Matroska and WebM formats have a StereoMode field for that purpose). If no meta data is available, Bino tries to autodetect the input layout based on the file name. See File Name Conventions. If that fails, too, Bino guesses based on the resolution of the input.

3.2 Supported Input Layouts

mono

Single view (2D conventional video).
input-layout-mono

separate-left-right

Separate streams: left view first, right view second.
input-layout-separate-left-right

separate-right-left

Separate streams: right view first, left view second.
input-layout-separate-right-left

alternating-left-right

Alternating frames: left view first, right view second.
input-layout-alternating-left-right

alternating-right-left

Alternating frames: right view first, left view second.
input-layout-alternating-right-left

top-bottom

Single stream: left view top, right view bottom.
input-layout-top-bottom

top-bottom-half

Single stream: left view top, right view bottom, both with half height.
input-layout-top-bottom-half

bottom-top

Single stream: right view top, left view bottom.
input-layout-bottom-top

bottom-top-half

Single stream: right view top, left view bottom, both with half height.
input-layout-bottom-top-half

left-right

Single stream: left view left, right view right.
input-layout-left-right

left-right-half

Single stream: left view left, right view right, both with half width.
input-layout-left-right-half

right-left

Single stream: right view left, left view right.
input-layout-right-left

right-left-half

Single stream: right view left, left view right, both with half width.
input-layout-right-left-half

even-odd-rows

Single stream: left view in even rows, right view in odd rows.
input-layout-even-odd-rows

odd-even-rows

Single stream: right view in even rows, left view in odd rows.
input-layout-odd-even-rows

3.3 File Name Conventions

If the meta data stored in a file does not indicate the input layout, Bino tries to guess it by looking at the last part of the file name before the file name extension (.ext).

The following file name forms are recognized:

*-lr.ext

Input layout left-right.

*-lrh.ext
*-lrq.ext

Input layout left-right-half.

*-rl.ext

Input layout right-left.

*-rlh.ext
*-rlq.ext

Input layout right-left-half.

*-tb.ext
*-ab.ext

Input layout top-bottom.

*-tbh.ext
*-abq.ext

Input layout top-bottom-half.

*-bt.ext
*-ba.ext

Input layout bottom-top.

*-bth.ext
*-baq.ext

Input layout bottom-top-half.

*-eo.ext
*-eoq.ext
*-3dir.ext

Input layout even-odd-rows.

*-oe.ext
*-oeq.ext
*-3di.ext

Input layout odd-even-rows.

*-2d.ext

Input layout mono.


Next: , Previous: , Up: Top   [Contents]

4 Output Techniques

4.1 Overview

The left and right view of a stereoscopic video need to be displayed in a way that ensures that the left view is only seen by the left eye of the user and the right view is only seen by the right eye. There are many different techniques to achieve this separation of left and right view, and Bino supports most of them.

With some display techniques, some part of the right view may also seen by the left eye and vice versa. This is called crosstalk and leads to ghosting artefacts that reduce image quality. For some display types, Bino can reduce such artefacts. See Crosstalk Ghostbusting.

One of the simplest output techniques is anaglyph glasses. Such glasses use color filters to separate the left and right view. Anaglyph glasses are cheap and work with every display, but the view separation and color reproduction are of relatively low quality. Still, depending on the video material, Bino can achieve high quality results using the Dubois method to produce video output for anaglyph glasses.

With OpenGL, the default method to display stereoscopic 3D content is OpenGL quad buffered stereo, often used with active shutter glasses. However, graphics card manufacturers tend to enable this output technique only on expensive high end hardware.

Many 3D computer displays use polarized glasses to separate left and right view, and some autostereoscopic displays do not require any glasses at all. Most of these 3D computer displays expect left and right view packed in a single video frame, e.g. on top of each other or next to each other or partitioned into even and odd pixel lines or columns. Bino supports all variants of such modes; refer to the manual of your display to find out which mode is required.

Another common way to display 3D stereoscopic content is to use two conventional 2D displays or projectors for the left and right view and combine both views either using a half-transparent mirror, or a single screen with polarized glasses. This is supported in Bino using multiscreen output. See Basic Multi Display Support.

For more complex setups, such as powerwalls or virtual reality installations driven by render clusters, Bino supports distributed video rendering via Equalizer. See Advanced Multi Display Support.

The default output technique for stereoscopic 3D input is OpenGL quad buffered stereo if the graphics card supports it, otherwise red/cyan anaglyph glasses.

4.2 Supported Output Techniques

stereo

OpenGL quad-buffer stereo.
output-type-stereo

alternating

Left and right view alternating. This can be used for shutter glasses on systems that do not support OpenGL quad-buffer stereo, but note that this mode may be unreliable and may swap left/right eyes occasionally, depending on your system. In case of problems, disabling the fullscreen mode screensaver inhibition may help.
output-type-alternating

mono-left

Left view only.
output-type-mono-left

mono-right

Right view only.
output-type-mono-right

top-bottom

Left view top, right view bottom.
output-type-top-bottom

top-bottom-half

Left view top, right view bottom, both with half height.
output-type-top-bottom-half

left-right

Left view left, right view right.
output-type-left-right

left-right-half

Left view left, right view right, both with half width.
output-type-left-right-half

even-odd-rows

Left view in even rows, right view in odd rows.
output-type-even-odd-rows

even-odd-columns

Left view in even columns, right view in odd columns.
output-type-even-odd-columns

checkerboard

Left and right view in a checkerboard pattern.
output-type-checkerboard

hdmi-frame-pack

HDMI frame packing mode (left top, right bottom, plus extra blank lines separating the two views). This mode is only necessary if you are forcing your display into the corresponding HDMI 3D mode. A description how to do this on GNU/Linux can be found in this post to the Bino mailing list.
output-type-hdmi-frame-pack

red-cyan-monochrome

Red/cyan anaglyph glasses, monochrome method.
output-type-red-cyan

red-cyan-half-color

Red/cyan anaglyph glasses, half color method.
output-type-red-cyan

red-cyan-full-color

Red/cyan anaglyph glasses, full color method.
output-type-red-cyan

red-cyan-dubois

Red/cyan anaglyph glasses, high-quality Dubois method.
output-type-red-cyan

green-magenta-monochrome

Green/magenta anaglyph glasses, monochrome method.
output-type-green-magenta

green-magenta-half-color

Green/magenta anaglyph glasses, half color method.
output-type-green-magenta

green-magenta-full-color

Green/magenta anaglyph glasses, full color method.
output-type-green-magenta

green-magenta-dubois

Green/magenta anaglyph glasses, high-quality Dubois method.
output-type-green-magenta

amber-blue-monochrome

Amber/blue anaglyph glasses, monochrome method.
output-type-amber-blue

amber-blue-half-color

Amber/blue anaglyph glasses, half color method.
output-type-amber-blue

amber-blue-full-color

Amber/blue anaglyph glasses, full color method.
output-type-amber-blue

amber-blue-dubois

Amber/blue anaglyph glasses, high-quality Dubois method.
output-type-amber-blue

red-green-monochrome

Red/green anaglyph glasses, monochrome method.
output-type-red-green

red-blue-monochrome

Red/blue anaglyph glasses, monochrome method.
output-type-red-blue

equalizer

Multi-display OpenGL via Equalizer with a 2D canvas setup.

equalizer-3d

Multi-display OpenGL via Equalizer with a 3D screen setup.

4.3 Crosstalk Ghostbusting

Many stereoscopic display devices suffer from crosstalk between the left and right view. This results in ghosting artifacts that can degrade the viewing quality, depending on the video content.

Bino can optionally reduce the ghosting artifacts. For this, it needs two know

  1. the amount of crosstalk of your display device and
  2. the amount of ghostbusting that is adequate for the video you want to watch.

Please note that ghostbusting does not work with anaglyph glasses.

To measure the display crosstalk, do the following:

  1. Display the gamma-pattern-tb.png image and correct the display gamma settings according to the included instructions. You need to have correct gamma settings before measuring crosstalk.
  2. Display the crosstalk-pattern-tb.png image and determine the crosstalk levels using the included instructions.

You now have three crosstalk values for the red, green, and blue channels. You can now tell Bino about this using the --crosstalk option. For example, if you have measured 8% of crosstalk for red, 12% for green, and 10% for blue, use

$ bino --crosstalk 0.08,0.12,0.10

Once you know the crosstalk levels of your display device, you can set the amount of ghostbusting that Bino should apply using the --ghostbust option. This will vary depending on the content you want to watch. Movies with very dark scenes should be viewed with at least 50% ghostbusting (--ghostbust 0.5), whereas overall bright movies, where crosstalk is less disturbing, could be viewed with a lower level (e.g. --ghostbust 0.1).

To check if you crosstalk calibration is correct, display the crosstalk patterns with full ghostbusting, like this:

$ bino --crosstalk 0.08,0.12,0.10 --ghostbust 1.0 crosstalk-pattern-tb.png

The remaining crosstalk should optimally be 0%.

4.4 Basic Multi Display Support

For basic multi display support, Bino requires that all displays are connected to a single computer and are configured to display one large desktop. For such a setup, you can configure which screens Bino should use in fullscreen mode.

For example, if you have two projectors L and R that project onto a single screen with polarization filters, and you have configured your desktop to cover both projectors next to each other (LR), then you can configure fullscreen mode to use both projectors and select the left-right output technique.

For similar setups, it is sometimes useful to mirror either the left or the right view horizontally or vertically. This, too, can be configured in Bino’s fullscreen settings.

Of course, you can also combine multiple monitors to form one large display and use this with some other output technique, e.g. anaglyph glasses.

For more advanced setups, e.g. involving multiple computers and/or graphics cards or non-planar projection surfaces, you can use Bino’s advanced multi display support via Equalizer.

4.5 Advanced Multi Display Support

Bino supports distributed multi-display output via the Equalizer framework.

This is how it works:

4.5.1 Building Bino with Equalizer Support

First, install Equalizer 1.0 or later. See http://www.equalizergraphics.com/. Verify that it works by running the included eqHello example.

Then, build Bino with Equalizer support. The output of configure should contain the following line:

Equalizer: yes

Now you need an Equalizer configuration file for your display setup.

4.5.2 Configuring Equalizer and Starting Bino

Bino needs a two-dimensional Equalizer canvas (= combined screen area), subdivided into segments (= single display areas). For example, if you have two projectors that project onto a 2m x 1m screen side-by-side, then your canvas is 2m x 1m large, and you have two segments: the first segment fills the left half of the canvas, and the second segment fills the right half.

Next, Equalizer needs to know how to render into each segment. For this purpose, you define several hierarchical objects: nodes (= processes, possibly on different systems), pipes (= graphics cards), windows (= output windows with OpenGL contexts), and channels (= parts of windows). The video output happens at the channel level: each channel is assigned to one segment of the canvas. Most probably you just have one fullscreen window per pipe, and a single output channel per window.

Note that one node is special: the application node, which is the node that you initially start (the other nodes are started automatically by Equalizer). The application node is called ’appNode’ in the Equalizer configuration, and Bino will play audio only on the application node. All video output is then synchronized to this audio output.

Once you have your configuration file (examples are given below), you can check if it works correctly using the eqHello example:

$ eqHello --eq-config configuration.eqc

Once you made sure that this works, you can start Bino using this command:

$ bino -o equalizer --eq-config configuration.eqc video.mp4

Note that all your nodes need access to the video file using the same name, so a shared filesystem is helpful if you use multiple systems.

To play live video from a webcam or TV card, you can set up a streaming server using ffserver (part of FFmpeg) or vlc, and then give the appropriate URL to Bino. You can use multicast to stream the video to multiple systems efficiently.

The output mode -o equalizer-3d allows to configure non-planar projections. Bino projects the video onto a virtual screen in 3D space. The screen is located in the distance of the biggest front-facing segment, and sized to fill the wall optimally. By configuring the output segments accordingly, various advanced display configurations can be used, e.g. displays rotated around the Z axis by an arbitrary angle or non-planar screens.

4.5.3 Example Configurations

Simple 2D video output

In this example, you have a 2m x 1m screen and two projectors: one for the left half of the screen, and one for the right half. The two projectors are connected to two graphics cards on the same system.

In this situation, you have one node with two pipes, and each pipe has a fullscreen window with a single output channel. The first output channel is assigned to the left segment, and the second output channel is assigned to the right channel. The resulting configuration looks like this:

server
{
    config
    {
        appNode
        {
            pipe { device 0 window { attributes { hint_fullscreen ON } channel { name "left" }}}
            pipe { device 1 window { attributes { hint_fullscreen ON } channel { name "right" }}}
        }
        observer {}
        layout { view { observer 0 }}
        canvas
        {
            layout 0
            wall
            {
                bottom_left  [ 0.0  0.0 -1 ]
                bottom_right [ 2.0  0.0 -1 ]
                top_left     [ 0.0  1.0 -1 ]
            }
            segment { channel "left" viewport [ 0.0 0.0 0.5 1.0 ] }
            segment { channel "right" viewport [ 0.5 0.0 0.5 1.0 ] }
        }
        compound
        {
            compound { channel ( view 0 segment 0 ) swapbarrier {} }
            compound { channel ( view 0 segment 1 ) swapbarrier {} }
        }
    }
}

3D video output across multiple systems

In the following example, you have a 4m x 3m screen for 3D projection via passive stereo (e.g. polarization). You have two systems, "render1" and "render2", each equipped with two graphics cards. The two cards on "render1" generate two images for the left half of the screen: one for the left eye view and one for the right eye view. The two cards on "render2" generate left and right view for the right half of the screen. Additionally, you have a system called "master" which has a sound card and should display a small control window.

This setup is very similar to the situation shown in multi-display-vrlab.jpg.

The configuration looks like this:

server
{
    connection { hostname "master" }
    config
    {
        appNode
        {
            connection { hostname "master" }
            pipe { window { viewport [ 100 100 400 300 ] channel { name "control" }}}
        }
        node
        {
            connection { hostname "render1" }
            pipe { device 0 window { attributes { hint_fullscreen ON } channel { name "render1left" }}}
            pipe { device 1 window { attributes { hint_fullscreen ON } channel { name "render1right" }}}
        }
        node
        {
            connection { hostname "render2" }
            pipe { device 0 window { attributes { hint_fullscreen ON } channel { name "render2left" }}}
            pipe { device 1 window { attributes { hint_fullscreen ON } channel { name "render2right" }}}
        }
        observer {}
        layout { view { observer 0 }}
        canvas
        {
            layout 0
            wall
            {
                bottom_left  [ 0.0 0.0 -1 ]
                bottom_right [ 4.0 0.0 -1 ]
                top_left     [ 0.0 3.0 -1 ]
            }
            segment { channel "render1left"  viewport [ 0.0 0.0 0.5 1.0 ] }
            segment { channel "render1right" viewport [ 0.0 0.0 0.5 1.0 ] }
            segment { channel "render2left"  viewport [ 0.5 0.0 0.5 1.0 ] }
            segment { channel "render2right" viewport [ 0.5 0.0 0.5 1.0 ] }
            segment { channel "control"      viewport [ 0.0 0.0 1.0 1.0 ] }
        }
        compound
        {
            compound { eye [ LEFT  ] channel ( view 0 segment 0 ) swapbarrier {} }
            compound { eye [ RIGHT ] channel ( view 0 segment 1 ) swapbarrier {} }
            compound { eye [ LEFT  ] channel ( view 0 segment 2 ) swapbarrier {} }
            compound { eye [ RIGHT ] channel ( view 0 segment 3 ) swapbarrier {} }
            compound {               channel ( view 0 segment 4 ) swapbarrier {} }
        }
    }
}

Non-planar Displays

The -o equalizer-3d mode allows to set up arbitrary-oriented screens using either the wall-based or projection-based 3D frustum descriptions.

In this example we set up two 16:10 displays side-by-side which have been rotated around their Z axis by 1.3 degrees radians (~74 degrees). The image multi-display-rotated.jpg illustrates this setup. Other setups include distortion-correct projection for curved screens, or arbitrarily-placed screens in a 3D space.

First, we rotate a normally-aligned screen by 1.3 degrees and output the result:

eq::Matrix4f matrix(eq::Matrix4f::IDENTITY);
matrix.rotate(1.3f, eq::Vector3f::FORWARD);
wall.bottomLeft = matrix * wall.bottomLeft;
wall.bottomRight = matrix * wall.bottomRight;
wall.topLeft = matrix * wall.topLeft;
std::cout << wall << std::endl;

yields a rotated screen centered on the origin:

bottom_left  [   -0.69578     0.6371         -1 ]
bottom_right [   -0.26778    -0.9046         -1 ]
top_left     [    0.26778     0.9046         -1 ]

This screen has to be moved along the X-axis for the left and right screen by 0.5195m, which places the edges of the screen on the origin. The resulting wall descriptions are used for the left and right segment, as shown in the configuration below.

The configuration references two GPUs full-screen output. By changing the node resource section, the outputs may be mapped to two computers. When disabling the fullscreen mode and setting ’device 0’ for the second pipe, two windows simulate this setup on a single machine.

global
{
    EQ_WINDOW_IATTR_HINT_FULLSCREEN ON
}

server
{
    config
    {
        appNode
        {
            pipe
            {
                device 0
                window
                {
                    viewport [ .215 .5 .4 .4 ]
                    channel { name "channel1" }
                }
            }
            pipe
            {
                device 1
                window
                {
                    viewport [ .285 .1 .4 .4 ]
                    attributes{ hint_drawable window }
                    channel { name "channel2" }
                }
            }
        }

        layout { view{ }}
        canvas
        {
            layout   0

            segment
            {
                channel  "channel1"
                wall
                {
                    bottom_left  [   -1.21528     0.6371         -1 ]
                    bottom_right [   -0.78728    -0.9046         -1 ]
                    top_left     [   -0.25172     0.9046         -1 ]
                }
            }
            segment
            {
                channel  "channel2"
                wall
                {
                    bottom_left  [   -0.17628     0.6371         -1 ]
                    bottom_right [    0.25172    -0.9046         -1 ]
                    top_left     [    0.78728     0.9046         -1 ]
                }
            }
        }

        compound
        {
            compound
            {
                channel ( segment 0 )
                swapbarrier{}
            }
            compound
            {
                channel ( segment 1 )
                swapbarrier{}
            }
        }
    }
}

Next: , Previous: , Up: Top   [Contents]

5 Interactive Control

5.1 Keyboard Shortcuts

Bino reacts on a number of keyboard shortcuts during playback.

The following shortcuts are recognized:

ESC

Leave fullscreen mode, or quit when in window mode.

q

Quit.

p
SPACE

Pause / unpause.

f

Toggle fullscreen.

c

Center window.

e
F7

Swap left/right eye.

v

Cycle through available video streams.

a

Cycle through available audio streams.

s

Cycle through available subtitle streams.

1, 2

Adjust contrast.

3, 4

Adjust brightness.

5, 6

Adjust hue.

7, 8

Adjust saturation.

[, ]

Adjust parallax.

(, )

Adjust ghostbusting.

<, >

Adjust zoom for videos that are wider than the screen.

/, *

Adjust audio volume.

m

Toggle audio mute.

.

Step a single video frame forward.

LEFT, RIGHT

Seek 10 seconds backward / forward.

DOWN, UP

Seek 1 minute backward / forward.

PAGE DOWN, PAGE UP

Seek 10 minutes backward / forward.

Mouse click

Seek according to the horizontal click position.

"Media Keys"

Media keys (if available) should work as expected.

5.2 Remote Controls

Bino supports remote controls via LIRC.

Use the client name ‘bino’ in your LIRC configuration. The default LIRC configuration file usually is ~/.lircrc. You can use the ‘--lirc-config’ option to use one or more custom LIRC configuration files instead.

The available commands are the same commands that are available for scripting. See Script Commands.

Example LIRC configuration file excerpt:

begin
  remote = ...
  button = ...
  prog   = bino
  config = adjust-brightness +0.05
end

Next: , Previous: , Up: Top   [Contents]

6 Scripting

Bino can read commands from one or multiple script files. Use the ‘--read-commands’ option to specify script files.

Available script commands are listed below. See Script Commands.

A script file can be a standard text file, but it can also be a named pipe, which allows other programs or scripts to submit commands to Bino as they see fit.

$ mkfifo ~/bino-command-fifo
$ bino --read-commands ~/bino-command-fifo &

$ echo 'set-contrast 0.1' > ~/bino-command-fifo
$ ...

Using the ‘netcat’ utility, this also works over the network.

$ mkfifo ~/bino-command-fifo
$ bino --read-commands ~/bino-command-fifo &

$ nc -l 1234 > ~/bino-command-fifo &
$ telnet localhost 1234
set-contrast 0.1
...

Here is a simple example script file:

# Play all videos in fullscreen mode.
toggle-fullscreen
# Open the first video.
open /path/to/video.webm
# Start playing.
play
# Wait until the video finishes before continuing this script.
wait stop
# Open a second video. This one has a space in its file name.
open /path/to/video%20file.webm
# Start playing.
play
# Immediately increase brightness.
adjust-brightness +0.1
# Immediately seek to 60 seconds within the video.
seek 60.0
# Let the video play for 30.0 seconds before continuing with this script.
wait 30.0
# Open a third video. This one has left and right view in separate files.
open /path/to/left.webm /path/to/right.webm
# Start playing.
play

This script is executed with the following command. The ‘--no-gui’ option is not necessary, but prevents the GUI to remember the changed brightness setting in future sessions.

$ bino --read-commands /path/to/script.txt --no-gui

6.1 Script Commands

One script line defines exactly one script command. Empty lines or lines starting with the ‘#’ character are comment lines and define the ‘noop’ command, which has no effect.

noop

This command has no effect.

quit

Quit the application.

wait stop|seconds

Wait until the currently playing video stops, or wait for the given number of seconds, before processing more commands from this file, script, or FIFO.
(This command is not available for LIRC remote controls.)

open [option…] file

Open the given files.
You can use percent-encoding to encode special characters. See http://en.wikipedia.org/wiki/Percent_encoding. Use this if the file names contain whitespace.
To open devices, the following options are available, analogous to the command line options with the same name:

--device-type=none|default|firewire|x11
--device-frame-size=WxH
--device-frame-rate=N/D
--device-format=default|mjpeg
close

Close the currently opened input.

toggle-play

Toggle playback.

play

Start playback, or exit pause mode.

stop

Stop playback.

toggle-pause

Toggle pause mode.

pause

When playing, go into pause mode.

step

Single-step to the next video frame.

seek delta

Seek by the given number of seconds relative to the current position. For example -60.0 seeks backwards one minute, and +600.0 seeks forward ten minutes.

set-pos pos

Seek by setting an absolute position in the stream, with pos between 0 and 1. For example, to seek to the middle of the video, use 0.5.

set-audio-device dev

Set the audio device to the one with the given index.

set-quality q

Set rendering quality, from 0 (fastest) to 4 (best, default).

set-stereo-mode mode

Set the stereo mode. See Supported Output Techniques.

set-stereo-mode-swap swap

Set stereo mode left/right swap (on or off).

toggle-stereo-mode-swap

Toggle stereo mode left/right swap.

set-crosstalk cr cg cb

Set display crosstalk levels for red, green, and blue. Each value must be between 0 and 1.

set-fullscreen-screens screens

Set screens to use in fullscreen mode. The value is an integer in which bits are set for each screen that should be used (screen 1 = lowest bit). The value 0 means the default screen.

set-fullscreen-flip-left b

Set fullscreen flip left (on or off).

set-fullscreen-flop-leftb

Set fullscreen flop left (on or off).

set-fullscreen-flip-right b

Set fullscreen flip right (on or off).

set-fullscreen-flop-right b

Set fullscreen flop right (on or off).

set-fullscreen-inhibit-screensaver b

Set fullscreen inhibit screensaver (on or off).

set-fullscreen-3dr-sync b

Set fullscreen DLP® 3-D Ready Sync (on or off).

set-contrast value

Set contrast to the given value, from -1 to +1.

adjust-contrast delta

Adjust contrast by adding delta, e.g. -0.05 or +0.05.

set-brightness value

Set brightness to the given value, from -1 to +1.

adjust-brightness delta

Adjust brightness by adding delta, e.g. -0.05 or +0.05.

set-hue value

Set hue to the given value, from -1 to +1.

adjust-hue delta

Adjust hue by adding delta, e.g. -0.05 or +0.05.

set-saturation value

Set saturation to the given value, from -1 to +1.

adjust-saturation delta

Adjust saturation by adding delta, e.g. -0.05 or +0.05.

set-zoom value

Set zoom to the given value, from 0 to 1.

adjust-zoom delta

Adjust zoom by adding delta, e.g. -0.05 or +0.05.

set-loop-mode mode

Set loop mode to ‘off’ or ‘current’.

set-audio-delay milliseconds

Set audio delay.

set-subtitle-encoding enc

Set subtitle encoding. An empty value means to use the default.

set-subtitle-font font

Set subtitle font. An empty value means to use the default.

set-subtitle-size size

Set the subtitle font size. The value is an integer, e.g. 12. Use -1 to keep the default size.

set-subtitle-color color

Set the subtitle color as an integer that represents an RGB color. Use a value larger than UINT32_MAX to keep the default color.

set-subtitle-shadow mode

Set subtitle shadow to force-on (1), force-off (0), or default (-1).

set-video-stream stream

Set video stream. Stream numbers start with 0.

cycle-video-stream

Cycle through available video streams.

set-audio-stream stream

Set audio stream. Stream numbers start with 0.

cycle-audio-stream

Cycle through available audio streams.

set-subtitle-stream stream

Set subtitle stream. Stream numbers start with 0. Using -1 disables subtitles.

cycle-subtitle-stream

Cycle through available subtitle streams.

set-stereo-layout layout

Set stereo layout. See Supported Input Layouts. Note that here only the left first, right second modes are supported. To get the right first, left second modes, use ‘set-stereo-layout-swap’.

set-stereo-layout-swap b

Set stereo layout swap (on or off).

set-crop-aspect-ratio ar

Set crop aspect ratio, either as a floating point number (e.g. 1.78), or as a ratio (e.g. 16:9).

set-parallax value

Set parallax, from -1 to +1.

adjust-parallax delta

Adjust parallax by adding delta, e.g. -0.05 or + 0.05.

set-ghostbust value

Set ghostbust, from -1 to +1.

adjust-ghostbust delta

Adjust ghostbust by adding delta, e.g. -0.05 or + 0.05.

set-subtitle-parallax value

Set subtitle parallax, from -1 to +1.

adjust-subtitle-parallax delta

Adjust subtitle parallax by adding delta, e.g. -0.05 or + 0.05.

toggle-fullscreen

Toggle fullscreen.

center

Center window.

set-audio-volume value

Set audio volume, from 0 to 1.

adjust-audio-volume delta

Adjust audio volume by adding delta, e.g. -0.05 or +0.05.

toggle-audio-mute

Toggle audio mute.


Next: , Previous: , Up: Top   [Contents]

7 Camera Devices

Bino supports the following types of camera devices:

Note: for firewire and x11 devices to work, your FFmpeg libraries must have libdc1394 and x11grab support enabled.


Next: , Previous: , Up: Top   [Contents]

8 Audio/Video Synchronization

Bino uses OpenGL to display video, and OpenGL unfortunately does not provide a way to determine exactly when a frame will be visible on screen. On most systems, a frame is displayed almost immediately, but some systems introduce a delay, and this can cause notable audio/video synchronization errors. This effect may be aggravated by compositing window managers. See bug 35103 for more information.

You can check the audio/video synchronization on your system using the file audio-video-sync.mp4 (created on 12/18/2011 by S. Christian Collins). It contains a few bright flashes accompanied by "tick" sounds. The flashes and the sounds should be exactly in sync.

If they are not, you can adjust an audio delay that compensates for the video delay. Increase audio delay (e.g. in steps of 50 milliseconds) and replay the test video until audio and video are synchronized.


Previous: , Up: Top   [Contents]

9 Performance Tweaking

Bino should be able to play most video files on a computer with reasonable CPU and graphics power.

If Bino cannot play a video fast enough, it drops frames. Audio continues to play, but video begins to stutter or even to stop completely.

This can have to two causes: either your CPU cannot decode the video fast enough, or your graphics card cannot render the video fast enough.

In the first case, there is currently not much you can do.

In the second case, try the following to improve performance:

  1. Reduce the quality setting as far as necessary.
  2. Use a lower-quality anaglyph mode instead of the high-quality Dubois mode.
  3. Avoid color adjustments: set the contrast, brightness, hue, and saturation adjustments to 0.
  4. Avoid ghostbusting: set the ghostbusting parameter to 0.
  5. Disable subtitles.