Qball's Weblog

Writing a lyrics provider plugin for GMPC

Tags gmpc 

This is a quick (and dirty) tutorial on how to add provider plugin to GMPC.
The plugin is written in VALA and assumed to be part of the GMPC source tree. (so not a separate plugin).
You can use the EXACT same tutorial to write an external plugin, you only need to add some auto-fu and the following line at the bottom of the file:

?View Code CSHARP
1
2
3
public Type plugin_get_type () {
        return typeof (Gmpc.Provider.ChartLyrics);
}

So GMPC knows what type of Object to instantiate.

The tutorial:

Empty (metadata) plugin template

Inside the GMPC source directory we first create a template:

?View Code CSHARP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
/* Gnome Music Player Client (GMPC)
 * Copyright (C) 2004-2011 Qball Cow qball@gmpclient.org
 * Project homepage: http://gmpclient.org/
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */
 
using Config;
using Gmpc;
using Gmpc.Plugin;
 
/* Needed to solve some vala odities */
private const bool use_transition_ppclyr = Gmpc.use_transition;
private const string some_unique_name_ppclyr = Config.VERSION;
 
/* Log domain, do gmpc gmpc --log-filter=Gmpc.Provider.Chartlyrics to see this output */
private const string log_domain_ppclyr = "Gmpc.Provider.ChartLyrics";
 
/**
 * Plugin implements the Base class and the Metadata interface
 */
public class Gmpc.Provider.ChartLyrics: Gmpc.Plugin.Base,Gmpc.Plugin.MetaDataIface
{
 
    /**
     * Gmpc.Plugin.Base
     */
     private const int[] version = {,,2};
 
    /** Return the plugin version. For an internal plugin this is not that interresting.
     * But we implement it anyway 
     */
    public override unowned int[] get_version()
    {
        return this.version;
    }
 
    /**
     * The name of the plugin 
     */
    public override unowned string get_name()
    {
        return N_("ChartLyrics Plugin");
    }
 
    /**
     * Constructor
     */
    construct
    {
         // Not needed, but lets do it anyway. This means metadata provider
        // and internal plugin.
        this.plugin_type = 8+32;
    }
 
    /**
     * Gmpc.Plugin.MetaDataIface
     */
    /**
     * Priority of the plugin, default 50
     */
    public void set_priority(int priority)
    {
        config.set_int(this.get_name(),"priority",priority);
    }
    public int get_priority()
    {
        return config.get_int_with_default(this.get_name(),"priority",50);
    }
 
    public void get_metadata (MPD.Song song,
                Gmpc.MetaData.Type type,
                MetaDataCallback callback)
    {
         /* Check request type */
        if(type != Gmpc.MetaData.Type.SONG_TXT) {
            /* Signal that we do not find anything */
            callback(null);
            return;
        }
        /* Check if we have enough metadata to fetch lyrics */
        if(song == null || song.artist == null || song.title == null)
	{
            log(log_domain_ppclyr, GLib.LogLevelFlags.LEVEL_DEBUG,
			"Insufficient information. doing nothing");
	    /* Tell that we found nothing */
	    callback(null);
	    return;
	}
        /* integrate fetcher here */
    }
}

Downloading and parsing results

The next step would be to do the query and download the results. Because the plugin is not allowed to block, and GMPC provides an async downloader (C version so it does not nicely intergrate into vala) we need to create an object that we use to remember out state. (So if multiple queries come in, we do not get race conditions.)

?View Code CSHARP
1
2
3
4
5
6
7
8
9
10
11
12
  /**
 * This class is used to go around the limitations of
 *  GmpcEasyAsyncDownload (it is no GLibSimpleAsync implementation.)
 */
 [Compact]
 private class Prop
 {
 public MPD.Song song;
 public ChartLyrics this;
 public MetaDataCallback callback;
 public List<metadata .Item> list = null;
 }</metadata>

We place this somewhere inside our class. (p.s. ignore wordpress adding the closing tags, no idea how to get rid of them)

Now we create the query we want todo:

?View Code CSHARP
1
	const string query = "http://api.chartlyrics.com/apiv1.asmx/SearchLyricDirect?artist=%s&song=%s";

and add the download at the point “integrate fetcher here”

