Internet radio browser GUI for music/video streams from various directory services.

⌈⌋ ⎇ branch:  streamtuner2


Changes To write a plugin

Changes to "write a plugin" between 2015-04-03 19:20:30 and 2015-04-05 22:25:57

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
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







-
-
-















+
+


+
+

+
+







    # url: http://www.mymusicstation.com/
    # config: -

    from config import *
    from channels import *

    class myplugin (ChannelPlugin):
        title = "MyNewChannel"
        module = "myplugin"

        has_search = False
        titles = dict(listeners=False)
        categories = []
        catmap = {}

        def update_categories(self):
            self.categories = ["Pop", "Rock", "etc"]

        def update_streams(self, cat, search=None):
            entries = []
            # ...
            # get it from somewhere
            # ...        
            return entries

### Plugin meta block

The description block on top is used for the [plugin management](wiki/plugin+meta+data) (and documentative purposes). This is meant to cleanly separate in-application values (like .module or .has_search, .catmap) from attributes that just serve initialization.

### update_categories()

Each plugin needs a `update_categories()` method. This can be a stub, if the channel plugin has a static list of genres. If so, just set the `categories = [...]` declaration right away. The method is only used if the default categories list is empty, needs to be renewed from the service (e.g. whenever the menu entry Channel>Update_categories is used). There's also a `catmap={}` dict in case category/genre titles have to be associated with service ids.

### update_streams()

More importantly you need the `update_streams()` method to fetch station lists. It receives a `cat` parameter, for instance `"Pop"`. Then do whatever API query or website scraping (regex/pyquery) is necessary to populate a list.

Most plugins will return a list of dicts like:

     {title: Radio123, url: http://pls, genre: Pop, playing: Song123}

63
64
65
66
67
68
69



70
71


72


73
74
75
76
77
78

79
80


81
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







+
+
+


+
+

+
+






+


+
+

      * <kbd>search_col</kbd> - search color
      * <kbd>search_set</kbd> - search state

   * With a `datamap=[]` declaration custom field names could be displayed.

   * Often you just want to rename the column titles however - per `title=dict(listeners="Whatever")` in the class declaration.


### streams = {}

Received station lists get stored internally in a `streams={"Pop":[...]}` dict, and cached in the `~/.config/streamtuner2/cache/` directory of course.

### conf. options

You can access your <kbd>config:</kbd> options per the global `conf.*` dict. Take care to prefer unambigious names like `conf.myplugin_pagesize` etc.

### Attributes

The `has_search` class flag permits live server searches. If one is issued, the `update_streams()` method will be called with `cat=None` and `search="Find me maybe"` set instead.

  * Other class options include `listformat="audio/x-scpls"` for declaring the station URL mime type (here `pls` for example).
  * And `audioformat="audio/mpeg"` for the default audio mime type.
  * While `default="Pop"` can specify which category is visible per default. (Will be retired in later versions. More a clutch for current Gtk handling.)
  * With `titles = dict(listeners=False)` you simply rename one of the default columns. You can also rename them with e.g. `titles = dict(playing="Current Song", genre="Group", title="Artist")` for example.
  * Other internal fields are listed in `channels/_generic.py`

### Installation

To have a new plugin picked up, you need to copy/symlink the file into `/usr/share/streamtuner2/channels/`. It's imported from the `channels` module group automatically. Which allows relocatability, and later even local plugins. (Which is commonly unneeded featuritis though. So not yet implemented.)