Project Topology

The main bulk of a project lives within a Yjs Document. The structure of the document can be seen in our Typescript type here: https://github.com/Vija02/TheOpenPresenter/blob/main/packages/base-plugin/src/types.ts

Here's how a project document might look like:

{
  "meta": {
    "id": "project_01j96y7vz1f5c9pphfx0nkqg6h",
    "name": "Test Project",
    "createdAt": "2024-10-02T15:40:36.706Z"
  },
  "data": {
    "scene_01j9c3wn6mfcpafk2ee8jwcw5t": {
      "name": "Audio Recorder",
      "order": 1,
      "type": "scene",
      "children": {
        "plugin_01j9c3wn6mfcpafk2eecfj37s5": {
          "plugin": "audio-recorder",
          "order": 1,
          "pluginData": {
            "recordings": [],
            "activeStreams": []
          }
        }
      }
    },
    "scene_01j9740ysfemzsdyvqn2pyhb5m": {
      "name": "Radio",
      "order": 2,
      "type": "scene",
      "children": {
        "plugin_01j9740ysge6wv45h29rqkddtt": {
          "plugin": "radio",
          "order": 1,
          "pluginData": {
            "url": ""
          }
        }
      }
    }
  },
  "renderer": {
    "1": {
      "currentScene": "scene_01jbf18xagf24a30sf1wvf19wh",
      "overlay": null,
      "children": {
        "scene_01j9740ysfemzsdyvqn2pyhb5m": {
          "plugin_01j9740ysge6wv45h29rqkddtt": {
            "volume": 0.05,
            "isPlaying": false
          }
        },
        "scene_01j9c3wn6mfcpafk2ee8jwcw5t": {
          "plugin_01j9c3wn6mfcpafk2eecfj37s5": {}
        }
      }
    }
  }
}

Some parts of this document might still change. Particularly around meta and renderer

ID

All ID inside our document should be a TypeID. Notice that they are also prefixed with strings like scene, plugin and project.

Meta

The meta object stores any meta information about the project. It is quite basic at the moment but we may add more things in the future.

Data

The majority of information is stored in the data object. A project can contain many scenes.

Scene

A scene controls what is shown in a single view. It contains one or more plugins.

Plugin

Each plugin is responsible for a specific functionality. Eg: Video playing. You can include multiple plugin inside a single scene.

For example, you may have a plugin to show a moving background. And then use another plugin to show text on top of it.

Crucially, each plugin can store its own data in the document. This data will be used by the Renderer to render the right things.

Renderer

Multiple Views

A project have many views at any single time. This is useful to show different views to multiple screens. For example, to be used as a confidence monitor.

This is the first level under renderer.

Active scene

Each view will show the scene that is set in the currentScene property.

Meanwhile, the overlay property is used to override/overlay the view with something else like a black screen.

Children

The children property maps the scenes and plugins that exists in data. Correspondingly, each plugin is responsible for the data that is stored inside those properties.

While we have the concept of views and active scenes, a plugin does not have to strictly obey them. For example, an song player plugin probably wants to keep playing across scenes. However, we encourage to keep crossovers to the minimum.

Custom state in data vs renderer

So there are 2 location where plugin can store their state. When should you store state in data vs renderer?

If your data will be the same across views, they should be stored in data.

If your data will be different across views, they should be stored in renderer.

For example:

A lyrics plugin may store its songs in the data property. However, it may choose to store the display information in the renderer property. This allows users to show different lyrics of the same song in screens within the same plugin.