HOW-TO:Audio addon

From Official Kodi Wiki
Jump to: navigation, search
Home icon grey.png   ▶ Development ▶ Add-on development ▶ Python development ▶ HOW-TO:Audio addon

1 Introduction

This tutorial will explain how to write your first Kodi/XBMC audio plugin Add-on

2 Tools

Assuming you have already followed the Hello World Add-on you will have a text editor already setup. Since we are dealing with audio this time its probably a good idea to have a music player setup. We recommend another great open source project for this:


3 Installing

For this example we will use a nice basic video Add-on tutorials You can find the source-code here:

You can either download as a zip and install both of these inside the kodi GUI from the install from zip feature. Or extract the zip into your userdata/add-ons folder(If you do it this way, you will have to download the beautiful soup module manually as well).

4 Testing

You can first give the add-on a test run by going to: System >> Add-Ons >> Enabled Add-Ons >> Audio Add-Ons >> Example Kodi audio Plugin. You should now be able to listen to some test tracks hosted from an internet web server.

Audio Addon tutorial 1.jpg

5 Explanation

So whats happening in this add-on?

Basically the Add-on is checking a website for the hosted audio files and artwork. In this example we are directly linking to the mp3 files, but there are possibilities for dynamic content and scraping of just about any online source

Once the audio link is sent to Kodi, our music player takes over and buffers, then plays the track just like any other media.

6 Structure <-- This is the actual python code for your Add-On

addon.xml <-- This is the Add-Ons metadata

icon.png <-- A PNG icon for the add-on. It can be 256x256 or 512x512 pixels big. Try to make it look nice! <-- The readme text file with a description of the Add-on and install instructions. This shows on the front of the GitHub page and helps users to understand your Add-on before downloading.

7 The Code

So now we come to the actual Add-On code, this is where most of your Add-on is written and is a simple text file containing python code.

First we initialize the Add-on and import and bits we need. Notice we are using a special web page parsing module called Beautiful Soup.

     import os
     import sys
     import urllib
     import urlparse
     import xbmcaddon
     import xbmcgui
     import xbmcplugin
     import requests
     from bs4 import BeautifulSoup

Now we do check the base URL...

def build_url(query):
      base_url = sys.argv[0]
      return base_url + '?' + urllib.urlencode(query)

Here we set the download source page using the Beautiful soup module

def get_page(url):
     # download the source HTML for the page using requests
     # and parse the page using BeautifulSoup
     return BeautifulSoup(requests.get(url).text, 'html.parser')

The sample below is specific for the page we are scraping you will need to view the source of the page(s) you are planning to scrape to find the content you want to display this will return all the <a> elements on the page: <a href="some_url">some_text</a>

def parse_page(page):
    songs = {}
    index = 1
    for item in page.find_all('a'):
        # the item contains a link to an album cover
        if item['href'].find('.jpg') > 1:
            # format the url for the album cover to include the site url and url encode any spaces
            album_cover = '{0}{1}'.format(sample_page, item['href'].replace(' ', '%20'))
        # the item contains a link to a song containing '.mp3'
        if item['href'].find('.mp3') > 1:
            # update dictionary with the album cover url, song filename, and song url
            songs.update({index: {'album_cover': album_cover, 'title': item['href'], 'url': '{0}{1}'.format(sample_page, item['href'])}})
            index += 1
    return songs

And now iterate over the contents of the dictionary songs to build the list

def build_song_list(songs):
    song_list = []
    for song in songs:
        # create a list item using the song filename for the label
        li = xbmcgui.ListItem(label=songs[song]['title'], thumbnailImage=songs[song]['album_cover'])
        # set the fanart to the albumc cover
        li.setProperty('fanart_image', songs[song]['album_cover'])
        # set the list item to playable
        li.setProperty('IsPlayable', 'true')
        # build the plugin url for Kodi
        # Example: plugin://
        url = build_url({'mode': 'stream', 'url': songs[song]['url'], 'title': songs[song]['title']})
        # add the current list item to a list
        song_list.append((url, li, False))
    # add list to Kodi per Martijn
    xbmcplugin.addDirectoryItems(addon_handle, song_list, len(song_list))
    # set the content of the directory
    xbmcplugin.setContent(addon_handle, 'songs')

And now we set the path of the song to a list item

def play_song(url):
    play_item = xbmcgui.ListItem(path=url)
    xbmcplugin.setResolvedUrl(addon_handle, True, listitem=play_item)

And here we grab the HTML page and launch the Add-on and display the list of songs

def main():
    args = urlparse.parse_qs(sys.argv[2][1:])
    mode = args.get('mode', None)
    if mode is None:
        page = get_page(sample_page)
        content = parse_page(page)
    elif mode[0] == 'stream':

Now we tell Kodi what page to parse and launch the Add-on

if __name__ == '__main__':
    sample_page = ''
    addon_handle = int(sys.argv[1])

8 Final Thoughts

Writing a Audio Add-on is actually pretty simple once you get the basic structure correct. You can scrape most online sources with Regex, or host your own music on the web.

If you have any questions about this tutorial, feel free to discuss it on our forums here