Przejdź do treści
Biblioteka skilli
Inne · Budowanie i kod

xlights

/xlights

Tworzy, edytuje i renderuje sekwencje świateł xLights (.xsq) dla pokazów LED, z efektami, osią czasu i grupami modeli.

Repozytorium
xlights-skill ↗
Licencja
MIT
Ostatnia zmiana repozytorium
11.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
69
Skrypty
1
Komentarze HTML
2
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 11.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co sprawdzić przed instalacją
  • 1 skrypt w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
  • SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.

Skrypty: scripts/xsq.py

Co robi i kiedy

Tworzy, edytuje i renderuje sekwencje świateł xLights (.xsq) dla pokazów LED, z efektami, osią czasu i grupami modeli.

Oryginalny opis (EN)

Create, edit, inspect, validate and render xLights light-show sequences (.xsq) and show folders (xlights_rgbeffects.xml layout, xlights_networks.xml controllers, .xtiming, .fseq). Use for anything involving xLights, pixel/LED Christmas or Halloween displays, sequencing a song to lights or building non-musical looping animations, effects (Bars, Spirals, Color Wash, Twinkle, Singing Faces...), timing tracks, beats, lyrics, model groups and submodels, colour palettes for RGB pixels, gamma and dimming curves, value curves, layer blending, Falcon Player (FPP) uploads/playlists or xSchedule playback

Jak działa

  1. Golden rules
  2. Which reference to read
  3. The format in 60 seconds
  4. Helper script: scripts/xsq.py (Python 3.9+, stdlib only)
  5. Typical workflows
  6. Talking to users
Sekcje z nagłówków SKILL.md, w oryginale · 160 linii, 1 264 słów
Podgląd SKILL.md
---
name: xlights
description: Create, edit, inspect, validate and render xLights light-show sequences (.xsq) and show folders (xlights_rgbeffects.xml layout, xlights_networks.xml controllers, .xtiming, .fseq). Use for anything involving xLights, pixel/LED Christmas or Halloween displays, sequencing a song to lights or building non-musical looping animations, effects (Bars, Spirals, Color Wash, Twinkle, Singing Faces...), timing tracks, beats, lyrics, model groups and submodels, colour palettes for RGB pixels, gamma and dimming curves, value curves, layer blending, Falcon Player (FPP) uploads/playlists or xSchedule playback, or the xLights automation/REST/MCP API. Has the exact XML formats, a full per-effect setting-key reference, a Python helper to build and validate sequences, LED colour guidance, and design advice for beginners and experienced sequencers.
license: MIT
---

# xLights sequences and shows

xLights is a free sequencer for computer-controlled light displays. A **show folder** holds the layout
(models = props), controller config, and sequences. A **sequence** (`.xsq`, XML) places **effects** on
**models/groups** along a timeline. A sequence is either a **musical** sequence synced to a song via
**timing tracks**, or a **non-musical animation** (no audio) that usually loops all evening. Many
displays run only animations, so don't assume music. Ask. xLights **renders** each sequence to a `.fseq`,
which **Falcon Player (FPP)** (most common) or xSchedule plays on the lights.

## Golden rules

1. **Look before you write.** Read the layout first (`scripts/xsq.py layout SHOWDIR`). Model and group
   names in a sequence must match the layout **exactly**. Open an existing sequence with
   `scripts/xsq.py info FILE` before changing it.
2. **xLights must not have the file open.** xLights keeps the sequence and layout in memory and overwrites
   them on save. Ask the user to close the sequence (or xLights), or drive the running app through the
   automation API (`references/automation.md`).
3. **Back up first.** `Sequence.save()` writes a timestamped `*.agentbak` copy automatically. For the layout
   or networks XML, copy the file yourself. Never delete the user's `Backup/` or `.xbkp` files.
4. **Never hand-edit `.fseq`.** It's render output. Re-render instead.
5. **Validate after every edit**: `scripts/xsq.py validate FILE --show SHOWDIR` must report 0 errors.
   Then render (`scripts/xsq.py render FILE --show SHOWDIR`) if xLights is installed, and remind the user
   that the player only sees the `.fseq`: re-render, then re-upload to FPP (FPP Connect).
6. **Use the generated reference for setting keys**, never guessed names: `scripts/xsq.py effect NAME`
   or `references/effects/<Name>.md`. Wrong keys are silently ignored.
