Skip to content

Commit

Permalink
updates after meeting 2025-01-14
Browse files Browse the repository at this point in the history
  • Loading branch information
@nytamin
nytamin committed Jan 15, 2025
1 parent 591f45f commit 436c615
Show file tree
Hide file tree
Showing 19 changed files with 1,393 additions and 1,058 deletions.
150 changes: 115 additions & 35 deletions WIP-notes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,50 +4,41 @@ _This is a document where we can scribble down notes while working on this defin

---

- We should split the manifest into { info, manifest }

* We should split the manifest into { info, manifest }

* Should we aim for frame accuracy?
- Should we aim for frame accuracy?
Discussion: Probably not. HTML rendering is best-effort. ref: https://spxgc.tawk.help/article/help-config-renderer#bottom


* Batch commands, to guarantee that they will be executed on the same frame in multiple Graphics
* Will it be enough to be able to batch "invokeAction" commands, or do we need to consider other commands?
- Batch commands, to guarantee that they will be executed on the same frame in multiple Graphics \* Will it be enough to be able to batch "invokeAction" commands, or do we need to consider other commands?
Discussion: Probably not.


## Uploading Graphic File


* Can it be a zipped file?
* Can file size be a problem?
* Should the upload url contain :id/:version? (Since it can be read from the file itself)

- Can it be a zipped file?
- Can file size be a problem?
- Should the upload url contain :id/:version? (Since it can be read from the file itself)

## Graphic

* Do we need to provide a base url to the GraphicInstance on load? So that it knows from where to load resources.
* Should the Graphic WebComponent be added to the DOM before or after calling the load() method?

- Do we need to provide a base url to the GraphicInstance on load? So that it knows from where to load resources.
- Should the Graphic WebComponent be added to the DOM before or after calling the load() method?

* A Question about positioning:
Should we render Graphics in full frame or in a container?
- A Question about positioning:
Should we render Graphics in full frame or in a container?

Conclusion: Graphics should be rendered in full frame, ie they take up the entire screen.
If a Renderer wants to handle transition logic and advanced composition, it can do so by communicating with the Graphics using vendor specific methods.
Conclusion: Graphics should be rendered in full frame, ie they take up the entire screen.
If a Renderer wants to handle transition logic and advanced composition, it can do so by communicating with the Graphics using vendor specific methods.

blog post: Need to communicate between difference Graphics? - use LocalStorage!

* How to handle non-realtime graphics?
- How to handle non-realtime graphics?

* Thumbnails?

* Graphic Capabilities, Renderer properties
dimensions, GPU acceleration

* Graphics in hierarchy? paths?
- Thumbnails?

- Graphic Capabilities, Renderer properties
dimensions, GPU acceleration

- Graphics in hierarchy? paths?

export graphic - mainly used BY the Graphic itself in renderer

Expand All @@ -56,8 +47,7 @@ RenderTarget - intentionally vague
Renderer Status - vendor specific?

Scope:
GraphicsInstance - OK.

GraphicsInstance - OK.

Should it be webComponent?
We'd need to explain it well, and provide examples.
Expand All @@ -70,12 +60,102 @@ Scope:
Should we have the Renderer as a MUST
question of scope: Will vendors implement separate Renderers?


standard methods:
* play: "animate in"
* update: "update state"
* continue?
* step x?
* stop: "animate out"
standard methods:
_ play: "animate in"
_ update: "update state"
_ continue?
_ step x? \* stop: "animate out"

* infer state-based data?

Notes from 2015-01-15:

- For non-realtime: in & out animation durations
AE: "Protected Regions" for in & outs
The durations are 99% fixed and wont change.

it should be okay to add this to the manifest

- AE uses "xxxLocalized" in their schema
- content credentials (for AI created content)?
- Style changes mid-show
- Redundancy

Extensible graphic
Standard graphic

manifest:
{
actions: {
update: { // should be called before play
label: 'Update',
schema: {
data
}

returns: {
stepCount: number
currentStep: number
}
},
play: {
label: 'Play',
animationDuration: number
schema: null
},
stop: {
label: 'Play',
animationDuration: number
schema: null // or obj
},

step: { // play is essentially a step to 1
label: 'Step',
animationDuration: number
schema: {
type: 'object',
properties: {
// jump to step
// advance x steps forward/backward
// (no anination)
// play next step (with animation)

absoluteStep?: number
deltaStep?: number
animate: boolean
}
}
},
return {
currentStep: number // is 0 if step resulted in animate out
}


}
properties {
isStandardTemplate: true
stepCount: number
}

}

step() // continues
step(param) // step to that step

continue(nextStep) // animates out, if its on the last step

play==in
stop==out

tuomos slides:
fire-and-forget
update+in
stepCount=0
in-and-out in -- hold -- out
update+in+out
update+step(1)+step(0)
stepCount=1
multi-step-template
update+in+next+next+next+out
update+in+next+out
stepCount=2+
10 changes: 4 additions & 6 deletions definition/definition/GraphicsAPI.md
View file
Original file line number Diff line number Diff line change
@@ -1,22 +1,20 @@
# Graphics API

The Graphics API is a javascript interface between the Renderer and the Graphics (a [Web Component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)).
The Graphics API is a javascript interface between the **Renderer** and a Graphic (a [Web Component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)).

**TO BE WRITTEN. CURRENTLY A WORK IN PROGRESS CAN BE FOUND IN [../derived/typescript](../derived/typescript/README.md)**

Graphics are rendered in full-frame, ie they take up the entire screen.


