Documentació Crea un espectacle de llums

Referència de l'API d'entorns

Tot el que un paquet d'entorn pot declarar, rebre i importar. Aquesta és la versió 1 de l'API d'entorns.

Aquesta és la referència per a qui escriu un entorn de l'espectacle de llums. Crear un entorn és el recorregut pas a pas, i Com funciona l'espectacle de llums explica d'on surten les dades.

Dins d'una mateixa versió de l'API només s'hi afegeixen coses. Un paquet escrit per a la versió 1 continua funcionant en qualsevol Rainy que parli la versió 1.

El paquet

Un paquet és un fitxer .zip:

my-show.zip
  rainy-environment.json    the manifest
  index.js                  the entry module
  style.css                 optional
  preview.jpg               the picture people choose it by
  …                         your own modules, libraries, shaders, images, fonts

El manifest és a l'arrel del zip, o dins d'una única carpeta de primer nivell, que és el que dona la baixada d'un repositori.

Límit
Mida	20 MB comprimit, 60 MB descomprimit, 500 fitxers.
Tipus de fitxer	`js` `mjs` `json` `css` `wasm`; imatges `png` `jpg` `jpeg` `webp` `avif` `gif` `svg`; tipus de lletra `woff2` `woff` `ttf` `otf`; shaders i text `glsl` `vert` `frag` `wgsl` `txt` `md`; dades `bin` `ktx2` `hdr`; multimèdia `mp3` `ogg` `mp4` `webm`.
S'ometen	Els fitxers ocults, `node_modules` i el que afegeixen els compressors (`__MACOSX`, `.DS_Store`).
Es rebutgen	Camins absoluts, `..`, enllaços, altres tipus de fitxer i tot el que superi els límits.

El manifest

rainy-environment.json:

Camp
`manifest`	obligatori	Versió del format d'aquest fitxer: `1`.
`api`	obligatori	Versió de l'API d'entorns per a la qual s'ha escrit el codi: `1`. Rainy rebutja un paquet escrit per a una versió que no parla.
`id`	obligatori	De 2 a 32 caràcters: lletres minúscules, dígits i guions, començant per una lletra. Instal·lar un paquet amb l'id d'un de ja instal·lat el substitueix. `classic` està reservat.
`name`	obligatori	Es mostra a la Configuració i a l'espectacle. Fins a 60 caràcters.
`version`	obligatori	Amb la forma `1.2.3`.
`entry`	obligatori	El mòdul que es carrega: un fitxer `.js` o `.mjs` del paquet.
`description`		Una línia per al selector. Fins a 300 caràcters.
`author`, `license`		Es mostren a la Configuració.
`homepage`		Una adreça `http` o `https`.
`styles`		Fins a 8 fulls d'estil, que es carreguen mentre l'entorn és a escena i es retiren quan se'n va. Consulta Donar estil al reproductor.
`preview`	recomanat	La imatge de la Configuració: una imatge 16:9; 960 × 540 és de sobres. Sense ella, l'entorn rep una placa en blanc.
`layout`		`stage` (per defecte) o `immersive`. Consulta Dissenys.
`requires`		Qualsevol de `webgl`, `webgl2`, `webgpu`. En un dispositiu que no en tingui algun, l'entorn no es pot triar.
`i18n`		`name` i `description` per codi d'idioma: `{ "es": { "description": "…" } }`.

La classe de l'entorn

L'exportació per defecte del mòdul d'entrada és una classe. Rainy en crea una instància quan l'entorn surt a escena. Només els quatre primers mètodes són obligatoris.

