Příručka uživatele

Aktuální vydání CueX

1. Co je CueX a jak přemýšlí

CueX je editor a simulátor show pro instalace řízené show-controllerem (světla DMX, video player BrightSign, projektory, větráky). Pracuješ v něm bez hardwaru — všechno vidíš v simulaci — a do reálu pak nasazuješ přes Deploy sheet (checklist) a sACN record (nahrání světel do S-Play).

Hierarchie dat:

PROJEKT  (soubor .json — všechno v jednom)
 ├─ ZAŘÍZENÍ    světla, video player, projektor, větráky + DMX patch
 ├─ PLOCHY      projekční okna na stage (kam se kreslí video)
 ├─ TRIGGERY    VSTUPY — co show spouští zvenku (OSC / UDP / GPI)
 └─ PLAYLISTY   každý = jedna timeline
     ├─ STOPY   řádky timeline, každá patří jednomu zařízení (nebo skupině)
     │   ├─ obálková stopa (envelope) → plynulé hodnoty: barva, jas, rychlost
     │   │   ├─ KEYFRAMY   body, mezi nimiž se hodnota plynule přelévá
     │   │   └─ FX         efekty navrch (vlnění, blikání, pulz) — kap. 7
     │   └─ eventová stopa (event) → jednorázové povely: diamanty
     │       (např. PLAY_LEGENDA pro BrightSign v čase 0:00.2)
     └─ MARKERY pojmenované značky (C01, C02…) pro orientaci a rychlý skok

2. Hlavní obrazovka

┌──────────────────────────────────────────────────────────────────┐
│ HEADER   logo · ▶Play ■ ⟲ ⟳ · timecode · ●LIVE ⬤GPI               │
│          Výstupy · Media ▾ · Zobrazení ▾ · Projekt ▾              │
├────────────┬─────────────────────────────────────────────────────┤
│ ZAŘÍZENÍ   │  STAGE — náhled sálu: projekce, světla, větráky     │
│ (levý rail)│                                                     │
├────────────┴─────────────────────────────────────────────────────┤
│ TIMELINE — taby playlistů · pravítko s markery · stopy           │
├──────────────────────────────────────────────────────────────────┤
│ FOOTER — stav, universe, autosave čas, nápověda zkratek          │
└──────────────────────────────────────────────────────────────────┘

3. Přehrávání: Play × LIVE

Přehrávací tlačítka:

■ Stop zastaví přehrávání a vrátí playhead na začátek. ⟲ / ⟳ = Zpět / Znovu (Ctrl+Z / Ctrl+Shift+Z), až 50 kroků.

Pro připojení k CueX Boxu klikni na indikátor ⬤ runtime v patičce (vždy viditelný, šedé = offline, žluté = připojeno, zelené = Převzetí).

Jazyk stavů tlačítek

Tlačítka v CueX mají vizuálně konzistentní stavy:

LIVE stavový panel

Jakmile vstoupíš do LIVE, objeví se stavový panel vedle timecode:

• LIVE · MM:SS — čas od vstupu do LIVE
• Seznam běžících playlistů s elapsed časem — např. Ambient (0:42), Show (1:05)

Tlačítko ▶ Play v LIVE zůstane viditelné, ale disabled (ztlumené) — v LIVE řídí přehrávání triggery a scheduler, ne ruční Play (kap. 22).

Triggery = VSTUPY, ne výstupy

Častý omyl: sekce Triggery neurčuje, co CueX posílá ven. Určuje, na co show reaguje zvenku:

Každý trigger říká: když přijde tento signál → spusť/zastav tento playlist. Výstupy ven (povely pro BrightSign, projektor) jsou naopak eventy — diamanty na eventové stopě zařízení (kap. 9).

4. Zařízení a patch

Tlačítko Zařízení v headeru otevře správce zařízení. Zde přidáváš:

• DMX světlo — vybereš typ (PAR, strobo, kombinované wash+strobo, větrák, dimmer…) a DMX adresu. CueX hlídá kolize adres (universe 1, 512 kanálů; obsazení vidíš v patičce).
• Media player (UDP) — BrightSign: IP, port, sloty (soubory) a commandy (jaký UDP string spustí jaký slot na jakém výstupu).
• Projektor (PJLink) — IP, přiřazená plocha, doba náběhu (warmup). CueX varuje, když video startuje dřív, než projektor stihne naběhnout.

Levý rail ukazuje všechna zařízení s adresami. Pozici na stage přesuneš v režimu Layout (kap. 5).

Tab Profily — editor fixture profilů

Rail má dva taby: Zařízení (výchozí) a Profily.

V tabu Profily vidíš:

• Zabudované profily (badge built-in, jen čtení) — standardní typy jako rgbpar, strobe, fan, venom-strobe-bar-v2-14ch, auri-12ch a další.
• Vlastní profily (badge vlastní, plně editovatelné) — profily, které jsi vytvořil nebo přizpůsobil.

Overlay: pokud máš vlastní profil se stejným klíčem jako zabudovaný (např. venom-strobe-bar-v2-14ch s upraveným mapováním kanálů), zobrazí se badge překrývá built-in. Zabudovaný pak zálohu tvoří jen tehdy, pokud vlastní smažeš.

Editor profilu: ID profilu (unikátní klíč), Název, Footprint (počet kanálů), tabulka kanálů (offset, size 1/3, název parametru). Pokud footprint nového profilu způsobí DMX kolizi, editor ji ihned zobrazí.

Live náhled: při otevřeném editoru se zařízení s daným typem na stage okamžitě renderuje podle rozeditovaného profilu — vidíš vliv změny bez uložení. Uložit = commit; Zrušit = beze změn.

LIVE režim: v LIVE je tab Profily pouze pro čtení.

5. Stage a Layout

Stage = náhled sálu. Světla svítí, větráky se točí, na plochách běží video.

Tlačítko Layout přepne do editace rozmístění:

• táhni zařízení = přesun po sále,
• táhni plochu = přesun projekce; roh plochy = změna velikosti,
• výběr plochy otevře inspector — tlačítko „Přizpůsobit poměru videa" nastaví plochu přesně na poměr stran načteného videa.

Video se vždy kreslí letterboxem (nikdy se nedeformuje). Když show neběží, plocha ukazuje ztlumený první frame s „▶ PLAY pro projekci". Layout ukonči dalším klikem na Layout. Změny se ukládají automaticky.

6. Timeline: pohyb, výběr, editace

Pohyb

Vlnovka a akcenty

Media pruh v timeline ukazuje vlnovku zvuku (i zvukové stopy videa) — akcenty hudby vidíš přímo pod keyframy. Z vlnovky se automaticky detekují akcenty (údery/nástupy) a zobrazují se jako drobné bílé čárky ve spodku pravítka.

Keyframy (obálkové stopy)

• klik do stopy = přidat/vybrat keyframe; hodnotu a čas doladíš v inspectoru
• tažení keyframu = posun v čase/hodnotě
• ⇧klik = multi-select; Ctrl+C / Ctrl+V = kopírovat/vložit
• Delete = smazat výběr
• šipky ←→ = posun o 0,1 s (se Shift o 1 s); ↑↓ = hodnota ±5
• U barevných stop keyframe nese barvu (RGB picker v inspectoru)

Stopy

• M/S u labelu = mute/solo stopy (jen pro náhled, neukládá se do show)
• tažení za label = změna pořadí řádků (organizace: PARy k sobě atd.)
• + Skupina = skupinová stopa (kap. 8)

Markery

• M v timeline = přidat marker na pozici playheadu; přejmenování/mazání v inspectoru
• M jinde (mimo textové pole) = toggle DMX monitor (kap. 15)
• Markery vidíš v pravítku a v Deploy sheetu (tabulka cues s timecody)

Ripple posun

Kdykoli přidáš cue uprostřed hotové show, vše za ním musíš posunout. Ripple to udělá za tebe.

Ripple platí jen pro elementy na téže stopě — stopy jiných zařízení se neposouvají.

Filmstrip náhledy videa

Media pruh (záhlaví eventové stopy s přiřazeným videem) zobrazuje sled miniatur z načteného videa — vidíš, co hraje v každém okamžiku bez nutnosti přehrávat.

• Náhledy se generují automaticky po načtení videa (BrightSign hraje vždy od začátku — bez trim-pointu).
• Hustota miniatur se přizpůsobí zoomu timeline.
• Pruh s audiostopou (bez videa) ukazuje jen vlnovku.

7. FX efekty — sine, flicker, pulse

Ruční klikání „blikání ohně" po keyframech by bylo šílené. Od toho jsou FX segmenty: efekt položený NAVRCH základní obálky, na vybraný úsek času.

U vybrané obálkové stopy (jen číselné parametry — jas, rychlost; ne barva) najdeš v inspectoru sekci FX → „přidat":

Parametry:

• t0 / t1 — od kdy do kdy efekt běží (sekundy)
• rateHz — rychlost: 0,2 = pomalé dýchání (5 s perioda), 4 = rychlé chvění
• depth — síla v DMX jednotkách 0–255 (30 = jemné, 127 = extrém)
• seed (jen flicker) — jiné číslo = jiný náhodný průběh; stejné = vždy stejný

Efekt je v timeline vidět jako podbarvený pruh a křivka ukazuje výslednou (zmodulovanou) hodnotu. Překrývající se efekty se sčítají.

8. Skupinové stopy

K čemu: stejná obálka pro víc zařízení najednou. Místo čtyř identických stop „jas" pro všechny PARy máš jednu skupinovou.

Vytvoření: tlačítko + Skupina (u timeline) → vybereš zařízení a parametr → vznikne stopa označená „Skupina (N×)".

Úprava členů: klikni na skupinovou stopu → inspector → sekce Členi skupiny — přidání/odebrání zařízení, nebo rozdělit skupinu (rozpadne se na samostatné kopie pro každé zařízení — hodí se, když se zařízení mají začít chovat různě).

Ukládání: skupina je normální součást playlistu — uloží se s projektem, nic zvláštního dělat nemusíš.

9. Video a media (BrightSign)

• Sloty playeru (Zařízení → BrightSign) odkazují na soubory videí/audia.
• Event stopa playeru nese diamanty s commandy — např. PLAY_LEGENDA v čase 0:00.2 spustí video na HDMI-1. To je ta cesta „CueX → ven".
• Posun v čase: media pruh jde v timeline táhnout myší — mění se čas play eventu (v reálu = čas eventu v S-Play playlistu, 1:1 přenositelné). Zvuk ve videu se posouvá s obrazem. Trim začátku neexistuje záměrně — BrightSign neumí „pusť soubor od poloviny", takže by to v reálu nešlo.
• Automatické načtení: soubor pojmenovaný podle slotu vlož do složky media/ vedle projektu — načte se sám při otevření. Jinak klik na slot → vybrat soubor ručně.
• Zvuk: ikona 🔊 v headeru = mute/unmute zvuku videa v simulaci. (V reálu jde zvuk z analogového výstupu BrightSignu, ne z CueX.)
• On media end pravidla (co se stane, když video doběhne) se nastavují u playeru v Zařízeních — simulují chování BrightAuthor:connected.

