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.

If one has installed NymphCast server using the setup script (for Debian-based Linux), the apps/ folder can be found under /opt/nymphcast/, otherwise you have to manually copy the apps/ folder from the root of the NymphCast project folder into the folder where the NymphCast server binary is found (usually src/server/bin).

API calls

A few custom functions are made available to NymphCast applications, allowing them to perform HTTP queries, play back tracks, and so on. The list of current available API calls is:

In addition, NymphCast offers the string, and dictionary and array extensions by default. 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.

AngelScript reference

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