Skip to content
Lyrius

Lyrius ScriptTesting

Automate the service with small scripts

TypeScript scripts that talk to Lyrius: project, tell the band, switch the lights, get the screen ready. Each one gets only the permissions it declares and runs isolated from the rest of the app.

Not ready yet. Lyrius Script is still in testing and has not been released in public versions. This page shows how it will work — the API may change until then.

How it will work

You write it in your own editor, with types and autocomplete, and install it in Lyrius as a package.

  1. 1

    Write it in TypeScript

    The @lyrius/script-sdk package brings the typed API (lyrius.songs, lyrius.stage…), mocks for testing and a small command line to get started.

  2. 2

    Declare its permissions

    In the manifest, the script says what it may do: read songs, control the stage, reach the local network. Everything else is refused.

  3. 3

    Install it in Lyrius

    Package it as a .lyrius-script file and install it in Automation › Scripts. In developer mode, every build reloads it.

  4. 4

    Run it when you need it

    From a button, a shortcut, a macro, a song's menu or a trigger: when the chorus comes in, a timer hits zero or the service starts.

Examples

Written with the API the SDK already has. Names and functions may still change before release.

Start the service

One button that opens the screen, puts the first song of the queue on air and tells the band.

Permissions: display.control, output.control, queue.read, songs.control, stage.control, notifications

src/index.ts
import { defineScript, lyrius } from "@lyrius/script-sdk";

// One button (or shortcut) that gets everything ready to start the service.
export default defineScript({
  async main() {
    await lyrius.displays.public.open(); // opens the main screen
    await lyrius.output.live();

    const [first] = (await lyrius.queue.list()).filter((item) => item.songId);
    if (!first?.songId) {
      await lyrius.ui.notify({ type: "warning", message: "The queue has no songs." });
      return;
    }

    await lyrius.songs.show(first.songId);
    await lyrius.stage.message(`Starting: ${first.title}`);
  },
});

Chorus heads-up on stage

Tied to a slide-change trigger, it tells the musicians when the chorus comes in and counts how many times it was sung.

Permissions: presentation.read, songs.read, stage.control, storage

src/index.ts
import { defineScript, lyrius } from "@lyrius/script-sdk";

// Trigger: presentation.slideChanged. Tells the band when the chorus comes in.
export default defineScript({
  async main() {
    const current = await lyrius.presentation.current();
    if (current.source !== "song" || !current.songId) return;

    const song = await lyrius.songs.get(current.songId);
    const slide = song.slides.find((s) => s.id === current.slideId);
    if (!slide || !/chorus/i.test(slide.type)) return;

    // Every script has its own storage.
    const count = (await lyrius.storage.get<number>("choruses", 0)) + 1;
    await lyrius.storage.set("choruses", count);
    await lyrius.stage.message(`Chorus (${count}) • ${song.title}`);
  },
});

Lights that follow the song

When a song starts, it sends the title to the lighting desk on the church network. The address is a script setting, adjusted inside Lyrius.

Permissions: presentation.read, songs.read, network.local

src/index.ts
import { defineScript, lyrius } from "@lyrius/script-sdk";

// Trigger: song.started. Switches the lighting scene over the church network.
export default defineScript({
  async main(context) {
    const current = await lyrius.presentation.current();
    if (!current.songId) return;

    const song = await lyrius.songs.get(current.songId);
    const url = String(context.settings.lightsUrl); // set inside Lyrius

    // Only works with the "network.local" permission in the manifest.
    await lyrius.http.post(`${url}/scene`, { scene: song.title });
    lyrius.log.info("Lighting scene:", song.title);
  },
});

The manifest

Every script has a lyrius.manifest.json: name, version, the API version it uses, its permissions and the settings shown in Lyrius.

lyrius.manifest.json
{
  "id": "org.mychurch.lights",
  "name": "Lights per song",
  "version": "1.0.0",
  "api": "^1.0.0",
  "entry": "dist/index.js",
  "permissions": ["presentation.read", "songs.read", "network.local"],
  "settings": {
    "lightsUrl": { "type": "string", "label": "Lighting desk address", "default": "http://192.168.0.50" }
  }
}

Built not to get in the way of the service

The service is live. A broken script must never freeze the presentation.

  • Sandboxed

    Each script runs in its own engine (QuickJS), apart from the app. No access to files, the shell or other programs.

  • Only what is allowed

    Calling anything outside the manifest's permissions is refused. Network only with permission, and the local network is separate from the internet.

  • With limits

    Time, memory and calls per minute are limited. A script that keeps failing is paused automatically (circuit breaker).

  • Live Lock and logs

    During the service, Live Lock can block scripts without touching the presentation. Every run is logged, with no secrets in the log.

The API

Everything lives under lyrius.* — some of the functions the SDK already has:

lyrius.presentation
next · previous · current · showSong · showSlide
lyrius.output
live · clear · black
lyrius.songs
list · search · get · show
lyrius.bible
show("jo 3 16")
lyrius.media
list · search · show · play · pause
lyrius.queue
list · addSong · remove
lyrius.stage
message · clear
lyrius.displays
public.open · stage.toggle
lyrius.storage
get · set · delete
lyrius.events
on(name, listener)
lyrius.http
get · post · request
lyrius.ui
notify

Want to try it before everyone else?

If your church has someone who codes and wants to help test Lyrius Script, get in touch.

Talk to the team