10. Playlisty

Taby nad timeline. Každý playlist = samostatná timeline s vlastními stopami.

Vlastnosti (klik na tab → inspector): délka, počet přehrání (1×/∞), priorita, autostart (v LIVE se spustí sám).

Délka timeline: konec playlistu je v pravítku vyznačená hrana — jde táhnout myší. Tlačítko „Přizpůsobit médiím" v inspectoru nastaví délku na konec nejdelšího média + dojezd. Cokoliv (keyframe, event, FX) za koncem playlistu se nemaže, jen na to upozorní validace.

Po skončení (follow rules): v inspectoru playlistu sekce „Po skončení" — vyber playlist, který se má spustit po přirozeném doběhnutí (ne po ručním stopu nebo stop triggeru). Volitelné zpoždění v ms (0 = okamžitě). Typický vzor: ambient loop (∞, priorita 10) → show (1×, priorita 80, follow → ambient). Show přebije ambient při přehrávání, po doběhnutí se ambient sám rozeběhne.

Souběh v LIVE: běží-li víc playlistů a sahají na stejné DMX kanály, vyhrává vyšší priorita (řeší se po kanálech). Editor tě varuje, když mají dva playlisty stejnou prioritu a sdílejí zařízení.

Duplikovat playlist: v kontextovém menu taby (⋯) → Duplikovat — vytvoří kopii se všemi stopami a klíčovými snímky, název „<původní> 1" (nebo „2", „3", …), bez triggerů, autostart=false. MCP: playlist_duplicate({sourceId}).

11. Ukládání a verze

12. Nasazení do reálu

1. Deploy sheet (tlačítko v headeru) — vygeneruje checklist: S-Play playlisty, BrightSign pravidla, DMX patch tabulku, triggery, markery, síť.
2. sACN OUT — CueX vysílá světla po síti (universe 1); S-Play Mini je nahraje jako Dynamic Cues (record). Vyžaduje spuštěný sidecar (npm run sacn) a LAN spojení.
3. Video/projektory se konfigurují ručně dle deploy sheetu (S-Play nemá API).

Ověření fixtury na place (doporučený postup)

U odhadovaných DMX profilů (LWS 384, Auri Strobe) nebo neznámých svítidel:

1. Locate → rozsvítí svítidlo naplno (kap. 15) — ověříš, že patch adresa souhlasí s reálným světlem.
2. DMX monitor (M nebo klik na čítač universe v patičce) → živá mřížka kanálů — vidíš, které kanály Locate posílá a jaké hodnoty.
3. Porovnej s manuálem svítidla: pokud nesouhlasí, přejdi v railu do tabu Profily → duplikuj zabudovaný profil → uprav kanály → ulož → znovu Locate.
4. Opakuj, dokud DMX monitor nepotvrdí správné hodnoty na správných kanálech.
5. Teprve pak nasazuj show (sACN record do S-Play).

15. DMX monitor a Locate

DMX monitor

Otevření: klávesa M (kdekoliv mimo textové pole) nebo klik na čítač „univ. N ch" v patičce. Drawer se vynoří nad patičkou.

Co vidíš: mřížka 512 kanálů s aktuálními hodnotami (0–255) v reálném čase. Kanály s nenulovými hodnotami jsou zvýrazněny; hover ukáže jméno zařízení, které kanál vlastní (pokud je v patch).

Použití na place:

• Spusť show (nebo Locate) → monitor ukazuje, co skutečně jde ze sACN.
• Klikni na kanál → inspector zobrazí přiřazené zařízení a parametr.
• Porovnej s očekáváním z deploy sheetu.

Highlight / Locate

Na place potřebuješ vědět, které světlo je které. Locate rozsvítí jedno svítidlo naplno, zbytek nechá tak.

• Klikni na ◎ (ikonka kruhu) u zařízení v levém railu → dané svítidlo skočí na plné hodnoty (RGB = bílá, dimmer = 255, jiné kanály = 0).
• Auto-off: po 60 sekundách se Locate automaticky vypne.
• Exkluzivita: vždy svítí max. jedno zařízení. Klik na jiné ◎ → předchozí se vypne.
• Klikni znovu na aktivní ◎ (nebo počkej 60 s) → Locate se vypne.

Locate vs. přehrávání: Locate je překryv výstupu, nezasahuje do show. Playback pokračuje normálně; Locate hodnoty jsou NAVRCH výstupu (viditelné v DMX monitoru).

LIVE: Locate funguje i v LIVE — hodí se pro rychlé ověření svítidla za provozu.

13. Klávesové zkratky — přehled

14. Ovládání agentem (MCP)

CueX obsahuje MCP server — rozhraní, přes které může AI asistent (Claude Code, Claude Desktop) číst i editovat projekt textovými příkazy. Agent zná strukturu projektů, DMX patch, limity S-Play i celou terminologii — nemusíš mu nic vysvětlovat.

Typický use case: pošleš mu světelný scénář ve formátu .xlsx nebo čistého textu; on přidá zařízení, vytvoří playlisty, vyplní keyframy, přidá FX efekty a nastaví markery — celá show za minuty.

Jak zapojit

Claude Code — vytvoř soubor .mcp.json v kořenu projektu:

{
  "mcpServers": {
    "cuex": {
      "command": "node",
      "args": ["mcp/server.mjs"]
    }
  }
}

Claude Desktop — přidej do ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cuex": {
      "command": "node",
      "args": ["/absolutní/cesta/k/peklo-sim/mcp/server.mjs"]
    }
  }
}

Poprvé spusť (jen jednou): cd mcp && npm install

Pak otevři CueX (webová app nebo desktop). Patička ukáže ⬤ agent zeleně, jakmile se MCP server připojí.

Příklad promptu: stavba show ze scénáře

Agent zavolá get_project (přečte, co je), přidá zařízení, playlist, stopy, keyframy, FX a markery — výsledek uvidíš v timeline.

Souběh Desktop + Claude Code

Pokud máš CueX otevřený v Claude Desktop i v Claude Code zároveň, obě instance MCP serveru fungují bez konfliktu — první se stane hostem (hub), každá další se připojí jako relay a přeposílá příkazy témuž hubu. Příkazy z obou asistentů se vyřizují jeden po druhém.

Pokud Desktop zavřeš, relay instance automaticky převezme port do ~5 s a CueX app se přepojí (retry každých 5 s — bez změny konfigurace).

Pravidlo LIVE — read-only

Když je CueX v LIVE režimu, agent může jen číst (get_project, get_state), ale nemůže nic měnit. Editační příkazy vrátí chybu. Zapni LIVE až po dokončení show.

Ctrl+Z vrací zásahy agenta

Každá dávka příkazů agenta vytvoří jeden krok undo. Pokud se výsledek nelíbí, stiskni Ctrl+Z — celý zásah se vrátí. Agent může i sám zavolat undo, pokud pozná, že udělal chybu.

Variantní projekty (save / open)

Potřebuješ dvě podobné show (jen jiné video)?

Agent použije nástroje save_project_as a open_project_file — soubory žijí v ~/Documents/CueX, appka vždy zobrazuje jeden. Přepínání: „Otevři show_a.json."

Nové MCP nástroje (bundle authoring2_dmx_install)

DMX monitor (čtení stavu výstupu):

• read_dmx_output — vrátí aktuální hodnoty všech 512 kanálů DMX universe 1. Dostupný i v LIVE. Vhodné pro ladění: agent přečte kanály a porovná s tím, co by dle profilu mělo svítit.

Locate (fyzické ztotožnění svítidel):

• locate_device { device_id } — zapne Locate pro dané DMX zařízení (full override výstupu, auto-off 60 s). Jen v editačním režimu.
• locate_off — vypne Locate.

# Příklad: ověření kanálů LWS 384 agentem
locate_device(device_id="lws1")   → zapne svítidlo naplno
read_dmx_output()                 → zjistí, které kanály jsou na 255
locate_off()                      → vypne

Fixture profily (CRUD):

• list_fixture_profiles — seznam všech profilů (built-in + custom merged)
• get_fixture_profile { key } — detail profilu (footprint, params)
• upsert_fixture_profile { key, def } — vytvoří nebo přepíše vlastní profil. Jen v editačním režimu.
• delete_fixture_profile { key } — smaže vlastní profil. Zamítne, pokud by zařízení zůstala bez profilu. Jen v editačním režimu.

LIVE read-only pravidlo: locate_device, locate_off, upsert_fixture_profile, delete_fixture_profile — v LIVE vrátí chybu. Ostatní (read_dmx_output, get_project, list_fixture_profiles atd.) fungují i v LIVE.

DMX capture (nahrání z pultu):

• capture_start — spustí nahrávání sACN vstupu. Jen v editačním režimu.
• capture_status — vrátí {state, frameCount, durationSeconds, truncated}. Bezpečné volat v smyčce.
• capture_stop_import { playlistId, tolerance? } — zastaví + importuje do playlistu. Jeden krok undo. Jen v editačním režimu.
• capture_discard — zahodí nahrávku bez importu.

Viz kapitolu 17 pro celý workflow.

16. Agent bez instalace vývojářských nástrojů

Pokud nemáš repo nakopírované lokálně, použij průvodce v menu: Nápověda → Připojit agenta (Claude Desktop)…

Dialog nabídne dvě akce:

1. Zkopírovat konfiguraci — vloží do schránky hotový JSON snippet s přesnou cestou ke konektoru odvozené z tvé instalace. Snippet pak vlož ručně do ~/Library/Application Support/Claude/claude_desktop_config.json.
2. Zapsat do Claude Desktop — CueX najde config Claude Desktop, zobrazí co přidá a po tvém potvrzení zapíše (ostatní servery zůstanou zachovány, stávající config bude zazálohován do .bak-cuex). Po zápisu restartuj Claude Desktop.

Pokud Claude Desktop není nainstalovaný nebo config nebyl nalezen, dialog nabídne jen kopírování snippetu a postup pro ruční vložení.

Pokud konektor cuex v configu již existuje, dialog nabídne aktualizaci cesty — žádné duplikáty nevzniknou.

