aboutsummaryrefslogtreecommitdiff
path: root/multimedia/glyr/README.html
blob: 5c77d8830e4de65bd18cb5a8a771a134d7cd4243 (plain)
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
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html><head><title>Glyr is a search engine for music related metadata</title></head><body><h1>Glyr is a search engine for music related metadata</h1>

<p>The finest search you can buy for no money <sup>TM</sup></p>

<p><img src="https://github.com/sahib/glyr/blob/master/doc/screenshot.png" alt="[screenshot]" /></p>

It comes both in a command-line interface tool and as a C library, both with an easy to use interface.<br />
The sort of metadata glyr is searching (and downloading) is usually the data you see in your musicplayer.<br />
And indeed, originally it was written to serve as internally library for a musicplayer, but has been extended to <br />
work as a standalone program which is able to download:<br />
<p>
<table border="1">
<tr>
<th>Getter</th><th>Description</th>
</tr>
<tr><td>cover</td><td>Coverart (front images supported only)</td></tr>
<tr><td>lyrics</td><td>Songtext</td></tr>
<tr><td>artistphotos</td><td>Photos of a certain band (press or live)</td></tr>
<tr><td>artistbio</td><td>Artist biography from various sites</td></tr>
<tr><td>review</td><td>album reviews from various sites</td></tr>
<tr><td>albumlist</td><td>A list of albums from a specific artist.</td></tr>
<tr><td>tags</td><td>Tags, either related to artist, album or title</td></tr>
<tr><td>relations</td><td>links to wikipedia, myspace, musicbrainz ...</td></tr>
<tr><td>similarartists</td><td>similar artists</td></tr>
<tr><td>similarsongs</td><td>similar songs</td></tr>
<tr><td>tracklist</td><td>tracklists of an album</td></tr>
<tr><td>guitartabs</td><td>guitartabs in textual form</td></tr>
<tr><td>backdrops</td><td> Large artist photos, suitable for backgrounds</td></tr>
</table>
</p>

<p><strong>Terminology</strong>:<br />
To prevent disambiguation the following terms are used below: 	<br />
* <em>glyrc</em> is the command-line interface to libglyr.<br />
* <em>libglyr</em> is the library behind, which may be used by your program.<br />
* a <em>getter</em> is a type of metadata to download, e.g. <code>cover</code>, sometimes also called <em>fetcher</em><br />
* a <em>provider</em> is a source libglyr queries in order to find the data.<br />
* <em>glyros</em> is the ruby wrapper for this lib. Currently it is not maintained.</p>

<h2><span class="caps">FEATURES</span></h2>

<ul>
<li>Many built-in providers (46 at time of writing, ~30 distinct sites), high success-rate (the longer the search, the higher the risk :))</li>
<li>Portable: Windows and Linux are supported (Developement on Linux) see <sub><sup class="footnote"><a href="#fn1">1</a></sup></sub> for Mac <span class="caps">OSX, </span></li>
<li>Fuzzy matching: Search providers with Levenshtein algorithm to eliminate typos and enhance search results.</li>
<li>Decent Unicode support: All sort of valid <span class="caps">UTF8 </span>is taken, and UTf8 output can be forced.</li>
<li>Fast Download: libcurl is used internally, and sources are searched in parallel, unneeded data is not downloaded if possible.</li>
<li>Lightweight dependencies: libcurl, glib and sqlite (for caching) - typical linux systems have those installed.</li>
<li>Download of a user defined amount of items, <code>glyrc cover -a Foo -b Bar -n 30</code> tries to load 30 covers of album &#39;Bar&#39; by artist &#39;Foo&#39;.</li>
<li>Grouped download: Query providers by descending Accuray / Speed; controllable by the user over the <code>qsratio</code></li>
<li>Optional download of images, <span class="caps">URL </span>is returned otherwise - so it can act a bit like a search-engine.</li>
<li>Free Software licensed under the terms of the <span class="caps">GPL</span>v3</li>
<li>libglyr is portable, easy, threadsafe and lowlevel enough for everyone.</li>
<li>...lots of other options like min/max size for images.</li>
<li>A built-in cache to store the metadata (using <span class="caps">SQL</span>ite)</li>
</ul>

<h2><span class="caps">GETTING STARTED</span></h2>

<h3>Compiling</h3>

<p>See the <a href="https://github.com/sahib/glyr/wiki/Compiling">compile page</a>.</p>

<h3>libglyr:</h3>

<p>See the <a href="https://github.com/sahib/glyr/wiki">examples in src/examples</a> for a quickstart.<br />
There&#39;s also a more <a href="https://github.com/sahib/glyr/wiki/Introduction-to-libglyr">gentle (and brief) introduction.</a><br />
Also see the <a href="http://sahib.github.com/glyr/doc/html/index.html"><span class="caps">API</span> Reference</a><br />
<strong>Please note:</strong> Since version 1.0.0 the <span class="caps">API </span>will be stable, and will only be open for extensions.</p>

<h3>glyrc:</h3>

<p>Please refer to <code>glyrc -h</code> which gives you a brief introduction to the arguments you can pass,<br />
See the <a href="https://github.com/sahib/glyr/wiki/Commandline-arguments">wiki</a> for more detailed information about the options.</p>

<h2><span class="caps">FAQ</span></h2>

<h3>Anyone using it already?</h3>

