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

⌈⌋ ⎇ branch:  streamtuner2


Update of "write a plugin"

Overview

Artifact ID: 1601e85fb04d9e4fe970de931bd52ce6e7a2419d
Page Name:write a plugin
Date: 2015-03-25 16:24:15
Original User: mario
Mimetype:text/x-markdown
Parent: 1917fddb852be91556943fb4e75428ddd67008c7 (diff)
Next 795731e691db4d74051d48f00ed56ee6de59f8f5
Content

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. (Received data gets stored internally in a streams={} dict.)

  • Standard fields are: genre, title, url, playing, homepage, bitrate, listeners, favicon. Internal fields are: state, deleted, favourite.

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

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