7. **Ask about hardware-affecting actions** (turning lights on, uploading to controllers, changing the
   show folder) before doing them.

## Which reference to read

| Task | Read |
|---|---|
| Understand or edit `.xsq` structure | `references/xsq-format.md` |
| Effect settings, palettes, value curves, layer blending, transitions, buffers | `references/effect-settings.md` |
| Keys/defaults/ranges for one effect | `references/effects/<Name>.md` (index: `references/effects/README.md`), or `xsq.py effect NAME` |
| Layout, models, groups, submodels, faces, states, controllers | `references/show-files.md` |
| Beats, timing tracks, lyrics/phonemes, `.xtiming` | `references/timing-and-lyrics.md` |
| Making it look good: planning, composition, layering recipes, workflow | `references/sequencing-guide.md` |
| Non-musical animations: looping ambient looks, seamless loops, rotating playlists | `references/animations-and-ambient.md` |
| Falcon Player: FPP Connect uploads, playlists, schedules, troubleshooting playback | `references/falcon-player.md` |
| Colour on real LEDs: RGB mixing, gamma, dimming, palettes that work on *their* lights | `references/color-and-leds.md` |
| Headless render, REST/xlDo commands, MCP server, Lua | `references/automation.md` |

## The format in 60 seconds

```xml
<xsequence ... FixedPointTiming="1" ModelBlending="true">
  <head> ... <sequenceTiming>50 ms</sequenceTiming> <mediaFile>Audio/song.mp3</mediaFile>
         <sequenceDuration>185.000</sequenceDuration> ... </head>
  <ColorPalettes><ColorPalette>C_BUTTON_Palette1=#FF0000,C_CHECKBOX_Palette1=1,...</ColorPalette></ColorPalettes>
  <EffectDB><Effect>E_CHOICE_Bars_Direction=up,E_SLIDER_Bars_BarCount=1,T_CHOICE_LayerMethod=Normal,...</Effect></EffectDB>
  <DataLayers>...Nutcracker...</DataLayers>
  <DisplayElements>                        <!-- rows; every ElementEffects element needs one -->
    <Element type="timing" name="Beats" visible="1" collapsed="0" views="Master View" active="1"/>
    <Element type="model"  name="Mega Tree" visible="1" collapsed="0"/>
  </DisplayElements>
  <ElementEffects>
    <Element type="timing" name="Beats"><EffectLayer><Effect label="" startTime="0" endTime="500"/>...</EffectLayer></Element>
    <Element type="model" name="Mega Tree">
      <EffectLayer>  <!-- layer 0 = TOP -->
        <Effect ref="0" name="Bars" startTime="0" endTime="5000" palette="0"/>
      </EffectLayer>
    </Element>
  </ElementEffects>
  <lastView>0</lastView><TimingTags>...10 Tag elements...</TimingTags>
</xsequence>
```

- Times are **integer ms**, multiples of the frame time, `start < end`, **no overlaps within a layer**.
- `ref` indexes `<EffectDB>` (E_/T_/B_ keys); `palette` indexes `<ColorPalettes>` (C_ keys). Append new
  entries and never renumber existing ones.
- Values escape `&`→`&amp;` then `,`→`&comma;` before XML escaping.
- `EffectDB`/`ColorPalettes`/`DisplayElements` must come **before** `ElementEffects` (single-pass loader).
- Layers composite bottom-up. An upper layer's `T_CHOICE_LayerMethod` mixes it over everything below.

## Helper script: `scripts/xsq.py` (Python 3.9+, stdlib only)

Run from the skill directory, or put `scripts/` on `sys.path` to import it.

```bash
python3 scripts/xsq.py layout   "/path/Show"                       # models, groups, submodels, faces
python3 scripts/xsq.py info     "/path/Show/Song.xsq" [-v]         # what's in a sequence
python3 scripts/xsq.py validate "/path/Show/Song.xsq" --show "/path/Show"
python3 scripts/xsq.py effect   Bars [--all]                       # keys, defaults, ranges, options
python3 scripts/xsq.py new      "/path/Show/New.xsq" --duration 185 --media Audio/song.mp3 --models "Mega Tree,Arches"
python3 scripts/xsq.py add-effect "/path/Show/New.xsq" --model "Mega Tree" --effect Spirals \
        --start 0 --end 8000 --layer 0 --set E_SLIDER_Spirals_Count=3 --colors "#FF0000,#FFFFFF"
python3 scripts/xsq.py add-timing "/path/Show/New.xsq" --name Beats --marks 0,500,1000,1500
python3 scripts/xsq.py vc Bars Bars_Cycles Ramp 10 50              # value-curve setting string
python3 scripts/xsq.py color-test "/path/Show/Color Test.xsq" --show "/path/Show" --colors "#FF3000,#6000FF,#FFB060"
python3 scripts/xsq.py render   "/path/Show/New.xsq" --show "/path/Show"   # headless render to .fseq
```