Vývojářský setup z kapitoly 14 (.mcp.json + node mcp/server.mjs) zůstává aktuální pro práci s lokálním klonem repozitáře a pro Claude Code.

17. Nahrání show z pultu (DMX capture)

CueX umí nahrát DMX provoz z fyzického osvětlovacího pultu přes sACN (E1.31, universe 1) a převést jej na editovatelné stopy v timeline.

Předpoklady

1. Pult nebo zdroj sACN připojen na stejnou LAN, universe 1 (multicast 239.255.0.1:5568). Zdrojový název nesmí být peklo-sim (echo filtr).
2. sACN bridge: npm run sacn. Ve verzi desktop app se spouští automaticky.
3. CueX v editačním režimu — LIVE capture zamká.

Postup v DMX monitoru (UI)

1. Otevři DMX monitor klávesou M a přepni zdroj na Vstup. Ověř příchod dat.
2. Klikni ● REC — nahrávání startuje.
3. Přehraj show na pultu nebo emulátoru.
4. Zastav kliknutím ■ Stop — otevře se importní dialog.
5. Nastav toleranci, zkontroluj náhled a klikni Importovat.

Postup přes agenta (MCP)

capture_start()
capture_status()   → {state:"recording", frameCount:87, durationSeconds:6.5}
capture_stop_import({playlistId:"pl1", tolerance:3})
→ {ok:true, report:{tracksCreated:6, unmappedChannels:[], genericsCreated:0}}

Limity

• Universe 1 (Art-Net pro vstup zatím není).
• Max 10 minut — po překročení auto-stop (truncated: true).
• Kanál = stopa jen pokud se hodnota změnila o více než tolerance DMX jednotek.
• Import vytvoří jeden krok undo — Ctrl+Z vše vrátí.

18. Výstupy — sACN, Art-Net, USB-DMX

CueX přeposílá DMX z timeline na fyzické světla třemi protokoly. Každý výstup lze zapnout/vypnout nezávisle kliknutím na tlačítko Výstupy v headertu (ikona sítě vedle dot-indikátoru). Konfigurace se uloží do projektu a obnoví při dalším otevření.

Kdy jaký výstup

sACN (E1.31)

• Výchozí stav: zapnuto.
• Universe 1, multicast 239.255.0.1:5568.
• Potřebuje sACN bridge: npm run sacn. Ve verzi desktop app se spouští automaticky.

Art-Net (ArtDMX)

• Výchozí stav: vypnuto.
• Universe 0 (= fyzická universe 1; Art-Net čísluje od nuly), port UDP 6454.
• Cíl — nastavíš v popovertm:
  255.255.255.255 — broadcast (všechna zařízení na LAN)
  konkrétní IP — unicast (jeden Art-Net přijímač nebo splitter)

USB-DMX (ENTTEC USB Pro)

• Výchozí stav: povoleno — aktivuje se automaticky při připojení adaptéru.
• Plug-and-play: CueX detekuje adaptér každé 3 sekundy. Při připojení se zobrazí název portu v dot-indikátoru; při odpojení zmizí — žádné ruční konfigurování.
• Výstup lze zakázat checkboxem v popovertm (adaptér zůstane detekován, data se neposílají).

Popover Výstupy

Klikni na tlačítko Výstupy v headertu (vpravo od indikátoru). Zobrazí se tři řádky: sACN toggle, Art-Net toggle + IP pole, USB-DMX toggle (disabled = adaptér nepřipojen).

Dot-indikátor v headertu: zelený = alespoň jeden výstup aktivní, šedý = vše vypnuto, červený = chyba výstupu.

Postup přes agenta (MCP)

outputs_get / outputs_set jsou dostupné i v LIVE režimu (výjimka z LIVE read-only pravidla — výstupy jsou operativní nastavení, ne data show).

outputs_get()
→ { config: { sacn:{enabled:true}, artnet:{enabled:false, target:"255.255.255.255"} },
    status: { sacn:{enabled:true, frames:1234, error:null}, ... } }

outputs_set({ artnet: { enabled: true, target: "192.168.1.100" } })
→ { ok: true, config: {...} }

// Zakázat sACN + zapnout Art-Net broadcast:
outputs_set({ sacn: { enabled: false }, artnet: { enabled: true } })

19. Ovládání z mobilu (Claude na telefonu)

CueX umí být ovládán vzdáleně přes claude.ai (nebo mobilní Claude) pomocí MCP konektoru přes cloudflared tunel. Funguje i bez vývojářských nástrojů na telefonu.

Co Claude může z mobilu dělat

Výchozí nastavení je read-only — Claude může sledovat a komentovat, ale nemůže změnit show bez explicitního odemčení.

Bezpečnostní model

Claude (mobil/web)
       │  HTTPS + Bearer token
       ▼
cuex-mcp.xlabbot.win  (cloudflared tunel)
       │  HTTP (po validaci tokenu)
       ▼
auth_gateway.py  :9442
       │
       ▼
server-http.mjs  :9441  (read-only nebo full profile)
       │  WebSocket
       ▼
CueX hub  :9440

• Bearer token — sdílené tajemství, uložené v ~/.config/cuex/remote.token. Bez tokenu gateway vrátí 401 Unauthorized.
• Read-only default — HTTP transport vždy spouští s profilem remote (11 nástrojů, žádné mutace). CUEX_REMOTE_WRITE=1 odemkne všechny nástroje.
• LIVE ochrana — i s CUEX_REMOTE_WRITE=1 jsou mutace projektu v LIVE režimu odmítnuty (hub to vynucuje).

Registrace konektoru v claude.ai

1. Přejdi na claude.ai → Settings → Integrations → Add MCP Server
2. Vyplň:
   • URL: https://cuex-mcp.xlabbot.win/mcp
   • Auth type: Bearer Token
   • Token: obsah souboru ~/.config/cuex/remote.token (přečti: cat ~/.config/cuex/remote.token)
3. Ulož a otestuj — Claude by měl ihned vidět nástroje CueX.

Pozor: Konektor funguje, jen když na Macu běží CueX nebo alespoň server-http.mjs a auth_gateway.py. Viz kap. 16 pro spuštění bez vývojářských nástrojů.

Příklad konverzace z telefonu

Ty:   Jak vypadá aktuální show?
Claude: [volá get_state] Show "Peklo 2026" — 2 playlisty, 8 zařízení,
        aktuálně zastaven na 00:00.000.

Ty:   Poznamenej si: mikrofon třeba zkontrolovat.
Claude: [volá add_note] Uloženo jako poznámka #3.

Ty:   Přidej stroboskop na DMX adresu 50.
Claude: [remote profil — add_device chybí] Nemám oprávnění přidávat
        zařízení v aktuálním profilu. Pro editaci spusť server s
        CUEX_REMOTE_WRITE=1.

20. Zobrazení — zoom, kontrast

Menu Zobrazení ▾ v headeru (mezi Media a Projekt) sdružuje nastavení, která se ukládají na úrovni prohlížeče/systému — nezávisle na projektu.

Jak otevřít

Klikni na tlačítko Zobrazení ▾ v horní liště. Nebo v Electron appce: menu Zobrazení v menubar (macOS).

Zoom celého UI

Zoom mění měřítko celého rozhraní — vhodné na menší notebooky nebo velké monitory. Dostupné kroky: 90 % / 100 % / 110 % / 125 % / 150 %.

Nastavení se pamatuje přes restarty v localStorage (tedy jen v konkrétním prohlížeči / instalaci appky, ne v souboru show).

Vysoký kontrast

Přepínač Vysoký kontrast zesiluje čitelnost nejmenších textů a tlumených prvků — tmavý motiv zůstane, jen se zvýší kontrast popředí.

• Zapnuto: text a pomocné linky jsou výraznější
• Vypnuto (výchozí): standardní CueX tmavý motiv

DMX monitor přes menu

Položka DMX monitor v sekci Panely otevírá / zavírá DMX monitor (stejně jako klávesa M). Užitečné, pokud preferuješ ovládání myší.

21. Zkouškový playback — video a zvuk přímo z CueX

CueX umí otevřít výstupní okna s videem — každý přehrávač může mít svůj výstup na samostatné okno (nebo displej). Hodí se pro zkoušení synchronizace světel a videa bez reálného BrightSignu.

Kdy to použít

• Příprava show bez hardwaru: chceš vidět, jak video ladí s DMX obálkami
• Zkouška na laptopech: 2 HDMI adaptéry → 2 výstupní okna = 2 virtuální displeje
• Ověření přiřazení médií a načasování před instalací

⚠ Limit: není to produkční přehrávač

CueX výstupní okna jsou zkouškový nástroj, ne náhrada BrightSignu v produkci:

Pro finální produkci vždy použij reálný BrightSign.

Typy přehrávačů

Vlastní typ přidáš v Device manageru (tab Profily → Přehrávače): zvolíš klíč, název, počet HDMI výstupů (1–4), přítomnost audio jacku a doporučený počet mediálních slotů.

Jak routovat video do oken

1. Přidej přehrávač: levý rail → + → vybrat typ z katalogu (např. XD1035)
2. Přiřaď médium: inspektor → záložka média → slot videoA → vyber soubor
3. Inspektor → sekce Video výstup → změň routing z „Náhled (stage)" na Okno 1 nebo Okno 2
4. Okno se otevře automaticky — v Electron appce jako nové BrowserWindow (černé pozadí, frameless), ve web verzi jako window.open
5. Přetáhni okno na druhý displej; dvojklik = fullscreen, Esc = exit fullscreen
6. Po zavření okna se routing automaticky vrátí na „Náhled"

Jak routovat audio do zvukovky

1. Přehrávač musí mít profil s audioOut = true (XD1035, XT1144 — ano; LS445 — ne)
2. Inspektor → sekce Audio výstup → vyber zařízení ze seznamu
3. Routing se přepne okamžitě (funguje i za přehrávání)
4. Hot-plug: seznam zařízení se aktualizuje, když klikneš na dropdown

Při odpojení zvukové karty CueX automaticky přepne na systémový default a upozorní toastem. Při dalším zapojení zvukovky ji znovu vyber v inspektoru.

Poznámka: LS445 nemá dedikovaný audio jack — zvuk jde přes HDMI kabel. Pro tento model sekce „Audio výstup" v inspektoru nezobrazí.

Hlasitost (simulátor) — mute a gain per výstup

V inspektoru přehrávače je sekce Hlasitost (sim). Platí pro přehrávače s driverem udp (BrightSign) i osc (Honza/Svipr HD). Pro každý výstup:

