Merge pull request #3 from feat/render-requirements

nytamin · nytamin · commit 0e3e0fc16687 · 2025-05-16T12:39:20.000+02:00
Add renderRequirements to manifest json-schemas
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,3 +14,4 @@ The log below details the changes during development of this version:
 * 2025-03-27: Draft 0 made public.
 * 2025-04-23: Fix in JSON-schemas: Changed `main` property in Graphics manifest to be **mandatory**.
   (Before, it was defined as mandatory in the specification document, but not in the JSON-schemas.)
+* 2025-05-16: Add `renderRequirements` property to Graphics manifest
diff --git a/v1-draft-0/examples/l3rd-name/manifest.json b/v1-draft-0/examples/l3rd-name/manifest.json
@@ -4,7 +4,6 @@
     "description": "Name lower third",
     "id": "l3rd-name",
     "version": "0",
-    "main": "graphic.mjs",
     "author": {
         "name": "Johan Nyman, SuperFly.tv"
     },
diff --git a/v1-draft-0/examples/minimal/manifest.json b/v1-draft-0/examples/minimal/manifest.json
@@ -3,7 +3,6 @@
     "name": "Minimal Test Graphic",
     "description": "This Graphic includes the bare minimum required to be a valid OGraf Graphic. It displays a 'Hello World!' message.",
     "id": "minimal-example",
-    "main": "graphic.mjs",
     "supportsRealTime": true,
     "supportsNonRealTime": false
 }
diff --git a/v1-draft-0/examples/ograf-logo/manifest.json b/v1-draft-0/examples/ograf-logo/manifest.json
@@ -3,10 +3,17 @@
     "name": "Minimal Test Graphics",
     "description": "This Graphic shows an OGraf logo",
     "id": "minimal-logo",
-    "main": "graphic.mjs",
     "supportsRealTime": true,
     "supportsNonRealTime": false,
     "author": {
         "name": "Markus Nygård, YLE"
-    }
+    },
+    "renderRequirements": [
+        {
+            "resolution": {
+                "width": { "min": 600, "max": 4000, "ideal": 1920 }
+            },
+            "frameRate": { "min": 1, "max": 240, "ideal": 60 }
+        }
+    ]
 }