Mètode	Quan
`mount(ctx)`	Una vegada, per construir-ho tot. Pot retornar una promesa.
`update(S)`	A cada fotograma, primer: llegir l'espectacle, llançar efectes, moure les lletres.
`render(S)`	A cada fotograma, després: dibuixar.
`unmount()`	Una vegada, per alliberar el que la pàgina no pot alliberar per tu: contextos WebGL, workers, temporitzadors.
`resize(cssW, cssH, { tier, lowPower, scale })`	A cada fotograma, abans d'`update`. Surt de seguida quan no hagi canviat res. Dibuixa a `cssW × scale` per `cssH × scale`. `tier` és 0 (complet), 1 o 2 (el més lleuger).
`setScore(score)`	Ha arribat la partitura de la cançó, o ha desaparegut (`null`).
`setTrack(track)`	`{ id, title, artist, cover }` de la cançó a escena, o `null`. `cover` és l'adreça d'una imatge o `null`.
`onTrackChange()`	Ha començat una altra cançó.
`leave()`	Un altre entorn pren el relleu. La teva capa ja s'està esvaint.
`dropLyrics()`	Retira les lletres d'escena ara.

Quan un entorn falla

Rainy retira l'entorn de l'escenari, treu tot el que havia afegit i continua a Clàssic quan:

update o render llancen una excepció tres fotogrames seguits,
qualsevol altre mètode llança una excepció,
carregar i muntar triguen més de deu segons, o
l'entorn crida ctx.fail(error).

Continua retirat en aquell dispositiu fins que es recarregui la pàgina o s'actualitzi el paquet. L'error queda registrat a la consola del navegador.

`ctx`

El que rep mount.


`ctx.root`	La teva pròpia capa sobre l'escenari: un element buit que l'ocupa sencer. Els canvas i el DOM van aquí. Rainy la fa aparèixer després de `mount`, l'esvaeix quan te'n vas i l'elimina. Ignora el punter tret que posis `pointer-events` en alguna cosa del seu interior.
`ctx.lyrics`	La línia de temps de les lletres, que també arriba a cada fotograma com a `S.lyrics`.
`ctx.asset(path)`	L'adreça d'un fitxer del teu paquet. Les importacions relatives i `url()` als teus fulls d'estil també funcionen com sempre.
`ctx.ui.safeArea()`	`{ top, right, bottom, left }`, cadascun de 0 a 1: quina part d'aquell costat de l'escenari cobreix el reproductor ara mateix.
`ctx.ui.addButton({ icon, title, onClick, pressed })`	Un botó propi a la barra de l'espectacle. `icon` és marcatge SVG, de 14 píxels. Retorna `{ el, setPressed(on), remove() }`.
`ctx.ui.toast(message)`	Un avís breu.
`ctx.ui.fontFamily`	El tipus de lletra de la interfície, per al text que dibuixis tu.
`ctx.locale`	Idioma de la interfície: `en`, `ca`, `es` o `pl`.
`ctx.id`, `ctx.manifest`	El teu id i el teu manifest.
`ctx.api`	La versió de l'API d'aquest Rainy.
`ctx.fail(error)`	No pots continuar. Rainy torna a Clàssic.

`@rainy/lightshow`

L'únic mòdul de Rainy que importa un paquet.

Exportació
`API_VERSION`	`1`.
`TAU`, `clamp(v, a, b)`, `lerp(a, b, t)`, `smooth(t)`	Matemàtiques. `smooth` és un smoothstep de 0 a 1.
`hsl(h, s, l)`, `mixHue(a, b, t)`, `mixRgb(a, b, t)`, `toWhite(c, t)`	Color. Un color és `[r, g, b]`, cadascun de 0 a 255.
`rgba(c, alpha)`	Un color com a cadena CSS.
`paletteFor({ accentHue, key, mode, label, genre, swap })`	La paleta d'una secció, tal com la calcula el director. Per a quan et calen els colors d'una secció abans que soni.
`stepEase(beat)`, `altBeat(beat)`	Moviment fixat al pols: un valor que avança un pas a cada pols amb un lliscament breu, i un altre que oscil·la d'un costat a l'altre en polsos alterns.
`hash(n)`	Un nombre pseudoaleatori repetible de 0 a 1.
`floorIndex(sortedArray, t)`	Índex de l'últim element que és com a màxim `t`, o -1. Per als arrays de temps de la partitura.
`LEAD`, `HOLD_MAX`, `REST_AFTER`, `HELD`	Els temps de les lletres que comparteixen tots els entorns, en segons.
`pickTransition(F, lineIndex, last)`	Quin dels sis relleus rep una línia de lletra: `slam`, `fall`, `flicker`, `sweep`, `collapse` o `lift`. Segueix la música i no es repeteix mai dues vegades seguides.
`MIN_FLASH_GAP`, `PHRASE_BARS`	Els límits del director: segons entre flaixos complets, i compassos d'una frase.

