Boblightd is a daemon that controls lights based on input from clients over udp, it supports three rs232 based protocols, it can output a pwm signal with a soundcard (using alsa) and it can open a program with popen() for easy implementation of custom protocols.

Clients connect to boblightd over udp, then request lights configuration, send their own configuration etc. Each client can set their own parameters for each light, whether it wants to use it etc. Also every client sends a priority, boblightd chooses which client controls each light based on priority, whether the client wants to control the light and how long the client has been connected.
The priority can be anything from 0 to 255, where 0 is the highest priority and 255 is the lowest priority.

Its default configuration file is /etc/boblight.conf (or boblight.conf in the current directory for windows), you can select a different configuration file with the -c flag.
Since boblight 1.3, it's possible to set realtime priority on both windows and linux using the -r or --realtime flag.

Configuring boblight
The configuration file is divided into 4 sections, global, device, color and light.

[global] section
The global section has 11 parameters:

interface

Interface to bind the udp socket to, only ip addresses will work at the moment, sorry
if you don't specify this parameter, boblightd will bind to all interfaces.
Example: interface 127.0.0.1

port

Port to bind the udp socket to, if you don't specify this parameter, boblightd will bind to port 19333.
Example: port 19333

timeout

Timeout for the clients, if you don't specify this parameter, boblightd will use a timeout of 20 seconds.
Example: timeout 20

interpolation (added since boblight 1.2)

Global setting for interpolation, set to 1 to turn it on, set to 0 to turn it off. This parameter is optional, the default is 1.
In boblight 1.3, this is changed to "interpolation on" or "interpolation off"
Example: interpolation on

proportional (added since boblight 1.2)

Global setting for proportional, the range is from 0.0 to 100.0. This parameter is optional, the default is 100.0.
Example: proportional 5.0

saturation (added since boblight 1.2)

Global setting for saturation, the range starts at 0.0. This parameter is optional, the default is 1.0.
Example: saturation 3.0

value (added since boblight 1.2)

Global setting for value, the range starts at 0.0. This parameter is optional, the default is 1.0.
Example: value 3.0

valuerange (added since boblight 1.2)

Global setting for valuerange. This parameter is optional, the default is 0.0-1.0.
Example: valuerange 0.0 1.0

method (added since boblight 1.2)

Global setting for method, valid parameters are average and median. This parameter is optional, the default is average.
Example: method average

use (added since boblight 1.2)

Global setting for use, valid parameters are 0 and 1. This parameter is optional, the default is 1.
In boblight 1.3, this is changes to "use yes" or "use no". Example: use yes

threshold (added since boblight 1.3)

Global setting for threshold, range is from 0 to 255. This parameter is optional, the default is 0.
Example: threshold 20

A global section can look like this:

[global]
timeout 20
interface 127.0.0.1
port 19333
interpolation on
proportional 5.0
saturation 3.0
value 10.0
valuerange 0.0 1.0
method median
use yes
threshold 20


[device] section
A device section has 9 parameters:

name

Name of the device, this parameter is mandatory and must be unique.
Example: name ambilight

type

Type of the device, this parameter is mandatory and must be either LTBL, momo, atmo (since boblight 1.2), popen or sound. Check out devices explained
Example: type momo

output

Where the device has it's output, this parameter is mandatory and must be in between " ", this is a serial port for LTBL, atmo and momo, an alsa device for sound and an executable for popen.
Examples:
output "/dev/ttyS0"
output "surround51"
output "dd bs=109"

rate

The baudrate for the serial port or the sample rate for the soundcard, this parameter is mandatory for LTBL, momo, atmo and sound devices.
Example: rate 38400

channels

Number of channels the device has, this parameter is mandatory.
Example: channels 12

interval

The interval in microseconds for sending new values to the device, this parameter is mandatory for LTBL, momo, atmo and popen devices, a good value seems to be 20000 for an update rate of 50 hertz.
Example: interval 20000

prefix

Prefix for momo and atmo devices, this parameter is optional. You can specify a single byte to be sent before the channel bytes, this helps keeping things in sync. The prefix byte is specified in hex notation. If this parameter is not specified, no prefix is used.
Example: prefix FF

period

Period size, this parameter is mandatory for sound devices. A good value seems to be 1024, this makes the update rate 46.875 hertz for a samplerate of 48000.
Example: period 1024

buffer

Buffer size, this parameter is mandatory for sound devices. A good value seems to be 2048 for my audigy, this gives a delay of 21.3 ms for a samplerate of 48000, you could try lower values for a smaller delay. I have no idea what soundcards allow what buffer size
Example: buffer 2048

A device section can look like this:

[device]
name ambilight
type momo
output "/dev/ttyACM0"
rate 19200
channels 12
interval 20000
prefix FF

Or like this:

[device]
name ambilight
type popen
output "dd bs=109"
channels 12
interval 50000

Or like this:

[device]
name ambilight
type sound
output "surround51"
rate 48000
channels 6
period 1024
buffer 1024

Or like this:

[device]
name ambilight
type LTBL
output "/dev/ttyS0"
rate 38400
channels 12
interval 20000

Or like this:

[device]
name ambilight
type atmo
output "/dev/ttyS0"
rate 38400
channels 15
interval 20000
prefix FF


