D 2015-03-25T16:31:51.918
L write\sa\splugin
N text/x-markdown
P 795731e691db4d74051d48f00ed56ee6de59f8f5
U mario
W 3858
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

    from channels import *

    class myplugin (ChannelPlugin):
        title = "MyNewChannel"
        module = "myplugin"
        homepage = "http://www.mymusicstation.com/"
        has_search = False
        titles = dict(listeners=False)
        categories = []
        catmap = {}
        config = []

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

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

The description block on top is used for the plugin management, and decorative purposes. Some fields like `title` and and `module` are repeated in the class declaration though.

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.

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.

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

There's also a `config=[]` list, in case your plugin needs to keep some settings. (For example an API key.)

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 audio mime type.
  * While `current=""` and `default="Pop"` can specify which category is visible per default, or currently active. (Both will be retired in later versions. More a clutch for current Gtk handling.)
  * Other internal fields are listed in `channels/_generic.py`


Z e0e83df39dbf9b21a83e2d104739229d