autocamlight 0.2.0

Automate your webcam light.

AutoCamLight

╔═══╗    ╖      ╔═══╕         ╖         ╖   ╖  
║   ║    ║      ║             ║    °    ║   ║  
╠═══╣╖  ╓╠═╛╔══╗║    ╒══╗╔═╦═╗║    ╖╔══╗╠══╗╠═╛
║   ║║  ║║  ║  ║║    ╔══╣║ ║ ║║    ║║  ║║  ║║  
╜   ╙╚══╝╚═╛╚══╝╚═══╛╚══╝╜ ╙ ╙╚═══╛╙╚══╣╜  ╙╚═╛
                                    ╓  ║  
AutoCamLight                        ╚══╝  

A small linux utility to automate your webcam light via Home Assistant.

Monitors /dev/video* and sends a state update to HA via MQTT when it detects that video is being captured.

Usage

Install, configure and run in the background.

After the first time the webcam is used, the device & entity will be created in Home Assistant, so you can set up your automations.

Install

Use of uv is highly recommended:

uv tool install autocamlight

Configure

Create a autocamlight.toml file in one of the following locations:

1. $XDG_CONFIG_HOME (or ~/.config if unset), or
2. $XDG_CONFIG_DIRS (or /etc/xdg if unset), read as a list of folder split by :, as per the XDG specification, or
3. the current working directory.

The files are read in the order they are listed, so you can override settings. But only top level keys can be overridden in their entirety, no table merging is performed.

Example configuration with some comments:

# Log level, one of: CRITICAL, ERROR, WARNING, INFO, DEBUG
log_level = "DEBUG"

# Time to wait for inotify events, in seconds.
# Longer times will reduce CPU usage, but will increase the delay and jitter of the state updates.
inotify_block_duration = 0.1

# Time to wait after before sending the state update, in seconds.
# If another event is received before this time, the timer is reset.
debounce_duration = 0.5

# MQTT settings from https://github.com/unixorn/ha-mqtt-discoverable
[mqtt]
host = "homeassistant.local"
username = "mqtt"
password = "Correct Horse Battery Staple"

# Entity settings from https://github.com/unixorn/ha-mqtt-discoverable
[entity]
name = "Webcam"
unique_id = "fe4bd497-7c2f-4f35-899f-f147f9f84738-capturing"

# Device settings from https://github.com/unixorn/ha-mqtt-discoverable
[entity.device]
name = "Webcam"
identifiers = "fe4bd497-7c2f-4f35-899f-f147f9f84738"

The file structure is dictated mostly by ha_mqtt_discoverable.

Auto-run on login

Create a new (user) unit file:

systemctl --user --force --full edit autocamlight

Add the following to the file, assuming uv is installed in /usr/bin:

[Unit]
Description=AutoCamLight
After=multi-user.target

[Service]
Type=simple
ExecStart=/usr/bin/uv tool run autocamlight
Restart=on-failure
RestartSec=5
Environment=PYTHONUNBUFFERED=1

[Install]
WantedBy=default.target

Now enable & start the unit:

systemctl --user enable autocamlight
systemctl --user start autocamlight

You can monitor the service status with:

systemctl --user status autocamlight
journalctl --user -u autocamlight -f

Test

Open any program that uses the webcam, e.g. Cheese.

If you have the logs open, an INFO message should appear. The entity should be created in Home Assistant.

Support the Project

If you find this project useful, a tip is always welcome via PayPal: