Helium supports a plug-in architecture for downloading of information from different sources.

Please note that you will need Helium version 12.0.14094 or newer to be able to work with this API.


API definition

It is possible to create custom plug-ins using the defined interfaces in ImPluginEngine.Abstractions:


 IPlugin (mandatory)

 

    public interface IPlugin
    {
        string Name { get; }
        string Version { get; }
    }

 

IPluginConfig

Implement this interface if your plug-in supports configuration.

 

    public interface IPluginConfig
    {
        void ConfigurePlugin();
    }

 

IAlbumPicture

Implement this interface if your plug-in supports downloading of album pictures.

  

    public interface IAlbumPicture
    {
        Task GetAlbumPicture(PluginAlbum album, CancellationToken ct, Action<PluginImage> updateAction);
    }

The implementation needs to be async, hence the method signature returns a Task and not void.

Be sure to use the CancellationToken in your executing code to support cancellation.

The last parameter, updateAction, is a delegate that the plug-in should fill with return data and Helium will read to display and handle the result. See below for a defintition of the PluginImage class.


IArtistPicture

Implement this interface if your plug-in supports downloading of artist pictures.

 

    public interface IArtistPicture
    {
        Task GetArtistPicture(PluginArtist artist, CancellationToken ct, Action<PluginImage> updateAction);
    }

The implementation needs to be async, hence the method signature returns a Task and not void.

Be sure to use the CancellationToken in your executing code to support cancellation.

The last parameter, updateAction, is a delegate that the plug-in should fill with return data and Helium will read to display and handle the result. See below for a defintition of the PluginImage class.


IArtistPlugin

Implement this interface if your plug-in supports downloading of artist information.

 

    public interface IArtistPlugin
    {
        Task<PluginArtist> GetArtistData(PluginArtist artist, CancellationToken ct);
    }

The implementation needs to be async, hence the method signature returns a Task and not void.

Be sure to use the CancellationToken in your executing code to support cancellation.


The resulting value should be populated with the values your plug-in has found. See below for a definition of the PluginArtist class.

ILabelPicture
Implement this interface if your plug-in supports downloading of label pictures.

 

    public interface ILabelPicture
    {
        Task GetLabelPicture(PluginLabelInformation label, CancellationToken ct, Action<PluginImage> updateAction);
    }

 

The implementation needs to be async, hence the method signature returns a Task and not void.

Be sure to use the CancellationToken in your executing code to support cancellation.

The last parameter, updateAction, is a delegate that the plug-in should fill with return data and Helium will read to display and handle the result. See below for a defintition of the PluginImage class.


ILabelPlugin

Implement this into your plug-in supports downloading of label information.

 

    public interface ILabelPlugin
    {
        Task<PluginLabelInformation> GetLabelData(PluginLabelInformation label, CancellationToken ct);
    }

The implementation needs to be async, hence the method signature returns a Task and not void.

Be sure to use the CancellationToken in your executing code to support cancellation.


The resulting value should be populated with the values your plug-in has found. See below for a definition of the PluginLabelInformation class.


ILyrics

Implement this in your plug-in to support downloading of lyrics.

    public interface ILyrics
    {
        Task GetLyrics(PluginLyricsInput input, CancellationToken ct, Action<PluginLyricsResult> updateAction);
    }

The implementation needs to be async, hence the method signature returns a Task and not void.

Be sure to use the CancellationToken in your executing code to support cancellation.


The updateAction Action should be invoked when a result is found.
See below for a definition of the PluginLyricsInput and PluginLyricsResult classes.

 



PluginImage

This is a class which is used as a return type for resulting data.

 

    public class PluginImage
    {
        public string Filename { get; set; }
        public int Width { get; set; }
        public int Height { get; set; }
        public string FoundByPlugin { get; set; }
        public string SizeString { get { return string.Format("{0}*{1}", Width, Height); } }
        public int Id { get; set; }
    }

 When a plug-in returns information it should set the following properties:

  • Filename should be set to the absolute filepath of the downloaded image
  • Width should be set to the width of the downloaded image
  • Height should be set to the height of the downloaded image
  • FoundByPlugin should be set to the plug-ins name
  • Id should be set to the album or artist id (via the in parameter, e.g. album.Id

PluginArtist

 

    public class PluginArtist
    {
        public string Name { get; set; }
        public string BornName { get; set; }
        public string MusicBrainzId { get; set; }
        public string Biography { get; set; }
        public int Formed { get; set; }
        public int Disbanded { get; set; }
        public string Country { get; set; }
        public string ImageName { get; set; }
        public string ArtistUrl { get; set; }

        public List<string> Akas { get; set; }
        public List<string> GroupMembers { get; set; }
        public List<string> MemberOf { get; set; }
        public List<string> SimilarArtists { get; set; }
        public List<string> InfluencedBy { get; set; }
        public List<string> Followers { get; set; }
        public List<string> SeeAlso { get; set; }
        public List<string> PerformedSongsBy { get; set; }
        public int Id { get; set; }
    }

 

PluginLabelInformation

 

    public class PluginLabelInformation
    {
        public string Name { get; set; }
        public string ContactInfo { get; set; }
        public string ParentLabel { get; set; }
        public string WebPage { get; set; }
        public string Profile { get; set; }
        public string ImageName { get; set; }

        public int Formed { get; set; }
        public int Disbanded { get; set; }
        public string LabelCode { get; set; }
        public string Country { get; set; }
        public List<string> Sublabels { get; set; }
        public int Id { get; set; }

    }

 

PluginLyricsInput

 

    public class PluginLyricsInput
    {
        public string Artist { get; set; }
        public string Title { get; set; }
    }

 

PluginLyricsResult

 

    public class PluginLyricsResult
    {
        public string FoundByPlugin { get; set; }
        public string Lyrics { get; set; }
        public string Artist { get; set; }
        public string Title { get; set; }
    }

 


Examples

You can download the full source-code to the Last.fm plug-in from the link below:

https://github.com/ImplodedSoftware/LastFmPlugin


You can download the full source-code to the Amazon plug-in from the link below:

https://github.com/ImplodedSoftware/AmazonPlugin