diff --git a/v1-draft-0/specification/docs/Specification.md b/v1-draft-0/specification/docs/Specification.md
@@ -68,6 +68,7 @@ The manifest file is a JSON file containing metadata about the Graphic. It consi
 | 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()`.                 |
 | 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.                   |
 | stepCount           | integer            |          |    1    | The number of steps a Graphic consists of.                                                                                                                         |
+| 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.   |
 
 #### Real-time vs. non-real-time
 
@@ -116,6 +117,46 @@ supports the following fields:
 | description | string |          |         | A longer description of the action.                       |
 | schema      | object |          |         | The JSON schema definition for the payload of the action. |
 
+#### RenderRequirements
+
+A RenderRequirement in the manifest file is an object that describes which requirements a Graphic has for the rendering environment.
+The `renderRequirements` is a list of RenderRequirements, where at least one requirement must be fulfilled by the renderer for a
+Graphic to be expected to work.
+
+The RenderRequirement object contains the following fields:
+
+
+| Field             | Type             | Required | Default | Description                                               |
+|-------------------|------------------|:--------:|:-------:|-----------------------------------------------------------|
+| resolution        | object           |          |         | Object that describes resolution requirements. |
+| resolution.width  | NumberConstraint |          |         | Specifies renderer width resolution requirement. |
+| resolution.height | NumberConstraint |          |         | Specifies renderer height resolution requirement. |
+| frameRate         | NumberConstraint |          |         | Specifies renderer frameRate requirement. |
+
+##### NumberConstraint
+
+A NumberConstraint is an object that describes a constraints for a numerical value.
+(This is inspired by https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#constraindouble)
+It contains the following fields:
+
+| Field             | Type             | Required | Default | Description                                               |
+|-------------------|------------------|:--------:|:-------:|-----------------------------------------------------------|
+| 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. |
+| 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. |
+| exact             | number           |          |         | A number specifying a specific, required, value the property must have to be considered acceptable. |
+| 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. |
+
+##### StringConstraint
+
+A StringConstraint is an object that describes a constraints for a textual value.
+(This is inspired by https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#constraindouble)
+It contains the following fields:
+
+| Field             | Type             | Required | Default | Description                                               |
+|-------------------|------------------|:--------:|:-------:|-----------------------------------------------------------|
+| exact             | string           |          |         | A string specifying a specific, required, value the property must have to be considered acceptable. |
+| 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. |
+
 #### Vendor-specific fields
 
 Vendor-specific fields are additional fields that are not part of this specification, but used for vendor-specific means.
diff --git a/v1-draft-0/specification/json-schemas/graphics/schema.json b/v1-draft-0/specification/json-schemas/graphics/schema.json
@@ -77,13 +77,42 @@
             "description": "The schema is used by a Graphic to define the data parameters of the 'update' method.",
             "type": "object",
             "$ref": "https://superflytv.github.io/GraphicsDataDefinition/gdd-meta-schema/v1/lib/object.json"
+        },
+        "renderRequirements": {
+            "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.",
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "resolution": {
+                        "description": "If set, specifies requirements for the resolution of the Renderer.",
+                        "type": "object",
+                        "properties": {
+                            "width": {
+                                "$ref": "https://ograf.ebu.io/v1-draft-0/specification/json-schemas/lib/constraints/number.json"
+                            },
+                            "height": {
+                                "$ref": "https://ograf.ebu.io/v1-draft-0/specification/json-schemas/lib/constraints/number.json"
+                            }
+                        }
+                    },
+                    "frameRate": {
+                        "description": "If set, specifies requirements for frame rate of the Renderer. Example: 60 fps",
+                        "$ref": "https://ograf.ebu.io/v1-draft-0/specification/json-schemas/lib/constraints/number.json"
+                    }
+
+                },
+                "patternProperties": {
+                    "^v_.*": {}
+                },
+                "additionalProperties": false
+            }
         }
     },
     "required": [
         "$schema",
         "id",
         "name",
-        "main",
         "supportsRealTime",
         "supportsNonRealTime"
     ],
diff --git a/v1-draft-0/specification/json-schemas/lib/constraints/number.json b/v1-draft-0/specification/json-schemas/lib/constraints/number.json
@@ -0,0 +1,28 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://ograf.ebu.io/v1-draft-0/specification/json-schemas/lib/constraints/number.json",
+    "type": "object",
+    "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)",
+    "properties": {
+        "max": {
+            "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.",
+            "type": "number"
+        },
+        "min": {
+            "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.",
+            "type": "number"
+        },
+        "exact": {
+            "description": "A number specifying a specific, required, value the property must have to be considered acceptable.",
+            "type": "number"
+        },
+        "ideal": {
+            "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.",
+            "type": "number"
+        }
+    },
+    "patternProperties": {
+        "^v_.*": {}
+    },
+    "additionalProperties": false
+}
diff --git a/v1-draft-0/specification/json-schemas/lib/constraints/string.json b/v1-draft-0/specification/json-schemas/lib/constraints/string.json
@@ -0,0 +1,30 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://ograf.ebu.io/v1-draft-0/specification/json-schemas/lib/constraints/string.json",
+    "type": "object",
+    "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)",
+    "properties": {
+        "exact": {
+            "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.",
+            "type": "string"
+        },
+        "ideal": {
+            "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.",
+            "oneOf": [
+                {
+                    "type": "string"
+                },
+                {
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                }
+            ]
+        }
+    },
+    "patternProperties": {
+        "^v_.*": {}
+    },
+    "additionalProperties": false
+}
diff --git a/v1-draft-0/typescript-definitions/package-lock.json b/v1-draft-0/typescript-definitions/package-lock.json
diff --git a/v1-draft-0/typescript-definitions/src/apis/graphicsAPI.ts b/v1-draft-0/typescript-definitions/src/apis/graphicsAPI.ts
@@ -1,3 +1,4 @@
+import { RenderCharacteristics } from "../definitions/render";
 import {
   PlayActionReturnPayload,
   ActionInvokeParams,
@@ -29,6 +30,9 @@ export interface Graphic {
     params: {
       /** Whether the rendering is done in realtime or non-realtime */
       renderType: "realtime" | "non-realtime";
+
+      /** A set of characteristics / capabilities of the Renderer, that affects how the Graphic will be rendered. */
+      renderCharacteristics: RenderCharacteristics;
     } & VendorExtend
   ) => Promise<ReturnPayload>;
 
diff --git a/v1-draft-0/typescript-definitions/src/definitions/render.ts b/v1-draft-0/typescript-definitions/src/definitions/render.ts
@@ -0,0 +1,54 @@
+import { VendorExtend } from "./types";
+
+/**
+ * A RenderCharacteristics is a set of characteristics / capabilities
+ * of the Renderer, that affects how the Graphic will be rendered.
+ */
+export type RenderCharacteristics = {
+  resolution?: {
+    width: number;
+    height: number;
+  } & VendorExtend;
+  /** Which frameRate the renderer will be rendering in. Examples: 50, 60, 29.97 */
+  frameRate?: number;
+
+  // Ideas for future:
+  // webcamInputs
+  // accessToPublicInternet?: boolean // Whether the renderer has access to the public internet (so the graphic can fetch resources)
+  // keyer?: boolean; //
+
+} & VendorExtend;
+
+// These are inspired by the MediaTrackConstraints Web API.
+// see https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints
+
+export type ConstrainBoolean = {
+  /** A Boolean which must be the value of the property. If the property can't be set to this value, matching will fail. */
+  exact?: boolean;
+
+  /** A Boolean 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. */
+  ideal?: boolean;
+} & VendorExtend;
+
+export type ConstrainNumber = {
+  /** 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. */
+  max?: 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. */
+  min?: number;
+
+  /** A number specifying a specific, required, value the property must have to be considered acceptable. */
+  exact?: 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. */
+  ideal?: number;
+} & VendorExtend;
+
+/** The ConstrainString constraint type is used to specify a constraint for a property whose value is a string. */
+export type ConstrainString<T extends string> = {
+  /** 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. */
+  exact: T | T[];
+
+  /** 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. */
+  ideal: T | T[];
+} & VendorExtend;
diff --git a/v1-draft-0/typescript-definitions/src/generated/graphics-manifest.ts b/v1-draft-0/typescript-definitions/src/generated/graphics-manifest.ts
@@ -511,6 +511,25 @@ export interface HttpsOgrafEbuIoV1Draft0SpecificationJsonSchemasGraphicsSchemaJs
    */
   stepCount?: number;
   schema?: HttpsSuperflytvGithubIoGraphicsDataDefinitionGddMetaSchemaV1LibObjectJson1;
+  /**
+   * 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.
+   */
+  renderRequirements?: {
+    /**
+     * If set, specifies requirements for the resolution of the Renderer.
+     */
+    resolution?: {
+      width?: HttpsOgrafEbuIoV1Draft0SpecificationJsonSchemasLibConstraintsNumberJson;
+      height?: HttpsOgrafEbuIoV1Draft0SpecificationJsonSchemasLibConstraintsNumberJson;
+      [k: string]: unknown;
+    };
+    frameRate?: HttpsOgrafEbuIoV1Draft0SpecificationJsonSchemasLibConstraintsNumberJson1;
+    /**
+     * This interface was referenced by `undefined`'s JSON-Schema definition
+     * via the `patternProperty` "^v_.*".
+     */
+    [k: string]: unknown;
+  }[];
   /**
    * This interface was referenced by `HttpsOgrafEbuIoV1Draft0SpecificationJsonSchemasGraphicsSchemaJson`'s JSON-Schema definition
    * via the `patternProperty` "^v_.*".
@@ -540,3 +559,79 @@ export interface HttpsOgrafEbuIoV1Draft0SpecificationJsonSchemasLibActionJson {
    */
   [k: string]: unknown;
 }
+/**
+ * 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)
+ */
+export interface HttpsOgrafEbuIoV1Draft0SpecificationJsonSchemasLibConstraintsNumberJson {
+  /**
+   *  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.
+   */
+  max?: 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.
+   */
+  min?: number;
+  /**
+   *  A number specifying a specific, required, value the property must have to be considered acceptable.
+   */
+  exact?: 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.
+   */
+  ideal?: number;
+  /**
+   * This interface was referenced by `HttpsOgrafEbuIoV1Draft0SpecificationJsonSchemasLibConstraintsNumberJson`'s JSON-Schema definition
+   * via the `patternProperty` "^v_.*".
+   *
+   * This interface was referenced by `HttpsOgrafEbuIoV1Draft0SpecificationJsonSchemasLibConstraintsNumberJson1`'s JSON-Schema definition
+   * via the `patternProperty` "^v_.*".
+   */
+  [k: string]: unknown;
+}
+/**
+ * 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)
+ */
+export interface HttpsOgrafEbuIoV1Draft0SpecificationJsonSchemasLibConstraintsNumberJson1 {
+  /**
+   *  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.
+   */
+  max?: 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.
+   */
+  min?: number;
+  /**
+   *  A number specifying a specific, required, value the property must have to be considered acceptable.
+   */
+  exact?: 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.
+   */
+  ideal?: number;
+  /**
+   * This interface was referenced by `HttpsOgrafEbuIoV1Draft0SpecificationJsonSchemasLibConstraintsNumberJson`'s JSON-Schema definition
+   * via the `patternProperty` "^v_.*".
+   *
+   * This interface was referenced by `HttpsOgrafEbuIoV1Draft0SpecificationJsonSchemasLibConstraintsNumberJson1`'s JSON-Schema definition
+   * via the `patternProperty` "^v_.*".
+   */
+  [k: string]: unknown;
+}
+/**
+ * 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)
+ */
+export interface HttpsOgrafEbuIoV1Draft0SpecificationJsonSchemasLibConstraintsStringJson {
+  /**
+   * 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.
+   */
+  exact?: 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.
+   */
+  ideal?: string | string[];
+  /**
+   * This interface was referenced by `HttpsOgrafEbuIoV1Draft0SpecificationJsonSchemasLibConstraintsStringJson`'s JSON-Schema definition
+   * via the `patternProperty` "^v_.*".
+   */
+  [k: string]: unknown;
+}
diff --git a/v1-draft-0/typescript-definitions/src/main.ts b/v1-draft-0/typescript-definitions/src/main.ts
@@ -1,5 +1,6 @@
 export * as GraphicsAPI from "./apis/graphicsAPI";
 
+export * from "./definitions/render";
 export * from "./definitions/types";
 export * from "./definitions/vendor";
 import * as GeneratedGraphicsManifest from "./generated/graphics-manifest";

Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,6 @@`
`3`	`3`	`"name": "Minimal Test Graphic",`
`4`	`4`	`"description": "This Graphic includes the bare minimum required to be a valid OGraf Graphic. It displays a 'Hello World!' message.",`
`5`	`5`	`"id": "minimal-example",`
`6`		`- "main": "graphic.mjs",`
`7`	`6`	`"supportsRealTime": true,`
`8`	`7`	`"supportsNonRealTime": false`
`9`	`8`	`}`