D 2015-04-14T10:11:46.223
L write\sa\splugin
N text/x-markdown
P 0fe76e43f580b21fcd92d458b02571f3f0d5b2d5
U mario
W 5740
Writing a new plugin is often trivial.
Just create a new `channels/name.py` following this structure:

    # title: MyPlugin
    # description: my radio list
    # url: http://www.mymusicstation.com/
    # version: 0.1
    # type: channel
    # category: radio
    # priority: optional
    # 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.

All fields show up in `self.meta`, for instance the `meta["title"]` or `meta["url"]` are occasionally used. The `config[]` entry is a list/dict combination, and its defaults automatically thrown into `conf.*` variables. Therefore plugins can use their settings right away (e.g. `conf.myplugin_bitrate=128`)

### 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},
      {title: Next.Radio, url: http://pls, genre: Pop, playing: Next Song},
      ...
    ]

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

There are a couple of other attributes.

 - **has_search** `= False`  
   This flag documents if live server searches are available. If it's supported, then the `update_streams()` method may be called with `cat=None` and `search="Find me maybe"` instead; and it's then responsible to do some searching.

 - **audioformat** `= "audio/mpeg"`  
   Sets the default audio stream type for this channel. (Note that each individual stream entry may carry its own `format` attribute, jsut in case.)

 - **listformat** `= "pls"`  
   Declares the channel service playlist type. Can be either "pls" or "m3u" or "xspf" if the server is super modern. It's also possible to use "href" here, if 
you can't be sure of audio or playlist format types. And "srv" if the provider has a clean list of direct streaming URLs only.

 - **default** = "Pop"  
   Is obsolete. Used to specify the first shown category. (That was a workaround for initial crude Gtk handling.)

 - **titles =** `dict(listeners=False)`  
   This defines which station column titles to show. There are title=, genre= which you commonly have. And there is playing= or bitrate= and homepage= which you can omit by setting it to `=False`. Alternatively just rename them with `playing="Artist/Album name`.

 - **datamap** = `[...]`  
   If you want some complexity, column title renaming, and using custom row attributes can be accomplished with a Gtk TreeView datamap. No, you don't want to do that.

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