01
Stateful by default
照明状態は一時的な OSC メッセージではなく store に保持される。active mode、palette、音響特徴量、transport health、fail-safe reason を明示的に管理する。
OSC / Hue Entertainment / Safety Fallback
Light Behaves Like a Runtime.
OSC をそのまま Hue に流さず、入力・状態・レンダリング・出力を分離したローカルエンジンで解釈する。音楽反応、持続的な自律モード、運用時の安全制御を一つの照明ランタイムにまとめた。
Why this exists
Hue の通常 REST 制御をリアルタイム照明の主経路にせず、同じ OSC ストリームから安定した見え方を再構成するための中間ランタイムとして設計している。
02
Self-running motion
`/mode/floating/start` のような単発トリガーだけで、OSC が止まっても内部アニメーションが継続する。Reactive だけに依存しないため、空間が破綻しにくい。
03
Transport-aware output
連続出力は Hue Entertainment を前提にし、成立しない場面では低頻度の REST fallback に切り替える。出力 path の能力差を runtime が吸収する。
04
Operable without hardware
simulator backend と WebUI により、実機がなくても OSC から render loop までを検証できる。現場前の開発と運用テストを分離できる。
Runtime architecture
構造は input、state、engine、output、ops に分けている。Hue は backend の一つとして扱い、今後の非 Hue transport 追加を妨げない。
Input
OSC receiver & router
Audio features、event triggers、mode controls を受けて、typed state update に正規化する。
- Continuous: rms / low / high / centroid / beatPhase
- One-shot: kick / snare / drop / scene_change
- Operator: blackout / restore / mode parameter updates
State
Persistent store
render loop が読む唯一の現在地。音が止まっても lighting intent が残るようにする。
- Modes: activeMode, params, cooldowns
- Audio: last features with timestamps
- Safety: watchdog, transport health, fallback reason
Engine
Mode manager & resolver
自律モーション、イベントアクセント、manual override を同じ frame に統合する。
- Generators: floating, drift, candle, underwater
- Smoothing: suppresses chatter and small fluctuations
- Priority: deterministic arbitration across layers
Output
Hue adapter & simulator
実機の有無に応じて backend を切り替えつつ、engine は同じ resolved frame を出力し続ける。
- Primary: Hue Entertainment streaming
- Fallback: rate-limited Local API V2 light updates
- Offline: browser simulator with per-fixture state view
01 Input
OSC Messages
Audio features, events, mode commands.
→
02 Normalize
Router
Aliases and payload typing are resolved once.
→
03 Persist
State Store
Current mode, features, timers, override flags.
→
04 Render
Priority Resolver
Deterministic frame output across competing layers.
Control model
runtime は明示的な優先順位で振る舞う。これにより、強い cue が入っても空間のベースモーションが崩れず、復帰先も predictable になる。
最上位。直ちに全出力を落とす。
OSC 停止や transport failure 時の安全な待避。
WebUI からの operator control。
展開転換の強い意図を優先する。
kick や drop の一時的な上書き。
floating などの持続モーション。
連続特徴量による穏やかな変調。
OSC Namespace
Continuous features and triggers
Audio stream は state update の材料であって、照明フレームそのものではない。
- /audio/* rms, low, lowMid, mid, high, centroid, beatPhase, tempo
- /event/* kick, snare, drop, breakdown, scene_change
- /mode/* start, stop, speed, depth, palette parameters
Autonomy
One-shot starts persistent motion
単発の mode start 後は engine が内部クロックで動き続ける。OSC loss 後も aggressive な freeze に落ちず、安全な ambient に戻れる。
- Floating: soft drift for general ambient fill
- Drift: slower minimal movement for long-form background
- Candle / Underwater: specialized motion families for texture shifts
Operation and testing
headless runtime を前提にしつつ、現場では WebUI、開発では simulator を使える。実機の有無で運用経路を分けても engine 本体は変わらない。
01
Startup validation
bridge、fixtures、transport availability を起動時に検証し、設定不整合を早期に露出させる。
- Bridge: Local API V2 auth and resource fetch
- Mapping: fixture names to Hue light IDs
- Fallback: REST path remains available when entertainment is not
02
Operator surface
WebUI では manual override、blackout、restore、floating speed などの現場操作を行える。manual override は watchdog に潰されない。
- Controls: color, brightness, blackout, restore, floating speed
- State view: active mode, fallback status, per-fixture summary
- Headless safe: all core operations also work without GUI
03
Offline verification
simulator backend を使うと、OSC -> engine -> output のパイプラインをブラウザ上で追える。実機がなくても見え方の検討と回帰確認が可能になる。
- Port: separate simulator HTTP endpoint
- Use: fixture hue, saturation, brightness monitoring
- Goal: test without hardware dependency
Testing Modes
Same engine, different outputs
`OUTPUT_BACKEND=simulator` では offline preview、通常起動では Hue output。backend だけ切り替えても state model と render loop は共通。
Default look
Floating as safe ambient baseline
起動時の既定 mode を floating にして、OSC が来なくても空間がふわふわと動く。静止した aggressive state に留まらない。
Documents and source
protocol、runtime architecture、運用手順、設定形状を文書化している。公開ページは要約だが、実装と運用は repo 内の文書とコードに紐づく。
Repository
Source code
TypeScript runtime, Hue adapter, simulator backend, WebUI, and operational tooling.
Docs
Design package
`TECHNICAL_DESIGN.md`、`OSC_SPEC.md`、`IMPLEMENTATION_PLAN.md`、`OPERATING_GUIDE.md` に architecture と運用判断を残している。
Configuration
Deployable runtime config
Hue bridge、entertainment area、fixture mapping、REST fallback rate、simulator、WebUI を YAML で定義できる。
Usage
Headless and operator workflows
CLI と WebUI の両方から mode start、blackout、restore、manual override を運用できる。