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

  • genre - the category name
  • title - station title
  • url - streaming url (to pls or m3u resource)
  • playing - currently playing song, if any
  • homepage - station homepage
  • bitrate - (int) audio bitrate (like 128)
  • listeners - (int) number of listeners
  • favicon - url to favicon, if any
  • format - to set a custom audio format (audio/ogg)

• Internal fields are:

  • state - a gtk icon
  • deleted - strikethrough for deleted entries
  • favourite - add a star for bookmarked stations
  • search_col - search color
  • search_set - 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 config: 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.)