• Mute toggle (🔊 / 🔇) — ztlumí zvuk daného výstupu v simulátoru. Kliknutím přepne stav; ikona se změní na 🔇 a gain slider se deaktivuje.
• Gain slider (0–1) — hlasitost výstupu od 0 (ticho) do 1 (plná). Slider je zakázán, je-li výstup zmutovaný.

Kapitola pro agenta: player_def a routing nástroje

Profily přehrávačů:

Video routing:

Audio routing:

Audio mute/gain (sim):

player_audio_get()
  → {outputs: [{playerId:"bs_a", outputId:"HDMI-1", muted:false, gain:1}]}
player_audio_set(bs_a, HDMI-1, muted=true, gain=0.5)
player_audio_get()
  → {outputs: [{playerId:"bs_a", outputId:"HDMI-1", muted:true, gain:0.5}]}

E2E skripty: node mcp/e2e-media.mjs — automatický MCP průchod (routing assertions + time-advance poll); node mcp/e2e-audio-mute.mjs — round-trip mute/gain (get → set → ověření → restore). Vizuální gate (obě okna na obrazovce s různým obsahem) je ruční krok pro Architekta.

22. Triggery — spouštěče show

Triggery spouštějí nebo zastavují playlisty na základě příchozích signálů — OSC zpráv, UDP stringů, náběžné hrany DMX kanálu nebo GPI/web vstupu.

22.1 Zdroje triggerů

22.2 Editor triggerů (záložka Triggery)

V postranním panelu otevři záložku Triggery. Pro každý trigger:

1. Vyber zdroj (osc / udp / dmx / gpi / web) — zobrazí se příslušná pole.
2. Vyber akci a playlist:

   Akce	Chování
   start	Spustí playlist od začátku (nebo od holdAt).
   stop	Zastaví playlist — fade out (DMX plynule na 0). Nikdy náhlý výpadek.
   pause	Zmrazí přehrávání na aktuální pozici.
   resume	Uvolní pauzu — pokračuje od místa zastavení.
   toggle	Běžící → stop (fade); zastavený → start. Jedno tlačítko = zapnout/vypnout.

3. Vyplň zdrojová pole:
   • OSC: adresa (např. /play/1), volitelně argMatch: index + hodnota
   • UDP: text pattern (přesná shoda)
   • DMX: kanál (1–512), threshold (0–255), hysteresis (def 16), debounce (ms)
   • GPI / web: pattern (pin nebo cesta)
4. Klikni ▷ Test pro ruční spuštění akce — jen v LIVE (v editačním módu je tlačítko šedé).

Změny se ukládají přes operaci set_triggers — každá úprava vytvoří krok pro Undo (Cmd+Z).

22.3 Sémantika DMX triggeru (náběžná hrana)

• Spuštění: kanál překročí threshold (výchozí 127)
• Hysteresis: engine se znovu nastaví (armed) teprve, když hodnota klesne pod threshold − hysteresis
• Debounce: po spuštění ignoruje další hrany po dobu debounceMs milisekund
• Přetrvávající hodnota: spustí se JEDNOU — nepůsobí opakovaně

⚠️ Kolize kanálů: Použij pro trigger kanál mimo DMX patch (CueX zobrazí varování ve validaci).

22.4 OSC argMatch

Jeden OSC trigger může filtrovat podle hodnoty konkrétního argumentu:

source: osc, pattern: /play, argMatch: {index: 0, equals: 1}  → start
source: osc, pattern: /play, argMatch: {index: 0, equals: 0}  → stop

Pro float porovnání platí tolerance ±0.001.

22.5 Debug pohled — poslední přijaté události

Záložka Triggery zobrazuje posledních ~20 přijatých událostí (osc/udp/dmx) s časem a payloadem. Řádky označené ✓ skutečně vyvolaly akci triggeru.

22.6 DMX monitor — zvýraznění trigger kanálů

DMX monitor (klávesa M) v režimu Vstup zvýrazňuje kanály s DMX triggery:

• Modrý rámeček: kanál má trigger a čeká na signál (armed)
• Zelený rámeček: trigger byl právě spuštěn

22.7 MCP nástroje

triggers_get()
  → {triggers: []}
set_triggers([{
  source: "dmx", pattern: "", action: "start", playlistId: "show",
  dmxChannel: 5, dmxThreshold: 200, dmxHysteresis: 20, dmxDebounceMs: 100
}])
triggers_get()
  → {triggers: [{source:"dmx", dmxChannel:5, dmxThreshold:200, ...}]}

24. CueX vs S-Play — přehled parity

CueX pokrývá všechny klíčové funkce ENTTEC S-Play a S-Play Mini a v řadě oblastí jde dál. Kompletní srovnávačka je v docs/splay-parity.md. Tato kapitola je přehledový souhrn.

24.1 Co CueX umí (parity s S-Play)

24.2 Co CueX přináší navíc (nad rámec S-Play)

• MCP server — AI agent (Claude) ovládá show; žádný jiný show controller to nemá
• Nativní follow/chaining — bez UDP loopback triku
• PJLink projektory a BrightSign media playery přímo v timeline
• Simulátor — 2D stage, DMX vizualizace, filmstrip, audio vlnovka
• Vzdálené MCP — ovládání z mobilu přes HTTPS gateway
• Scheduler i pro „Mini" profil — S-Play Mini scheduler nemá

24.3 S-Play Mini limity — validátor

CueX upozorňuje při překročení hardwarových limitů cílového zařízení. Limity závisí na poli project.settings.splayModel (výchozí: mini):

Varování se zobrazí v hlavičce vygenerovaného deploy sheetu. Export neblokují.

Změna přes agenta:

schedules_set({ schedules: [], settings: { splayModel: 'full' } })

24.4 Vědomá vynechání

Fyzické GPI vstupy, relé výstupy a RS-232 už CueX Box má (§28) — zbývá jen IOE/MQTT a lunární fáze scheduleru, které CueX záměrně neimplementuje.

25. CueX Runtime — provoz bez prohlížeče

CueX Runtime je headless Node.js process, který spouští show bez otevřeného editoru — vhodný pro produkční instalace.

25.1 Spuštění

# Přímý start
node runtime/cli.mjs show.json --data-dir /var/cuex --ops-port 9080

# Doporučeno: supervisor s exponenciálním backoffem (1s→30s)
runtime/run-supervised.sh show.json --data-dir /var/cuex --ops-port 9080

Playlisty s autostart: true se spustí automaticky.

25.2 Stavový watchdog

Pokud tick smyčka nestihne doběhnout do 2 sekund, process se ukončí (exit 1) a supervisor ho obnoví — SHOW pokračuje.

25.3 Zachytávání DMX (runtime capture)

Runtime nahrává DMX vstup ze sACN/Art-Net a importuje nahrávku do playlistu přes Ops API nebo OSC:

# Arm přes Ops API
curl -X POST http://localhost:9080/api/capture/arm \
  -H 'Content-Type: application/json' \
  -d '{"playlistId":"pl1","stopDmxQuiet":{"seconds":3}}'

# Stav
curl http://localhost:9080/api/capture/status

25.4 Soak test

Skript runtime/soak.mjs ověří stabilitu 24 h (nebo 5 min v CI):

node runtime/soak.mjs --duration 300 --data-dir /tmp/soak
cat /tmp/soak/soak-report.json

Prahové hodnoty PASS: RSS drift < 20 %, OSC p99 < 50 ms, 0 restartů.

25.5 Servisní povely (SERVIS mode)

Systémové DMX přepisy pro oživení/servis instalace — obcházejí playlisty, nezávisle na scheduleru. Ovládatelné z Manageru (§32.9b), MCP, nebo přímo webem Runtime (karta SERVIS).

curl -X POST http://cuex-box:9080/api/service/all-on \
  -H 'Content-Type: application/json' -d '{"intensity":0.5}'

26. PlayX — XLAB show player (drop-in Svipr)

PlayX je software daemon (budoucí XLAB HW produkt) — drop-in náhrada Honza playeru / Svipr HD na Raspberry Pi 5 s HiFiBerry DAC2 Pro XLR.

SW stav: HOTOVO (bundle playx_core, 2026-07-20). Čeká na fyzický HW Pi 5 + DAC.

26.1 Sémantika slotů

26.2 OSC (port 7000, Svipr-kompatibilní)

26.3 UDP text (port 10000, Svipr fallback)

hrej01\n  …  hrejNN\n    — přehraj slot N
preruseno\n              — přeruš

26.4 Ops API (HTTP+WS, port 9100)

curl http://PI_IP:9100/api/status
curl -X POST http://PI_IP:9100/api/play -d '{"slot":1}' -H 'Content-Type: application/json'
curl -X PUT http://PI_IP:9100/api/media/1 --data-binary @video1.mp4

Web UI: http://PI_IP:9100 (vestavěný operátorský panel).

26.5 MCP server

node playx/mcp/server-playx.mjs --ops-url http://PI_IP:9100

Nástroje: playx_status, playx_play, playx_stop, playx_volume, playx_mute, playx_media_list, playx_media_upload_path, playx_slot_gain_get, playx_slot_gain_set, playx_slot_rule_get, playx_slot_rule_set.

26.6 Testování parity (SW)

npx vitest run tests/playx-svipr-parity.test.ts
node scripts/build-playx.mjs
node playx/scripts/e2e-chain.mjs
node playx/scripts/soak.mjs --duration 300 --data-dir /tmp/playx-soak

Parity dokument: docs/playx-svipr-parity.md.

26.7 Drop-in swap Svipr → PlayX

1. Přiřaď PlayX stejnou IP jako nahrazovaný Svipr
2. Nakopíruj média do slotsDir jako video0.mp4, video1.mp4, …
3. Spusť daemon: node playx/daemon/cli.mjs --config playx.json
4. CueX / S-Play OSC příkazy fungují beze změny

26.8 Nahrání médií z Editoru

Editor CueX (macOS) umí nahrát videosoubory přímo do PlayX daemonů bez SSH — přes sekci Média playerů v connect dialogu.

1. Klikni na tlačítko Propojit (toolbar → connect ikona)
2. V connect dialogu se zobrazí sekce Média playerů pro každý OscPlayer
3. Klikni Zkontrolovat stav — Editor porovná SHA-256 hash lokálního souboru s manifestem PlayX
4. Klikni Nahrát média (vše) nebo Nahrát u konkrétního playeru

MCP: media_sync_status (čtení) + media_sync_push (zápis, full profil).

26.9 Per-slot hlasitost (slot gain)

Každý slot může mít vlastní korekci hlasitosti (0.0–1.0), která se násobí s master volume. Výsledná hlasitost = master × slotGain(n). Výchozí = 1.0 (žádná korekce).

