alexei.dolgolyov/wled-screen-controller-mixed

Files

Lint & Test / test (push) Has been cancelled

Details

feat: asset-based image/video sources, notification sounds, UI improvements

- Replace URL-based image_source/url fields with image_asset_id/video_asset_id
  on StaticImagePictureSource and VideoCaptureSource (clean break, no migration)
- Resolve asset IDs to file paths at runtime via AssetStore.get_file_path()
- Add EntitySelect asset pickers for image/video in stream editor modal
- Add notification sound configuration (global sound + per-app overrides)
- Unify per-app color and sound overrides into single "Per-App Overrides" section
- Persist notification history between server restarts
- Add asset management system (upload, edit, delete, soft-delete)
- Replace emoji buttons with SVG icons throughout UI
- Various backend improvements: SQLite stores, auth, backup, MQTT, webhooks

2026-03-26 20:40:25 +03:00

3.0 KiB

Raw Blame History

Claude Instructions for WLED Screen Controller Server

Project Structure

src/wled_controller/main.py — FastAPI application entry point
src/wled_controller/api/routes/ — REST API endpoints (one file per entity)
src/wled_controller/api/schemas/ — Pydantic request/response models (one file per entity)
src/wled_controller/core/ — Core business logic (capture, devices, audio, processing, automations)
src/wled_controller/storage/ — Data models (dataclasses) and JSON persistence stores
src/wled_controller/utils/ — Utility functions (logging, monitor detection, SSRF validation, sound playback)
src/wled_controller/static/ — Frontend files (TypeScript, CSS, locales)
src/wled_controller/templates/ — Jinja2 HTML templates
config/ — Configuration files (YAML)
data/ — Runtime data (JSON stores, persisted state)

Entity & Storage Pattern

Each entity follows: dataclass model (storage/) + JSON store (storage/*_store.py) + Pydantic schemas (api/schemas/) + routes (api/routes/).

Authentication

Server uses API key authentication via Bearer token in Authorization header.

Config: config/default_config.yaml under auth.api_keys
Env var: WLED_AUTH__API_KEYS
When api_keys is empty (default), auth is disabled — all endpoints are open
To enable auth, add key entries (e.g. dev: "your-secret-key")

Common Tasks

Adding a new API endpoint

Create route file in api/routes/
Define request/response schemas in api/schemas/
Register the router in main.py
Restart the server
Test via /docs (Swagger UI)

Adding a new field to existing API

Update Pydantic schema in api/schemas/
Update corresponding dataclass in storage/
Update backend logic to populate the field
Restart the server
Update frontend to display the new field
Rebuild bundle: cd server && npm run build

Adding translations

Add keys to static/locales/en.json, static/locales/ru.json, and static/locales/zh.json
Add data-i18n attributes to HTML elements in templates/
Use t('key') in TypeScript modules (static/js/)
No server restart needed (frontend only), but rebuild bundle if JS changed

Modifying display/monitor detection

Update functions in utils/monitor_names.py or core/screen_capture.py
Restart the server
Test with GET /api/v1/config/displays

Testing

cd server && pytest                    # Run all tests
cd server && pytest --cov              # With coverage report
cd server && pytest tests/test_api.py  # Single test file

Tests are in server/tests/. Config in pyproject.toml under [tool.pytest].

Frontend Conventions

For all frontend conventions (CSS variables, UI patterns, modals, localization, icons, bundling), see contexts/frontend.md.

Server Operations

For restart procedures, server modes, and demo mode checklist, see contexts/server-operations.md.

3.0 KiB Raw Blame History