HelloWorld BD-J Application: Your first cup for the next generation DVD

Background

This document is to help you with getting your first HelloWorld Java application executed on a new Blu-Ray Disc (BD) player you have purchased. The primary target audience are those who are familiar with Java programming and interested in writing BD-J apps.

What You Will Need

General Java programming skill and knowledge about BD-J APIs

You don't need much APIs for the HelloWorld application, but you need to know the APIs for doing anything interesting.

Roughly speaking, BD-J APIs consist of

• PBP 1.0, which is essentially a jdk 1.3 subset,
• JavaTV 1.1,
• GEM 1.0.2 subset, including HAVi,
• Some org.bluray extension APIs.

The complete BD-J spec is available only to the licensees. Licensing terms can be seen at http://www.blu-raydisc.info. It also means that there is no freely available BD-J spec classes that you can compile your application against.

One can download APIs from different sites and add them up; for example, PBP and JavaTV^? specs are available through http://www.jcp.org (http://jcp.org/aboutJava/communityprocess/mrel/jsr129/index.html for PBP, http://jcp.org/aboutJava/communityprocess/mrel/jsr927/index.html for JavaTV). I have also heard that developing against MHP, such as the binary available at http://www.openmhp.org, would get you very close to the BD-J environment. Finally, there is an option to compile against a PC player implementation, which is described next.

BD PC Players

Why They are So Great

There is no BD platform emulator available out there, but these PC players almost work like one. It'll let you execute a BD-J content on a PC off of it's hard disk.

