A repository is like your own application hub. Users may add your repository URL from the Boxee app store. The following describes the steps you need to follow in order to host your own repository.
The protocol that the Boxee client communicates with the repository is HTTP. You can use any HTTP web server such as Apache to host your custom Boxee repository. The repository can reside on any directory under your web server.
Important: Every application in a repository must have the application repository id as a prefix to the application id. For example: if your repository if called com.myboxee and you want to build app called “myapp”, then the application id MUST be com.myboxee.myapp. This is required in order to assure global uniqueness in the application ids.
The structure of files under the repository root are as follows:
<root_of_repository> | +-- repository.xml | +-- index.xml | +-+ download | +-- <appid>-<version>.zip | +-- ...
|repository.xml||Descriptor file of the repository (name, thumbnail, etc)|
|index.xml||Index of all the applications and versions in the repository.|
|download||Folder that contains ZIP files of all the applications in the different versions. Each application should be packaged as described below.|
Boxee caches repositories' information once you've added them to your repositories list as a user.
If you changed your repository's repository.xml and the changes do not reflect in your repositories immediately please be patient - if your repository is public (accessible by boxee's servers) than Boxee will update its information once a week by accessing your repository.xml file.
Note: If your repository is private (resides in an address not accessible by boxee's servers) boxee will not save its name and description. Which means that you will see it full name when you add it to your repositories on the client but the next time you'll look at your repositories list you will see only it's URL.
This is a descriptor of the repository. The descriptor file is an XML document which has the root element called repository. The following sub-elements should be placed under that element:
|id||Unique identifier for the repository. We recommend to use the reverse domain of where the repository is hosted. For example, if you host at mydomain.com, the repository should have the id of com.mydomain.|
|url||The full URL of the repository. For example: http://www.mydomain.com.|
|name||The name of the repository. For example: My BOXEE Repository.|
|thumb||URL of a thumbnail to the repository. For example: http://www.mydomain.com/thumb.png. The thumbnail size should be 200×200. The background of the thumbnail must be a graay gradient which can be downloaded from here.|
|description||Free text desribing the repository, creator and its contents.|
<repository> <id>com.mydomain</id> <url>http://www.mydomain.com</url> <name>mydomain</name> <thumb>http://www.mydomain.com/thumb.png</thumb> <description>Official mydomain.com repository.</description> </repository>
This is a index or manifest of all the applications hosted in the repository. The index file is an XML document which has the root element called apps. Under the root element, there are one or more application descriptors (including their app element) as described in the Application Descriptor File specification.
An example of a index file from www.mydomain.com which contains two applications:
<apps> <app> <id>com.mydomain.appid</id> <name>app name</name> <version>0.1</version> <description>High quality live-action and animated films displayed in high resolution</description> <thumb>http://www.mydomain.com/apps/appid/thumb.png</thumb> <repositoryid>com.mydomain</repositoryid> <repository>http://www.mydomain.com</repository> <media>video</media> <author>team-mydomain</author> <copyright>mydomain.com</copyright> <email>email@example.com</email> <type>skin</type> <startWindow>14000</startWindow> <platform>all</platform> <minversion>0.9.14</minversion> </app> <app> <id>com.mydomain.gametrailers</id> <name>GameTrailers</name> <version>1.0</version> <description>Watch videos from GameTrailers.com</description> <thumb>http://www.mydomain.com/apps/gametrailers/thumb.png</thumb> <repositoryid>com.mydomain</repositoryid> <repository>http://www.mydomain.com</repository> <media>video</media> <author>team-mydomain</author> <copyright>mydomain.com</copyright> <email>firstname.lastname@example.org</email> <type>skin</type> <startWindow>14000</startWindow> <platform>all</platform> <minversion>0.9.14</minversion> </app> </apps>
- The download directory contains packaged applications. Boxee applications are packaged in ZIP files.
- The ZIP file must be called appid-ver.zip. For example: com.myboxee.myapp-1.12.zip which means that the the application is called "com.myboxee.myapp" with version number "1.12". See note above that every application in the repository must have the repository id as a prefix.
- The ZIP file must include the application folder. folder name must match the application id.
- The application id and version number must match the information in the application descriptor file.
- The ZIP file must include the application descriptor file called "descriptor.xml" at the root.
- GUI Applications should include all skin files and python files.
- Plugins should also include the file "default.py" and any other additional Python and/or resource files.
Signing Your Applications
When distributing your own applications, you need to sign your application with an API key from the Boxee Developer Profile. Follow these steps to download your app signature file and place in your repository's download directory.
- Login to boxee.tv
- Navigate to http://boxee.tv/developer
- If you haven't already, register as a developer by filling out the profile form
- Click on the Apps tab
- Upload the zip of your application that you will distribute in your repository.
- Click "All Versions and Signatures"
- Click "Download Signature"
- Place the downloaded xml file in your repository's download folder
Prepare your Application
Please perform the following checklist before uploading your application and submitting it.
- No restricted system calls (e.g. "exec") or loading unauthorized binaries
- No uncaught exceptions should appear in the debug log
- No malicious code
- You must have a distributable license for all bundled software (e.g. Python modules)
When naming a Boxee application it's important to be specific - create a name that quickly distinguishes your application from others available on Boxee - this means your collection of great comedy movie scenes from the 90s probably shouldn't just be called "Funny Scenes" :)
Additionally your application name should not be anything that's copyrighted or trademarked. The easiest way to avoid this issue is to do a quick web search for the name of your application. If there's a company, product, or existing show with that name in the first 2-3 pages of results we suggest you change it or reach out to the company to gain permission. If you do obtain permission to use the name please let us know when submitting your application.
Remove unused files and folders
Clear any files/temp files which are not required for you application to run.
- remove thumbs.db, hidden files and directories such as .svn
- remove backup files, or files that ends with ~.
Tripple check your descriptor.xml
- email: Make sure your email or support email is included in the descriptor. The default Boxee support email should not be used if it wasn't developed by Boxee.
- Thumbnail: Your thumbnail MUST be a 200x200 png.
- Adult content: if your app contains adult content, the rating element <rating>adult</rating> must be present.
- Remove the test-app element.
- Make sure the repository element value is http://dir.boxee.tv/apps
- For more descriptor "musts", read Anatomy of a Boxee App under descriptor section.
We ask that if your application contains python scripts to please include the py file and not just the compile pyo files. Although the app will still function its best to keep the code as open as possible. However if you are working with a company that requires this you can zip only the pyo but you must include the python code source (not compiled) in another zip file and attach it to the submission request on JIRA once created. All files are scanned by our QA team for possible malicious code.
- Make sure to increment the version number every time you upload a new version of your application.
- Compress zip your application folder up in normal zip compression.
- MAC Users: Compress the folder using the console zip utility. This will create an archive without including mac hidden files/folders such as __MACOSX ._.DS_Store .DS_Store
zip -r appid-version.zip appid/
For instance... if your application id is baseballvideos and the application version is 1.8, navigate to where your application folder lives. then simply:
zip -r baseballvideos-1.8.zip baseballvideos/
API Terms of Service
- By utilizing the Boxee API you are agreeing to and accepting the terms and conditions set forth in the API Terms of Service