?View Code CSHARP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
        Prop *p = new Prop();
        /* add reference to ourself here */
        p->this = this;
        /* Make a copy of the song */
        p->song = song;
        /* Pointer to the callback we have to call */
        p->callback = callback;
        /* Create the query. The escape_uri will make sure it is properly html escaped */
        var path = query.printf(Gmpc.AsyncDownload.escape_uri(song.artist),
            Gmpc.AsyncDownload.escape_uri(song.title));
        /* for debugging */
        log(log_domain_ppclyr, GLib.LogLevelFlags.LEVEL_DEBUG,
            "Query song txt: %s ", path);
        /* Start the download, when done it calls handle download */
        Gmpc.AsyncDownload.download_vala(path, p, handle_chartlyr_download);

Now we are going to handle the download results. (handle_download function).

?View Code CSHARP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
    /**
     * This function handles the callback from Gmpc.AsyncDownload 
     */
    private void handle_chartlyr_download(Gmpc.AsyncDownload.Handle handle,
        Gmpc.AsyncDownload.Status status,
        void *d)
    {
        Prop *p = (Prop *)d;
        if(status == Gmpc.AsyncDownload.Status.DONE)
        {
            var data = handle.get_data();
            /* If there is results parse it */
            if(data != null)
                parse_data(p, data);
 
            log(log_domain_ppclyr, GLib.LogLevelFlags.LEVEL_DEBUG,
                "Download done: results: %u ", p->results.length);
 
            /* Call the callback with the results,
             * this will take over the reference
             * of the result list, and takes care of freeing it
             */
            p->callback((owned)(p->list));
            delete p;
        }
        else if (status == Gmpc.AsyncDownload.Status.PROGRESS)
        {
            // do nothing when downloading
        }
        else
        {
            /* Nothying found, or error, so return this and cleanup */
            p->callback(null);
            /* delete Prop */
            delete p;
        }
    }

So all that is remaining is to parse the returned data (parse_data) and create “MetaData.Item” objects with the result.

The result is XML, so lets look at the parser:

?View Code CSHARP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
    /** 
     * Parse the result 
     */
   private void parse_data(Prop *p, uchar[] data)
   {
 
       Xml.Doc *doc = Xml.Parser.parse_memory((string)data, data.length); 
       /* nothing found */
       if(doc == null) return;
 
       Xml.Node *root = doc->get_root_element();
       if(root != null)
       {
           for(Xml.Node *child = root->children; 
                   child != null ; 
                   child = child->next)
           {
                if(child->name == "Lyric")
                {
                    string lyric = child->get_content();
                    /* it returns empty lyrics when no hit, so catch that */
                    if(lyric.length > ) 
                    {
                        /* Create a new metadata item, of th right type
                         * and add it to the list */
                        MetaData.Item pitem = new MetaData.Item();
                        pitem.type = Gmpc.MetaData.Type.SONG_TXT;
                        pitem.plugin_name = get_name();
                        pitem.content_type = MetaData.ContentType.TEXT;
                        pitem.set_text(lyric);
                        p->list.append((owned)pitem);
                    }
                }
           }
       }
   }

Build system integration

And that is (almost) it.
Add the vala file in src/Providers/, add it to src/Makefile.am.
Edit src/Tools/plugin-man.c and add

?View Code C
1
2
3
    plugin_add_new((GmpcPluginBase *) 
            gmpc_provider_chart_lyrics_new(),
            , NULL);

To the load_internal_plugins function.
Compile GMPC and it works.

Final result

The complete plugin is now:

?View Code CSHARP
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
/* Gnome Music Player Client (GMPC)
 * Copyright (C) 2004-2011 Qball Cow qball@gmpclient.org
 * Project homepage: http://gmpclient.org/
 
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */
 
using Config;
using Gmpc;
using Gmpc.Plugin;
 
/* Needed to solve some vala odities */
private const bool use_transition_ppclyr = Gmpc.use_transition;
private const string some_unique_name_ppclyr = Config.VERSION;
 
/* Log domain, do gmpc gmpc --log-filter=Gmpc.Provider.Chartlyrics to see this output */
private const string log_domain_ppclyr = "Gmpc.Provider.ChartLyrics";
 
/**
 * Plugin implements the Base class and the Metadata interface
 */
public class Gmpc.Provider.ChartLyrics: Gmpc.Plugin.Base,Gmpc.Plugin.MetaDataIface
{
 
    /**
     * Gmpc.Plugin.Base
     */
    private const int[] version = {,,2};
 
    /** Return the plugin version. For an internal plugin this is not that interresting.
     * But we implement it anyway 
     */
    public override unowned int[] get_version()
    {
        return this.version;
    }
 