`S`: l'espectacle

Arriba a update i a render a cada fotograma.


`S.F`	El fotograma musical. Consulta més avall.
`S.t`	El temps de la cançó en segons, suavitzat i desplaçat pel desfasament de sincronització de l'usuari.
`S.now`, `S.dt`	Rellotge real i durada del fotograma, en segons. Per a tot allò que no és música.
`S.running`	La cançó està sonant. Llança els efectes puntuals només quan soni.
`S.I`	Intensitat, de 0,3 a 1.
`S.pulse`	`{ k, s, h }`: envolupants de bombo, caixa i xarles, de 0 a 1.
`S.phrase`	Quina frase de vuit compassos de la secció és aquesta, des de 0.
`S.palette`	`{ a, b, c, w, deep }`: primari, secundari, terciari, blanc tenyit i ambient.
`S.accentHue`	To del color d'accent de l'usuari, de 0 a 360.
`S.dim`	Atenuador general, de 0 a 1. Multiplica la teva llum per ell.
`S.flash(amount, color)`	Demana un flaix, de 0 a 1. Limitat a tres flaixos complets per segon, i suavitzat amb Redueix els flaixos.
`S.blind(amount)`	Demana un encegador: un bany de blanc més lent.
`S.burst(amount)`	Demana una ràfega: un reforç que s'extingeix en aproximadament mig segon.
`S.flashAmt`, `S.flashColor`	El que cal dibuixar dels flaixos en aquest fotograma.
`S.blinderAmt`, `S.burstAmt`	El que cal dibuixar de l'encegador i de la ràfega.
`S.prefs`	La configuració de l'usuari: `reduceFlashing`, `disableLasers`, `showBgBlur`, `lowPower` (booleans) i `intensity` (`auto`, `chill`, `balanced` o `hype`).
`S.lyrics`, `S.lyricsOn`	La línia de temps de les lletres, i si les lletres són a escena ara mateix.
`S.songId`	Id de la cançó a escena.

`F`: la música

S.F, el fotograma musical.

Amb partitura, F.scripted és true i tot és exacte. Mentre una cançó encara s'analitza, Rainy estima els mateixos camps a partir de l'àudio: no hi ha anticipació (nextIn i dropIn valen Infinity), i section és una suposició.


`F.t`	El temps de la cançó en segons.
`F.bands`	`{ sub, bass, mid, high, air, rms, harm }`, cadascun de 0 a 1: energia per banda, volum, i com de tonal és el so.
`F.hits`	`{ k, s, h }`: força d'un bombo, una caixa o un xarles que ha caigut en aquest fotograma; si no, 0.
`F.beat`, `F.bar`	Números de pols i de compàs, amb decimals.
`F.beatPhase`, `F.barPhase`	Posició dins del pols i del compàs, de 0 a 1.
`F.beatInBar`	De 0 a 3.
`F.period`	Segons per pols.
`F.newBeat`, `F.newBar`	En aquest fotograma ha començat un pols o un compàs.
`F.section`	`{ idx, label, t0, t1, key, mode, energy, density }`. `label` és `intro`, `verse`, `build`, `chorus`, `drop`, `breakdown` o `outro`.
`F.sectionProgress`, `F.sectionBar`	De 0 a 1 al llarg de la secció, i compassos des que ha començat.
`F.nextSection`, `F.nextIn`	La secció que segueix, i segons fins a ella.
`F.dropIn`	Segons fins al proper drop.
`F.buildProgress`	De 0 a 1 al llarg d'una pujada.
`F.stopDepth`, `F.stopIn`	Quant s'ha entrat en un silenci, de 0 a 1, i segons fins al següent.
`F.events`	El que ha passat en aquest fotograma: `{ type, t }`, amb `type` igual a `drop`, `impact`, `stop` o `riser`.
`F.profile`	`{ genre, intensity }`. `genre` és `edm`, `pop`, `rock`, `hiphop`, `latin`, `chill` o `orchestral`.
`F.tempoConf`	Com de segur està l'analitzador del tempo, de 0 a 1.
`F.jumped`	L'usuari ha saltat a un altre punt, o ha canviat la pista. Canvia de cop, no llisquis.
`F.running`	La cançó està sonant.

