Introduction

Helium supports download scripts written in JavaScript, which are loaded and executed in a sandbox for security reasons. Internally, this engine uses JINT (https://github.com/sebastienros/jint).

Most common JavaScript features are available in JINT. However, please refer to the official webpage for known limitations.


Available script types

  • Tag downloader: This tool guides the user through a process that first downloads a set of possible results. The user can then select the appropriate result, and all information for the specific release (including the track list), artist information, and label information will be downloaded.

  • Lyrics: Available from the Tag Editors, this feature allows the user to download lyrics for a specific track.

  • Album picture: Allows the user to download an album picture using either the artist and album as input, or via catalog number or barcode.

  • Artist picture: Allows the user to download a picture of the artist.

  • Label picture: Allows the user to download a picture of the label.

  • Label information: Allows the user to download information about a label, with optional picture support.

  • Artist information: Allows the user to download information about an artist or group, with optional picture support.


Available backing functions, variables and payloads

When a script is invoked from Helium, Helium will "inject" several variables, input payloads, and functions that can be accessed from the script. 


Variables

  • searchModeAlbumArtist = 0
  • searchModeBarcode = 1
  • searchModeCatalogNumber = 2


These variables can be used to check which mode was set in a tag-downloader script's payload to determine which URL should be used to search for results. For more information on how this is used, see the script musicbrainz-downloader.js. 


  • scriptTypeTagDownloader = 0
  • scriptTypeLyrics = 1
  • scriptTypeAlbumPicture = 2
  • scriptTypeArtistPicture = 3
  • scriptTypeLabelPicture = 4
  • scriptTypeLabelInfo = 5
  • scriptTypeArtistInfo = 6


These variables should be used in the getScriptData function to describe the type of script.

Apart from the statically defined variables above, variables defined in Tools > Options > Variables will be sent to the scripting engine and made available to scripts. This is particularly useful for accessing authorization information and other sensitive data that you would not want to expose directly in a script.


Example

From Tools > Options > Variables, add a new variable LastFmApiKey with a value.

In the script, you can access the value of this variable by name using the following code:

const APIKEY = LastfmApiKey;


Functions

Some standard functions are not available in JINT, such as console.log, fetch, and alert. To address this, Helium injects the following functions so they can be used within downloading scripts to provide similar functionality:

  • log(data: string) - Logs the value of data into Helium's log file.
  • fetch(url: string, agent: string = '', authorization = ''): string - Fetches a document from the given URL and returns the result in the script. The agent parameter sets a user-agent string in the header (some scripts require this), and the authorization parameter sets the authorization string in the header (required by the Discogs script).
  • alert(data: string) - Displays a message box with the value in the data parameter to the user.


Payloads

Most script types will have a payload object available, with input data generated from the selected data in Helium. Use these payloads to form URLs to fetch data. 


Tag downloader

  • TrackDownloadMode - a value between 0 and 2, see Variables above, with the selected downloadmode from the tool
  • Artist - The name of the artist
  • Album - The name of the album
  • Barcode - The barcode for the album (if available)
  • CatalogNumber - The catalog number for the album (if available)

Lyrics

  • Artist - The name of the artist
  • Title - The title of the track

Album picture

  • Artist - The name of the artist
  • Album - The name of the album
  • Barcode - The barcode for the album (if available)
  • CatalogNumber - The catalog number for the album (if available) 

Artist picture

  • Artist - The name of the artist

Label picture

  • Label - The name of the label

Label information

  • Label - The name of the label

Artist information

  • Artist - The name of the artist

Function signatures

Each script requires at least two functions to be implemented, with specific names so that they can be accessed from Helium. Depending on the script type, additional functions may need to be implemented. 


Each function should return data in a specific response format. For more information about the response types, please see the Download Script Response Types page.


  • getScriptData() - Called from Helium to identify the name and type of script.
  • getAlbumResults() - Called from Helium to get a list of album results to present to the user. This is used only in the Tag Downloader script.
  • getAlbumWithTracks(id: string) - Called from Helium to download a specific album selected from the results page in the Tag Downloader.
  • getLyrics() - Called from Helium to download lyrics. Please note that the response type is a string, not an object.
  • getAlbumPictures() - Called from a script that implements the downloading of album pictures.
  • getArtistPictures() - Called from a script that implements the downloading of artist pictures.
  • getLabelPictures() - Called from a script that implements the downloading of label pictures.
  • getLabelInformation() - Called from a script that implements the downloading of label information.
  • getArtistInformation() - Called from a script that implements the downloading of artist information.