Nebular Overlay SDK

Build, preview and maintain a repository of graphics templates for Nebular Overlay Studio.

Overlay templates are ordinary, self-contained web pages rendered over live video. A template may expose configurable values that operators can edit in Studio or update through the Overlay API while a live session is running.

Quick start

1. Create your template repository

Initialize a new directory from one of the included starter packs:

npx @nebularstreams/overlay-sdk init my-overlay-templates basic

The destination must not already exist. The command creates my-overlay-templates and copies the selected pack into it.

Available packs:

| Pack | Contents | | --- | --- | | all | The complete example catalogue. | | basic | A practical starter selection of broadcast, engagement and scoreboard templates. | | empty | One minimal empty template—the cleanest starting point for a design of your own. | | games | The gambling, game and interactive quiz templates. |

For example, to begin with every supplied template:

npx @nebularstreams/overlay-sdk init my-overlay-templates all

The newly created directory is your template repository. It is independent of the SDK package and is the folder you should place under version control.

2. Open the local Studio preview

Enter the repository and start the preview application:

cd my-overlay-templates
npx @nebularstreams/overlay-sdk preview

The command opens a local template catalogue. Select any template to edit its manifest parameters and inspect the result in the live preview. Templates are discovered directly from the filesystem, so there is no generated index to maintain. Refresh the page after adding or removing template directories.

The preview uses two loopback origins: one serves the Studio-style application and API, while the other serves sandboxed template frames. This reproduces the isolation used by the hosted Studio preview.

You may preview another directory explicitly, choose the application port, or prevent the browser from opening automatically:

npx @nebularstreams/overlay-sdk preview ./my-overlay-templates --port 4173
npx @nebularstreams/overlay-sdk preview --no-open

The template server uses the following port (4174 when the application uses 4173). Press Ctrl-C to stop both servers.

3. Create and customize templates

Each template is a directory containing an index.html presentation and a manifest.json parameter definition. Edit an included example or add a new template directory, then use the local preview to test its defaults, controls and live updates.

Refer to Authoring Templates to learn how to create new templates, and how templates are structured inside the repository you have just created.

4. Optionally install the Codex skill

The package includes a skill that teaches Codex how to create and validate Nebular overlay templates:

npx @nebularstreams/overlay-sdk skill install

Restart or refresh Codex after installation, then invoke the skill with $nebular-overlay while working inside your template repository. To replace an existing installation with the package's current version, add --force.

5. Version the repository

The initialized directory contains presentation code and metadata only. Commit it to your organization's private source-control repository using your normal workflow:

git init
git add .
git commit -m "Initialize overlay templates"

Overlay sessions, persisted parameter values, credentials and Overlay Server configuration do not belong in this repository.

Template repositories

All templates belonging to your organization live in the repository you just created.

• Your organization controls this repository and can create and maintain its templates independently from the Overlay Server.

• The Nebular Overlay Server operator can synchronize your organization's template library using the supplied administration tool.

• Where enabled by the platform operator, your organization may also trigger synchronization through the API.

Repository structure

Use folders to categorize your templates. Templates may be organized at any depth:

.
├── broadcast/
│   └── lower-third/
│       ├── index.html
│       └── manifest.json
├── gaming/
│   └── gta/
│       └── mission/
│           ├── index.html
│           └── manifest.json
└── sports/
    └── tennis/
        └── scoreboard/
            ├── index.html
            └── manifest.json

The corresponding template IDs are:

broadcast/lower-third
gaming/gta/mission
sports/tennis/scoreboard

Any directory containing index.html is treated as a template. It is therefore a leaf in the template tree: do not place other templates beneath it.

Creating or editing template

Please refer to Authoring Templates to learn how to create new templates.