Documentation / Build a light show

Environment API reference

Everything an environment package can declare, receive and import. This is version 1 of the environment API.

This is the reference for people writing a light show environment. Create an environment is the walkthrough, and How the light show works explains where the data comes from.

Within one API version, things are only ever added. A package written for version 1 keeps working on every Rainy that speaks version 1.

The package

A package is a .zip file:

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

The manifest sits at the root of the zip, or inside a single top-level folder, which is what a repository download gives you.

The manifest

rainy-environment.json:

The environment class

The entry module's default export is a class. Rainy creates one instance when the environment goes on stage. Only the first four methods are required.

When an environment fails

Rainy takes the environment off stage, removes everything it added and continues in Classic when:

• update or render throws three frames in a row,
• any other method throws,
• loading and mounting take more than ten seconds, or
• the environment calls ctx.fail(error).

It stays off on that device until the page is reloaded or the package is updated. The error is logged to the browser's console.

ctx

What mount receives.

@rainy/lightshow

The one module of Rainy's that a package imports.

S: the show

Passed to update and render every frame.

F: the music

S.F, the musical frame.

With a score, F.scripted is true and everything is exact. While a song is still being analysed, Rainy estimates the same fields from the audio: there is no look-ahead (nextIn and dropIn are Infinity), and section is a guess.

The score

What setScore receives: the whole song at once.

The lyrics

S.lyrics, the lyrics timeline. Worth reading when S.lyricsOn is true.

Layouts

layout in the manifest says how the player is arranged around your layer.

Styling the player

An environment restyles the fullscreen player with the stylesheets it lists under styles. Rainy loads them when the environment goes on stage and removes them when it leaves.

While your environment is on stage, the player has the class ls-env-<id>. Start every rule with it:

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

State classes

On #fullscreen-player:

Parts

Anything not in this table is internal and may change without notice.

Variables

Use a palette variable as rgb(var(--ls-a)) or, with transparency, rgb(var(--ls-a) / 0.5). The palette variables are set while the show runs, and glide from one section's colours to the next.

Limits

• Keep to the fullscreen player. Your rules should not match anything outside #fullscreen-player.ls-env-<id>.
• Do not hide or cover #fs-close-btn or #fs-lightshow-btn, and keep the playback controls usable.
• CSS gets the palette, not the beat. Draw anything that moves with the music in your layer.

Tools

Related

• Create an environment
• How the light show works
• Light show environments