NymphCast

Developing NymphCast applications

 

NymphCast supports custom applications that run on the NymphCast server, which is the device that is connected to the television or audio system. These applications are written in AngelScript and can use a range of functions that are implemented in the NymphCast runtime.

In this document we will be looking at how to get started with developing a NymphCast application, and how to develop a simple 'Hello World' level application that retrieves a music file via HTTP and plays it back.

Development environment

To start developing NymphCast apps, one needs to have nothing more than some kind of text editor, preferably one that has built-in syntax highlighting for AngelScript or at least C++. Since C++ and AngelScript's syntax is virtually identical, either works.

For testing whether the script works, one can run a local NymphCast server instance with the new script installed (see later on this page on how to do this) and connect to it with the NymphCast Player app to validate its functionality. One can also use the NymphCast client SDK to develop a custom client application, both for end-users and for integration testing.

Hello World

A simple example of a NymphCast app can be found in the 'HelloCast' app that is included in the default NymphCast distribution. Its source can be found under apps/hellocast/ and looks as follows:

string command_processor(string input) {
	// Available commands:
	// - help
	// - play
	if (input == "help") {
		return "Commands:\n- help\n- play";
	}
	else if (input == "play") {
		// Play the standard track.
		string url = "https://github.com/MayaPosch/NymphCast/releases/download/v0.1-alpha/How_it_Began.mp3";
		return streamTrack(url);
	}
	
	return "Invalid command.";
}

This shows the basic structure of a NymphCast app, with the 'command_processor' function as the entry point. It accepts a string as input, and returns a string upon completion.

Installing an application

Apps are defined in the apps.ini file in the apps/ folder of a NymphCast server installation. To install a new application, add it in a new section, using the following format:

[HelloCast]
name = HelloCast
location = local
url = hellocast/hellocast.as

The value for 'name' should always be the name of the application as string. The location value can be either 'local' or 'remote', meaning in the apps/ folder, or on a remote server accessible via HTTP or HTTPS. The 'url' value is thus either the relative file path, or the full HTTP(S) URL to the root AngelScript file.

API calls

A few custom functions are made available to NymphCast applications, allowing them to perform HTTP queries, play back tracks, and so on. In addition, NymphCast offers the standard AngelScript string, and dictionary and array extensions by default. The list of current available API calls is:

HTTP

JSON

There is also a JSON module, for parsing JSON. For example:

JSONFile json;
if (!json.fromString(response)) {
	return "Failed to parse JSON response.";
}

JSONValue root = json.getRoot();

string output = "";
for (int i = 0; i < root.get_size(); ++i) {
	JSONValue user = root[i];
	
	// Get the ID, artist name from the Object.
	string user_id = formatUInt(user.get("id").getUInt());
	string username = user.get("username").getString();
	
	output += user_id + "\t" + username + "\n";
}

The API for JSONValue is essentially identical to that of the Urho3D engine's JSONValue API. Please see its documentation for further details.

SQLite

Each NymphCast app can create and use a single SQLite database unique to that app to store and retrieve key/value pairs. The API for this is:

Regular expressions

API:

Queue track

URLs to a track to be streamed can be added to the queue using this API.

Templates

HTML templates (from a templates folder within the app's folder) can be read using this function:

Note currently no keyword replace or similar templating features are available. This API is expected to be heavily developed during v0.2 development of NymphCast.

AngelScript reference

Documentation for the AngelScript language can be found on the official website.