Le Biniou - User's manual
Le Biniou is made of a set of plugins (nearly one hundred), that produce various graphic effects, depending on a source input (usually, your soundcard).
There are several types of plugins:
- Input plugins (sound inputs: OSS, ALSA, PulseAudio, ...)
- Drawing plugins (oscilloscopes, screensaver effects, ...)
- Filtering plugins (blurs, distortions, ...)
- Image plugins (that use a background image)
- Color plugins (modify the current colormap)
These plugins can be selected and organized in a particular order, forming "sequences".
Sequences can be created by the user (in the interactive mode), or by Le Biniou's Artificial Intelligence (in the automatic mode).
Le Biniou has an integrated On Screen Display (OSD), that shows you what's going on, and acts as a User Interface to select, organize or reorder plugins when you're in the interactive mode.
By default, Le Biniou starts in automatic mode, without OSD.
Le Biniou can randomly pick between many different colormaps and background images, allowing evolving rendering effects.
There are also three "auto-modes", that will randomly change the current sequence between user-defined and/or Le Biniou-generated ones.
Keyboard controls will be shown like this: "Hit the [SPACE] key".
Note: This is just a quickstart guide, for a full list of keyboard controls, please refer to the man page:
Starting Le Biniou
Le Biniou can be started by:
- the Applications/Multimedia menu
- using the command line
Using the command line, you can set specific options, like the display mode (window size, full-screen, etc.), the input source to use, which On Screen Display mode to activate, and more.
Please refer to the "Command line options" section for more informations.
Options can also be set with a user-defined configuration file.
Note: You can create a shortlink to your ~/.lebiniou folder, so it is easily accessible:
Essential keyboard controls
- Switch full-screen on/off using the [Ctrl-f] key
- Exit Le Biniou with [Shift-q]
- Exit Le Biniou, saving the current sequence with [Shift-x]. This sequence will be activated next time you start Le Biniou.
Note: Sequences are saved in your "~/.lebiniou/sequences/" folder.
- Take a screenshot with [Shift-PRINTSCREEN].
Note: Screenshots are saved in your "~/.lebiniou/screenshots/" folder.
- Switch the webcam on/off using [SPACE], set the reference image using [Ctrl-SPACE]
- Use [TAB] to use the next available webcam
When started, Le Biniou will create a new sequence regularly using it's Artificial Intelligence engine. Stop this mode by hitting [ESCAPE].
If the OSD is activated, a progress bar on the right will show you the time remaining until Le Biniou creates a new sequence.
- Use [Ctrl-BACKSPACE] to make the AI create a new sequence.
- Use [Ctrl-m] or [Shift-m] to switch between the different random modes:
- Select random user sequences
- Select random AI sequences
- Select random user and AI sequences
- Hit [Ctrl-l] to "lock" a plugin. When generating random sequences, Le Biniou will do it's best to include that plugin in new sequences. Use [Ctrl-l] again on the plugin to unlock it.
At some point, you may want to create your own sequences. We will show you how to do this with a complete example.
To create new sequences, it is recommended to set the OSD in full mode (so that you can see the sequence, the plugin list and their description), and of course to turn Automatic Mode off (using [ESCAPE]).
Essential keyboard controls
- Use [e]/[r] to cycle through the colormaps
- Use [t] to randomly pick one
- Use [Ctrl-t] to switch "random colormaps mode" on/off.
In this mode, Le Biniou will change colormaps every few seconds
- Show or hide the current colormap using [Alt-c]
- Use [y]/[u] to cycle through the images
- Use [i] to randomly pick one
- Use [Ctrl-i] to switch "random images mode" on/off.
In this mode, Le Biniou will change images every few seconds
Your first sequence
To start from the begining, use [Shift-z] to remove all the plugins, and [n] to clear the screen.
Note: In the top-left part of the OSD, the sequence will have the name "(none)".
- First, add a plugin: find the "rotors" plugin in the list and add it to the sequence.
- Use [UP]/[DOWN] to navigate through the list, and [RETURN] to add or remove the plugin.
- Use [PAGEUP]/[PAGEDOWN] to scroll faster in the list.
- Now, add a filtering effect: find the "blur2" plugin and add it. New plugins will be added at the end of the sequence (except a few plugins, like the "clear" plugin, that will be added at the front).
- Then, change the colormap (using the controls described before) to one that pleases you.
- Finally, add a plugin that reacts to the sound, for example, the "X oscillo stereo" plugin.
You can save your newly created sequence using [Ctrl-s] (will include colormaps and images information), or [Ctrl-Shift-s] (will only save the plugins list). From now on, the sequence will have a name (the timestamp you saved it), for example: "1300821622". It will be saved in your "~/.lebiniou/sequences/" folder under the name "1300821622.xml". Later, you can rename this file to a suitable name, e.g. "My cool sequence.xml". This new name will be displayed in the OSD.
You can update an existing sequence using [Ctrl-u] (full sequence), or [Ctrl-Shift-u] (only the plugins).
When you have several sequences, you can cycle through them using [Shift-LEFT] and [Shift-RIGHT], pick one at random using [BACKSPACE], and use them in the Automatic Mode. Use [Ctrl-p] to select the most recent sequence.
Reorganizing the sequence
You can change the plugins order in the sequence:
- Use [Shift-UP]/[Shift-DOWN] to select a plugin in the sequence (the selected plugin will have an arrow before it's name)
- Use [Ctrl-UP]/[Ctrl-DOWN] to move the selected plugin up/down in the sequence
Example sequences are available, install them by issuing the following command in your home directory:
Some plugins don't propagate their result to the next plugins, to avoid video-feedback. These are known as "lens plugins":
Some plugins (e.g.: cth_[xy]roller, taquin) give nice results when allowing them to video-feedback.
You can switch the "lens mode" on/off on any plugin with [Shift-l].
You can control how a plugin effects are melt with the previous one by controlling it's "layer mode" (think of merging layers in the GIMP):
There are 6 layer modes available:
- NOR (Normal): plugin works with defaults
- OVL (Overlay): pixels are added to the previous layer, if not null
- XOR (XOR): pixels are xored with the previous layer
- AVG (Average): takes the average of the layers
- RND (Random): takes pixels randomly between the layers (~50% of each will be chosen)
- --- (NULL): does nothing. pretty useless unless you want to disable a plugin without removing it from the sequence
Select the next layer mode using [Shift-y] or reset to it's default using [Alt-y]
You can permanently set options in a configuration file (~/.lebiniourc), install this file by issuing the following command:
This file is self-documented, and comes with suitable default values.
Using your own images
Images must be in PNG format, without comments (see below for how to strip them).
Images are organized as "themes", that is, by directory.
Put your images under ~/.lebiniou/images/<my_theme_name>.
Then start, using the "-t" switch with your theme name, prefixed with a "~":
Or a comma-separated list of themes:
Use the images from lebiniou-data package by removing the leading "~":
You can also set this in your ~/.lebiniourc configuration file. For example:
Themes = biniou,~theme1,~theme2
To remove comments from a PNG file
Assuming you have the "convert" command (from the ImageMagick package):
You can bind sequences, colormaps and images to the function keys to organize and quickly activate them. You are given 12 "banksets", each bankset contains 12 "banks" that can be mapped to sequences/colormaps/images.
- Select a bank mode:
- Sequences: [Ctrl-g]
- Colormaps: [Ctrl-h]
- Images: [Ctrl-j]
- Select a bankset using [Ctrl-F1]..[Ctrl-F12]
- Store the current sequence/colormap/image in a bank using [Shift-F1]..[Shift-F12]
- Recall a stored sequence/colormap/image from a bank using [F1]..[F12]
- Clear a bank using [Ctrl-Shift-F1]..[Ctrl-Shift-F12]
Note: Banks are not saved to disk until you use [Ctrl-b].
Note: They are stored in your "~/.lebiniou/banks.xml" file.
- Display the list of available input/output plugins with:
- Use "-i <INPUT>" to select the input plugin.
- Use "-o <OUTPUT>" to select the output plugin.
Some options can be configured through environment variables:
- Main application
- LEBINIOU_NO_BANNER: do not display the banner on startup
- LEBINIOU_WEBCAM: comma-separated list of options to pass to the webcam input:
- webcams: number of webcams to use (default: 1)
- device: path to the first webcam device (default: /dev/video)
- hflip: flip webcam horizontally
- vflip: flip webcam vertically
- LEBINIOU_SEED: set this to a (positive) number to initialize the random number generator.
- Video input plugin
- LEBINIOU_VIDEO: absolute path to a video to be played in loop. This can also be set in the configuration file.
- SDL2/OSD font
- LEBINIOU_FONT: absolute path to a .ttf font file
- LEBINIOU_FONT_SIZE: the font size
- JACKAudio input plugin
- sndfile input plugin
- LEBINIOU_SNDFILE: set the sample file to read
- LEBINIOU_SNDFILE_LOOP: loop the sample
- RTMP output plugin (experimental feature)
- libcaca output plugin
Some plugins (e.g.: the "galaxy" plugin) operate in 3D.
- Use [Alt-b] to display a bounding shape (cube, sphere, wired sphere, or none)
- Drag and drop the mouse to rotate the 3D view
- Use the mouse wheel to zoom in/out
- Hit [Alt-r] to toggle 3D rotations on/off
Making videos from your sessions
If you need sound, the easiest way to record is to use some a screen-recorder (e.g. SimpleScreenRecorder, vokoscreen).
Nevertheless, there are two output plugins you can use:
- mp4 plugin. This plugin will create a video in your "~/.lebiniou/videos/" folder.
Example: Assuming you have your track available in a format readable by libsndfile:
- diskwriter plugin (legacy). This plugin dumps all frames to your "~/.lebiniou/screenshots/" folder, so that you can reassemble them to a video using e.g. ffmpeg. Note: Dumping to disk may slow down your system. To avoid this, put the screenshots folder on a SSD drive, or a RAM-disk. Or better, use the more recent mp4 output plugin.
Miscellaneous keyboard controls
- [Shift-d], [Alt-d]: adjust the phase-space delay
- [Shift-s], [Alt-s]: adjust the spline span size
- [Shift-v], [Alt-v]: scale volume up/down
- [Ctrl-TAB]: freeze/unfreeze sound
- [Alt-m]: show/hide the mouse cursor
- [Shift-n]: fill screen with random pixels