RFC: TSR Device Feedback -> Rundown (SOFIE-311)

[Julusian]

About Me

This RFC is posted on behalf of the BBC.

Use Case

As an extension of shared control it would be good to have a blueprint method that can respond to changes in the playout devices.

This method should be able to modify current and upcoming parts (potentially the whole running order?)

A sub-task of this would be to able to implement this feedback mechanism in response to HTTP response Body's in the HTTPSend and HTTPListen device.

Proposal

Note: My knowledge of shared control is limited, I believe it operates entirely inside TSR so isn’t something that sofie-core can directly build upon.

Producing events in TSR

I believe there are a few types of events that we will care about:

• When a shared control address is controlled elsewhere (including every time this state changes)
• When a shared control address returns control to sofie
• HTTPSend/Websocket message response received on certain commands

TSR should only produce events that the blueprints are interested in consuming, by default TSR should be producing no events unless the blueprints have expressed interest in them.

This opt-in/subscription could be implemented in a few ways, but we believe an important aspect of this is to let TSR perform any needed filtering (potentially inside of the tsr device threads), so that we can avoid piping numerous events back to sofie-core/blueprints before the irrelevent events can be discarded.

To achieve this, we propose that this should be defined by a new property produced alongside the rundown and rundown-baseline during ingest. Sofie will pipe this to TSR as the activate rundown changes to update the subscription. (It should also be possible to use this with the studio baseline, which may be future scope and not implemented by us)

I think there are a couple of approaches that could be taken with this. I do not know which is best at this stage, and would appreciate any input on both the implications from the perspective of blueprints or tsr.

A: Link these events to the layers/mappings

Each event will look something like:

interface TSRStateEvent {
  type: 'tsr'
  deviceId: string // eg atem0
  deviceType: DeviceType
  layerId: string // The mapping it corresponds to
  eventPath: string // the 'programInput'
  eventPayload: unknown
}

The payload and path properties will want to be strongly typed, meaning this interface may need to become a type union to make that possible

During ingest for a rundown, the blueprints should be able to declare their desire to ‘subscribe’ to events such as with:

const tsrStateSubscriptions = [
{
  deviceId: 'atem0',
  layerId: 'atem_me_program', // The mapping
  eventPath: 'programInput',
}
]

Note: these types are a rough sketch, and are not yet fully formed.

My concern here is that the current implementation of shared control does not link states back to mappings, and a particular address could be influenced by multiple mappings/layers.

B: Use the shared control addresses

Each event will look something like:

interface TSRStateEvent {
  type: 'tsr'
  deviceId: string // eg atem0
  deviceType: DeviceType
  eventAddress: string // the 'shared control address', or somethins like `me-program.1`  ?
  eventPayload: unknown
}

And subscription

const tsrStateSubscriptions = [
{
  deviceId: 'atem0',
  eventAddress: 'me-program.{{ mappings.atem_me_program.index }}', // Interpolated with options from mappings
}
]

It may be desirable to support wildcards/globs in the paths, or that may be future scope.

My concern here is that it puts the work of translating state addresses to mappings on the blueprints, but this might be fine or even beneficial as some states may not perfectly map to a single mapping anyway.

Consuming events

I think that this would be best handled by a new adlib-action like blueprint method. That would allow blueprints to easily apply changes to the current and next partinstances based on this state, using familiar methods and workflows.

But it is possible that this wont be enough, and more changes may want to be made to the rundown. For this, I would propose that this blueprint method can dispatch an ingest update that will be received as a new ‘change’ type in processIngestData. This then allows ingest blueprints to process the change however it likes, again in a process that doesn’t invent much here.

Getting the events from playout-gateway to the blueprints sounds simple, as we already have the bidirectional ddp flow, so playout-gateway will be able to dispatch events to be processed by the blueprints.

Sofie-core should perform a debounce/queue of these events, and batch them so that bursts of events don’t cause a queue of handlers. Instead the blueprints should expect to receive an array of batched events.

Future scope

While this RFC is focused on events from TSR devices, it is reasonable that in the future it may be desirable to add some other event source. The types, naming and structure should reflect this and try not to be too TSR specific. The event type itself will likely want to be a union, so that additional types can be added to it in the future.

In the future, it may be desirable to have more filtering of events based on the eventPayload, but we see this as an optimisation stage that can be added later.

Process

The Sofie Team will evaluate this RFC and open up a discussion about it, usually within a week.

• RFC created
• Sofie Team has evaluated the RFC
• A workshop has been planned
• RFC has been discussed in a workshop
• A conclusion has been reached, see comments in thread

[coderabbitai]

🔗 Related PRs

#1605 - feat: add info about AB channels (players) to LSG (SOFIE-288) [merged]
#1618 - feat: Add isRehearsal method for blueprints to use [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[ianshade]

Sounds useful to us as long as the new adlib-action like blueprint method can modify the playout persistent state. This could be used for mirroring and presenting over the LSG things like the state of PTZ cameras e.g. the zoom and focus distance, AF/MF mode - things that don't necessary belong to parts, pieces or the timeline, because we control them using TSR actions, not the timeline.

[mint-dewit]

I did have this use case in the back of my head while designing/implementing TSR Shared Control. I've always thought of the addresses themselves to remain internal to the device integrations. Instead each mapping should be able to be translated into a relevant address. Multiple mappings may resolve to the same address. If the Address State changes an event should fire for all affected mappings. If the Blueprints would be subscribed to events for any of those mappings it should receive the event.

I've mostly thought of it like that to keep the concept of "Addresses" out of the Blueprints as they are another layer of abstraction/complexity to think about. Perhaps it's not the right way though.

Perhaps an alternative is to let the integration define some "Events" in the types package and provide a hook for the integration to transform its internal AddressStates to these external events?

Types:

export type AtemEvent = Event<AtemMixEffectEvent> | Event<...>

export interface AtemMixEffectEvent {
  programInput: number
  previewInput: number
}

export function getAtemMixEffectEventKey(mixEffect: number): string {
  // note - wish there was a good way to tie these keys to the payloads but may be tricky as they are dynamic
  return `video.mixEffects.${mixEffect}`
}

Integration:

export class AtemDevice extends ... {
  ...

  getEventFromAddressStateChange(address: string, oldState: AtemAddressState, newState: AtemAddressState): AtemEvent {
    switch (newState.type) {
      case 'mixEffect':
       return {
         event: `video.mixEffects.${newState.index[0]}`
         payload: {
           programInput: newState.programInput,
           previewInput: newState.previewInput
         }
       }
    }
  }
}

Blueprints:

export const tsrStateSubscriptions = [
  {
    deviceId: 'atem0',
    eventPath: getAtemMixEffectEventKey(0),
  }
]

export function 

export function receivedEvent(context: ..., event: TSREventAny) {
  if (event.eventKey === getAtemMixEffectEventKey(0)) {
    const payload = event.payload as AtemMixEffectEvent // this is where it would be nice to have typescript infer this from the getAtemMixEffectEventKey function
   // update things for payload.programInput now...
  }
}

What might be nice about not tying into the AddressStates fully is that we could provide a context method for the TSR Integration to emit these events at will? Things like an HTTP Watcher integration might not make too much sense to implement through Shared Control

[jstarpl]

I definitely like Mint's idea of not exporting the concept of Addresses out of TSR's internals. It feels like that allows the most flexibility to the TSR's drivers and potentially being able to respond to events that are not directly state-modifying (GPI? Macro start?)