[color] section
A color section has 5 parameters:

name

Name of the color, this parameter is mandatory and must be unique
Example: name red

rgb

RGB value of the color, this is in hex notation, for example red is FF0000, green is 00FF00 and blue is 0000FF. This way you can specify any color you want. This parameter is mandatory.
Example: color FF0000

gamma

Gamma adjustment, can be anything from 0.0 to inifinity, this parameter is optional
Example: gamma 1.0

adjust

Final adjustment value, can be anything from 0.0 to 1.0, this parameter is optional. If you want to adjust single colors, it's better to adjust the rgb value.
Example: adjust 1.0

blacklevel

Minimal value of the color, this is useful for incandescent light to increase longevity, for leds or ccfl's just set it to 0.0 .
Example: blacklevel 0.0

A color section can look like this:

[color]
name red
rgb FF0000
gamma 1.0
adjust 1.0
blacklevel 0.0

Or like this:

[color]
name purplishgray
rgb 9F7F9F
gamma 1.0
adjust 1.0
blacklevel 0.0

Or like this:

[color]
name crappywhiteled
rgb 101010
gamma 1.0
adjust 1.0
blacklevel 0.0


[light] section
A light section has 12 parameters:

name

Name of the light, this parameter is mandatory and must be unique.
Example: name left

color

A color that this light uses, the syntax is color colorname devicename devicechannel, you can add as many colors as the light has. Make sure the color and device this light uses are defined above the light section.
Example: color red ambilight 2

interpolation

Specifies if this light uses interpolation, this parameter is optional, set to 1 for interpolation or 0 for no interpolation, if the parameter is not given the global setting for interpolation is used.
In boblight 1.3, this is changed to "interpolation on" or "interpolation off"
Example: interpolation on

hscan

Horizontal scanrange in percentages, this parameter is mandatory, syntax is hscan start end.
Example: hscan 0 50

vscan

Vertical scanrange in percentages, this parameter is mandatory, syntax is vscan start end.
Example: vscan 0 100

proportional

Proportional adjustment, this parameter is optional, can be anything from 0.0 to 100.0.
This makes the light react slower, it creates a very nice effect. When using an interval of 20000 a proportional value of 5.0 seems to be nice. Since boblight 1.2 the lights react at the same speed for a given proportional, no matter what the interval is. When this parameter is not given the global setting for proportional is used.
Example: proportional 5.0

saturation

Saturation multiplier, this parameter is optional, this enhances colors, a value of 3 seems to be nice. When not given the global parameter for saturation is used.
Example: saturation 3.0

value

Value multiplier, this parameter is optionnal, it helps to prevent flickering, a value of 10.0 seems to be nice. When not given the global parameter for value is used.
Example: value 10.0

valuerange

Value range adjustment, this parameter is optional, the value is clamped between this range. When not given the global parameter for valuerange is used.
Example: valuerange 0.0 1.0

use

Whether this light is used by default, this parameter is optional, set to 1 to use the light, set to 0 not to use it, when not given the global parameter for use is used.
In boblight 1.3, this is changed to "use yes" or "use no"
Example: use yes

method (added since boblight 1.2)

Method for scanning clients like boblight-X11 and boblight-v4l, valid parameters are average and median. When not given the global parameter for method is used. The average method takes the average color of the screen, the median method sort of takes the most occurring hue of the screen, it doesn't work that well though.
Example: method average

threshold (added since boblight 1.3)

Setting for threshold, range is from 0 to 255. This parameter is optional, the default is 0.
This setting affects scanning clients like boblight-X11 and boblight-v4l, whenever all subpixels of a pixel are below this value, the pixel is treated as a black pixel, a good value seems to be 20.
Example: threshold 20

A light section can look like this:

[light]
name left
color red ambilight 2
color green ambilight 4
color blue ambilight 6
hscan 0 50
vscan 0 100

Or like this:

[light]
name right
color red ambilight 1
color green ambilight 3
color blue ambilight 5
interpolation on
hscan 50 100
vscan 0 100
proportional 5.0
saturation 3.0
value 10.0
valuerange 0.0 1.0
use yes
threshold 20


Example configuration file:


[global]
timeout 20
interface 127.0.0.1
port 19333

[device]
name ambilight
type momo
output "/dev/ttyACM0"
rate 19200
channels 12
interval 20000
prefix FF

[color]
name red
rgb FF0000
gamma 1.0
adjust 1.0
blacklevel 0.0

[color]
name green
rgb 00FF00
gamma 1.0
adjust 1.0
blacklevel 0.0

[color]
name blue
rgb 0000FF
gamma 1.0
adjust 1.0
blacklevel 0.0

[light]
name left
color red ambilight 2
color green ambilight 4
color blue ambilight 6
interpolation on
hscan 0 100
vscan 0 100
proportional 5.0
saturation 3.0
value 10.0
valuerange 0.0 1.0
use yes
threshold 20

[light]
name right
color red ambilight 1
color green ambilight 3
color blue ambilight 5
interpolation on
hscan 0 100
vscan 0 100
proportional 5.0
saturation 3.0
value 10.0
valuerange 0.0 1.0
use yes
threshold 20