Guide to Custom Forms

Introduction

The form settings in Accurate Player makes it possible to create custom metadata forms for timeline markers. This can be used for a wide array of use cases, such as: Reduce the amount of metadata fields to only what is needed, use different sets of metadata fields for different rows in the timeline, or to create advanced metadata forms that fit complex business requirements.

Creating new forms settings can generally be broken down into three steps:
1. Define the metadata format using a json schema
2. Define the layout of the form with a UI schema
3. Declare which form should be used for a marker based on its row

The full documentation for the json forms settings can be found here: accurate.video/docs/install-setup/frontend-configurations/#forms

Examples

Below are a couple of examples following the outline described above.

Basic Example

First up, a basic setup with a single metadata field which apply for all markers.

Step 1: Metadata format

Defining the metadata format for this example is fairly straightforward. The root element always has to be an object, all metadata fields are defined as properties on this object. For this example there will be a single field which will be called "exampleField" and it will be a string.

The key markerDefault is used for the form in this example, the form with this key is used for all markers by default.

You can read more about the available types here: json-schema.org/understanding-json-schema/reference/type.html

Add the following to the root object in settings file:

forms: {
  markerDefault: {
    schema: {
      type: "object",
      properties: {
        exampleField: {
          type: "string",
        },
      },
    },
  },
},

Step 2: Form layout

The Next step is to define how the form should look like, this is done by defining a uischema object together with the schema object created in the previous step. Forms are made up of controls and layouts, controls represent the actual inputs for the metadata fields and layouts to define how those controls are laid out on the screen.

The root element has to be a layout element, a VerticalLayout will be used in this example which will cause the controls to be laid out vertically in the form. A control for the exampleField can then be added to the elements array of the layout. The label field on the control is used to define a human readable label to be displayed on the control. The scope field tells the control which metadata field it should correspond to, note how its value corresponds to the structure in the schema defined in the previous step.

Read more about available layout elements here: jsonforms.io/docs/uischema/layouts

Combining the uischema with the previous step results in the following:

forms: {
  defaultMarker: {
    schema: {
      type: "object",
      properties: {
        exampleField: {
          type: "string",
        },
      },
    },
    uischema: {
      type: "VerticalLayout",
      elements: [
        {
          type: "Control",
          label: "Example data",
          scope: "#/properties/exampleField",
        },
      ],
    },
  },
},

Step 3: Row assignment

When there is only a single form that is to be used for all markers there is no need to deal with row assignment. There will be more information on how to do this in the next example.

Summary

This should result in a settings file that looks something like this:

{
  forms: {
    defaultMarker: {
      schema: {
        type: "object",
        properties: {
          exampleField: {
            type: "string",
          },
        },
      },
      uischema: {
        type: "VerticalLayout",
        elements: [
          {
            type: "Control",
            label: "Example data",
            scope: "#/properties/exampleField",
          },
        ],
      },
    },
  },
}

The resulting form should look something like:
Image showing the form resulting from our settings

Field validation & multiple forms

This example explains how to set up the player with two different forms, one simple form with a single field and a more complex form with some validation rules that's assigned to markers on a specific row.

Step 1: Metadata format

Multiple forms can be defined by adding several objects to the forms array, it is important to assign unique id fields so that they can be referenced later.

The first form will contain a single name field, the second form will contain two fields with some validation rules. maxlength limits the maximum length for the string value of issue, and enum limits the values that the type field can take on to "audio", "video" or "subtitles".

The required field in the schema can be used to mark a set of metadata fields as required, users will not be able to leave those fields empty in the form.

Note that the key issueForm is used for the second form, this will be referenced in step 3.

More information about string validation rules can be found here: json-schema.org/understanding-json-schema/reference/string.html

Add the following to the settings file:

forms: {
  defaultMarker: {
    schema: {
      type: "object",
      properties: {
        name: {
          type: "string",
        },
      },
    },
  },
  issueForm: {
    schema: {
      type: "object",
      properties: {
        issue: {
          type: "string",
          maxlength: 16
        },
        type: {
          type: "string",
          enum: ["audio", "video", "subtitles"]
        },
      },
      required: ["type"],
    },
  },
},

Step 2: Form layout

A uischema has to be added to both of the forms of this example. The HorizontalLayout in the second form will cause controls to be laid out horizontally in the form, layouts can contain other layouts so it's possible to combine them to group controls in various ways.

As with the previous example the label adds human readable labels to controls and the scope field connects controls to a metadata fields.

Some metadata types support alternative input controls. Metadata fields with the enum keyword use a dropdown by default, that can be changed to display as radio buttons or an autocomplete instead using the format option on the control.

With uischema added to the forms the settings should look like this:

