Introduction

The  Blu-ray platform is unique and has its own advantages compared compared to PC and video game consoles. Coding a Blu-ray application or video game is about knowing the limitations, and taking advantage of the options you have. Limitations breed creativity. This guide is for hobbyists and developers interested in creating custom Blu-ray applications and games, not just standard movie playback. Blu-ray applications uses the 💿 Blu-ray disc.

Blu-ray Overview

Blu-ray Platform Overview

File Structure Overview

1. BDMV directory: contains the PLAYLIST, CLIPINF, STREAM, AUXDATA, and BACKUP directories.
   • PLAYLIST directory: contains the Database files for Movie PlayLists.
     • 📃 xxxxx.mpls files: store information corresponding to Movie PlayLists.
   • CLIPINF directory: contains the Database files for Clips.
     • 🎞️ zzzzz.clpi files: store Clip information associated with a Clip AV stream file.
   • STREAM directory: contains AV stream files.
     • 🎦 zzzzz.m2ts file: contains a BDAV MPEG-2 transport stream.
   • AUXDATA directory: contains Sound data, Image, Font, and asset files.
     • 🔊 sound.bdmv file: stores data relating to one or more interactive sounds.
     • 🔠 aaaaa.otf file: stores the font information associated with Text subtitle applications or BD-J text.
   • BACKUP directory: contains copies of the "index.bdmv" file, the "MovieObject.bdmv" file, all the files in the PLAYLIST directory, and all files in the CLIPINF directory.
   • 🗂️ index.bdmv file: stores information describing the contents of the BDMV directory. There is only one index.bdmv file under the BDMV directory.
   • 💾 MovieObject.bdmv file: stores information for one or more Movie Objects. There is only one MovieObject.bdmv under the BDMV directory.
   • BD-J Object directory: contains BD-J objects.
   • 💽 xxxxx.bdjo file: stores information for one or more BD-J objects.
   • JAR directory: contains Java Archive files (JAR) for BD-J mode.
     • 🫙xxxxx.jar file: A package file used to store Java class files and associated metadata and resources (text, images, etc.) but assets can be stored outside the file.
   • META directory: Subdirectory containing disc metadata and information.
   • DL directory contains the DL XML metadata file
   • dlmt_000.xml file: metadata for the whole disc and would include the title of the movie, and the JPEG/PNG image thumbnail.
   • xxxxx.jpeg: large 640x320 title thumbnail icon.
   • xxxxx.jpeg: small 416x240 title thumbnail icon.

1. CERTIFICATE: Directory containing BD-J security certificate information.
   • app.discroot.crt: contains the BD-J root certificate.
   • id.bdmv: contains the disc's ID information.
   • BACKUP directory: contains copies of the "app.discroot.crt" file, and the "id.bdmv" file.

1. AACS: Directory containing the Blu-ray's DRM AACS decryption files (not required for homebrew or commercial BD-Rs).

Coding/Programming

Blu-ray primarily uses two programing languages for movie and interactive titles.

• HDMV Navigation Commands - An assembly-like command language for HDMV mode
• Java  - A high level object-oriented programing language for BD-J mode
• XML - An optional markup language (used with Java) commonly used for menu UIs and other data via parsing in BD-J mode

Media Codecs

• Graphics - Graphics formats used for menus and app/game assets
• Audio - Audio formats used for linear and interactive sounds
• Video  - Video formats used for movies or video backgrounds

Controls

Blu-ray players primary uses a standard IR remote control for playback and interactive navigation  

    See: Controller 

Limitations

The Blu-ray format comes with limitations such as memory constraints, so you need to be creative and conservative.

    See: Memory & Limitations 

BD-J Build Tools

To compile your BD-J project, you simply need to link the BDJ.jar file and configure javac to use 1.3 for both source and target compatibility. Strictly speaking, the official procedure requires gathering various stub files from multiple vendors and assembling them to create the BDJ.jar file yourself. 

However, this "proper" protocol is no longer practical because many of those original stub files have disappeared from the internet, rendering most online tutorials obsolete. Fortunately, you can bypass this process by sourcing a pre-built BDJ.jar from modern alternatives, such as the Minimal BD-J SDK or the internal files of media player software like CyberLink PowerDVD.

