Welcome to RadioKit Engine’s documentation!¶

RadioKit Engine is a cloud computing platform for building multimedia, mainly audio-oriented applications. You can think about it as of “Amazon Web Services for Audio”.

Instead of building complicated infrastructure from scratch, you can take existing “building blocks” and build your app on top of them. Then RadioKit takes care about what’s hidden from the users, and you can focus on what is your core business and brings the most value to your users.

Platform is API-oriented. That means that most of the functionality is available only through programming interfaces. There are some user interfaces for management, but they show only part of the potential.

The API is mostly based on the REST API convention; so all communication with the system is done over HTTPS protocol, which is the most widely adopted Internet application protocol in the world. Data is serialized as JSON. That makes it effectively platform-independent, it does not matter what language or technology different parts of the system use, as they talk to each other with universal protocol.

Pieces composing RadioKit Engine are built as micro services. There are several backends responsible for various tasks. Technically speaking they are separate applications (although still speaking with the same protocol). That allows us to keep system modular, create derivatives that fit specific clients’ needs, use different languages for different purposes and makes system more reliable.

As most broadcasting applications have demand of high availability, we run our software only within credible, reliable datacentres and providers such as:

Heroku (the biggest Platform-as-a-Service platform, itself hosted at Amazon Web Services),
OVH (the biggest European datacentre),
Microsoft Azure (cloud computing platform from Microsoft).

It is however, possible to host it within users’ datacentre if certain technical requirements are met.

We utilize worldwide Content Delivery Network CloudFlare which provides us geocaching, speed optimization, encryption and protects the whole infrastructure from DDoS attacks.

Contents¶

Services¶

Contents:

Agenda (Schedule Manager)¶

Contents:

Broadcast Channel¶

Broadcast.Channel is a model in Agenda microservice which is a kind of superior container for broadcast streams and contents.

Broadcast channel records are accessible using Official RadioKit REST Api. The following URL should be used to obtain Broadcast.Channel records:

https://agenda.backend.url/api/rest/v1.0/broadcast/channel

Broadcast channel data¶

The following broadcast channel data fields are available for the user for index and show MVC action:

Field	Type	Description
id	UUID	Refer to: Model Common Fields.
name	string	Refer to: Model Common Fields.
slug	string
timezone	string	Timezone used for the channel
description	string	Channel’s description
media_routing_group_id	UUID
homepage_url	string	Homepage’s URL
genre	string	Channel’s genre
references	map	Refer to: Model Common Fields.
extra	map	Refer to: Model Common Fields.
inserted_at	DateTime	Refer to: Model Common Fields.
updated_at	DateTime	Refer to: Model Common Fields.

Fields That Can/Must Be Specified During Creation¶

During creation of the record user can specify values for some of the fields. Some of them are required for the creation of the record ad some of them are optional. Not specifying all the required fields for the creation of the record will result in request being rejected.

Field	Type	Required
name	string	yes
slug	string	yes
timezone	string	yes
description	string	no
media_routing_group_id	UUID	yes
homepage_url	string	no
genre	string	no
references	map	no
extra	map	no

Fields That Can Be Updated After Creation¶

There are some fields for which the value can be updated after the record is created. Crucial fields can be assigned a value only during creation and they cannot be changed later. The following fields can be updated by the user after record creation:

Field	Type
name	string
timezone	string
description	string
homepage_url	string
genre	string
references	map
extra	map

Fields That Can Be Used in Conditions¶

The following broacast channel data fields can be used in conditions in index and show MVC actions:

Field	Type
name	string
slug	string

Other Records That Can Be Used for Join¶

The following records can be used for join operation in index and show MVC actions:

Field	Model	Description
schedule_content_types	Agenda.Broadcast.ContentType	Content types that belong to broadcast channel
broadcast_streams	Agenda.Broadcast.Stream	Broadcast streams that belong to broadcast channel

Auth (Authentication & Authorization provider)¶

Contents:

Plumber (Live Audio Mixer)¶

Contents:

Official RadioKit REST API¶

Contents:

Official RadioKit REST API¶