<ul>
<li><a href="http://gmpc.wikia.com/wiki/Gnome_Music_Player_Client"><span class="caps">GMPC</span></a></li>
<li><a href="http://pragha.wikispaces.com/">Pragha</a></li>
<li><a href="https://github.com/studentkittens/Freya">Freya</a></li>
<li><a href="http://ok100.github.com/lyvi/">lyvi</a></li>
</ul>

<h3>Glyr.. such a silly name! Why? </h3>

<p>Indeed. Should have named it &#39;Glyros&#39; (too late, damnit).</p>

<h3>Is it hard to write something with it?</h3>

<p>Some knowledge of C might be required, but the code is straight forward most of the time.</p>

<p>Bash scripts are pretty straight-forward:<br />
<code>glyrc cover --artist Equilibrium --album Sagas --write &#39;/tmp/:artist:_:album:.:format:&#39; --callback &#39;sxiv &quot;:path:&quot;&#39;</code></p>

<p>Additionally there are bindings to Python and Ruby:</p>

<ul>
<li><a href="https://github.com/sahib/python-glyr">plyr</a> by me (complete <span class="caps">API</span>).</li>
<li><a href="https://github.com/meh/ruby-glyr">ruby-glyr</a> by meh (complete <span class="caps">API</span>).</li>
</ul>


<h3>How..how am I supposed to use it?</h3>

<p>Well, as normal user you could use <code>glyrc</code> to retrieve some metadata in a batchlike fashion.<br />
As developers you have lots of option, you could write glyr-plugins for musicplayers (gmpc!), set up a webserver with this,<br />
hack up little scripts showing covers on the desktop.. everything related to musicmetadat is possible here.<br />
You could also extend libglyr itself but that&#39;s a little harder.</p>

<h3>Isn&#39;t there musicbrainz already?</h3>

<ol>
<li>The kind of metadata downloaded by glyr differs heavily from musicbrainz.<br />
i.e. glyr finds metadata for musicplayers while musicbrainz finds data for CD Rippers and taggers.</li>
<li>Musicbrainz runs remotely on some server and uses a large database which is searched through lucene.<br />
Glyr is a client program which hops over several sites and does not cache anything, unless you do it yourself.<br />
You could of course let glyr run on a (remote) server, and cache all results to do something similiar.</li>
<li>There is <a href="http://www.coverartarchive.org">coverarchive.org</a> , but it does not seem to fully work yet. But it will be accessible once it does.</li>
</ol>

<h2><span class="caps">AUTHOR</span></h2>

<p>See the <span class="caps">AUTHORS </span>file that comes in glyr&#39;s distribution.<br />
See also <span class="caps">COPYING </span>to know about your rights.</p>

<h2>I <span class="caps">CAN HAZ HELP</span>?</h2>

<h3><span class="caps">BUGS</span></h3>

<p>If you found one: <em>Meh. Sorry for that.</em><br />
If you file a bugreport: <em>Hey, thank you!</em></p>

<p>Use the <a href="https://github.com/sahib/glyr/issues">Issue Tracker</a> to share your find.<br />
Alternatively you may drop me a mail at <sahib@online.de></p>

<h3><span class="caps">PATCHES</span></h3>

<p>If you hacked one: Excellent! Send it to me via mail or see below.<br />
If you want to add new providers you should look at the existing provider plugins to get an idea how to write one.<br />
Starting with lib/cover/lastfm.c isn&#39;t a bad idea either, because it is one of the very simple ones.</p>

<p><i>Take the usual Git(Hub) approach:</i><br />
# Fork this project<br />
# Make your changes<br />
# Make a Pull request</p>

<p>If you&#39;re not familiar with git, or just don&#39;t like it,<br />
you can also send me the patch via mail: <sahib@online.de></p>

<p>Thanks for any help in advance!</p>

<h3><span class="caps">WRITE SOFTWARE THAT USES GLYR</span></h3>

<p>May sound strange, but you&#39;re giving me a reason to maintain it, write new providers etc.<br />
Also bugreports (well, there are no bugs, just in case) are appreciated, or just questions.<br />
Those help to make the documentation more clear.</p>

<h3><span class="caps">DONATE</span></h3>

<p>You also might consider a small (CS-Students are already motivated by 1 Cent <img src="http://www.blendpolis.de/images/smilies/icon_wink.gif"/>) donation if you use feel like it:<a class="FlattrButton" style="display:none;" rev="flattr;button:compact;" href="https://github.com/sahib/glyr"></a><br />
<noscript><a href="http://flattr.com/thing/302682/libglyr" target="_blank"><br />
<img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this" title="Flattr this" border="0" /></a></noscript>
(For now only possible via Flattr or <a href="http://sahib.github.com/donate.html">Paypal</a> , you gonna need an account there - Sorry)</p>

<h2><span class="caps">DISCLAIMER</span></h2>

<p>As usual, no warranty is granted that this software works like expected.<br />
Refer to the <span class="caps">GPL</span>v3 copy you got with libglyr. It is <a href="https://github.com/sahib/glyr/blob/master/COPYING">here.</a><br />
Glyr is just a way to find the data, it does not own any rights on the data it found.</p>

<p><b>All retrieved items are copyrighted by their respective copyright owners.</b></p>

<p>Refer to the provider&#39;s terms of use. Every item you get from libglyr contains the name and a url to the provider, so lookup there terms of use there.</p>

<p><br /><br />
<br /></p>



<p>[1] Glyr has not been tested on Mac <span class="caps">OSX </span>yet. If you own a Mac, any help with &#39;porting&#39; glyr is highly appreciated. My guess would be that no to almost no changes need to be done though.</p></body></html>