Kasa Bulbs Control & Sync

A unified tool for controlling TP-Link Kasa smart bulbs. It provides two main modes:

1. Sync: Real-time synchronization of bulbs to an RTMP video stream (for ambient lighting).
2. Bulb: One-shot control to set bulbs to specific colors or states.

Installation

cargo build --release
# Binary is at target/release/kasa-rs

Usage

1. Set Mode (One-Shot Control)

Set one or multiple bulbs to a specific state. You can mix global defaults with specific overrides.

Syntax: kasa-rs bulb [OPTIONS] TARGETS...

Where TARGET is IP or IP:KEY=VALUE,KEY=VALUE...

Supported Keys:

• h or hue: 0-360 (Color)
• s or sat: 0-100 (Richness)
• v or val or bri: 0-100 (Brightness)
• on: Turn bulb on
• off: Turn bulb off

Examples:

Turn all bulbs red:

kasa-rs bulb --hue 0 --sat 100 --val 100 192.168.1.50 192.168.1.51

Turn one green and one blue:

kasa-rs bulb 192.168.1.50:h=120,s=100,v=100 192.168.1.51:h=240,s=100,v=100

Set a default brightness but override color for specific bulbs:

kasa-rs bulb --val 50 192.168.1.50:h=0 192.168.1.51:h=120

Turn off one bulb and dim another:

kasa-rs bulb 192.168.1.50:off 192.168.1.51:v=10

2. Sync Mode (Ambient Lighting)

Syncs bulbs to an audio/video stream. Requires ffmpeg installed.

Syntax: kasa-rs sync [OPTIONS] --bulbs IP:SCALE ...

Example:

kasa-rs sync \
  --source rtmp://localhost/live/stream \
  --mode ambient \
  --bulbs 192.168.1.50:1.0 192.168.1.51:0.5

Scene color knobs

The sync command now exposes tools to tame how each frame is reduced to a single color:

• --color-mode <average|median|dominant|brightest> chooses whether the HSV comes from the weighted average, the per-channel median, the dominant hue bin, or the brightest pixel in the frame.
• --scene-saturation-boost <0.0-1.0> lifts the computed saturation so dim scenes stay colorful.
• --scene-brightness-floor <0.0-1.0> keeps the light from collapsing to black during very dark shots.
• --scene-dark-threshold <0.0-1.0> tells the analyzer when a frame counts as a "dark scene," while --scene-dark-scale <0.0-1.0> scales the final brightness so those scenes stay moody rather than flickering to green.

---

Understanding HSV vs. Brightness

Smart bulbs generally work in the HSV color model. It's often clearer than RGB for lighting control.

Hue (H) - The "Color"

• Range: 0 to 360 degrees.
• Represents the pigment of the color.
• Examples:
  • 0 = Red
  • 120 = Green
  • 240 = Blue
  • 60 = Yellow
  • 300 = Magenta

Saturation (S) - The "Richness"

• Range: 0 to 100%.
• Represents how "pure" the color is versus how "washed out" (white) it is.
• Examples:
  • 100% = Pure, deep color (e.g., Neon Red).
  • 50% = Pastel color (e.g., Pink).
  • 0% = White/Gray (no color).

Value (V) - The "Brightness"

• Range: 0 to 100%.
• Represents the intensity of the light emitted.
• Also known as: Brightness.
• Note: In this tool, val, bri, and v are synonyms.
• Examples:
  • 100% = Full brightness.
  • 10% = Dim night light.
  • 0% = Off (Black).

Common Scenarios

"I just want to dim the lights" Keep Hue and Saturation as is (or don't specify them if partial updates are supported/defaults used) and reduce Value. kasa-rs bulb 192.168.1.50:v=20

"I want warm white light" Set Hue to Orange/Yellow (~30-40), Saturation to a low value (~10-20), and Value to taste. kasa-rs bulb 192.168.1.50:h=35,s=15,v=80

"I want pure white" Set Saturation to 0. Hue doesn't matter (usually). kasa-rs bulb 192.168.1.50:s=0,v=100