D 2015-04-05T22:25:57.879
L write\sa\splugin
N text/x-markdown
P 1ef15ddc927e2ff9ef2d503119760ffc0522c6ca
U mario
W 4570
Wrting a new plugin is often trivial.
Just create a new `channels/name.py` following this structure:
# title: MyPlugin
# description: my radio list
# version: 0.1
# type: channel
# category: radio
# url: http://www.mymusicstation.com/
# config: -
from config import *
from channels import *
class myplugin (ChannelPlugin):
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}
The title is required, and the streaming URL of course. Other fields are mostly optional.
* Standard fields are:
* <kbd>genre</kbd> - the category name
* <kbd>title</kbd> - station title
* <kbd>url</kbd> - streaming url (to pls or m3u resource)
* <kbd>playing</kbd> - currently playing song, if any
* <kbd>homepage</kbd> - station homepage
* <kbd>bitrate</kbd> - (int) audio bitrate (like 128)
* <kbd>listeners</kbd> - (int) number of listeners
* <kbd>favicon</kbd> - url to favicon, if any
* <kbd>format</kbd> - to set a custom audio format (audio/ogg)
* Internal fields are:
* <kbd>state</kbd> - a gtk icon
* <kbd>deleted</kbd> - strikethrough for deleted entries
* <kbd>favourite</kbd> - add a star for bookmarked stations
* <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.)
Z 33a16177a35199511076502fd1f6ffc4