Applications
From DevWiki
Contents |
Application Anatomy
Before you start building your application, you must first understand the basic structure and anatomy of every Boxee application. These details remain the same across all platforms and devices.
- Directory Structure
- A Boxee application is simply a folder which contains a descriptor.xml, python scripts (not required), skin/gui xml files, and images used within the skin.
- Application Directory Structure - See the full directory structure for every Boxee application.
- descriptor.xml
- The descriptor is used by Boxee to display application specific information to the user such as title and description. It also tells Boxee how to handle your application, what platforms it should be visible to and where within the application library it should be stored. The descriptor.xml is a required file located in the base of your application directory.
- Descriptor XML - Descriptor XML structure and specifications.
- Python
- Python code can reside either in the Window XML itself within the <controls> tag wrapped in cdata tags or in the root of your application directory. Multiple scripts can be used. If you choose to save your python script(s) in the root of your application folder you can call it from within your application by using the import function.
- Python API - Full Python API documentation with examples.
- Window XML Files
- The skin/Boxee Skin NG/720p/ directory holds all your window xml files. Each one defines the UI for a single window and all have the same basic layout. With each window you can place different controls and define how the user will navigate those controls and the window itself. The structure of the window .xml files can be found on the Window Structure page.
- Window Structure - Get detailed information regarding Window XML files.
- Controls
- Controls define everything from buttons, labels, images, lists and more. There are many different types of controls, all which represent UI elements displayed on-screen and most can be interacted with by the user. Each control, as the window it self, has a basic structure with default properties and specific properties which represent its behavior and look.
- Media
- The skin/Boxee Skin NG/media/ folder stores all your images used within your application. PNG, JPEG and even GIF will work (with limitations) in your application. However we strongly urge you to stick with PNG format. This offers excellent quality with the option of transparency. It scales very well in our UI. Some things to note:
- Images only stretch, they will not repeat or tile.
- Images will be packaged with your application. Keep them as small as you can without loosing quality.
- We can't guarantee that GIFs or JPEG will render properly. Best to stay away.
Examples
- The Basics – The "Hello World" for Boxee.
- The Basics w/Python – Example utilizing our Python API.
- Your First App – Step by step to build your first app by gonzee.tv.
- Vimeo Video App – Example template application.
- Additional Python Examples
Documentation
- Boxee GUI API – The guts of every Boxee application.
- Python API – Using python with your application to expand its abilities.
Submitting Applications
Once you've created your application and you are satisfied with the outcome you need to get it distributed! As of February 27th, 2011, submitting applications to the Boxee Application Library is done using the developers interface on our website. After you submitted your application - the request is then being tracked using JIRA (issue tracking system).
- Application Submission – for submitting applications to the main Boxee repository
Custom Repository
If you choose not to submit your application to the Boxee repository, you may create and maintain your own. Remember that you will get less exposure if users don't see your content without adding a customer repository.
- Custom Repository – for creating and maintaining your own repository
Debugging
Applications can be ran locally from within Boxee without the need to deploy them into an online repository. Regarding debug logs: Please note that boxee debug logs includes details regarding your operating system, some of your hardware and indexed media, apart from registered operations on Boxee and errors from the latest Boxee session.
- On an attached USB drive, create a root folder named "BoxeeApps"
- Place the application folder under "BoxeeApps" folder.
- Add <test-app>true</test-app> to your app's descriptor.xml.
- Register your device (boxee box) using the devices section in the developers tab - and download the certificate.
- Place the dev-certificate.xml inside the BoxeeApps folder.
- Boxee will automatically load the application in "Apps > Favorites".
- Additionally, you can copy new versions of your test application into the "BoxeeApps" folder using the network by enabling Boxee "Windows File Sharing" and connecting via SMB.
Log File Location
- Find the IP address of your Boxee Box: Settings > System > Information.
- Enable Debug logging: Settings > Advanced > Debug Level and set to debug. The system will become slower, but will provide much more information to us.
- Open a web browser on your PC/Mac to http://ip_address:8080 (ie. http://192.168.2.5:8080)
- Click on Boxee Logs Get Latest
Testing
Before releasing your application to the public, you can invite people to beta test it to work out any issues. Boxee makes this easy for you and your testers. Once your app is uploaded and signed, you’ll be able to invite and manage your testers.
Figure 1. The Testers section in your application details screen
- You can add up to 10 testers for each application, including yourself.
- For each user you can select a specific version to be tested or you can select "Latest,” which means that the user will always get the most recent signed version. Most likely you will want to pick "Latest" for your testers.
- After adding a user as a tester, Boxee will send an e-mail on your behalf to him to confirm his participation.
- Once the user confirms his participation, a new (virtual) test repository under your name, will be available for him in the client (Under Apps > Repositories).
- On your application details screen (Figure 1) you can see a status indicator for each tester, next to his username:
- Waiting - A confirmation e-mail was sent to the user.
- Active - User confirmed his participation, your virtual test repository is available for him.
- Disabled - User removed your virtual test repository from his repositories list.
Please note that:
- Each app developer is responsible for all aspects of the uploaded app including providing support the test users.
- The Service does not require any action on the tester side other than approving (via link) of a specific developer app.
- The apps are 3rd party apps and maintained by the respective app developer, any reference should be directed to the app developer, and the app developer must provide its beta testers with contact information for support issues relating the app being tested. Boxee will not respond to any support inquiries about apps in beta testing.
- Boxee serves act only as the host service for publishing those apps for beta testing and by no means owns, reviews, tests validates etc. these applications.
- As the platform owner Boxee reserves the rights to remove, block or perform any administration activity as it sees fit.
- The app at all times, including during beta testing, remains subject to Boxee’s API Terms of Service.
Video Support
Boxee supports just about every type of video format and if you find one we don’t, let us know. From HLS, Flash to raw video formats, its all here. Find out whats supported and whats not and what needs to be done to get it working.
