Metadata for Templates

General
,
1

At our improvised Open Source Meetup, that actually only was a Caspar Meetup, we briefly discussed a way to add metadata to templates to allow a client to present an adapted user interface. Flash templates used to have a simple XML based way to do just that. HTML templates currently miss this feature.

One of my clients is AVECO, a company that does studio automations. Back in Flash days we used a slightly modified version of that XML and their software extracted the XML from the Flash template. In HTML we simply use a separate XML file with the same content.

The definition in Flash looked like that:

private const customParameterDescription:XML = 	
<parameters>
	<parameter id="Titel" type="string" info="Titel der Grafik" />
	<parameter id="LastUpdated" type="string" info="Stand, Monat & Jahr" />
	<parameter id="Person" type="string" info="Legende: Personen" />
	<parameter id="Value01" type="string" info="Die Werte als | separierter String" />
	<parameter id="Value02" type="string" info="Die Werte als | separierter String" />
	<parameter id="Value03" type="string" info="Die Werte als | separierter String" />
	<parameter id="Value04" type="string" info="Die Werte als | separierter String" />
	<parameter id="Value05" type="string" info="Die Werte als | separierter String" />
</parameters>;

The problem with this XML was, that it only could have 3 attributes, id, type and info. So everything needed to fit into this. While id is the name of the field and type defines the type of the data (and in Flash was by default string), only info can be used for something descriptive, like a tool-typ or the like.

Going from there we then defined a bunch of types and how they will be displayed in the UI (also noted, what the info attribute is for):

type="string"
Standard dynamic field. Displayed as a textbox. Info attribute: Tooltip.

type="integer"
Displayed as a textbox (or up/down box etc.) with input restricted to whole numbers (integers). Info attribute: Tooltip.

type="real"
Displayed as a textbox with input restricted to numbers with a fractional part. Info attribute: Tooltip.

type="image"
File URL. Displayed as browse for file dialog, restricted to image files (PNG, JPEG, Targa etc.). Info attribute: Tooltip.

type="clip"
Name of a video-clip or image file placed in Caspar’s media folder. Comes as relative path to the media folder (with / as separator) Use the CLS command to obtain a list from the server. Info attribute: Tooltip.

type="list"
A choice of predefined values. Displayed as Combo box. Info attribute: semicolon ; separated list of possible values.