I recommend to test your application on a software player first, and burn it on a BD and try it on a real consumer player such as PS/3 only after you're reasonably confident that the app will work. The consumer players don't give you any debugging capability by default (no System.out/err redirection - they probably shouldn't for a security reason), so if your app fails there, you can't get any information about the failure condition beyond what you see on the screen. It's very frustrating to insert a disc, see nothing on your HD television, and not having any clue why the disc didn't load.

Getting and Installing the Players

Some of the PC players out there are:

• ArcSoft Digital Theatre
• Cyberlink PowerDVD
• InterVideo WinDVD
• Nero ShowTime

Please refer to each player's web site for the system requirements. You do not need a BD drive on your machine for the installation, but the system needs to be reasonably current, in particular, it needs a decent graphics card for HD movie playback. Since each player behaves differently (due to a difference in interpreting the spec, or bugs), it seems to be common for developers to install multiple players and test apps on all of them.

These PC players come with the BD-J platform classes, so you could also search the installation directory for the appropriate .jar or .zip classes and use that to compile your BD-J apps against.

How to get debug message out of the players

Please note that none of these are officially documented feature and can change in any moment. I am listing this because it is very useful to be able to see the stacktrace and your System.out.println output.

• TotalMedia Theatre

It stores the log files in C:\bdlogs. To activate, however, you need to set "-Dlog.level=1" in the file:

C:\Program Files\ArcSoft\...\TotalMedia Theatre\BDJ\jvmoption_CVM_preload.cfg

Each time the player is launched and begins playing, it will create a new log file with a time-stamped file name.

• PowerDVD

Trace log output Windows registry setting:

HKLM\SOFTWARE\Cyberlink\PowerDVD\BDJDebugLog DWORD 0x1

Trace log found in:

C:\Program Files\Cyberlink\PowerDVD\NavFilter\javaLog.txt

C:\Program Files\Cyberlink\PowerDVD\NavFilter\DVBTestlog.txt

• WinDVD

Trace output can be found here (note, I have not verified this):

C:\Documents and Settings\All Users\Application Data\InterVideo\BDJ\ApplicationData\\\DVBTestLog.txt

Also, WinDVD supports remote debugging functionality, which really makes it a great BD-J emulator. If you want more information about it, see the contact information at "http://wiki.java.net/bin/view/Mobileandembedded/BDJPCPlayers".

• ShowTime

To activate the logging feature, you need to place in ShowTime folder a configuration file called:

C:\Program Files\Nero\Nero8\Nero ShowTime\log.cfg

In this file you will specify logging options:

      logFile=<outputlog.txt>
      flushLogFile=[on | off]
      fileInfo=[on | off]
      timestamp=[on | off]
      longname=[on | off]
      log=[fatal | error | warning | info | debug | none | all]

Alternatively, you can create an environment variable called LOG_BDJ_CONFIG, to point to your configure file (in case you name it differently or place it elsewhere). Put any java options in bdj.cfg in ShowTime directory.

BD Consumer players

You need to make sure that your consumer player can read contents on BD-R or BD-RE disc.

PS/3 with the firmware update above 1.60 can read BD-RE.

BD Burner

The BD burner should come with a burning software. I'm using Roxio Creator Home, which was bundled to my Dell XPS M1710 laptop, and I've heard that Sony BluRay^? burner came with CyberLink^? Power2Go^? and it worked just fine too. I haven't heard of any success in making consumer players recognize BDMV image off of something other than a BD, such as a DVD disc and a memory stick. Would love to know if this is possible.

BD (disc)

I've been using BD-RE and not BD-R, since I frequently burn a test disc and it'll be too expensive to not be able to rewrite. I don't have a preference on a disc manufacturer. I tried Sony and Memorex 25GBs and they work great.

Software Development Tools

Creating movie assets

You probably want a BD development software tool, such as Sonic Scenarist, if you want to encode your own HD video and audio streams and assemble a full BDMV directory structure.

HDCookbook

The hdcookbook web page at http://hdcookbook.com, describes a book for BD-J programming. It's open source project at http://hdcookbook.dev.java.net contains tools and sample xlets for creating BD image. Our bdjoconverter tool there lets you edit a bdjo descriptor file, and the bdsigner tool can be used to sign BD-J applications, which is needed if your app needs to perform security sensitive actions. Please take a moment to visit these sites.

Step by Step Guide for running your first BD-J Application

Write, compile and archive your xlet

Write your xlet using your favorite editor or IDE. A sample HelloWorld^? xlet can also be found at the "Documents and Files" section of http://hdcookbook.dev.java.net. Follow the link on the right hand side index bar.

Compile your xlet against your BD-J API classes. Do not forget to add "-source 1.3 -target 1.3" option for javac, else you risk getting UnsupportedClassVersionError^? at runtime. A sample javac command line for HelloWorld^? xlet is:

javac -source 1.3 -target 1.3 -classpath /path/to/your/bdj/classes.zip MainXlet^?.java

Then use the jar command to archive the xlet. A sample jar command line is:

jar -cvf 00000.jar MainXlet^?

Add xlet to the BDMV directory

A sample BDMV can be found at the "Documents and Files" section of http://hdcookbook.dev.java.net. Follow the link on the right hand side index bar.

Your jar files should go into the BDMV/JAR directory.

Create an bdjo file

BDMV/BDJO/*.bdjo file is a descriptor file for the BD-J object. This binary file contains information about the xlets on the disc, such as the jar name and the initial class name (among many other things).

The repository at https://hdcookbook.dev.java.net/svn/hdcookbook/trunk includes a bdjoconverter tool that lets you convert .bdjo file to a human-readable form (.xml or .f3) and back. I've found the tool really useful.

There is a sample xml file for creating a bdjo in our hdcookbook repository also. Look into the grin/xlets/bdjo directory.

To create a bdjo file from the xml file, do:

java -jar bdjo.jar 00000.xml 00000.bdjo

A few notes in the xml file. Inside the "application" tag,

"baseDirectory" entry should match the name of the jar file, such as "00000" if an xlet is in the 00000.jar.

"initialClassName" entry should include the class name for the xlet, such as HelloWorldXlet^? in our example.

"applicationId" indicates the application ID to be used for this xlet. According to the MHP spec, an ID less than 0x3fff means the app is untrusted, and greater than 0x4000 means it's trusted. A trusted app needs to be signed, which I'll describe next. If your app is not going to be signed, make sure to use the ID less than 0x4000, and if signed, greater than 0x4000.

"controlCode" sets how the xlet should be launched. 1 means autostart.

For the complete description of the bdjo file format, refer to section 10.2 BD-J Object file of "System Description Blu-ray Disc Read-Only format" - Part 3 Audio Visual Basic Specifications.

Sign your xlet (Optional)

This step is not required for the HelloWorld^? xlet.

According to the spec, the jar file needs to be signed if the application wants to

* Use the network (given that it's network enabled profile) * Read/write to the local storage * Start/Stop other apps * Start other titles ... etc.

You need to include a Permission Request File, or PRF, in a jar file that you're signing. The PRF file should be named "bluray.XLETNAME.perm" where XLETNAME is the xlet's class name (excluding the package name). The PRF file should be in the same directory as the xlet .class file. For example, if the xlet's fully qualified name is com.sun.xlets.MyXlet, then the PRF should be named bluray.MyXlet.perm and be placed at com/sun/xlets/ in the jar, where MyXlet^?.class file also exists. You can search for some sample PRF files in the "grin/xlets" subdirectory of the hdcookbook repository, https://hdcookbook.dev.java.net/svn/hdcookbook/trunk.

Just like the bdjoconverter, the hdcookbook repository also includes a bdsigner tool that will let you sign one or more jar files. It is a modification to JDK's jarsigner and keytool command-line tools. It requires jdk 1.6 to run. It uses Bouncy Castle Provider for generating a root certificate, which you can download from http://www.bouncycastle.org.

To run the bdsigner tool, do

java -classpath bdsigner.jar:[Bouncy castle jar]:[tools.jar in your jdk installation] net.java.bd.tools.bdsigner.BDSigner org-ID list-of-jar-files

For example,

java -classpath bdsigner.jar:bcporv-jdk15-137.jar:c:/Java/jdk1.6.0_01/lib/tools.jar net.java.bd.tools.bdsigner.BDSigner 56789abc 00000.jar 00001.jar

This signs 00000.jar and 00001.jar with the same root certificate, Make sure that bdsigner.jar is placed before tools.jar in the command line. The organization ID is an 8 digit hex number specified in the index.bdmv file at the root of the BDMV directory structure (unfortunately the file is in the binary format). I've learned that "56789abc" is a safe ID to use for testing.

After running the command, there should be a file called app.discroot.crt in the directory where you've executed the command. This is your root certificate used for signing the jars, and this needs to be included in the BDMV image so that players can use this to authenticate the signing at runtime. Place the root certificate in the CERTIFICATE directory in the BDMV structure, in the same level as the id.bdmv file.

Test it on a PC player

The PC players have an option of playing the BD content off the hard disk. For PowerDVD^?, this is a "Select Source" button on the lower right of the large Play arrow key. Point the source to be the "BDMV" directory containing your .jar and .bdjo file.

Test it on a consumer player

Once you're confident about your application, burn the BDMV image to the Blu-ray Disc and pop it into your consumer player. Enjoy!!