La partitura

El que rep setScore: la cançó sencera de cop.


`score.duration`	Segons.
`score.tempo`, `score.period`	Polsos per minut, i segons per pols.
`score.beats`, `score.downbeats`	Temps en segons, ordenats.
`score.onsets.k`, `.s`, `.h`	Bombos, caixes i xarles: `{ t, s }`, dos arrays de la mateixa llargada amb el temps i la força.
`score.env`, `score.fps`	`score.env[band]` conté un byte per fotograma, de 0 a 255, per a cada banda de `F.bands`, a `score.fps` fotogrames per segon.
`score.envAt(band, t)`	El valor d'una banda en un instant, de 0 a 1.
`score.sections`, `score.sectionAt(t)`	Les seccions, com `F.section`.
`score.events`, `score.nextEvent(type, t, horizon)`	Els esdeveniments, com `F.events`, i el següent d'un tipus dins de `horizon` segons.
`score.beatAt(t)`, `score.barAt(t)`	Números de pols i de compàs en un instant.
`score.stopDepth(t)`	Quant s'ha entrat en un silenci en un instant.
`score.profile`	Com `F.profile`.

Les lletres

S.lyrics, la línia de temps de les lletres. Val la pena llegir-la quan S.lyricsOn és cert.


`lyrics.ready`	La cançó té lletres sincronitzades.
`lyrics.lines`	`{ t0, t1, on, end, blank, words }`. La línia surt a escena a `on`, i la seva última paraula acaba a `end`. `blank` marca una línia instrumental.
`words`	`{ text, s, e }`: una paraula, amb el seu inici i el seu final.
`lyrics.adlibs`	Els cors, separats de les línies: `{ s, e, k, words }`. `k` és un número correlatiu, útil per alternar costats.
`lyrics.aligned`	Els temps per paraula són exactes. Si no, s'estimen a partir de la llargada de la línia.
`lyrics.lineIndex(t)`	La línia a escena en un instant, o -1.
`lyrics.resting(t, index)`	Ningú no està cantant aquella línia ara mateix.
`lyrics.breakAt(t, index)`	`{ a, b }` quan hi ha una pausa instrumental en curs; si no, `null`.
`lyrics.version`	Canvia cada vegada que se substitueixen les línies: una cançó nova, o l'arribada dels temps exactes.

Dissenys

layout al manifest indica com s'organitza el reproductor al voltant de la teva capa.


`stage`	El reproductor tal com és, amb la seva caràtula, els seus controls i la seva cua. L'espectacle va al darrere.
`immersive`	L'espectacle és tota la imatge. La cua es plega i un botó de la barra la recupera per sobre de l'espectacle, la cançó i els seus controls passen a ser una targeta petita a la part inferior, i tot plegat s'atenua mentre el punter està quiet.

Donar estil al reproductor

Un entorn canvia l'estil del reproductor a pantalla completa amb els fulls d'estil que enumera a styles. Rainy els carrega quan l'entorn surt a escena i els retira quan se'n va.

Mentre el teu entorn és a escena, el reproductor té la classe ls-env-<id>. Comença totes les regles amb ella:

#fullscreen-player.ls-env-my-show .fs-progress-fill {
    background-color: rgb(var(--ls-a));
}

Classes d'estat

A #fullscreen-player:

Classe
`lightshow-on`	L'espectacle està en marxa.
`ls-env-<id>`	Aquell entorn és a escena.
`ls-immersive`	El disseny és immersiu.
`ls-idle`	Només en immersiu: el punter està quiet i el reproductor està atenuat.
`ls-queue-peek`	Només en immersiu: l'usuari ha obert la cua per sobre de l'espectacle.
`ls-lowpower`	El Mode de baix rendiment està activat. Treu els teus filtres i ombres.
`mode-modern`, `mode-standard`	El mode de pantalla completa que ha triat l'usuari. El modern té els seus propis controls. L'estàndard manté la barra del reproductor de l'aplicació a la part inferior, de manera que `.fs-player-controls` i el botó de volum estan amagats.
`layout-swapped`	La caràtula és a l'esquerra i la cua a la dreta, que és el valor per defecte. Sense ella estan al revés.

