Skip to content

Commit 7e35bd1

Browse files
nytaminnytamin
committed
feat: add renderRequirements to manifest json-schemas
1 parent 512bb32 commit 7e35bd1

File tree

13 files changed

+359
-7
lines changed

13 files changed

+359
-7
lines changed

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,4 @@ The log below details the changes during development of this version:
1414
* 2025-03-27: Draft 0 made public.
1515
* 2025-04-23: Fix in JSON-schemas: Changed `main` property in Graphics manifest to be **mandatory**.
1616
(Before, it was defined as mandatory in the specification document, but not in the JSON-schemas.)
17+
* 2025-xx-xx: Add `renderRequirements` property to Graphics manifest

‎v1-draft-0/examples/l3rd-name/manifest.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@
44
"description": "Name lower third",
55
"id": "l3rd-name",
66
"version": "0",
7-
"main": "graphic.mjs",
87
"author": {
98
"name": "Johan Nyman, SuperFly.tv"
109
},
@@ -33,5 +32,6 @@
3332
}
3433
}
3534
},
35+
"asd": 123,
3636
"v_myLittleNote": "Vendor-specific properties can be added using the 'v_' prefix, like this!"
3737
}

‎v1-draft-0/examples/minimal/manifest.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
"name": "Minimal Test Graphic",
44
"description": "This Graphic includes the bare minimum required to be a valid OGraf Graphic. It displays a 'Hello World!' message.",
55
"id": "minimal-example",
6-
"main": "graphic.mjs",
76
"supportsRealTime": true,
87
"supportsNonRealTime": false
98
}

‎v1-draft-0/examples/ograf-logo/manifest.json‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,17 @@
33
"name": "Minimal Test Graphics",
44
"description": "This Graphic shows an OGraf logo",
55
"id": "minimal-logo",
6-
"main": "graphic.mjs",
76
"supportsRealTime": true,
87
"supportsNonRealTime": false,
98
"author": {
109
"name": "Markus Nygård, YLE"
11-
}
10+
},
11+
"renderRequirements": [
12+
{
13+
"resolution": {
14+
"width": { "min": 600, "max": 4000, "ideal": 1920 }
15+
},
16+
"frameRate": { "min": 1, "max": 240, "ideal": 60 }
17+
}
18+
]
1219
}

‎v1-draft-0/specification/docs/Specification.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,7 @@ The manifest file is a JSON file containing metadata about the Graphic. It consi
6868
| supportsNonRealTime | boolean | X | | Indicates whether the Graphic supports non-real-time rendering. If true, the Graphic MUST implement the non-real-time functions `goToTime()` and `setActionsSchedule()`. |
6969
| schema | object | | | The JSON schema definition for the parameter of the `updateAction()` function. This schema can be seen as the (public) state model of the Graphic. |
7070
| stepCount | integer | | 1 | The number of steps a Graphic consists of. |
71+
| renderRequirements | RenderRequirement[]| | | A list of requirements that this Graphic has for the rendering environment. At least one of the requirements must be met for the graphic to be expected to work. |
7172

7273
#### Real-time vs. non-real-time
7374

@@ -116,6 +117,47 @@ supports the following fields:
116117
| description | string | | | A longer description of the action. |
117118
| schema | object | | | The JSON schema definition for the payload of the action. |
118119