    /**
     * The name of the plugin 
     */
    public override unowned string get_name()
    {
        return N_("ChartLyrics Plugin");
    }
 
    /**
     * Constructor
     */
    construct
    {
        // Not needed, but lets do it anyway. This means metadata provider
        // and internal plugin.
        this.plugin_type = 8+32;
    }
 
    /**
     * Gmpc.Plugin.MetaDataIface
     */
    /**
     * Priority of the plugin, default 50
     */
    public void set_priority(int priority)
    {
        config.set_int(this.get_name(),"priority",priority);
    }
 
    public int get_priority()
    {
        return config.get_int_with_default(this.get_name(),"priority",50);
    }
 
    const string query = "http://api.chartlyrics.com/apiv1.asmx/SearchLyricDirect?artist=%s&song=%s";
 
    public void get_metadata (MPD.Song song,
        Gmpc.MetaData.Type type,
        MetaDataCallback callback)
    {
        /* Check request type */
        if(type != Gmpc.MetaData.Type.SONG_TXT) {
            /* Signal that we do not find anything */
            callback(null);
            return;
        }
        /* Check if we have enough metadata to fetch lyrics */
        if(song == null || song.artist == null || song.title == null)
        {
            log(log_domain_ppclyr, GLib.LogLevelFlags.LEVEL_DEBUG,
                "Insufficient information. doing nothing");
            /* Tell that we found nothing */
            callback(null);
            return;
        }
        /* intergrate fetcher here */
        Prop *p = new Prop();
        p->this = this;
        p->song = song;
        p->callback = callback;
        var path = query.printf(Gmpc.AsyncDownload.escape_uri(song.artist),
            Gmpc.AsyncDownload.escape_uri(song.title));
        log(log_domain_ppclyr, GLib.LogLevelFlags.LEVEL_DEBUG,
            "Query song txt: %s ", path);
        Gmpc.AsyncDownload.download_vala(path, p, this.handle_chart_download);
    }
 
    /** 
     * Parse the result 
     */
   private void parse_data(Prop *p, uchar[] data)
   {
 
       Xml.Doc *doc = Xml.Parser.parse_memory((string)data, data.length); 
       /* nothing found */
       if(doc == null) return;
 
       Xml.Node *root = doc->get_root_element();
       if(root != null)
       {
           for(Xml.Node *child = root->children; 
                   child != null ; 
                   child = child->next)
           {
                if(child->name == "Lyric")
                {
                    string lyric = child->get_content();
                    /* it returns empty lyrics when no hit, so catch that */
                    if(lyric.length > ) 
                    {
                        /* Create a new metadata item, of th right type
                         * and add it to the list */
                        MetaData.Item pitem = new MetaData.Item();
                        pitem.type = Gmpc.MetaData.Type.SONG_TXT;
                        pitem.plugin_name = get_name();
                        pitem.content_type = MetaData.ContentType.TEXT;
                        pitem.set_text(lyric);
                        p->list.append((owned)pitem);
                    }
                }
           }
       }
   }
    /**
     * This function handles the callback from Gmpc.AsyncDownload 
     */
    private void handle_chart_download(Gmpc.AsyncDownload.Handle handle,
        Gmpc.AsyncDownload.Status status,
        void *d)
    {
        Prop *p = (Prop *)d;
        if(status == Gmpc.AsyncDownload.Status.DONE)
        {
            var data = handle.get_data();
            /* If there is results parse it */
            if(data != null)
                parse_data(p, data);
 
            log(log_domain_ppclyr, GLib.LogLevelFlags.LEVEL_DEBUG,
                "Download done: results: %u ", p->list.length());
 
            /* Call the callback with the results,
             * this will take over the reference
             * of the result list, and takes care of freeing it
             */
            p->callback((owned)(p->list));
            delete p;
        }
        else if (status == Gmpc.AsyncDownload.Status.PROGRESS)
        {
            // do nothing when downloading
        }
        else
        {
            /* Nothying found, or error, so return this and cleanup */
            p->callback(null);
            /* delete Prop */
            delete p;
        }
    }
    /**
     * This class is used to go around the limitations of
     *  GmpcEasyAsyncDownload (it is no GLibSimpleAsync implementation.)
     */
    [Compact]
    private class Prop
    {
        public MPD.Song song;
        public ChartLyrics this;
        public MetaDataCallback callback;
        public List<metadata .Item> list = null;
    }
}
</metadata>

Note

We might want to add some validation, to see if we get the correct lyric back. Now it might return the lyric for a different song. But this is something we should be able to catch.