Once you have the BDJ.jar, integrate it into your compilation process by adding it to your classpath. You can use the following javac command to target the appropriate environment:
javac -source 1.3 -target 1.3 -cp path/to/bdj.jar path/to/sourcefiles/*.java 

After successful compilation, you must package your class files into a JAR file. Note that BD-J applications specifically require a "permission request file" (typically an XML-based PRF) to be included within this JAR for proper execution on Blu-ray players. Detailed specifications for this file can be found in the documentation of the minimal BD-J SDK🔗.

Because you are using a standalone JAR rather than an official development kit, you will not have access to native BD-J Javadocs. However, since the platform is based on Java 2 SE v1.3.1, you can use standard Java 1.3 documentation for most general tasks. For specialized BD-J API calls, your best resource is to examine the source code of established BD-J projects.

You can use commercial products for Blu-ray application development:

• Scenarist BD: Top class professional authoring software for Blu-ray and UltraHD Blu-ray. $$$
• Adobe Encore: Discontinued. Professional Blu-ray disc authoring. HDMV only.
• Blu-Disc: Cheaper alternative to Scenarist, supports both BD-J and HDMV. 

Free Blu-ray professional authoring:

• BDedit 🔗: Professional editor, supports HDMV programming, but BD-J programming must be compiled using a different program. Old version free, but newest version requires donation payment. 
• BD-J SDK for Linux 🔗: Free and open-source SDK for building BD-J ISO images on GNU/Linux 

Test Tools

For testing you can use hardware media players or emulators. Simply open the Blu-ray folder or ISO file.

Emulators & Players for Testing 

• CyberLink PowerDVD: Windows only, has the strongest accuracy and reliability for development/testing. $100
• JRiver Media Center: Cross-platform, with solid menu/BD-J support on Windows. As of Version M24, Secondary Video/Audio is not supported yet. $124
• VLC Player: Not recommended for full testing due to bugs and compatibility issues with BD-J. HDMV support is "mostly" fine but with limited controls. Secondary Video/Audio not supported. Free

Hardware Players for Testing

• Dune HD Pro Vision 4K Solo/Real Vision 4K: Offers best-in-class BD-J support (BonusView, BD-Live), fast playback from either BD ISO files or BDMV folders via local drives (USB/SATA) or network (SMB/NFS).
• Dune HD Max (or older Signma-based models): Built-in optical drive + strong BD-J for both physical discs and full structures (ISO/BDMV folders) from HDD/Network. Full support for menus, BonusView and BD-Live, solid for hardware accurate testing. However, newer models are much faster.
• Oppo UDP-203/205 (or clones): Supports BDMV folders, but requires placing the folder structure inside an "AVCHD" folder (uppercase exact spelling) for network shares (SMB/NFS) or USB. BD ISO files are not supported unless jail broken. Unsupported models can also be jail broken, see: https://www.oppo-jb.com/🔗

You can connect a computer to a compatible Blu-ray player via SMB/NFS to run and test your BD app, and easily edit BDMV folders.

BD-J Signing

It's necessary to sign your Xlet for a simple app/game; signing is only necessary when/if you want to:

• Access files on the disc (outside the JAR)
• Use network (e.g. for online highscores, or for a secondary WiFi device)

Meaning you don't have to worry about signing at all at first. It is something you can look into later - if needed. Your application or game will run fine without signing it.

BD-J Hello World

Here's a short "Hello World" example from Blu-Play.com

package com.bluplay.helloworld;

public class HelloWorld extends java.awt.Container implements javax.tv.xlet.Xlet {

  private org.havi.ui.HScene scene;
  private java.awt.Font font;

  public void initXlet(javax.tv.xlet.XletContext context) {
    setSize(1280, 720);
    scene = org.havi.ui.HSceneFactory.getInstance().getDefaultHScene();
    scene.add(this);
    scene.validate();
  }

  public void startXlet() {
    setVisible(true);
    scene.setVisible(true);
    repaint();
  }

  public void pauseXlet() {
    setVisible(false);
  }

  public void destroyXlet(boolean unconditional) {
    scene.remove(this);
    scene = null;
  }

  public void paint(java.awt.Graphics g) {
    g.setColor(new java.awt.Color(0x000000));
    g.fillRect(0, 0, getWidth(), getHeight());
    g.setColor(new java.awt.Color(0xffffff));
    if (font == null) {
      font = new java.awt.Font(null, java.awt.Font.PLAIN, 30);
      g.setFont(font);
    }
    g.drawString("Hello World!", 50, 50);
  }
}

This code was written by Mistalu from Blu-Play.com🔗

HDMV Code Example

Here's a short example of HDMV commands in a Movie Object file. 

00000000 4D 4F 42 4A 30 32 30 30 00 00 00 00 00 00 00 00
00000010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00000020 00 00 00 00 00 00 00 00 00 00 00 26 00 00 00 00
00000030 00 02 00 00 00 01 21 81 00 00 00 00 00 01 00 00
00000040 00 00 00 00 00 01 21 81 00 00 00 00 00 01 00 00
00000050 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00000060 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00

Here's the same commands in it's hexadecimal values (colored).

[21810000,00000001 ,00000000]  Jump Title 1 
[21810000,00000001 ,00000000]  Jump Title 1 

The Jump Title 1 command jumps to the BDMV application's Title. This is useful for making a simple BD-J title. A single BD-J title is located in the BD-J Object file and will execute a Java Xlet.