forms: {
  defaultMarker: {
    schema: {
      type: "object",
      properties: {
        name: {
          type: "string",
        },
      },
    },
    uischema: {
      type: "VerticalLayout",
      elements: [
        {
          type: "Control",
          label: "Name",
          scope: "#/properties/name",
        },
      ],
    },
  },
  issueForm: {
    schema: {
      type: "object",
      properties: {
        issue: {
          type: "string",
          maxlength: 16
        },
        type: {
          type: "string",
          enum: ["audio", "video", "subtitles"]
        },
      },
      required: ["type"],
    },
    uischema: {
      type: "HorizontalLayout",
      elements: [
        {
          type: "Control",
          label: "Issue",
          scope: "#/properties/issue",
        },
        {
          type: "Control",
          label: "Issue type",
          scope: "#/properties/type",
          options: {
            format: "radio",
          },
        },
      ],
    },
  },
},

Step 3: Row assignment

The form with the key markerDefault is used for all markers unless something else is specified, as with this example it can still be specified for clarity.

There is a lot that goes into marker definitions but what is important here is the row form field which controls which form gets used for markers on that row, and the tooltip getters which are used to create tooltips based on the metadata of markers.

markers: {
  groups: [
    {
      match: (marker, track) => marker?.type === "Manual" || track?.type === "Manual",
      title: "Manual",
      id: "Manual",
      alwaysShow: true,
      allowCreateTrack: true,
      trackType: "Manual",
      rows: [
        {
          match: (marker) => marker?.metadata.get("trackId") === "av:track:video:issue",
          track: "av:track:video:issue",
          title: "Notes",
          markerType: "Manual",
          order: 0,
          markerStyle: { backgroundColor: "var(--AP-PRIMARY)" },

          form: "markerDefault",
          tooltip: (marker) => marker.metadata.get("name"),
        },
        {
          match: (marker) => marker?.metadata.get("trackId") === "av:track:video:default",
          track: "av:track:video:default",
          title: "Issues",
          markerType: "Manual",
          order: 1,
          markerStyle: { backgroundColor: "var(--AP-WARNING)" },

          form: "issueForm",
          tooltip: (marker) => marker.metadata.get("type") + " issue: " + marker.metadata.get("issue"),
        },
      ],
    },
  ],
},

Summary

This should result in a settings file that looks something like this:

{
  forms: {
    defaultMarker: {
      schema: {
        type: "object",
        properties: {
          name: {
            type: "string",
          },
        },
      },
      uischema: {
        type: "VerticalLayout",
        elements: [
          {
            type: "Control",
            label: "Name",
            scope: "#/properties/name",
          },
        ],
      },
    },
    issueForm: {
      schema: {
        type: "object",
        properties: {
          issue: {
            type: "string",
            maxlength: 16
          },
          type: {
            type: "string",
            enum: ["audio", "video", "subtitles"]
          },
        },
        required: ["type"]
      },
      uischema: {
        type: "HorizontalLayout",
        elements: [
          {
            type: "Control",
            label: "Issue",
            scope: "#/properties/issue",
          },
          {
            type: "Control",
            label: "Issue type",
            scope: "#/properties/type",
            options: {
              format: "radio",
            },
          },
        ],
      },
    },
  },
  markers: {
    groups: [
      {
        match: (marker, track) => marker?.type === "Manual" || track?.type === "Manual",
        title: "Manual",
        id: "Manual",
        alwaysShow: true,
        allowCreateTrack: true,
        trackType: "Manual",
        rows: [
          {
            match: (marker) => marker?.metadata.get("trackId") === "av:track:video:issue",
            track: "av:track:video:issue",
            title: "Notes",
            markerType: "Manual",
            order: 0,

            form: "markerDefault",
            tooltip: (marker) => marker.metadata.get("name"),
            markerStyle: { backgroundColor: "var(--AP-PRIMARY)" },
          },
          {
            match: (marker) => marker?.metadata.get("trackId") === "av:track:video:default",
            track: "av:track:video:default",
            title: "Issues",
            markerType: "Manual",
            order: 1,

            form: "issueForm",
            tooltip: (marker) => marker.metadata.get("type") + " issue: " + marker.metadata.get("issue"),
            markerStyle: { backgroundColor: "var(--AP-WARNING)" },
          },
        ],
      },
    ],
  },
},

This is how the resulting player will look like: Image showing the entire player

Tips & Tricks

It's possible to have markers assigned to different timeline rows based on data entered into the form, similar to how tooltips reference data from the form. For the second example it would be possible to add rows for each of the different types of issues and assign markers among them by changing the match function, like this:

match: (marker) => marker?.metadata.get("type") === "audio",

Json forms has a powerful rules system which allows controls to be hidden or disabled depending on values in the underlying metadata, there's more information available about that here: jsonforms.io/docs/uischema/rules

Json forms also provides a wide array of examples on how to set up different types of forms over here: jsonforms.io/examples/basic

Obtaining logs from Accurate.Video for creating support tickets. JSON Forms Documentation