Please note that this script and other download scripts are available from Helium's appdata folder, %APPDATA%\Imploded Software\Helium <version>\Downloaders.


Basics

All download scripts must implement one function that returns information about the script, getScriptData.

This function has the same structure for all download scripts:


function getScriptData() {
    const result = {
        name: 'iTunes Album Pictures',
        supportsAlbumArtist: false,
        supportsBarcode: false,
        supportsCatalognumber: false,
    scriptType: scriptTypeAlbumPicture
    };
    return JSON.stringify(result);
}

NOTE

  • The function must be declared as a function, not const getScriptData = () => { ... }. 
    While scripting supports const-declared functions (which is generally recommended), functions invoked from Helium must be declared as standard functions.
  • The name, getScriptData is case-sensitive.
  • Results from script functions should always be returned as JSON, using the JSON.stringify() method.

The following properties in the returned object need to be set:

  • name - A display name for the script
  • supportsAlbumArtist - Only needed for a tag-downloader script, if the script supports album and artist as input.
  • supportsBarcode - Only needed for a tag-downloader script, if the script supports barcode as input.
  • supportsCatalognumber - Only needed for a tag-downloader script, if the script supports catalog number as input. 
  • scriptType - The type of the download script. 
    A full description of all supported types is available in the download script API section. 


For this script, we set the name to 'iTunes Album Picture', the three supports properties to false, since this is not a tag-downloader script, and lastly, we set scriptType to scriptTypeAlbumPicture. 


Implementing the actual downloading

The part where the actual downloading takes place is defined in the getAlbumPictures function.
The sample code looks likt this: 

function getAlbumPictures() {
    const query = encodeURI(payload.artist + ' ' + payload.album);  
    const url = `https://itunes.apple.com/search?term=${query}&country=us&entity=album&limit=25`;
    const json = fetch(url);
    const data = JSON.parse(json);
    const results = data['results'];

    const result = [];
  results.forEach((x) => {
    const artist = x['artistName'].toLowerCase();
    const album = x['collectionName'].toLowerCase();
    
    if (artist === payload.artist.toLowerCase() && album === payload.album.toLowerCase()) {
      const url60 = x['artworkUrl60'];
      const url100 = x['artworkUrl100'];
      const imageUrl = url100 !== '' ? url100 : url60;
      const adjustedUrl = imageUrl.replace('100x100bb', '100000x100000-999');
      const resourceUrl = x['collectionViewUrl'];
      result.push({smallUrl: url60, Url: adjustedUrl, resourceUrl: resourceUrl})
    }
  });
    return JSON.stringify(result);
}

NOTE:
The getAlbumPictures function must be declared as a standard function. The name, getAlbumPictures, is case-sensitive, so it must be written exactly as specified.

The script can return one or more pictures. Therefore, the result object, result, is declared as a list (array) of objects. Each object in the list should represent a picture, containing relevant details like the picture URL and possibly other metadata.


Walkthough through the code

The following lines create a URL from the payload (incoming data) that will be used to fetch data from the iTunes API: 

    const query = encodeURI(payload.artist + ' ' + payload.album);  
    const url = `https://itunes.apple.com/search?term=${query}&country=us&entity=album&limit=25`;

The payload varies depending on the script type, but for album picture downloading, the payload contains the following properties, which are populated from Helium:

  • artist: The name of the artist.
  • album: The name of the album.
  • barcode: The barcode for the album, if available.
  • catalogNumber: The catalog number, if available.


In this example, the script builds a search query using the artist and album fields from the payload and sends it to the iTunes API to retrieve album-related data.

This line of code downloads data using the given URL and stores the result in the json variable:

    const json = fetch(url);

Please note that the built-in JavaScript version of fetch is not available. Instead, the fetch function is executed from Helium's code, but it can be accessed just like the default JavaScript version. This allows you to use fetch to retrieve data from external APIs within your script, while Helium handles the underlying request.

These two lines of code first parse the returned/downloaded data in the json variable into a JavaScript object:

    const data = JSON.parse(json);
    const results = data['results'];

This line of code declares an empty list as the default result: 


    const result = [];

Next, the following code iterates over each result in the results array: 

  results.forEach((x) => {
    const artist = x['artistName'].toLowerCase();
    const album = x['collectionName'].toLowerCase();
    
    if (artist === payload.artist.toLowerCase() && album === payload.album.toLowerCase()) {
      const url60 = x['artworkUrl60'];
      const url100 = x['artworkUrl100'];
      const imageUrl = url100 !== '' ? url100 : url60;
      const adjustedUrl = imageUrl.replace('100x100bb', '100000x100000-999');
      const resourceUrl = x['collectionViewUrl'];
      result.push({smallUrl: url60, Url: adjustedUrl, resourceUrl: resourceUrl})
    }
  });

For each result, the artist and album are extracted and compared to the input payload. If they match, a new object is created using the properties from the iTunes API response, and the match is appended to the result array with the following structure: 

result.push({smallUrl: url60, Url: adjustedUrl, resourceUrl: resourceUrl})

For scripts that download pictures, the result typically has this structure:

  • smallUrl: A URL to a thumbnail version of the result (if available).
  • Url: The full-size version of the resulting picture.
  • resourceUrl: (Optional) A link to the page where the result was found.

Finally, the result, built by the script, is returned to Helium using the JSON.stringify function: 

return JSON.stringify(result);


Tips and tricks

It's a good practice to review the code of the scripts included with Helium to better understand how they interact with various online sources for downloading data. By examining these scripts, you can learn how to structure your own scripts and how to utilize different APIs effectively.

If a specific service you'd like to use offers an API, it's recommended to use that API instead of manually extracting data from an HTML page, even though that is also possible. APIs are generally more reliable and easier to work with than scraping HTML. It may not be allowed to scrape certain sites. Please be aware of each sites rules.

The JavaScript engine used in Helium is called JINT. You can find more information about it at the following link:
https://github.com/sebastienros/jint