Parts

Selector
`.fs-backdrop`	La caràtula desenfocada que hi ha darrere de tot.
`.ls-env-root`	La teva capa.
`.fs-brand`	La marca de Rainy, a dalt a l'esquerra.
`#fs-volume-btn`, `#fs-lightshow-btn`, `#fs-close-btn`	Els botons de la part superior.
`.ls-hud`, `.ls-hud-btn`	La barra de l'espectacle, amb el tempo i el gènere, i els seus botons, inclosos els teus.
`.fs-content`	La caixa que conté la cançó i la cua.
`.fs-current-info`	La cançó: caràtula, títol, artista i controls. En un disseny immersiu és la targeta.
`.fs-artwork-container`	La caràtula de l'àlbum.
`.fs-title`, `.fs-artist`	El títol i l'artista de la cançó.
`.fs-player-controls`	La barra de progrés i els botons.
`.fs-progress-container`, `.fs-progress-bar`, `.fs-progress-fill`, `.fs-time`	La barra de progrés, la seva part plena i els dos temps.
`.fs-buttons`, `.fs-control-btn`, `.fs-control-btn.play-pause`	Els botons de reproducció.
`.fs-queue-container`	El panell amb la cua i les lletres.

Tot el que no és en aquesta taula és intern i pot canviar sense avís.

Variables

Variable
`--ls-a`, `--ls-b`, `--ls-c`	El color primari, secundari i terciari de la secció que està sonant, cadascun com a `r g b`. Els mateixos colors que `S.palette`.
`--ls-w`	El blanc tenyit, com a `r g b`.
`--ls-deep`	El color fosc d'ambient, com a `r g b`.
`--accent-primary`	El color d'accent de l'usuari.
`--text-primary`, `--text-secondary`, `--text-tertiary`	Els colors de text de Rainy.
`--bg-primary`, `--bg-secondary`, `--bg-tertiary`, `--bg-elevated`	Els colors de superfície de Rainy.
`--border-subtle`	El color de vora de Rainy.
`--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-full`	Radis de cantonada.
`--spacing-xs`, `--spacing-sm`, `--spacing-md`, `--spacing-lg`, `--spacing-xl`	Passos d'espaiat.
`--font-family`	El tipus de lletra de la interfície.

Fes servir una variable de la paleta com a rgb(var(--ls-a)) o, amb transparència, rgb(var(--ls-a) / 0.5). Les variables de la paleta existeixen mentre l'espectacle està en marxa, i llisquen dels colors d'una secció als de la següent.

Límits

Limita't al reproductor a pantalla completa. Les teves regles no han d'afectar res fora de #fullscreen-player.ls-env-<id>.
No amaguis ni tapis #fs-close-btn ni #fs-lightshow-btn, i mantén utilitzables els controls de reproducció.
El CSS rep la paleta, no el pols. Dibuixa a la teva capa tot el que es mogui amb la música.

Eines


`RAINY_DEV=1 RAINY_ENVIRONMENTS_DEV=<carpeta>`	Serveix paquets sense empaquetar des d'una carpeta, sense memòria cau. Cadascun apareix com un entorn amb l'etiqueta Desenvolupament, i ocupa el lloc del paquet instal·lat amb el mateix id.
`python scripts/pack_environment.py <carpeta> [-o <sortida>]`	Comprova una carpeta com un servidor comprova una pujada i escriu `<id>-<version>.zip`, a `dist` per defecte. Els mateixos fitxers donen sempre el mateix zip.
`node --import ./tests/js/sdk-hook.mjs --test <fitxers>`	Executa els tests propis d'un paquet a Node, amb `@rainy/lightshow` resolt com el resol el navegador.