Nastavení přes web UI PlayX (sekce Korekce hlasitosti slotů), Ops API (GET/POST /api/slots/:n/gain), OSC (/playx/slot/gain i <slot> f <0.0–1.0>) nebo MCP (playx_slot_gain_get/set). Gain přežívá restart daemonu (persistováno do playx.json).

26.10 Per-slot loop a řetězení (chain rules)

Výchozí chování po skončení slotu (EOF) = návrat do standby. Lze přepsat per slot:

Priorita: Příkazy play/stop vždy mají přednost — přijde-li OSC /playx/play během přehrávání, EOF pravidlo se neuplatní.

Nastavení přes web UI PlayX (sekce Pravidla slotů), Ops API (GET/POST /api/slots/:n/rule) nebo MCP (playx_slot_rule_get/set). Persistuje do playx.json.

26.11 GPI — fyzická tlačítka pro PlayX

PlayX podporuje fyzická tlačítka zapojená přes GPIO piny na Raspberry Pi 5. Tlačítko → play/stop slotu.

Mapování přes web UI (doporučeno): otevři http://PI_IP:9100, karta GPI mapování — tabulka pin/akce/slot s tlačítkem „+ Přidat vstup". Každá změna se uloží a aplikuje za běhu bez restartu daemonu (patička karty ukazuje aplikováno / potřebuje restart / chyba). Mapování na slot bez nahraného videa se uloží s nezávazným upozorněním.

Konfigurace ručně v playx.json (např. pro skriptované nasazení):

{
  "gpi": [
    { "pin": 17, "action": { "play": 1 } },
    { "pin": 27, "action": { "play": 2 } },
    { "pin": 22, "action": "stop" }
  ],
  "gpiDebounceMs": 50
}

Bezpečné piny s HiFiBerry DAC2 Pro XLR: 4, 17, 27, 22, 23, 24, 25, 5, 6, 12, 13, 16, 26. Nepouž. BCM 2, 3, 18, 19, 21 (DAC).

Bez gpi klíče v configu daemon vůbec GPI neuplatní. Ops API: GET/PUT /api/gpi/config, POST /api/gpi/sim/:n (sim backend). Detaily: playx/README.md sekce „GPI physical inputs".

26.12 OSC & síť — přehled v UI