Official RadioKit REST API is query-like interface to most of the resources provided to the users by RadioKit microservices.

Resources¶

Microservices provide resources stored as records in the database. Records of particular type are defined by models.

Resources of a given model can be obtained using HTTP methods with an URL specific for the given model.

URL¶

The general URL specifying both microservice and model:

https://<microservice>.backend.url/api/rest/v1.0/<model_path>

For example records for Broadcast.Channel model defined in Agenda microservice are obtainable via the following URL:

https://agenda.backend.url/api/rest/v1.0/broadcast/channel

Listing records¶

Listing records corresponds to index action in MVC design pattern and can be obtained using HTTP GET method on general model URL.

In general HTTP request GET https://agenda.backend.url/api/rest/v1.0/broadcast/channel should return JSON containing all broadcast channels defined in agenda microservice:

{
  meta: {},
  data: [
    // records here
  ]
}

The same can be obtained using JavaScript wrapper:

radiokit
  .query(“agenda”, “Broadcast.Channel”)
  .where(“name”, “eq”, “something”)
  .order(“name”, “asc”)
  .on(“fetch”, (_event, _query, data)) => {
    // data is already wrapped in Immutable.js array
  })
  .fetch();

Please note that at least one data field of the record must be specified in the request in order to verify this request as correct one.

Request which does not specify any data field is treated as incorrect and is rejected.

Record data¶

User can specify which record data should be returned in a response from server using ‘a’ parameter.

This allows to modify the server’s response to only this data that is of user’s interest.

Documentation for each model specifies which record data can be obtained by the user.

Example¶

GET https://agenda.backend.url/api/rest/v1.0/broadcast/channel?a[]=id

Above HTTP request will return all broadcast channels and each returned record will have only ‘id’ field specified.

Example¶

GET https://agenda.backend.url/api/rest/v1.0/broadcast/channel?a[]=id&a[]=name

Above HTTP request will return all broadcast channels and each returned record will have both ‘id’ and ‘name’ fields specified.

At least one data field must be specified in the request.

Record Methods¶

Some of the records provide methods that can be applied for a given record.

Methods are applied in the same manner as record data and the result of execution for given method is applied to the server response.

Documentation for each model specifies record methods available for given model.

Limiting number of returned records by using conditions¶

User can limit number of returned records to the ones that fulfill the condition specified in the request. Condition can be defined using ‘c’ parameter.

In order to specify the condition in the request the following syntax should be used:

?c[<field_name>][]=<operator>%20<specified_value>

The following operators can be used in conditions:

Operator	Description
in	checks if field’s value is included in specified_value
eq	checks if field’s value is equal to specified_value
neq	checks if field’s value is not equal to specified_value
lt	checks if field’s value is less than specified_value
gt	checks if field’s value is greater than specified_value
lte	checks if field’s value is less than or equal
gte	checks if field’s value is greater than or equal
isnull	checks if field’s value is is null
notnull	checks if field’s value is is not null
any
deq
dneq

Example¶

GET https://agenda.backend.url/api/rest/v1.0/broadcast/channel?a[]=id&c[name][]=eq%20Jazz

Above HTTP request will return all broadcast channels for which ‘name’ field is equal to ‘Jazz’ and each returned record will have only ‘id’ field specified.

Model Common Fields¶

There is a number of fields that are common for all the models in all the RadioKit microservices. This chapter describes those fields in details.

Field	Type	Description
id	UUID string	Unique identifier of each record. For more information about UUID type refer to Ecto.UUID.
name	string	Name of record
references	map	ID of the record in another microservice. Used to express relation between records in different microservices
extra	map	Container used to store all data that do not fit to predefined fields of the model
inserted_at	DateTime	Date and time of the last udpate for the record
updated_at	DateTime	Date and time when the record was created

Vault (Repository of Media Files)¶

Contents:

Importing¶

TODO

Uploading¶

There are several ways to upload media files into Vault. Depending on the context and desired integration with other applications you may want to push the whole file at once, ask service to pull it or upload it in chunks. Each of them has its benefits and drawbacks, described below.