type="color"
Hexadecimal color value (like: #61138e) Displayed as color dialog. Info attribute: Tooltip.

type="filename"
File URL. Displayed as browse for file dialog. Info attribute: Tooltip.

That is more or less what I currently have. There are a lot of extensions to this specification, like support for datetime or timespan values, restricting input (for numbers etc.) and the like. As we can add other attributes to the XML or we could use JSON, many things are possible.

The discussion is open.

2 Likes
3

Thanks Didi!
I’ll be ironing out my JSON-schema-based proposal within the next week, which I hope we can use as a basis for further discussions :slight_smile:

3 Likes
4

Great. Does nodecg do anything already that supports this?

5

No, currently not, but that could also be something worth considering. In older versions we had INFO TEMPLATE, that just returned this metadata. Would be nice to bring that back in a more polished version.

1 Like
6

You can implement this now by adding a “template” subfolder in the data folder with the same file structure as your templates (but instead of htmls would have the ftd files with json data)
Using DATA LIST “TEMPLATE” and DATA RETRIEVE “TEMPLATE/PATH/TO/TEMPLATE/FILE” you can list fetch and even save the parameters for your templates from your custom clients. I even store thumbnails for the templates within the json.

2 Likes
7

I was also present at the IBC meeting and there we also discussed the current SPX template definition specification and its potential suitability for the task.

A short example of a dropdown ftype:

// Example dropdown template field

  {
      "field": "f1",
      "ftype": "dropdown",
      "title": "Select logo scaling",
      "value": "0.3",
      "items": [
          {
              "text": "Tiny logo",
              "value": "0.3"
          },
          {
              "text": "Huge logo",
              "value": "1.2"
          }
      ]
  }

Happy to discuss this :+1:

You can try SPX online or download it from spx.graphics or see the project on Github.

2 Likes
8

Hi, primary author of NodeCG here. I’m keeping an eye on this thread and on GitHub - SuperFlyTV/GraphicsDataDefinition in particular. I have thoughts on how NodeCG might implement such a specification, once it is ratified.

1 Like
9

It took longer than i initially hoped, but I think it’s in a good-enough state now to receive some proper critique…

Here’s the draft for a definition/specification of JSON data interchange with Graphics templates:

The current state is… Well, that everything is a subject for discussion (including the naming of the specification), so feel free to open issues on Github to ask/discuss certain things, or talk here.

I especially need help with adding more “gddTypes” (special/custom input types)!

Some background:
This is intended to not be exclusive to CasparCG, but other HTML-based renders as well.
Furthermore, it is also intended to be useable by different types of playout-clients (not only web-based), therefore it is written in a language/platform-agnostic way.

2 Likes
10

Just gave it a quick read. Good job!

Some quick notes:

Should the definition provide for optional resolution and framerate information (e.g. designed for fixed 1080 or responsive, designed for 50fps)?
Should we provide durations as frames?
All select options don’t need to be of one type so it shouldn’t decouple values. Rather:

{
    "gddType": "select",
    "gddOptions": {
        "one": {"label": "Label for one", "value": "Value for one", "type": "string"},
        "two": {"label": "Label for two", "value": 2, "type": "integer"}
    }
}

Shouldn’t color just be any supported CSS color system and value?

file-path/image-path, how about just external-resource that can be either a file path or URI?

11

This is an interesting suggestion! Could you elaborate on what would the benefit be for this / who would use this?

Personally I would say no, as I make my templates framerate agnostic (ie in milliseconds), but if you think it’s needed, feel free to submit a PR with another gddType!

I see your point, and agree with you in theory.
But to allow multiple value types (string or number) makes the default implementation of a GUI much much harder. Perhaps the solution needs to be to add the enum type as a basic type, not just a gddType. That way the default implementation will be slightly harder (have to support dropdowns) but not much (only have to support one type, except for enums).

I think there’s a benefit of having a specified color syntax, if you want to be able to use it programatically it makes things manageable.
I would be all for adding another separate gddType that stores the color as “any CSS color” though!

The reason for having this gddType is to hint to the GUI that it can display a file-picker for images.
Though honestly I just threw this in there as an example of the graceful degradation concept. We could just remove it before we hit version 1.0 if noone likes it :slight_smile:

12

In the old metadata this was included. So I would also do that. maybe it could be good to know the resolution and framerate to create thumbnails.

I don’t see the use of that either. In the end it is one variable that is set with one of these items, so I guess the type should always be the same.

I would not remove that, as it is something, that is often used in sports (player pictures) of for elections etc. I would expect the resulting string, that is sent to Caspar to be a (file-) url.

1 Like
13

The old Flash info also read from the actual settings of the file (not just the added XML) and provided originalWidth, originalHeight and originalFrameRate. Some templates are created for a specific size (and can only really scale down). I have plenty of fixed 1080 templates along with responsive ones.

I only think about these things in frames.

Let’s just ignore that typing on the dropdowns, everyone will end up having it as strings anyways since that’s the only option supported in DOM.

2 Likes
14

Yes, and it also had authorName and authorEmail. That was automatically added by the template generator and was a help to get at the person that created the template, I would add that also somehow somewhere.

1 Like
15

Hey folks!
I’ve made some progress on this, so here’s a status update:

Firstly, there is a new version of CasparCG Media Scanner with GDD-support out. For the time being the GDD-info is only accessible when querying http://localhost:8000/templates as CasparCG itself doesn’t support json-data in the TLS command.

Secondly, in the alpha version of SuperConductor, there is now support for the GDD GUI, so we should be able to start playing with this for real now!

There are a few issues & PR:s with suggestions open on the GDD-Github, feel free to join the discussion! :slight_smile:

1 Like
16

@Nytamin COOL!!! That is a good thing.

What would be the way to get at the rest of the GDD data? Will it be embedded in the template itself (how) or will a JSON file go along with the template?

17

The gdd-data can be either embedded in the html file, or as a separate json-file (referenced by the html-file.

How to define it is documented here: GitHub - SuperFlyTV/GraphicsDataDefinition

1 Like