krad_webdev_guide.txt

Radical Revelations :: The Krad Radio Web Development Field Guide
-----------------------------------------------------------------

Hello and welcome to the hilarious adventure of of Krad Radio Web Development!
Lets get started. This brief guide will be all you need to begin developing
user interfaces and automated control systems for the Krad Radio interweb media
server using familar web 1.0 - 4.0 technologies such as HTTP, Javascipt/JSON,
WebSockets and WebRTC.

If you would like to build your own system from scratch you can connect to the
KR interweb server using HTTP or Websockets and use the JSON API to send
control commands, request state information or subscribe to realtime system
state broadcasts at the desired level of granularity.

[Insert JSON API docs link here]

If you want to add a custom user interface to the standard KR Rack UI then the
following information will describe how a Rack Control Unit (RCU) is
constructed.

When a web browser connects to the KR interweb server it is transmitted a HTML
file with a blank body tag and the JS/CSS assets that have possibly been
configured by the sysadmin. The standard rack ui has three main parts.

Kr Object - This is the object that handles the websocket connection. This also
takes care of sending API commands and calling the user interface object when
new data arrives. At a few hundred lines, this is all that it does, it does not
ever touch the DOM.

Rack Object - This is the object that manages the layout of the control units.
It lets you add and remove the controls that you want and makes sure incoming
data is routed to the correct units.

RCU Objects - Each of these represents an individual RCU, it is what takes
input from the user and also displays information about the current control
state.

An operational RCU involves the following:

A name and description.
An aspect ratio rule so that the unit can be placed correctly on the rack.
A div positioned by the Rack object in which to draw itself.
A create/destroy method for itself.
A callback method to receive incoming data that matches the current address
mask of the RCU.
An address mask array.

An address mask array is simply an array of KR unit addresses that this RCU is
interested in receiving incoming crates for. For example a mask array of
["/mixer"] would receive all incoming mixer state and ["/compositor/video0"]
would recieve only crates related to videoport video0.