It is recommended that Graphics SHOULD be designed to be responsive, ie support multiple resolutions and aspect ratios.


## Definition of a Graphic

A Graphic consists of the following files:

* **manifest.json** - A JSON file containing metadata about the Graphic. See XYZ for more information.
* **graphic.mjs** - A javascript file containing the Graphic class. See XYZ for more information.
* **resources** - (optional) A folder containing any resources used by the Graphic, such as images, videos, fonts, etc. The resources folder MAY contain sub folders.
- **manifest.json** - A JSON file containing metadata about the Graphic. See XYZ for more information.
- **graphic.mjs** - A javascript file containing the Graphic class. See XYZ for more information.
- **resources** - (optional) A folder containing any resources used by the Graphic, such as images, videos, fonts, etc. The resources folder MAY contain sub folders.

A Graphic MUST include the **manifest.json** and the **graphic.mjs** files (using these exact file names).
A Graphic MAY include a **resources** folder, it can be omitted if the Graphic does not use any resources.
Expand Down
80 changes: 38 additions & 42 deletions definition/definition/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,85 +2,81 @@

_This folder will contain the definitions in the form of text and JSON Schemas._





# Introduction & Overview

## Overview


The **Graphics Definition** is a specification to allow for interchangeable Graphics, Rendering Systems or Controllers in a broadcast environment.

_For certain definitions, see the [Glossary](/definition/definition/Glossary.md)_.

There are three main components in the **Graphics Definition**:

### The Editor

"A HTML template editor"
* A client or system where an end-user can create and edit **Graphics**.
* Uploads compiled **Graphics** to the **Server**

- A client or system where an end-user can create and edit **Graphics**.
- Uploads compiled **Graphics** to the **Server**

### The Controller

"A user-facing interface"
* Discovers available **Graphics** using the **Server**
* Displays an interface to a user using information about the **Graphics**
* Sends playout commands to **Renderers** (via the **Server**)

- Discovers available **Graphics** using the **Server**
- Displays an interface to a user using information about the **Graphics**
- Sends playout commands to **Renderers** (via the **Server**)

### Server
"A web-server"
* Stores and exposes **Graphics**
* Exposes an API for discovering **Graphics**
* Exposes an API for controlling **Renderers**
### The Rendering System

### Renderer
"A Web page"
* Acts on playout commands from the Server
* Fetches **Graphics** from the Server and renders them in a DOM
* Is a "Web page"
* Holds the state of the Graphics
A rendering system generally consists of a web-server and a Renderer.

*
The Controllers and Editors connect to the web-server using the **Server API**, to handle things like

_Note: Some vendors may choose to bundle a Renderer / Server into a single system._
- Managing **Graphics** (upload, delete etc).
- Discovering **Graphics**
- Controlling **Renderers**

The Rendering system is responsible to handles one or more **Renderers**. A Renderer is essentially a web page that:

- Acts on playout commands from the Server
- Fetches **Graphics** from the Server and renders them in a DOM
- Is a "Web page"
- Holds the state of the Graphics

_Note: Some vendors may choose to bundle a Renderer / Server into a single system._

### Intention and Scope

The **Graphics Definition** is created using the following principles:

* The **Graphics**, **Server**/**Renderer** and **Controllers** should be interchangeable.
* The Definition should _not_ define the internals of the **Graphics**, **Renderers** or **Controllers** - that's up to the vendors.
* The Definition should define the _interfaces_ between the **Graphics**, **Renderers** and **Controllers**.
* The Definition should allow for vendors to extend the defined APIs to provide vendor-specific functionality while still being compatible with the Definition.
* The Definition strives to be forwards and backwards compatible.
- The **Graphics**, **Rendering system** and **Controllers** are interchangeable.
- The Definition should _not_ define the internals of the **Graphics**, **Rendering system** nor **Controllers** - that's up to the vendors.
- The Definition should define the _interfaces_ between the **Graphics**, **Rendering system** and **Controllers**.
- The Definition should allow for vendors to extend the defined APIs to provide vendor-specific functionality while still being compatible with the Definition.
- The Definition strives to be forwards and backwards compatible.

### About the definitions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).


### API Definitions

The **Graphics Definition** consists of the following parts:

* Server API ([LINK](/definition/definition/ServerAPI.md))
* Renderer API ([LINK](/definition/definition/RendererAPI.md))
* Graphics API ([LINK](/definition/definition/GraphicsAPI.md))




The **Graphics Definition** consists of these two parts:

- Server API ([LINK](/definition/definition/ServerAPI.md))
- Graphics API ([LINK](/definition/definition/GraphicsAPI.md))

## To Vendors

Looking to implement a Graphic, a Server/Renderers or a Controller?
Looking to implement a Graphic, a Rendering system or a Controller?
Here are a few tips and tricks useful for you!

* Looking to extend the API? To ensure that you're compatible with future versions of the Graphic Definition, **always prefix your methods, properties or endpoints** with "_VENDORNAME" (ie beginning with underscore, then your vendor name).
* Look at the reference implementations for inspiration.
* Use the tools (TBD) to verify that your
- Looking to extend the API? To ensure that you're compatible with future versions of the Graphic Definition, **always prefix your methods, properties or endpoints** with "\_VENDORNAME" (ie beginning with underscore, then your vendor name).
- Look at the reference implementations for inspiration.

### For Graphics Developers

Looking to develop a **Graphic**? Read this Getting Started Guide.

- Use the tools (TBD) to verify that your
Loading

0 comments on commit 436c615

Please sign in to comment.