Connecting with AutomationLink

Every radio automation software is different, to deliver the best Visual Radio experience to our client’ radiostation Visual Radio Assist needs a couple of fields at minimum to function. Here is the guide on how to connect a new radio automation software with Visual Radio Assist. Visual Radio Assist already integrates with the fields from these radio automations: Link Radio Automation .

Integration Overview

The VRA Radio Automation integration solution works best in a “PUSH” manner. This means that on a change within the radio automation, VRA must be notified as soon as possible with the up-to-date state of the Currently playing and (optionally) upcoming/playlist items. See the complete overview of a possible radio automation data flow below:

Advised flow

Delivery

VRA (Visual Radio Assist) can receive the automation data payload in several ways (file, directory watch, tcp, (web)socket, Ember+, MQTT and HTTP(s)). But after several years of integration and video-audio syncing experience the advised way to deliver data to VRA is by making a sub ms HTTP call. The API from VRA Core is accessible in the local network by HTTP and HTTPS (you have to trust the certificate bundle → Advanced Installation). Example of a push request to the VRA Core API

POST https://core.vra.local:3001/alink/software_xyz
Content-type: application/(json|xml|..)
{payload}

VRA Core is also able to process data from your Radio Automation in the Cloud / Cloud Solution, via the Automation Cloud Link with sub 5 ms latency. Therefore a webhook could be configured to deliver the latest automation data to VRA. Get in contact to discuss the possibilities.

Payload format

After making contact with VRA, the content of your payload determines the possibilities of your client within Visual Radio. Delivering for example upcoming track info is optional, but can enhance the experience in several ways. The following fields are by default parsable by and required in the Core:

Item Field	Description	Accuracy	Required in: Current	Upcoming	🔄 Video sync
Artist			✅	✅	✅
Title			✅	✅	✅
ID	Unique identifier of the item in the radio automation context	`Preferred UUID / ULID`	✅	➖	✅
Type	String describing the global type of the item (Music / Jingle / Station ID)		➖	➖	➖
Start time	Starting timestamp of the item In case of upcoming: projected starttime in the moment of generating the payload.	`\|< ms`	➖	➖	✅
In point	Offset from the original beginning of the item	`\|< ms`	➖	➖	✅
Duration	Total playable duration of the item	`\|< ms`	➖	➖	➖
Category	String describing the category of the item. (90s, 2000s, Sweep)		➖	➖	➖
Extra Fields	All other fields are made available to the client in the Meta object.
General	Not required, but can improve processing
Message ID	Unique ID of the message, to prevent double processing
Message Timestamp	Generation timestamp, in-sync with sending machine’ time	`\|< ms`			✅

You are free to implement the fields and your additions in any parsable manner. But the advised 2023 payload format is a JSON request with a payload containing the wrapper with the General fields, the current field containing an array with the currently playing item(s) (multiple main players are able to play multiple items at the same time 😉) and the upcoming items within an array (by playing-order). A full example of a generic payload can be found in the Generic HTTP Radio Automation Link docs or below. Do note that if you implement the exact same payload, the Generic Radio Automation Integration is sufficient enough (and by default available) to meet the basic needs of a radiostation client.

Example payload

POST http://core.vra.local:3002/alink/generic
Content-type: application/json

{
  "id": "{MessageID}",
  "timestamp": "{MessageTimestamp}",
  "current": [
    {
      "id": "{ID}",
      "artist": "{Artist}",
      "title": "{Title}",
      "timestamp": "{Start time}",
      "position": "{Start position / In point}",
      "duration": "{Duration}",
      "type": "{Type}",
      "category": "{Category}",
      "meta_1": "{Meta Field 1}",
      "meta_2": "{Meta Field 2}"
    }
  ],
  "upcoming": [
    {
      "id": "{ID}",
      "artist": "{Artist}",
      "title": "{Title}",
      "timestamp": "{Start time}",
      "position": "{Start position / In point}",
      "duration": "{Duration}",
      "type": "{Type}",
      "category": "{Category}",
      "meta_1": "{Meta Field 1}",
      "meta_2": "{Meta Field 2}"
    },
    {
      "id": "{ID}",
      "artist": "{Artist}",
      "title": "{Title}",
      "timestamp": "{Start time}",
      "position": "{Start position / In point}",
      "duration": "{Duration}",
      "type": "{Type}",
      "category": "{Category}",
      "meta_1": "{Meta Field 1}",
      "meta_2": "{Meta Field 2}"
    }
  ]
}

Handling character encoding

The Core API is only able to process correctly encoded and parsable UTF-8 payloads in the provided Content-type. This means that special characters (often used in artist/title strings) MUST be encoded in the way that the content format describes. Otherwise the payload won’t be processed in the AutomationLink. Interesting characters in JSON or XML payloads for example: & " ' < > / $ , ;

More info

When working with XML or JSON payloads, it is crucial to properly encode special characters in the property values. This is because some characters, such as &, ", ', <, >, /, $, ,, and ;, have a special meaning in XML and JSON formats and can cause parsing errors if not encoded properly.To encode special characters in XML, you can use character entity references. These are special codes that represent the special characters in a way that can be read by the XML parser. For instance, to encode an ampersand character (&) in XML, you can use &. Similarly, to encode a single quote ('), you can use ’, and to encode a double quote (") you can use ".To encode special characters in JSON, you can use backslashes to escape the character. For example, to encode a double quote character (") in JSON, you can use \". Similarly, to encode a backslash (\), you can use \\.It is important to properly encode special characters to avoid processing errors in the AutomationLink. If you fail to do so, the XML or JSON parser may interpret a special character as a command or instruction, causing the payload to be parsed incorrectly. This can lead to data loss or other issues that can affect the functionality of your application.By following the guidelines described above, you can ensure that your XML or JSON payloads are properly encoded and parsed without any issues, making it easier to work with and integrate your data with other systems.

Ready to ingest? Request Integration 🔌

If the radio automation software is ready to deliver the automation now playing data in the described format, let us know! We are happy to built the most feature-rich integrations with all possible radio automation software systems in the 🌎.

Mail us at integration@visualradioassist.live with the following details about how to “export” the data from the radio automation software into Visual Radio Assist:🛠️ The Content-type of the request.💬 An example payload of the export message / request, Additionally, a description could be added to provide a better understanding of the format of the payload and the supported fields.📝 Any required Instructions (preferred with screenshots) on how to make the radio automation software ready to talk with Visual Radio Assist. For example, setting up a specific Template in “settings xyz” or adding a HTTP configuration somewhere. A good example of such an complete instruction is the link with PowerStudio: Link Power Studio to Visual Radio.🔑 Testing license of the software to build a minimal testing environment for the integration.

After receiving your integration request, we will start developing the integration to get it up and running. Once completed, the “AutomationLink Integration” will be made available to users on our beta environment. We will take care of creating documentation for the integration and informing users about the new possibilities with your software. Finally we get in contact to handle the final testing together and to make sure the client can start working with the integration in production at right moment (release schedule).

New to VRA

Live broadcast

Automation triggers

Outputs

Installation requirements

Clips

Advanced

Misc

Connecting with AutomationLink

Integration Overview

Advised flow

Delivery

Payload format

Handling character encoding

Ready to ingest? Request Integration 🔌

​Integration Overview

​Advised flow

​Delivery

​Payload format

​Handling character encoding

​Ready to ingest? Request Integration 🔌

Integration Overview

Advised flow

Delivery

Payload format

Handling character encoding

Ready to ingest? Request Integration 🔌