Accessing State Updates Monitoring

The API provides a means for clients to keep up to date on state changes in Pixera. The current approach is based on a polling model so it harmonizes well with the request/reply structure of communication via JSON-RPC.

To request the current state, send the method invocation with no parameters:

Pixera.Utility.pollMonitoring

The data is maintained separately for each connection to Pixera and is stored until the client requests it. It is worth noting that this constitutes an important difference to a "pure" polling model. Using only polling in the narrow sense state changes that are not in effect at the time of the polling could be missed by the client.

In the monitoring approach taken here, though, a discrete change like adding a cue is stored as an entry for the connection and this information remains available until whichever time the client decides to request it. This allows the client to optimize the polling interval for the frequency at which it wants to process the data without having to worry that it will miss any data.

This approach also allows the data to be stored and transferred more efficiently. Assume, for example, that two cues were changed since the monitoring state was last requested. This can then be represented with a string denoting the action, "cueChanged", along with a list of cue handles that were affected. It is not necessary to transfer the "cueChanged" string for every cue.

Some of the information available via monitoring represents values that change rapidly over time, e.g. the current position of a timeline. For these changes to conceptually continuous variables, only the most recent value is retained and that value is guaranteed to be present in the next monitoring data set that is transferred to the client.

As a result, a client monitoring all timeline positions at a rate lower than any of the timelines' FPS would only have precisely the data transferred that is relevant for the update frequency it is using.

The data is flushed from memory after it was returned to the caller on a connection. This means that only information that was generated since the last polling invocation is returned and the caller does not have to be able to identify and ignore stale data.

The returned data is organized by subjects. The range of subjects will be expanded as Pixera development continues. If a client is not interested in a subject, it can send the following request, e.g. for the subject "timelinePositions":

{
  "jsonrpc": "2.0",
  "id": 31,
  "method": "Pixera.Utility.unsubscribeMonitoringSubject",
  "params": {
    "subject": "timelinePositions"
  }
}

This will remove the subject from the updates for that particular connection. The function "Pixera.Utility.subscribeMonitoringSubject" can be used to re-subscribe to a subject.

Each monitoring response has an array named "result" with one entry for each subject. Each subject has a name and an array called "entries" with information on individual occurrences.

The currently available subjects are:

• clipAdded: The entries array contains a single JSON array called "handles". It contains the handles of all clips added since the last time the monitoring results were requested for the connection.
• clipChanged: As above, but for all clips that were changed.
• clipRemoved: As above, but for all clips that were removed.
• cueAdded: The entries array contains a single JSON array called "handles". It contains the handles of all cues added since the last time the monitoring results were requested for the connection.
• cueChanged: As above, but for all cues that were changed.
• cueRemoved: As above, but for all cues that were removed.
• cueApplied: As above, but for all cues that were applied, either by way of a running timeline reaching them or by other means, e.g. an API invocation.
• timelineAdded: The entries array contains a single JSON array called "handles". It contains the handles of all timelines added since the last time the monitoring results were requested for the connection.
• timelineRemoved: As above, but for all timelines that were removed.
• timelineTransport: The entries array contains "handle" / "value" pairs. The "value" holds the transport mode, as in the parameter to Pixera.Timelines.Timeline.setTransportMode, of the timeline with the "handle".
• timelinePositions: The entries array contains "handle" / "value" pairs. The "value" gives the time in frames of the timeline with the "handle".
• timelineCountdowns: The entries array contains "handle" / "value" / "flag" tuples. The "value" gives the time in frames of the current countdown of the timeline with the "handle". If the countdown is a result of the timeline moving towards the next cue the "flag" value will be 1. If the countdown is due to the timeline pausing while the wait duration of a cue is counted down then the "flag" value will be 2.

Monitoring Event Orientation

The state access mechanism discussed above gathers together all state changes for each connection and then transfers them all at once when the client requests it, via "Pixera.Utility.pollMonitoring".

Alternatively, monitoring can be used in an event-oriented mode in which monitoring entries are sent to the client connection as soon as they occur. To change the mode, send a message of the following form:

{
  "jsonrpc": "2.0",
  "id": 32,
  "method": "Pixera.Utility.setMonitoringEventMode",
  "params": {
    "mode": "all"
  }
}

The "mode" parameter can take three values:

• none (default): Entries are never sent directly. Rather, all data is transferred as a reply to the pollMonitoring request.
• all: All entries are immediately sent. With this setting, pollMonitoring need never be called. If it is called, the result will never contain any entries.
• onlyDiscrete: In this mode, those state changes which do not involve continuously changing values are sent immediately while state changes that consist of rapidly updating a value are only delivered as a response to pollMonitoring.

Clients can recognize incoming monitoring events by the fact that they have a "type" attribute with the value "monEvent".

For example, an event communicating that a cue has been added could look like this:

{
  "jsonrpc": "2.0",
  "id": -1,
  "type": "monEvent",
  "name": "cueAdded",
  "entries": [
    {
      "handles": [
        6511533668781846
      ]
    }
  ]
}

PIXERA 26.2 | 20.May 2026 | J.B.