120+
#### RenderRequirements
121+
122+
A RenderRequirement in the manifest file is an object that describes which requirements a Graphic has for the rendering environment.
123+
The `renderRequirements` is a list of RenderRequirements, where at least one requirement must be fulfilled by the renderer for a
124+
Graphic to be expected to work.
125+
126+
The RenderRequirement object contains the following fields:
127+
128+
129+
| Field | Type | Required | Default | Description |
130+
|-------------------|------------------|:--------:|:-------:|-----------------------------------------------------------|
131+
| resolution | object | | | Object that describes resolution requirements. |
132+
| resolution.width | NumberConstraint | | | Specifies renderer width resolution requirement. |
133+
| resolution.height | NumberConstraint | | | Specifies renderer height resolution requirement. |
134+
| frameRate | NumberConstraint | | | Specifies renderer frameRate requirement. |
135+
| colorSpace | StringConstraint | | | Specifies renderer color-space requirement. Allowed values are "sRGB" |
136+
137+
##### NumberConstraint
138+
139+
A NumberConstraint is an object that describes a constraints for a numerical value.
140+
(This is inspired by https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#constraindouble)
141+
It contains the following fields:
142+
143+
| Field | Type | Required | Default | Description |
144+
|-------------------|------------------|:--------:|:-------:|-----------------------------------------------------------|
145+
| max | number | | | A number specifying the largest permissible value of the property it describes. If the value cannot remain equal to or less than this value, matching will fail. |
146+
| min | number | | | A number specifying the smallest permissible value of the property it describes. If the value cannot remain equal to or greater than this value, matching will fail. |
147+
| exact | number | | | A number specifying a specific, required, value the property must have to be considered acceptable. |
148+
| ideal | number | | | A number specifying an ideal value for the property. If possible, this value will be used, but if it's not possible, the user agent will use the closest possible match. |
149+
150+
##### StringConstraint
151+
152+
A StringConstraint is an object that describes a constraints for a textual value.
153+
(This is inspired by https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#constraindouble)
154+
It contains the following fields:
155+
156+
| Field | Type | Required | Default | Description |
157+
|-------------------|------------------|:--------:|:-------:|-----------------------------------------------------------|
158+
| exact | string | | | A string specifying a specific, required, value the property must have to be considered acceptable. |
159+
| ideal | string, string[] | | | A string (or an array of strings), specifying ideal values for the property. If possible, one of the listed values will be used, but if it's not possible, the user agent will use the closest possible match. |
160+
119161
#### Vendor-specific fields
120162

121163
Vendor-specific fields are additional fields that are not part of this specification, but used for vendor-specific means.

‎v1-draft-0/specification/json-schemas/graphics/schema.json‎

Lines changed: 82 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,13 +77,94 @@
7777
"description": "The schema is used by a Graphic to define the data parameters of the 'update' method.",
7878
"type": "object",
7979
"$ref": "https://superflytv.github.io/GraphicsDataDefinition/gdd-meta-schema/v1/lib/object.json"
80+
},
81+
"renderRequirements": {
82+
"description": "A list of requirements that this Graphic has for the rendering environment. At least one of the requirements must be met for the graphic to be expected to work.",
83+
"type": "array",
84+
"items": {
85+
"type": "object",
86+
"properties": {
87+
"resolution": {
88+
"description": "If set, specifies requirements for the resolution of the Renderer.",
89+
"type": "object",
90+
"properties": {
91+
"width": {
92+
"$ref": "https://ograf.ebu.io/v1-draft-0/specification/json-schemas/lib/constraints/number.json"
93+
},
94+
"height": {
95+
"$ref": "https://ograf.ebu.io/v1-draft-0/specification/json-schemas/lib/constraints/number.json"
96+
}
97+
}
98+
},
99+
"frameRate": {
100+
"description": "If set, specifies requirements for frame rate of the Renderer. Example: 60 fps",
101+
"$ref": "https://ograf.ebu.io/v1-draft-0/specification/json-schemas/lib/constraints/number.json"
102+
},
103+
"colorSpace": {
104+
"description": "If set, specifies requirements for the colorSpace of the Renderer.",
105+
"allOf": [
106+
{
107+
108+
"$ref": "https://ograf.ebu.io/v1-draft-0/specification/json-schemas/lib/constraints/string.json"
109+
},
110+
{
111+
"type": "object",
112+
"properties": {
113+
"exact": {
114+
"oneOf": [
115+
{
116+
"type": "string",
117+
"enum": [
118+
"sRGB"
119+
]
120+
},
121+
{
122+
"type": "array",
123+
"items": {
124+
"type": "string",
125+
"enum": [
126+
"sRGB"
127+
]
128+
}
129+
}
130+
]
131+
},
132+
"ideal": {
133+
"oneOf": [
134+
{
135+
"type": "string",
136+
"enum": [
137+
"sRGB"
138+
]
139+
},
140+
{
141+
"type": "array",
142+
"items": {
143+
"type": "string",
144+
"enum": [
145+
"sRGB"
146+
]
147+
}
148+
}
149+
]
150+
}
151+
}
152+
}
153+
]
154+
}
155+
156+
},
157+
"patternProperties": {
158+
"^v_.*": {}
159+
},
160+
"additionalProperties": false
161+
}
80162
}
81163
},
82164
"required": [
83165
"$schema",
84166
"id",
85167
"name",
86-
"main",
87168
"supportsRealTime",
88169
"supportsNonRealTime"
89170
],