Karta OSC & síť (http://PI_IP:9100) zobrazuje porty (OSC/UDP), poslední přijatý příkaz a úplnou tabulku rozpoznávaných OSC adres a UDP textových příkazů — stejný zdroj dat, ze kterého daemon příkazy skutečně vyhodnocuje (nemůže se odchýlit od reality). Read-only, žádná editace. Ops API: GET /api/osc/commands.

26.13 Módy — přehled v UI

Karta Módy zobrazuje aktivní show mód (jméno + pořadové číslo) a tabulku mód→slot/vypnuto pro tuto krabičku (read-only) — viz §32.9 „Show módy" pro model a distribuci. Ops API: GET /api/modes.

26.14 Servisní testovací karta (SERVIS mode)

Servisní obrazovka pro oživení/servis instalace — obchází stavový stroj slotů (standby/playing se po skončení obnoví přesně tam, kde bylo). Ovládatelná z Manageru (§32.9b), MCP, nebo přímo webem PlayX (karta Servis).

curl -X POST http://PI_IP:9100/api/service/test-card \
  -H 'Content-Type: application/json' -d '{"label":"PLAYER · Sál","tone":true}'

26.15 Připojení k Manageru

Karta Připojení k manageru na http://PI_IP:9100 přihlásí (enrollne) krabičku k Manageru přímo z webu — bez SSH, bez ruční editace fleet/config.json na místě.

• Nepřipojeno — formulář: Manager URL + párovací kód (§32.2). PŘIPOJIT naváže spojení hned, bez restartu daemonu.
• Připojeno — stav spojení + tlačítko ODPOJIT (s potvrzením), zruší uložený token.
• Chyba — poslední chyba spojení (špatná URL, kód propadlý/spotřebovaný, síť nedostupná), formulář zůstává otevřený pro opravu.
• Pokud zrovna běží show, odpojení vyžaduje stejné potvrzení/force jako jiné servisní zásahy (§32.9b).

Stejná karta existuje i na Runtime webu (§27.5b, panel 13) — postup je identický pro obě role.

27. CueX Box — fyzická instalace (plug-and-play)

CueX Box je Raspberry Pi s předinstalovaným obrazem xlabshow. Jeden box = jedna role (cuex-box nebo playx). Role se nastaví v /boot/xlabshow.toml — krabička pak startuje automaticky.

27.1 Příprava image

# Build rootfs (jednou, pak reuse --no-rebuild)
./image/build-rootfs.sh

# Assemble SD image pro každou roli
./image/assemble-img.sh --role cuex-box   # → image/dist/xlabshow-cuex-box-YYYYMMDD.img.xz
./image/assemble-img.sh --role playx      # → image/dist/xlabshow-playx-YYYYMMDD.img.xz

27.2 Flash SD karty

1. Otevři Raspberry Pi Imager
2. Choose OS → Use custom → vyber xlabshow-<role>-YYYYMMDD.img.xz
3. Choose SD card
4. Klikni na ⚙️ — NEPOUŽÍVEJ OS customisation (konfigurace je v xlabshow.toml)
5. Write (~5 min/karta)

Po zápisu uprav /boot/xlabshow.toml přímo na kartě (před vložením do Pi):

role = "cuex-box"       # nebo "playx"
name = "cuex-box-peklo" # unikátní hostname

27.3 První zapnutí — LED sekvence

27.4 Nalezení IP adresy

# mDNS — krabičky se hlásí na <name>.local (~30 s po startu)
ping cuex-box-peklo.local
ping playx-honza-a.local

27.5 Ověření v prohlížeči

27.5b Operátorské rozhraní Runtime — panely

http://cuex-box-peklo.local:9080/ má číslované panely; nové jsou:

• 07 Vstupy & triggery (read-only) — živé listenery (OSC/UDP/sACN/Art-Net), tabulka triggerů z projektu (editace v CueX Editu, viz §22), mapa GPI (pin ↔ trigger) a podsekce Módy (aktivní mód + rozdistribuovaná tabulka).
• 08 Power sekvence — seznam s běhovým stavem každé sekvence (idle/probíhá+krok/hotovo/chyba/přerušeno), tlačítka Spustit (s potvrzením) / Přerušit, inline editor (název + kroky relé/stav/zpoždění) → PUT /api/power-sequences (manager/README.md §"Power sekvence").
• 13 Připojení k manageru — formulář Manager URL + párovací kód (§26.15 — postup je pro Runtime i PlayX stejný), nebo stav PŘIPOJENO/CHYBA s tlačítkem ODPOJIT. Živé přepnutí connect/disconnect bez restartu procesu.

27.6 Diagnostika (selftest)

# Výsledek posledního self-testu
curl http://cuex-box-peklo.local:9080/api/selftest
curl http://playx-honza-a.local:9100/api/selftest

# Spustit znovu a čekat
curl -X POST http://cuex-box-peklo.local:9080/api/selftest/run

Výsledek ok/warn = v pořádku. fail = zkontroluj pole action v JSON response.

27.7 Načtení show a médií

# Push-update z Macu (rsync + restart)
./image/push-update.sh cuex-box-peklo.local
./image/push-update.sh all               # všechny na LAN
./image/push-update.sh playx-honza-a.local --dry-run

27.8 Spuštění show

# Ručně
curl -X POST http://cuex-box-peklo.local:9080/api/playlist/main/start

27.9 Virtuální E2E test

./image/e2e-virtual-install.sh      # cuex-box + playx Docker, boot→OSC→selftest
./image/e2e-virtual-install.sh --ci # zkrácená CI varianta

27.10 Řešení problémů

28. Zapojení CueX Box — GPI / relé / RS-232 / DMX

Kompletní schémata, tabulky pinů a svorkovnic viz docs/box-wiring.md v repozitáři CueX.

28.1 GPI vstupy (libgpiod backend)

8 galvanicky oddělených vstupů přes PC817 optočlen (aktivní LOW, pull-up).
Výchozí BCM piny: 17, 18, 27, 22, 23, 24, 25, 4.
Konfigurace: xlabshow.toml sekce [io.gpiod] gpi_pins.

Trigger pattern: source="gpi", pattern = "gpi0" … "gpi7".

28.2 Relé výstupy (GPO)

4–8 relé přes Waveshare 8-relay HAT B. Výchozí BCM piny: 26, 20, 21, 16, 13, 12, 6, 5.
EventTrack příkazy: on, off, pulse (s parametrem ms).

28.3 RS-232 sériový port

USB-RS232 adaptér (CP2102 / FTDI). Konfigurace: [io.rs232] v xlabshow.toml.

• Trigger INPUT: přijatý řádek → source="rs232", pattern = text řádku.
• Event OUTPUT: Rs232Device v projektu → show posílá příkazy na port.

28.4 Backend výběr

[io]
backend = "gpiod"   # gpiod | tinkerforge | sim
gpi_count = 8
relay_count = 4

Self-test hlásí: gpiod ok (gpiomon v PATH), rs232 ok (zařízení nalezeno), warn = backend nakonfigurován, ale HW chybí (show běží bez I/O).

29. Deploy instalace — přímý deploy z Editoru

Editor CueX umí nasadit celou instalaci jednou akcí — bez ručního sheetu, bez SSH přístupu. Funkce se jmenuje Deploy instalace a je dostupná v connect dialogu, jakmile je Editor připojen k CueX Runtime.

Tip: Deploy sheet (§12) slouží jako dokumentace instalace a záloha. Pokud je CueX Runtime dostupný, použij Deploy instalace — je rychlejší a automaticky ověří stav.

Co Deploy instalace udělá

Čtyři kroky proběhnou automaticky v tomto pořadí:

1. Pre-check — ověří, že Runtime je dosažitelný; identifikuje online a offline PlayX playery v projektu
2. Push show — nahraje show.json do Runtime (projekt, playlisty, triggery, zařízení)
3. Sync médií — porovná SHA-256 hashe videosoubory lokálně vs. manifest PlayX playerů; nahraje pouze změněné soubory
4. Ověření — ověří Runtime (/api/status — projekt souhlasí) a manifest každého PlayX (/api/media)

Předpoklady

• CueX Runtime (CueX Box nebo npm run runtime) běží a vysílá heartbeat na UDP :9091
• PlayX daemony běží na všech video playerech a vysílají heartbeat na UDP :9091
• Videosoubory jsou uloženy ve složce ~/Documents/CueX/media/ na Macu (Electron app)
• Editor je připojen k Runtime (connect ikona v toolbaru → „Připojit")

Postup

1. Klikni na connect ikonu v toolbaru (nebo na runtime indikátor v patičce)
2. V dialogu v sekci Připojeno uvidíš modré tlačítko Deploy instalace
3. Klikni — deploy proběhne synchronně (tlačítko je po dobu nasazení neaktivní)
4. Po dokončení se zobrazí report se zelenými/žlutými/červenými řádky:
   • ✓ zelená — krok proběhl úspěšně
   • ⚠ žlutá — varování (např. offline player — deploy pokračoval pro ostatní)
   • ✗ červená — chyba (deploy přerušen)
5. Pokud jsou žluté nebo červené řádky, zobrazí se tlačítko Zopakovat jen červené — nahraje média jen pro problematické playery (show se nenahrává znovu)

Částečný deploy (offline player)

Pokud je jeden z PlayX playerů offline, deploy nepřeruší — show se nahraje do Runtime a ostatní playery se synchronizují. Offline player dostane varující řádek. Jakmile se player připojí, klikni Zopakovat jen červené — dožene synchronizaci bez opětovného nahrávání show.

MCP alternativa

# Nasadit celou instalaci (runtimeIp povinné v MCP kontextu)
deploy_install { "runtimeIp": "192.168.1.100" }

# Zopakovat jen pro offline player
deploy_install { "runtimeIp": "192.168.1.100", "retryPlayerIps": ["192.168.88.31"] }

Nástroj deploy_install je dostupný v full profilu (ne v remote profilu — ten je určen jen pro čtení).

30. Vlastní instalace (Runtime + PlayX) — Den zapojení

Tato kapitola shrnuje celý postup spuštění CueX Box instalace od SD karty po zelené akceptační výsledky. Podrobný krok za krokem: docs/runbook-den-zapojeni.md v repozitáři CueX.

Přehled rolí

Heartbeat discovery: obě role vysílají UDP na port 9091 každé 3 s.

Rychlý start (tři příkazy)

# 1. Build SD image (jednou nebo po aktualizaci kódu)
npm run build && ./image/build-rootfs.sh
./image/assemble-img.sh --role cuex-box   # → image/dist/xlabshow-cuex-box-*.img.xz
./image/assemble-img.sh --role playx       # → image/dist/xlabshow-playx-*.img.xz

# 2. Flash SD karty (Raspberry Pi Imager), uprav /boot/xlabshow.toml per krabička
# → viz §27 + runbook §2

# 3. Akceptační test po zapojení
cp plug-day.config.json.example plug-day.config.json
# uprav runtimeIp a players v plug-day.config.json
node scripts/plug-day-acceptance.mjs --config plug-day.config.json

Co akceptační skript testuje

Výstup: česká PASS/FAIL tabulka, exit 0 (OK) / 1 (chyba).

MCP varianta (z Claude Desktop):

plug_day_acceptance {}
# nebo s explicitním configem:
plug_day_acceptance { "configPath": "/abs/cesta/plug-day.config.json" }

Paralelní provoz se S-Play

CueX Box a S-Play nesmí zároveň posílat DMX na stejný universe. Přepínej fyzicky XLR/Art-Net kabel. S-Play zůstává jako fallback do pokynu k přepnutí.

Vzdálená správa

ssh xlab@cuex-box-peklo.local          # SSH přístup
./image/push-update.sh all             # aktualizace SW bez SD karty
curl http://cuex-box-peklo.local:9080/api/selftest  # stav krabičky

Restart / reboot / vypnutí krabičky

Web UI Runtime (http://cuex-box-peklo.local:9080/) obsahuje sekci Správa provozu s tlačítky Restart Runtime, Restart krabičky a Vypnout krabičku. Každá akce vyžaduje dvoukrokové potvrzení (potvrď do 30 s).

# Krok 1 — vydání tokenu (platný 30 s)
TOKEN=$(curl -s -X POST http://cuex-box-peklo.local:9080/api/system/restart \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['confirmToken'])")

# Krok 2 — potvrzení
curl -s -X POST http://cuex-box-peklo.local:9080/api/system/restart \
  -H 'Content-Type: application/json' \
  -d "{\"confirmToken\":\"$TOKEN\"}"

MCP nástroje: runtime_system_restart, runtime_system_reboot, runtime_system_poweroff (full profil, jen Linux pro reboot/poweroff).

MCP konektor na krabičce: viz §27.7 nebo image/README.md sekce „MCP".

Viz také

• §27 — CueX Box fyzická instalace (image pipeline, LED, selftest)
• §28 — Zapojení GPI / relé / RS-232 / DMX (wiring)
• §29 — Deploy instalace z Editoru (GUI workflow)
• §31 — Offline deploy balíček (alternativní deploy bez přímého síťového spojení)
• docs/runbook-den-zapojeni.md — kompletní runbook pro Den zapojení
• image/README.md — technická dokumentace image pipeline

31. Offline deploy balíček (export/import)

Offline balíček umožňuje nasadit show a média bez přímého síťového spojení s Runtime krabičkou — záloha na USB flash disk nebo sdílení souborem.

Formát

Soubor .cuexpkg — ZIP obsahující:

• manifest.json (verze, SHA-256 hashe médií, metadata)
• show.json (projekt CueX)
• mediální soubory (kopie ze ~/Documents/CueX/media/)

Export z Editoru

Nejjednodušeji: Projekt ▾ → Exportovat balíček Boxu (.cuexpkg)… — funguje bez připojení k Runtime, přímo v Electron i dev browseru.

Nebo přes MCP (AI agent):

export_deploy_package {}
# → uloží .cuexpkg do ~/Documents/CueX/

Import do Runtime (web upload)

1. Otevři http://cuex-box-peklo.local:9080/ v prohlížeči
2. Sekce Deploy balíček: klikni Vybrat soubor → vyber .cuexpkg
3. Klikni Nahrát — Runtime zobrazí diff (co se změní)
4. Klikni Aktivovat pro nasazení nebo Zamítnout pro storno

Import z USB disku

1. Vlož USB disk s .cuexpkg souborem v rootu do Runtime krabičky
2. Web UI zobrazí zprávu „Nalezen balíček na USB — klikněte Aktivovat"
3. Potvrzení přes web UI nebo curl -X POST http://cuex-box-peklo.local:9080/api/deploy/confirm
4. Zamítnutí: curl -X POST http://cuex-box-peklo.local:9080/api/deploy/reject

32. CueX Manager (dohled instalací)

CueX Manager je cloudová služba, která sleduje všechny instalace (cuex-box + playx-box) a poskytuje centrální správu přes webové rozhraní i MCP agentský protokol.

32.1 Co Manager hlídá

• Heartbeat — každé zařízení posílá status každých 10 s. Bez heartbeatu déle než 60 s → online = false.
• Self-test — výsledek posledního self-testu (ok / warn / fail).
• Verze — neshoda verzí SW v rámci instalace = P2 alert.

32.2 Přihlášení zařízení (enrollment)

1. Správce vytvoří pairing kód (platnost 15 minut):
   

   curl -X POST http://manager:4080/api/enroll/start \
     -H "Authorization: Bearer <token>" \
     -d '{"installationId": "peklo", "name": "Peklo Čertovina"}'

2. Kód se zadá do konfigurace krabičky (fleet/config.json, pole token).
3. Při prvním připojení Manager vrátí permanentní deviceToken, který si krabička uloží.

Nebo přímo z webu krabičky, bez editace configu. Runtime i PlayX mají vlastní kartu Připojení k manageru (Runtime §27.5b, PlayX §26.15) — stačí do formuláře vložit Manager URL + párovací kód z kroku 1, spojení se naváže hned, bez restartu procesu. Odpojení jde stejnou cestou (tlačítko ODPOJIT).

32.3 Webové rozhraní

Manager Dashboard (http://manager:4080/) zobrazuje stat karty (instalace, online/offline zařízení, alerty) a dva přepínatelné pohledy: Tabulka (výchozí, tiskový inventární přehled, viz §32.11) a Mapa (2D půdorys se zónami, viz §32.8).

32.4 Vzdálené akce

Akce	Popis
playlist_start	Spustí playlist (parametr id)
playlist_stop	Zastaví playlist
intensity_set	Master intenzita (0–255)
selftest_run	Self-test a výsledek
system_restart	Restart Runtime procesu (confirm: true)
system_reboot	Restart OS krabičky (confirm: true)

system_* bez confirm: true vrátí 202 needsConfirm — dvoukrokový guard.

32.5 Alerty

P0 (okamžitě): všechna zařízení offline > 60 s, self-test FAIL.

P2 (digest): WARN déle než 24 h, neshoda verzí v instalaci. Dedup: max 1× za 6 h.

32.6 MCP agentský přístup

Manager MCP server (manager/mcp/server.mjs) — 10 nástrojů:

Nástroj	Popis
fleet_list	Všechny instalace, jejich zařízení a zóny (strom)
device_status	Detail jednoho zařízení
device_selftest	Self-test a výsledek
device_action	RPC akce (whitelist 7 akcí)
alerts_recent	Posledních N alertů z digest souboru
zone_create	Vytvoří zónu v instalaci (volitelně podřízenou jiné zóně)
zone_assign_device	Přiřadí zařízení do zóny
layout_get	Načte layout dokument instalace
layout_set	Uloží celý layout dokument instalace
device_place	Umístí zónu nebo zařízení na mapě bez přepisu celého dokumentu

Doporučené pořadí pro stavbu mapy agentem: zone_create → zone_assign_device → device_place → layout_get (ověření).

Nastavení v Claude Desktop — do "mcpServers":

"cuex-manager": {
  "command": "node",
  "args": ["/cesta/k/peklo-sim/manager/mcp/server.mjs"],
  "env": {
    "MANAGER_URL": "http://localhost:4080",
    "MANAGER_ADMIN_TOKEN": "tvůj-token",
    "MANAGER_DATA_DIR": "/cesta/k/peklo-sim/data"
  }
}

32.7 Spuštění

# Přímé spuštění
MANAGER_ADMIN_TOKEN=tajny-token node manager/dist/server.mjs

# Docker
docker build -f manager/Dockerfile -t cuex-manager .
docker run -p 4080:4080 -e MANAGER_ADMIN_TOKEN=tajny-token \
  -v cuex-manager-data:/data cuex-manager

32.8 Mapa instalace (zóny + layout) — varianta A „Velín"

Vedle Tabulky (§32.11) má dashboard i Mapu — 3-panelový „velín" (locked 2026-07-26): vlevo strom zón, uprostřed 2D půdorys instalace, vpravo detail panel.

• Strom zón (vlevo) — zařízení lze zařadit do zón (i vnořených, např. Sál → Kout), každá zóna má zobrazený kód (kořenové zóny 01..NN, potomek = kód rodiče + pořadí, např. 05·3). Přepínač „UPRAVIT" zapne přetažení pro změnu pořadí zón v rámci stejného rodiče — mění se jen zobrazený kód, ne interní ID zóny (odkazy z módů/layoutu zůstávají platné).
• Stav zóny je kaskáda nejhoršího stavu zařízení v ní (a jejích podzónách): fault (červená) > offline (tečkovaná šedá) > warn (žlutá) > paused (modrá) > ok (zelená). Offline zařízení tak ztmaví celou zónu i všechny nadřazené zóny.
• Grafika na mapě = jen zařízení/položky s telemetrií — fleet Box/PlayX, plus (od 989) koncová zařízení, u kterých krabička zná reálný stav (projektor PJLink on/warming/off, media player playing/idle): glyf podle katalogového typu + stavová LED (zelená = OK, žlutá = warn), zakotvený u ikony vlastní krabičky. Pasivní položky bez telemetrie (PARy, stroba, …) se na mapě nekreslí — jsou vidět jen v panelu zóny (viz níže).
• Zařízení jako rámeček — fleet zařízení na mapě kreslí rámeček (ne barevná tečka): ikona role (▣ box / ▸ playx), stavová LED vpravo nahoře, popisek ID pod ním. V přeplněné zóně se zmenší na ikonu bez popisku, ale zůstává orámovaný — nikdy nezmizí do anonymní tečky.
• Layout — pozice zón a zařízení na mapě (0–1 souřadnice vůči volitelnému podkladovému obrázku) se nastavují ručně přes REST, nebo typicky agentem přes MCP nástroje výše.
• Ovládání mapy — tažení = posun, kolečko = zoom (kolem kurzoru), dvojklik na zónu = přiblížení. Klik na zařízení otevře stejný postranní panel akcí jako Tabulka. Zaškrtávátko „Jen problémy" ztlumí vše v pořádku. Nezařazená zařízení se zobrazí v liště pod mapou.
• Panel zóny (vpravo, klik na zónu ve stromu nebo na mapě) — hlavička (kód, název, kaskádový stav) a všechna zařízení zóny ve třech skupinách (přejmenováno úkolem 1003): ZAŘÍZENÍ (dřív „S TELEMETRIÍ" — fleet zařízení s živým stavem, odznak druhu BOX/PLAYER + přátelské jméno „druh · název show projektu" přesně jednou (oprava duplicity), syrové ID jen jako labelovaný řádek „ID: …" v detailu, který navíc má nahoře drobečkovou navigaci „‹zóna› / ‹zařízení›" s klikatelným návratem do zóny; klik → plný inspektor), KONCOVÁ S TELEMETRIÍ (dřív „KONCOVÁ ZAŘÍZENÍ" — položky s vlastní telemetrií — stejné jako glyfy na mapě, stav zobrazen textově mono, zeleně/žlutě, skupinové názvy česky: PROJEKTOR/FIXTURE/JINÉ) a BEZ TELEMETRIE (z inventáře — PARy, stroba…, jen výčet; klik → read-only technické údaje: driver, typ fixture, DMX adresa, universe). Prázdná sekce se sbalí na titulek + pomlčku místo tří různých vět „Žádná…". Koncové zařízení s telemetry.ok = false nastaví warn na krabičce i zóně (nikdy fault — ten je jen pro offline/selftest). Odznak „MÓD NESEDÍ" se zobrazí až po 2 po sobě jdoucích heartbeatech neshody (~20 s) — krátké přechodné nesrovnalosti hned po aktivaci módu nevytvářejí planý poplach; aktivní mód je navíc vidět jako malý odznak přímo v hlavičce vedle tlačítka MÓDY.
• Výběr na mapě — vybraná zóna nebo zařízení dostane bílý zvýrazňovací rámeček, synchronní s otevřeným panelem. Popisek zařízení pod ikonou je zkrácený (bez prefixu instalace, např. „PLAYX" místo „certovina-staging-playx") — celé ID je jen v detailu.
• Inventory — každá krabička hlásí Manageru svůj aktuální seznam kanálů/slotů; zdroj dat pro panel zóny i §32.10 přehled Plán vs. realita.
• Legenda vlevo dole na mapě: ▣ BOX · ▸ PLAYER · ● PAR · ▲ STROBO · ▭ PROJEKTOR.

Snímek obrazovky zatím chybí (headless prostředí Forge nemůže spouštět prohlížeč) — doplní Architect po vizuálním ověření redesignu 981 + polish 995–998 + builder 1004–1006.

32.8b Editace mapy — Builder (UPRAVIT)

Přepínač UPRAVIT u stromu zón vlevo odemkne stavbu instalace přímo na mapě — od nuly, klidně bez jediného připojeného zařízení:

• + NOVÁ INSTALACE / + ZÓNA — založí prázdnou instalaci, nebo novou zónu (i vnořenou). Zóna bez jakéhokoliv zařízení v celém podstromu se kreslí jako přízrak (tečkovaný rámeček, ztlumená výplň).
• KRESLIT ZÓNU (tlačítko nebo klávesa Z) — tažením na volné ploše vznikne nová zóna přesně v nakresleném obdélníku; tažení přes existující zónu založí podzónu (nejmenší zóna, která tažený obdélník celý obsahuje, se za tahu zvýrazní tečkovaně jako budoucí rodič).
• Mřížka (výchozí zapnuto, klávesa Alt dočasně invertuje) a zarovnávací vodítka (magnet na hrany ostatních zón) drží rozestavění úhledné.
• ✎ / ✕ u řádku zóny ve stromu — přejmenování / smazání (u neprázdné zóny s druhým potvrzením).
• PODKLAD / ODEBRAT PODKLAD — nahrání nebo odebrání podkladového obrázku mapy.

• Tažení zařízení mezi zónami teď přeřadí i jeho skutečné zařazení, ne jen pozici na mapě.
• Undo/redo (⌘Z / ⇧⌘Z) pokrývá každou editační akci vč. smazání zóny s obsahem a jeho vrácení zpět. Výběr více zón (klávesa V nebo Shift+klik) odemkne zarovnávací panel (vlevo/nahoře/na střed, stejná šířka/výška, rozestoupit, smazat). Klávesa „?" zobrazí přehled zkratek.
• Ikony zařízení jsou výrazně větší — 2,5× v UPRAVIT módu, 2× v běžném živém pohledu oproti dřívější výchozí velikosti, včetně úměrně zvětšeného klikacího/tažného okolí.
• Tažení jednotlivého zařízení — chyť a přetáhni ikonu na mapě, funguje i napříč zónami.
• Skupinové tažení — vyber víc zařízení (VÝBĚR nebo Shift+klik) a přetáhni kteroukoliv z nich — celý výběr se posune spolu, jedna dávka + jeden krok Undo, přeřazení zóny dávkově.
• Tažení plánované (šrafované/přízrak) položky — i položka bez skutečného zařízení jde chytit a přesunout na konkrétní místo v zóně; položky bez ruční pozice se dál automaticky rozmístí do zbývajících míst.

Plný technický popis: manager/README.md §„Editace mapy — Builder".

32.8c PROPOJENÍ — párovací wizard

Tlačítko PROPOJENÍ v hlavičce (s odznakem počtu nových zařízení) spáruje zařízení, které se právě přihlásilo, s položkou v plánu — automaticky (párovací kód vygenerovaný z konkrétní plánované položky) nebo ručně (obecný kód → sloupec „NOVÁ ZAŘÍZENÍ" → návrh nebo ruční výběr → PROPOJIT). ODPOJIT vrátí zpět zařazení do zóny i propojení s plánem. Díky tomuto párování funguje i mód navržený předem podle plánované položky (offline) — po spárování se mapování automaticky přepíše na skutečné ID zařízení. Kompletní scénář „doma → na place": Od nuly na plac.

32.9 Show módy

Mód = pojmenovaná varianta provozu instalace (např. „Muzikál", „Program pro školy"), přepínaná odkudkoliv — dashboard, MCP, ControlX/dotykáč po LAN. Exekuce je vždy lokální (funguje i bez internetu); Manager jen distribuuje a dohlíží. Plovoucí pult „MÓDY" v hlavičce dashboardu má velká dotyková tlačítka s potvrzením a výsledkem za každé zařízení; aktivní mód je vidět i v patičce a panelu zóny (badge „MÓD NESEDÍ" — zobrazí se až po 2 po sobě jdoucích heartbeatech neshody (~20 s), aby krátké přechodné nesrovnalosti hned po aktivaci módu nevytvářely planý poplach). Podrobný koncept a návod pro ControlX: samostatná stránka Show módy.

32.9b SERVIS — oživení instalace

Přepínač SERVIS v hlavičce (vedle UPRAVIT) proměňuje mapu v ovládací panel pro techniky na place — první zapojení nebo diagnostika bez otevírání CueX Editu. Aktivní SERVIS je vidět na první pohled: šrafovaný okraj mapy.

Postup na place — mapa → klik → co se stane:

• Klik na koncové zařízení s telemetrií (světlo, výstup) → LOCATE — fixture na plný výkon, 60 s auto-off. Klik na jiné zařízení přepne locate na něj (vždy jen jedno aktivní najednou).
• Klik na projektor → okamžité zapnutí přes PJLink + zobrazení stavu.
• Klik na PlayX box → TEST KARTA — zkušební obrazovka s popiskem (Manager doplní automaticky: přátelské jméno + zóna, např. „PLAYER · Sál"), 60 s auto-off. Alt+klik přidá zkušební tón (440 Hz).
• Odznak s odpočtem nad zařízením ukazuje zbývající čas do auto-off (nebo „AKTIVNÍ" u blackoutu, který auto-off nemá).

Hromadné povely (panel zóny v SERVIS módu, nebo REST na celou zónu/instalaci): VŠE ROZSVÍTIT (nastavitelná intenzita), BLACKOUT, VŠECHNY OBRAZOVKY (test karta na všechny PlayX boxy najednou). Offline zařízení se v odpovědi vrátí zvlášť, nezastaví zbytek dávky.

Guard — servisní povel během živé show. Pokud na zařízení právě běží playlist v SHOW módu, servisní povel vrátí 409 show_running — dashboard i lokální web UI na to zareagují potvrzovacím dialogem a při souhlasu povel zopakují s force:true. Bez potvrzení se show nikdy tiše nepřepíše servisním povelem.

curl -X POST http://manager:4080/api/devices/<deviceId>/action \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"action":"service_locate","params":{"deviceId":"<fixtureId>"}}'

Přímo na krabičce (bez Manageru): příručka §25.5 (Runtime) a §26.14 (PlayX).

32.9c AKCE módů — rychlé operátorské akce

Akce je pojmenovaný povel „stiskni tlačítko → něco se stane v zóně" — na rozdíl od módu (§32.9), který přepíná celou instalaci do jiné varianty provozu, akce cílí na jednu zónu a je určená k rychlému zásahu za provozu (bleskový efekt, ambientní zvuk zapnout/vypnout), ne k plánovanému přechodu.

Slotový model. Každý mód má 12 pevných slotů (stejný počet jako PlayX má fyzických tlačítek, §26 — sjednoceno záměrně). Slot buď ukazuje na jednu akci z katalogu instalace, nebo je prázdný. Tlačítka na pultu jsou vždy na stejném místě — obsah pod nimi se mění podle toho, jaký mód je zrovna aktivní.

• Momentární (symbol ⟳) — spustí playlist v zóně; playlist má vlastní krátké trvání a follow rule ho na konci sám vrátí zpátky na základní.
• Přepínací (symbol →) — spustí playlist a ten zůstává běžet, dokud ho neukončí jiná akce nebo změna módu.

Symboly ⟳/→ nahradily textové štítky MOMENTÁRNÍ/PŘEPÍNACÍ všude, kde se typ akce zobrazuje — katalog akcí, editor slotů, operátorský panel AKCE Manageru i oba pulty (box i PlayX).

Validace typu proti follow rules. Zařízení při každém rozeslání katalogu akcí samo ověří, jestli zvolený typ odpovídá skutečnému chování cílového playlistu — nesoulad (momentární bez návratové follow rule, nebo přepínací s automatickým návratem) je viditelný jako varování ⚠ u akce v katalogu a záznam v AKTIVITA logu Manageru. Ne hard-fail, jen upozornění na drift, typicky po úpravě playlistu v CueX Editu bez odpovídající úpravy katalogu akcí.

Konfigurační proces — čtyři kroky:

1. CueX Edit — playlisty. Nejdřív musí v show existovat playlisty, které chcete jako akci spouštět (efekt s follow rulí zpátky na základní, nebo přepínací ambientní stopa) — stejný editor jako pro běžnou show, §7–§14.
2. Manager — katalog akcí. Dashboard instalace → panel MÓDY → přepínač UPRAVIT → sekce Katalog akcí: název, typ (momentární/přepínací), a mapování zóna → playlistId.

3. Manager — sloty per mód. V témže UPRAVIT režimu, editor slotů pro vybraný mód: mřížka 12 polí, každé s výběrem „— prázdný —" nebo jedna z akcí katalogu.

4. Provoz. Akci spustí kdokoliv, kdo má přístup k pultu (viz níže), dashboard (POST .../actions/trigger), OSC gateway, nebo MCP (action_trigger). Mód bez slotů zobrazí na pultu jen hlášku „Tento mód nemá akce".

Pulty — kde akce zmáčknout. Runtime box i PlayX box mají vlastní webovou obrazovku pro dotykáč/tablet, na dvou adresách:

Adresa	Co ukáže
http://<ip-zařízení>:<port>/pult	Řízený panel — 12 slotů AKCE aktivního módu (popisky+barvy dle typu, prázdné šedé). Bez fleet konfigurace ukáže playlisty solo boxu místo akcí.
http://<ip-zařízení>:<port>/pult/lokalni	Vždy syrové playlisty té konkrétní krabičky, se stálým výstražným pruhem — obchází AKCE úplně. Z /pult sem nikdy nevede odkaz.

Každé zařízení má jinou adresu — /pult na jednom boxu ovládá jen zóny/zařízení, které TOTO zařízení fyzicky obsluhuje, ne celou instalaci. Adresy a QR kód obou pultů najdete na operátorském webu, panel „Pulty" — QR se generuje přímo na zařízení, stačí ho vyfotit tabletem a otevře se /pult.

Vstupy do akcí — čtyři cesty ke stejnému výsledku:

• Tablet/dotykáč na /pult (doporučeno) — HTTP, běžný prohlížeč.
• ControlX (mobilní OSC ovladač) — stejná OSC adresa jako gateway níže.
• GPI vstup (fyzické tlačítko/spínač na boxu) — §28.1.
• OSC přímo na gateway box — /cuex/action <n> (n = 1–12, slot aktivního módu). Gateway slot vyhodnotí lokálně (funguje i bez Manageru) a sám rozešle výsledek ostatním zařízením. Protokol: docs/osc-namespace.md §„AKCE".

Bezpečnost — proč dětský mód nemůže ukázat hororová tlačítka. Sloty patří módu, ne pultu. Pult vždy vykresluje sloty aktuálně aktivního módu — pokud mód „Program pro školy" nemá jedinou hororovou akci namapovanou, tlačítko BLESK/HOROR se na pultu fyzicky neobjeví, ať už obsluha zkusí cokoliv. Přepnutí mezi módy je samostatný, viditelný krok (§32.9) — nikdy vedlejší efekt zmáčknutí akce.

32.10 Plán zóny — editace a export do CueX Editu

Zóna v Manageru může mít plán — seznam zamýšlených zařízení z katalogu typů (panel zóny na Mapě, sekce PLÁN). Tento plán je jednosměrně předatelný do CueX Editu jako soubor .cuexplan, který v Editu založí odpovídající park zařízení — bez nutnosti je zakládat ručně a hledat DMX adresy.

Plánovaná položka bez zařízení se na mapě kreslí šrafovaně (viz „přízrak" v §32.8b) — v každé zóně, i takové, která už má reálná zařízení; přidání, úprava nebo smazání položky v panelu se na mapě promítne okamžitě, bez čekání na příští obnovení.

Editace plánu přímo v panelu (bez REST/agenta):

• + PŘIDAT (v hlavičce sekce PLÁN) — formulář: typ z katalogu (ikona + název), název (předvyplněný podle typu a pořadí, např. „PAR", pak „PAR 2"), počet 1–20 (vloží víc kusů najednou, očíslované), volitelná poznámka.
• ✎ u řádku plánu — inline úprava jména/poznámky.
• ✕ u řádku plánu — smaže položku (s potvrzením).
• Duplikovat zónu — tlačítko v panelu zóny, viditelné jen v režimu úprav stromu zón (přepínač UPRAVIT); zkopíruje celý plán do nově pojmenované zóny.
• Zóna bez plánu zobrazí místo prázdné sekce NAVÍC nápovědu s vlastním tlačítkem + PŘIDAT.

Sekce NAVÍC — zařízení, která se hlásí, ale nejsou v plánu. Hlavička sekce nese celý vysvětlující text „NAVÍC — v realitě, chybí v plánu" místo dřívějšího holého „NAVÍC (n)", plus viditelná nápovědná řádka pod ní (ne jen tooltip při najetí myší). Řádek s rozpoznaným typem zařízení má tlačítko „PŘIDAT DO PLÁNU" — jedno kliknutí založí odpovídající plánovanou položku a spáruje ji s existujícím zařízením hned při dalším přepočtu diffu. Nerozpoznaný typ místo tlačítka nabídne značku „?" s odkazem na ruční založení v sekci PLÁN.

Export z Manageru:

1. Otevři panel zóny na Mapě → tlačítko EXPORT PLÁNU v hlavičce sekce PLÁN
2. Stáhne se soubor plan-<zóna>.cuexplan (JSON: verze, název zóny, seznam položek s planId/typeId/name, u DMX typů i dmx.channels+fixtureType)

Nebo přes MCP (AI agent): plan_export {installationId, zoneId}.

Import do CueX Editu:

1. Projekt ▾ → Import plánu zóny…
2. Vyber stažený .cuexplan soubor
3. Zobrazí se náhled: počet zařízení, rozpoznané typy, položky k přeskočení (neznámý typ nebo typ bez odpovídajícího zařízení v Editu, např. „S-Play Mini" nebo samotný „CueX Box") a shody jména s existujícími zařízeními (jen informativní, neblokuje import)
4. Importovat — založí zařízení: DMX adresy se přidělí sekvenčně od první volné (doladíš v Device manageru), přehrávače dostanou výchozí šablonu podle typu (Svipr HD → OSC šablona, ostatní přehrávače → generická UDP šablona). Každé založené zařízení nese planId plánované položky, ze které vzniklo.

Jednosměrné předání, žádný sync zpět. Po importu žijí plán (Manager) a projekt (Edit) nezávisle — provozní autorita je show projekt. planId na zařízení ale nezmizí: pokud zařízení hlásí Manageru inventory (fleet phone-home), planId se propíše zpět a Manager podle něj v přehledu „Plán vs. realita" spáruje položku jednoznačně, i když se název zařízení mezitím v projektu změnil.

Kompletní koncept plánování (katalog → plán → duplikace podobných zón → import do Editu → přehled Plán vs. realita) i s návodem krok za krokem: samostatná stránka Plánování instalace.

32.11 Tabulka — inventární přehled a tisk

Záložka Tabulka (výchozí pohled dashboardu, nahradila starý Seznam) zobrazuje jednu instalaci jako jednu tiskovou tabulku, seskupenou podle zóny: fleet zařízení, koncová zařízení s telemetrií, pasivní inventory položky i plánované položky v jednom místě.

• Sloupce: Název (přátelské jméno), Kategorie (katalog + typ), Driver/adresa (dmx@N/uY / OSC / … — 🔒 needituje se tady, upravuje se v CueX Editu), Stav, Mód (aktivní mód + drift badge), Plán (OK / ČEKÁ NA INSTALACI / OK · ručně / CHYBÍ / NAVÍC — stejné pravidlo jako v panelu zóny: žádná NAVÍC položka, pokud zóna nemá plán; CHYBÍ teď znamená „bylo spárováno, pak přestalo hlásit", dosud nikdy spárovaná položka je ČEKÁ NA INSTALACI), Poznámka.
• Filtry (kombinovatelné): instalace, zóna, kategorie, „jen problémy".
• Inline editace: přeřazení zóny zařízení (výběr), jméno/poznámka plánované položky, checkbox „nainstalováno". Driver/adresa zůstává needitovatelné (🔒).
• Tisk: tlačítko „Tisk" (Cmd/Ctrl+P) — tisková šablona skryje ovládací prvky a přidá patičku s názvem instalace a datem.
• Plánované, ale nenainstalované položky se zobrazují jako „přízrak" (zešedlé, ▢ ikona).