File: PLUGINS.rst

package info (click to toggle)
sonata 1.7.0-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 4,164 kB
  • sloc: python: 9,480; sh: 33; makefile: 15
file content (69 lines) | stat: -rw-r--r-- 2,600 bytes parent folder | download | duplicates (2)
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
================================
Plugins documentation for Sonata
================================

This document explains how to write plugins for Sonata, a Gtk client for the
`Music Player Daemon`_.

Plugin metadata
===============

TODO


Plugin entr-points
==================

This is the list of entry-points that plugins can hook into Sonata

``cover_fetching(artist, album, on_save_callback, on_error_callback)``
----------------------------------------------------------------------

* ``on_save_callback(fp)``: takes a file-like object as argument, and will save
  its content in a place known by Sonata. However successful the saving was, it
  returns ``True`` if the plugin should *continue* to download more covers, or
  ``False`` if the plugin should *stop* to download covers.

* ``on_error_callback(reason=None)``: takes an optionnal `reason` as argument.
  This must be call if something wrong happens while fetching a cover. This
  returns ``True`` to indicate that the plugin shoud *stop* fetching new covers,
  or ``False`` if the plugin should *continue* fetching new covers.

This entry-point is called when Sonata is requesting a plugin to get a cover for
the specified ``album`` played by the ``artist``. On finding new covers, the
plugin has to call the ``on_save_callback`` callback, passing the content of the
cover as a file-like object. If finding a specific cover fails, the plugin
should call ``on_error_callback``, passing a possible `reason` why it fails.

Depending on the return value of the callbacks, the plugin should continue or
stop fetching new covers.

.. note::
    The reasoning behind both callbacks are as follow:

    * the plugin doesn't have to be responsible of saving the content of the
      cover on the file system, Sonata will do it.
    * the plugin should be told when there are enough covers fetched. This can
      be a hard limit, ranging from 1 (get me the first cover) to (currently) 50
      (get me all the covers that you can find and the user will choose the
      right one). This can also be a way to tell the plugin that the user has
      enough covers and there's no need to download more (the user already
      picked up the right cover).
    * the plugin should not stop in an "infinite", un-stoppable loop. Hence,
      even if fetching a cover fails, the plugin should notify Sonata it tried
      to get one, so it can either be stopped, or get a chance to find more.



``lyrics_fetching``
-------------------

TODO


``playing_song_observers``
--------------------------

TODO

.. _Music Player Daemon: http://musicpd.org