‎v1-draft-0/specification/json-schemas/lib/constraints/number.json‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://ograf.ebu.io/v1-draft-0/specification/json-schemas/lib/constraints/number.json",
4+
"type": "object",
5+
"description": "The number constraint is used to specify a constraint for a numerical property. (Inspired by https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#constraindouble)",
6+
"properties": {
7+
"max": {
8+
"description": "A number specifying the largest permissible value of the property it describes. If the value cannot remain equal to or less than this value, matching will fail.",
9+
"type": "number"
10+
},
11+
"min": {
12+
"description": "A number specifying the smallest permissible value of the property it describes. If the value cannot remain equal to or greater than this value, matching will fail.",
13+
"type": "number"
14+
},
15+
"exact": {
16+
"description": "A number specifying a specific, required, value the property must have to be considered acceptable.",
17+
"type": "number"
18+
},
19+
"ideal": {
20+
"description": "A number specifying an ideal value for the property. If possible, this value will be used, but if it's not possible, the user agent will use the closest possible match.",
21+
"type": "number"
22+
}
23+
},
24+
"patternProperties": {
25+
"^v_.*": {}
26+
},
27+
"additionalProperties": false
28+
}

‎v1-draft-0/specification/json-schemas/lib/constraints/string.json‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "https://ograf.ebu.io/v1-draft-0/specification/json-schemas/lib/constraints/string.json",
4+
"type": "object",
5+
"description": "The string constraint is used to specify a constraint for a string property. (Inspired by https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#constraindomstring)",
6+
"properties": {
7+
"exact": {
8+
"description": "A string or an array of strings, one of which must be the value of the property. If the property can't be set to one of the listed values, matching will fail.",
9+
"type": "string"
10+
},
11+
"ideal": {
12+
"description": "A string (or an array of strings), specifying ideal values for the property. If possible, one of the listed values will be used, but if it's not possible, the user agent will use the closest possible match.",
13+
"oneOf": [
14+
{
15+
"type": "string"
16+
},
17+
{
18+
"type": "array",
19+
"items": {
20+
"type": "string"
21+
}
22+
}
23+
]
24+
}
25+
},
26+
"patternProperties": {
27+
"^v_.*": {}
28+
},
29+
"additionalProperties": false
30+
}

‎v1-draft-0/typescript-definitions/package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎v1-draft-0/typescript-definitions/src/apis/graphicsAPI.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import { RenderCharacteristics } from "../definitions/render";
12
import {
23
PlayActionReturnPayload,
34
ActionInvokeParams,
@@ -29,6 +30,9 @@ export interface Graphic {
2930
params: {
3031
/** Whether the rendering is done in realtime or non-realtime */
3132
renderType: "realtime" | "non-realtime";
33+
34+
/** A set of characteristics / capabilities of the Renderer, that affects how the Graphic will be rendered. */
35+
renderCharacteristics: RenderCharacteristics;
3236
} & VendorExtend
3337
) => Promise<ReturnPayload>;
3438

0 commit comments

Comments
 (0)