Qball's Weblog
Writing a lyrics provider plugin for 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:
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:
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.)
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:
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”
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).
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:
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
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:
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.