```python
import sys; sys.path.insert(0, "<skill>/scripts")
from xsq import Sequence, load_layout, value_curve

seq = Sequence.new(duration_s=185, frame_ms=50, media="Audio/song.mp3", song="...", artist="...")
# or: seq = Sequence.load("/path/Show/Song.xsq")
seq.add_timing("Beats", marks=[0, 476, 952, 1428])          # boundaries, or [(start, end, label), ...]
seq.add_timing("Lyrics", layers=[phrases, words, phonemes])  # lyric track (3 layers)
seq.add_model("Mega Tree")                                    # exact layout name (model or group)
k, v = value_curve("Bars", "Bars_Cycles", "Ramp", 10, 50)    # raw units: 1.0 -> 5.0 cycles
seq.add_effect("Mega Tree", "Bars", 0, 8000, layer=0,
               settings={"E_CHOICE_Bars_Direction": "down", k: v, "T_TEXTCTRL_Fadeout": "0.50"},
               colors=["#FF0000", "#00FF00"], palette={"C_SLIDER_Brightness": 60})
seq.add_effect("Arches", "On", 0, 500, submodel="Arch 1")    # SubModelEffectLayer
for fx in seq.iter_effects(): ...                            # decoded settings/palette per effect
seq.clear_effects("Mega Tree", layer=0, start=0, end=8000)
fx = next(f for f in seq.iter_effects() if f["model"] == "Arches" and f["name"] == "On")
seq.update_effect(fx["node"], settings={"T_TEXTCTRL_Fadeout": "1.00"}, end=6000)  # edit in place
seq.save("/path/Show/Song.xsq")                              # writes Song.<timestamp>.agentbak first
```

`add_effect` fills in the effect's full default settings (like xLights does), snaps times to the frame
grid, de-duplicates EffectDB/palette entries, and refuses overlaps. Effect names are case and space
tolerant (`colorwash` becomes `Color Wash`).

## Typical workflows

**New sequence for a song**: ask for the audio file, the props that matter, mood, and existing timing.
Read the layout. Create the sequence with `--media` and the real duration. Build timing tracks
(`timing-and-lyrics.md`). Plan sections and energy, then place base, feature, and accent layers
(`sequencing-guide.md`). Validate, render, and summarise what you made and what the user should review.

**New animation (no music)**: ask which props, the feel (calm, festive, spooky), the loop length, and
whether it'll rotate with other looks. `xsq.py new OUT --duration 60 --models ...` (no `--media` gives
`sequenceType` Animation). Build a base layer plus a texture spanning the whole loop with whole-number
cycle counts so it loops seamlessly (`animations-and-ambient.md`). Validate, render, and explain how to
add it to a repeating FPP playlist.

**Get it onto the lights**: render, then upload with FPP Connect (sequence, media for musical shows,
target playlist). Uploads affect live hardware, so describe what will be sent and let the user run it or
approve it (`falcon-player.md`).

**Edit an existing sequence**: `info` it, make targeted changes with `Sequence.load` + `update_effect` (change an
effect's settings in place) / `add_effect` / `clear_effects`, save (auto backup), validate, render.

**Fix a broken sequence**: `validate --show`, which reports missing models, bad refs, overlaps, bad timing
track references, unknown keys, and canvas mistakes. Fix the causes, not the symptoms. For renamed
models, rename the element in the sequence (both DisplayElements and ElementEffects) or add an
`oldname:` alias in the layout.

**Colours look wrong on the lights**: read `color-and-leds.md`. Build a `color-test` sequence, have the
user watch it on the real display at night, and tune palettes and gamma.

**Layout or controller changes**: prefer the xLights UI. If editing XML, follow `show-files.md`.

## Talking to users

- Many users are new. Explain terms briefly the first time (model, group, layer, timing track, render)
  and say what you changed in plain language: "Added a red/white Spirals on the Mega Tree for the first
  chorus (0:45–1:05), on top of the existing wash."
- Don't overpromise taste. Generated sequences are a starting point, so invite the user to watch and tweak.
- When unsure about something you can't see (how colours look on their pixels, which props are most
  visible from the street, whether timing feels right), ask.
