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 .
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
jsonPOST 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
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
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).