App Anatomy

From DevWiki

Back to Home

Overview

Welcome the Anatomy of a Boxee Application 101. In this section we'll go over the basics of every application, the different parts of an app and how they interact with the client.

Structure

First things first, the app folder/file sctructure is very important for every application and is laid out in the following manner...

<boxee_app_folder>
|
+-+ <appid>
  |
  +-- descriptor.xml
  |
  +-- ...python scripts... (optional)
  |
  +-+ <skin>
    |
    +-+ <Boxee Skin NG>
      |
      +-+ <720p>
      | |
      | +-- ...skin xml files...
      |
      +-+ <media>
        |
        +-- ...images... (optional)

Details

Main Components

This section will pull apart each component of an application and explain in detail how they are used & implemented.

Descriptor

Each Boxee application must have a descriptor file and be packaged with the application, placed in the root folder and called descriptor.xml. The descriptor file is a UTF-8 encoded XML document which allows you to define specific attributes for your application such as the launch window or script, app title and description, version number and more. All attributes are wrapped in the app tag <app>...</app>.

Elements

Examples

Skinned app descriptor example

<?xml version="1.0" encoding="utf-8" ?>
<app>
  <id>pandora</id>
  <name>Pandora</name>
  <version>1.0</version>
  <description>Pandora Radio</description>
  <thumb>http://dir.boxee.tv/apps/pandora/thumb.png</thumb>
  <media>music</media>
  <copyright>Boxee</copyright>
  <email>support@boxee.tv</email>
  <type>skin</type>
  <platform>all</platform>
  <minversion>0.9.11</minversion>
  <startWindow>14000</startWindow>
</app>

Skin app that contains adult content and uses a python script to launch

<?xml version="1.0" encoding="utf-8" ?>
<app>
  <id>adultvideos</id>
  <name>Adult Videos</name>
  <version>1.0</version>
  <description>Adult streaming videos</description>
  <thumb>http://dir.boxee.tv/apps/adultvideos/thumb.png</thumb>
  <media>video</media>
  <copyright>Boxee</copyright>
  <email>support@boxee.tv</email>
  <type>skin</type>
  <platform>all</platform>
  <rating>adult</rating>
  <minversion>0.9.14</minversion>
  <startWindow>myscript</startWindow>
</app>

Skin app using geo blocking

<?xml version="1.0" encoding="utf-8" ?>
<app>
  <id>iplayer</id>
  <name>BBC iPlayer</name>
  <version>1.53</version>
  <description>BBC iPlayer</description>
  <thumb>http://dir.boxee.tv/apps/iplayer/thumb.png</thumb>
  <repository>http://dir.boxee.tv/apps</repository>
  <media>video</media>
  <copyright>Boxee</copyright>
  <email>support@boxee.tv</email>
  <type>skin</type>
  <startWindow>14000</startWindow>
  <platform>all</platform>
  <minversion>0.9.20</minversion>
  <country-allow>uk</country-allow>
</app>

Skin

The skin is what will be used to layout and display your content. Anything goes here. With transparency and animations at your disposal some truley great skins can be created. The Pandora application is a great example of this.

Skins are made up of 3 elements, 1 of which isn't required.

Content

Content can be delivered to your application in 2 different methods.

RSS Feeds

Rss feeds are the easiest way to bring content into your Boxee application. Any list control within boxee can be set to get its content from any rss feed.

<control type="list" id="120">
   ...
   <content type="url" url="rss://mysite.com/rss" />
</control>

Python

You don't need an RSS feed to power the content in your application. You can use python to bring in content from anywhere and build the list manually. It may sound difficult but its actually very simple.

Using the python Http() module (added in the beta version of boxee) allows you to make simple and easy get and post requests to any page, returning the contents of that page. Then, using python, parse the data you need and build the list. Below is an example of this...

import mc
import re
 
sg = mc.Http()
html = sg.Get(searchUrl)
results = re.compile("<alias>(.*?)</alias><link>(.*?)</link>").findall(html)
 
items = mc.ListItems()
for name,link in results:
    item = mc.ListItem( mc.ListItem.MEDIA_UNKNOWN )
    item.SetLabel(name)
    item.SetPath(link)
    item.SetThumbnail(link+"/%s/thumbanil.jpg" % (urllib.quote(name.lower())))
    items.append(item)
 
mc.GetActiveWindow().GetList(120).SetItems(items)

For more information on everything python API, see the Boxee Python API Documentation

PHP to RSS

If the python method scares you, don't just find some random rss feed on the net and slap an application together (unless its already working well for you). Put some php love into it! Yes you can submit php scripts with your application that generate properly formatted rss feeds and sends them back to your application. While not required, you can beef up your application with quality metadata formatted in a way boxee can see. 90% of all boxee official applications work this way to ensure the content is delivered correctly each and every time.

Any php scripts included with your application will be executed server side on the boxee servers and reside in a folder named from your application id. Examples:

App ID = netflix
http://dir.boxee.tv/apps/netflix/{phpscript}

App ID = kickermusic
http://dir.boxee.tv/apps/kickermusic/{phpscript}

NOTE: It is important to note that while you may submit php scripts to boxee for use with your application. We required that it be made available first on another server so we can test the application. Once reviewed by a member of our QA team and approved for the appbox you'll have to resubmit the same apps changing the links within to point to the boxee formated url as show in the above examples. While this may sound like a pain its the only way currently. This being said, its usually best to keep this script located on your own site

Your php script (along with python scripts) will be carefully reviewed for anything malicious. Warning: If anything is found to be malicious, we reserve the right to reject your application and ban you from future application submissions to our repository.

Testing

Apps can be tested locally from within Boxee. Simply place your application folder under the /UserData/apps/ folder and add <test-app>true</test-app> tag to your descriptor. Boxee will automatically load the app in your My Apps section within the Boxee client. To remove a test app, delete the folder from /UserData/apps.

Example using descriptor for a test application

<?xml version="1.0" encoding="utf-8" ?>
<app>
  <id>mytestapp</id>
  <name>mytestap</name>
  <version>1.0</version>
  <description>mytestapp videos</description>
  <thumb>http://dir.boxee.tv/apps/mytestapp/thumb.png</thumb>
  <media>video</media>
  <copyright>Boxee</copyright>
  <email>support@boxee.tv</email>
  <type>skin</type>
  <platform>all</platform>
  <minversion>0.9.20</minversion>
  <startWindow>14000</startWindow>
  <test-app>true</test-app>
</app>

Debugging

Boxee outputs a fairly detailed debug log for help with troubleshooting client and application issues. However to unlock all the debug output you must set your log level to 0. To do this you must first create advancedsettings.xml file in your user data folder:

• Linux: ~/.boxee/UserData/advancedsettings.xml
• Mac/ATV: ~/Library/Application Support/BOXEE/UserData/advancedsettings.xml
• Windows Vista: C:\Users\<windows user name>\AppData\Roaming\BOXEE\userdata\advancedsettings.xml
• Windows XP: C:\Documents and Settings\<your windows user name>\Application Data\BOXEE\userdata\advancedsettings.xml

In this file place the following code:

<advancedsettings>
   <loglevel>0</loglevel>
</advancedsettings>

After relaunching Boxee, your log will be located under the following locations:

• Linux: /tmp/<username>-boxee.log
• Mac/ATV: ~/Library/Logs/boxee.log
• Windows Vista: C:\Users\<your windows user name>\AppData\Roaming\BOXEE\boxee.log
• Windows XP: C:\Documents and Settings\<your windows user name>\Application Data\BOXEE\boxee.log