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

⌈⌋ branch:  streamtuner2

Update of "write a plugin"


Artifact ID: bf08d81a73c8daf1ea300460c974bd0bdf3b73f4
Page Name:write a plugin
Date: 2015-04-05 22:25:57
Original User: mario
Parent: 1ef15ddc927e2ff9ef2d503119760ffc0522c6ca (diff)
Next de6a5f3b567e6243fc9779ee20ab35b1fd4f2b80

Wrting a new plugin is often trivial. Just create a new channels/ following this structure:

# title: MyPlugin
# description: my radio list
# version: 0.1
# type: channel
# category: radio
# url:
# 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.


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:

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


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/


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