Please note that uploading refers to action initiated by user or another application. You also may want to take a look about importing features that can be used to automatically fetch content from existing applications without necessity to trigger such operation.

RadioKit JavaScript API¶

Official RadioKit JavaScript API provides methods for handling uploads. It encapsulates them in high-level wrappers and ensures that any future changes to the underlying architecture will be reflected without necessity to modify your code.

It encapsulates authentication procedures, provides ability to queue files, upload them in parallel (but by default it will upload only them one after another), restart uploads and the most importantly, divide them into chunks. This is a quite reliable way to create uploader that handles large files even on weak network connections.

This is the preferred way to do uploads through web browser. Please note that this API does not handle server-side JavaScript as it needs access to the DOM.

Example¶

import { Data } from "radiokit-api";

var data = new Data();
var upload;

data.on("auth::success", () => {
  upload = data.upload("80332F34-F903-11E5-A3E1-3E19FDC8A409", { autoStart: true })
  upload.assignBrowse(document.getElementById("#uploadButton"));
  upload.assignDrop(document.getElementById("#uploadDropzone"));
  upload.on("added", (_eventName, queue) => { console.log(queue.getQueue()); });
  upload.on("progress", (_eventName, queue) => { console.log(queue.getQueue()); });
  upload.on("retry", (_eventName, queue) => { console.log(queue.getQueue()); });
  upload.on("error", (_eventName, queue) => { console.log(queue.getQueue()); });
});

data.signIn(); // This will redirect to the authentication service

Resumable.JS¶

Vault also provides interface for uploading via Resumable.JS JavaScript library. This is an alternative way to import files through web browser. It is however, quite low-level, and especially authentication may be tricky as you have to get and refresh OAuth2 access token on your own. It is however still possible if you don’t want to use official RadioKit API due to any reason.

Resumable.JS provides ability to queue files, upload them in parallel, restart uploads and the most importantly, divide them into chunks. This is a quite reliable way to create uploader that handles large files even on weak network connections.

The endpoint for uploading is https://vault.radiokitapp.org/api/upload/v1.0/resumablejs. Maximum chunk size is 4MB. Testing if chunks are already present (the testChunks option) is not supported. You must pass some additional headers and parameters to the requests:

Authorization header with valid OAuth2 access token (see: Authentication)
radiokit query parameter that contains:
- record_repository_id with valid Repository ID (see: Repositories)

Please refer to Resumable.JS documentation for further information.

Example¶

var r = new Resumable({
  target: "https://vault.radiokitapp.org/api/upload/v1.0/resumablejs",
  query: {
    radiokit: {
      record_repository_id: "80332F34-F903-11E5-A3E1-3E19FDC8A409"
    }
  },
  headers: {
    Authorization: "Bearer 123"
  },
  testChunks: false,
});

if(!r.support)  {
  alert("Chunked upload is not supported, upgrade your web browser.");
}

r.assignDrop(document.getElementById("#uploadDropzone"))
r.assignBrowse(document.getElementById("#uploadButton"), false);

r.fileAdded(() => { r.upload() });

Support¶

If you need any support while developing services on top of the Engine and encounter any issues, our team of experts is ready to help.

Don’t hesitate to contact us at admin@radiokit.org

Welcome to RadioKit Engine’s documentation!¶

Contents¶

Services¶

Agenda (Schedule Manager)¶

Broadcast Channel¶

Broadcast channel data¶

Fields That Can/Must Be Specified During Creation¶

Fields That Can Be Updated After Creation¶

Fields That Can Be Used in Conditions¶

Other Records That Can Be Used for Join¶

Auth (Authentication & Authorization provider)¶

Plumber (Live Audio Mixer)¶

Official RadioKit REST API¶

Official RadioKit REST API¶

Resources¶

URL¶

Listing records¶

Record data¶

Record Methods¶

Limiting number of returned records by using conditions¶

Joining other related records¶

Model Common Fields¶

Vault (Repository of Media Files)¶

Importing¶

Uploading¶

RadioKit JavaScript API¶

Resumable.JS¶

Support¶