Imploded Software

Helium scripts are written in C#. If you are familiar with C# and the .NET Framework you will notice that you have access to most features and APIs that are available in a regular console application.

A script contains at least two files, one file with metadata that's used to describe the script, the entry point of the script and additional files that are included with the script.

The file should be in JSON format and named <scriptfile>.json.

The contents of the JSON file looks like this:

{
  "ScriptName": "The visual name, shown in menues",
  "Description": "The full description of the script, shown in the Run script dialog when the script is selected.",
  "EntryPoint": "firstscriptfiletoexecute.cs",
  "AdditionalFiles": null,
  "Author": "The name of the person which created the script",
  "Scope": "A text describing which input the script expects, e.g. selected tracks, all artists etc."
}

  The two first fields are self explanatory, the field EntryPoint should point to the file containing the definition below.

AdditionalFiles describes additional files (separate classes etc.) which the script depends on.

Here is a basic template for how an empty script should look like:

using NeonScripting;

namespace Neon
{
	public class Script
	{
		public bool Run(INeonScriptHost host)
		{
			// insert your own script code here

			return true;
		}
	}
}

The using NeonScripting directive is needed for accessing all Helium specific features in your script.

The namespace, class and Run methods are all part of the basic template and will need to be there in order to make the script execute.

The INeonScriptHost interface is where the interaction between Neon and your script will happen.

Getting started

A good way to get started with scripting is to check the contents of the scripts shipped with Helium.

These scripts uses the most available tasks and gives a good picture of how to use the functions in an easy way.

Helium looks for scripts in the following directory:

%APPDATA%\Imploded Software\Helium <VERSION>\scripts

Just replace <VERSION> with your specific Helium version.

Asynchronous vs synchrounous scripts

In Helium 17.4, support for asynchronous scripts has been added. For performance reasons, and to avoid deadlocks, it is recommended to use asynchronous calls, although support for synchronous scripts is still available.

The default scripts have been updated where needed.

An asynchronous script supports the await operator when calling asynchronous methods (those that return a Task).

It also requires a slightly different template structure.

using System;
using NeonScripting;
using System.Threading.Tasks;


public class Script
{
  public async Task<bool> RunAsync(INeonScriptHost host)
  {
    // insert your code here
    
    return true;
  }

}