- Experienced users want specifics: exact keys, layer methods, buffer styles, value-curve parameters.
  The references have them.
Pliki w paczce (69)
  • SKILL.md 11 KB
  • data/effects.json 265 KB
  • references/animations-and-ambient.md 5 KB
  • references/automation.md 6 KB
  • references/color-and-leds.md 10 KB
  • references/effect-settings.md 10 KB
  • references/falcon-player.md 5 KB
  • references/sequencing-guide.md 8 KB
  • references/show-files.md 7 KB
  • references/timing-and-lyrics.md 5 KB
  • references/xsq-format.md 10 KB
  • references/effects/Adjust.md 2 KB
  • references/effects/Bars.md 3 KB
  • references/effects/Butterfly.md 1 KB
  • references/effects/Candle.md 1 KB
  • references/effects/Circles.md 2 KB
  • references/effects/ColorWash.md 1 KB
  • references/effects/Curtain.md 1 KB
  • references/effects/DMX.md 8 KB
  • references/effects/Duplicate.md 1 KB
  • references/effects/Faces.md 6 KB
  • references/effects/Fan.md 4 KB
  • references/effects/Fill.md 2 KB
  • references/effects/Fire.md 2 KB
  • references/effects/Fireworks.md 3 KB
  • references/effects/Galaxy.md 3 KB
  • references/effects/Garlands.md 1 KB
  • references/effects/Glediator.md 1 KB
  • references/effects/Guitar.md 2 KB
  • references/effects/Kaleidoscope.md 2 KB
  • references/effects/Life.md 1 KB
  • references/effects/Lightning.md 2 KB
  • references/effects/Lines.md 1 KB
  • references/effects/Liquid.md 9 KB
  • references/effects/Marquee.md 3 KB
  • references/effects/Meteors.md 3 KB
  • references/effects/Morph.md 5 KB
  • references/effects/MovingHead.md 7 KB
  • references/effects/MusicEffect.md 2 KB
  • references/effects/Off.md 1 KB
  • references/effects/On.md 1 KB
  • references/effects/Piano.md 2 KB
  • references/effects/Pictures.md 4 KB
  • references/effects/Pinwheel.md 3 KB
  • references/effects/Plasma.md 1 KB
  • references/effects/README.md 2 KB
  • references/effects/Ripple.md 6 KB
  • references/effects/Servo.md 2 KB
  • references/effects/Shader.md 2 KB
  • references/effects/Shape.md 6 KB
  • references/effects/Shimmer.md 1 KB
  • references/effects/Shockwave.md 3 KB
  • references/effects/SingleStrand.md 5 KB
  • references/effects/Sketch.md 2 KB
  • references/effects/Snowflakes.md 1 KB
  • references/effects/Snowstorm.md 1 KB
  • references/effects/Spirals.md 2 KB
  • references/effects/Spirograph.md 2 KB
  • references/effects/State.md 2 KB
  • references/effects/Strobe.md 1 KB
  • references/effects/Tendril.md 3 KB
  • references/effects/Text.md 4 KB
  • references/effects/Tree.md 1 KB
  • references/effects/Twinkle.md 1 KB
  • references/effects/VUMeter.md 7 KB
  • references/effects/Video.md 4 KB
  • references/effects/Warp.md 2 KB
  • references/effects/Wave.md 2 KB
  • scripts/xsq.py 44 KB

Wersje

W bazie nie ma innych skilli o nazwie xlights.

Migawka bazy z 13.11.2026 · wersja paczki 2dbbacc18859 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95xlights-skill
    Projektuje sekwencje świateł xLights z piosenki: dzieli utwór na instrumenty, znajduje rytm i strukturę, a potem układa efekty świetlne.
  • 100xlights-sequencing-skill
    Układa sekwencję świateł do piosenki w xLights z właścicielem pokazu: analiza audio, okna czasowe, walidacja i zatwierdzanie zmian.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.