wittybluray

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

README

WittyBluray

Plays Blu-ray images and BDMV folders in WittyMediaServer the way a player does, with their menus, including 4K, HDR and 3D discs. You need it if your disc libraries hold Blu-rays.

A Blu-ray playing in a browser

A Blu-ray image, in a browser. Sita Sings the Blues, Nina Paley, CC0.

A Blu-ray's page

A disc's page in WittyMediaServer. Sita Sings the Blues, Nina Paley, CC0.

A message saying the disc is encrypted

An encrypted pressing gets a plain message, and nothing unlocks it. Big Buck Bunny, Blender Foundation, CC BY 3.0, from a disc pressed by Imagion AG.

What it does

  • Plays the disc's own program: first play, titles, interactive and pop-up menus with animated highlights, chapters and the navigation timer, through a virtual machine for the disc's commands.
  • Reads without mounting: .iso and .img images and BDMV folders, through WittyDisc.
  • 4K and HDR: it reads 2160p HEVC streams with their HDR10, HDR10+ and Dolby Vision flags, so a player can choose what to do on an SDR screen.
  • Subtitles from the disc's presentation graphics, read in windows so a large film is never scanned whole.
  • Java (BD-J) menus, only if you install a Java and turn this on. None is shipped. They run in a default-deny sandbox, and without Java the disc plays its titles.
  • Refuses encrypted discs. AACS-encrypted discs are refused and BD+ is not run. Nothing is decrypted. The server makes its own check as well, whatever a module says.
  • Tells you what's on a disc. The wittybluray command-line tool reports all of this, simulates the menus and draws menu pages.

It doesn't do these yet:

Not yet What happens instead
Secondary audio, picture in picture The disc's choice is recorded, not mixed in
The second view of a 3D disc The 2D view plays, and the second view is reported

Drawing menus into pictures, and the session code that turns steps into streams, stay with the server.

How to use it is in Help inside WittyMediaServer: see Blu-rays.

How to get it

An admin adds it from the module store inside WittyMediaServer: Settings → Modules, then Browse the store, then Add beside WittyBluray. That needs WittyMediaServer 0.6.0-alpha or later, and it works with nothing older. The range this version fits is in module.json: 0.6.0-alpha through 0.6.x.

What it needs

  • FFmpeg, which comes with the server.
  • Java 8 or newer on the server, only for discs with Java menus, and only if you turn that on.
  • WittyDisc, which reads the images, and WittyModule, which is how a server talks to it. Both are built in.
  • No media comes with it.

It's written in Go with no cgo, from the published disc structure.

Platforms

It has only been tested on custom-authored discs, so retail discs may show problems not seen yet.

A program is built for each system below, and the server uses the right one.

System Where it stands
Linux (x64, arm64, 32-bit ARM, x86) Its tests pass on x64, and a Blu-ray playlist has played from a test server with it installed, checked by script. The other CPUs are only built
Windows (x64, arm64) Built. This version hasn't been run on Windows since it became its own program
macOS (Intel, Apple silicon) Built by the release tool. It has not been run on a real Mac
FreeBSD (amd64, arm64) Cross-compiled only. It has not been run

On macOS and FreeBSD the server has no sandbox for a module's helper: it gets a small environment and a soft memory limit, and nothing more.

Building and testing

You need Go 1.26 or newer. In a worktree, first run the copy of dev-modules.mjs kept above the repositories (node D:/projects/dev-modules.mjs on the development machine). It writes a go.work that git ignores, so the checkout builds against the repositories beside it. Never run go work use.

go vet ./...
go test ./... -count=1
go run github.com/wittywilla/wittymodule/cmd/wittymodule check .

The last one checks the manifest. On the same tool, pack -targets linux/amd64 -out release . builds a release for one system. CI also builds for every system.

The tests run disc code in Java, and skip where there's no Java. WMS_REQUIRE_JAVA=1 makes a skip a failure, as CI does. bdj/runtime.jar is built by bdj/java/build.sh, which needs a JDK 11 or newer. You only need that to change the runtime.

To look at a disc by hand:

go run ./cmd/wittybluray info MY_DISC.iso
Command What it shows
wittybluray info <disc> Titles, the disc's program, playlists, clips and streams, 3D and HDR flags
wittybluray playlist <disc> <n> Every item, stream and chapter of one playlist
wittybluray menu <disc> <playlist> A playlist's menu: pages, buttons, every command
wittybluray walk <disc> [button...] Simulates inserting the disc, then pressing menu buttons by id
wittybluray render <disc> <dir> The first menu's pages as PNG files
wittybluray bdj <disc> [seconds [picture.png [key...]]] Java titles and what their code needs; with Java, runs them, pressing the keys named

To use it as a library, wittybluray.Open opens an image or folder, and wittybluray.NewNav gives a navigator: Start, PressButton, PlaylistEnded and the rest return what to do next. Check d.Encrypted first.

wittyblurayplayer/ is the same engine as a program of its own for WittyMediaPlayer, with its own go.mod and manifest.

Licence

Apache-2.0: see LICENSE and NOTICE. If you redistribute it or build on it, keep the NOTICE attribution. It's an original implementation and contains no code from other players. bdj/runtime.jar is original code that re-implements the published interfaces disc applications link against, and contains no Java runtime. Each release archive carries a THIRD-PARTY-NOTICES.txt for what its programs link.

WittyBluray is an independent open-source project. It isn't associated with, sponsored by or endorsed by the Blu-ray Disc Association, any film studio or any other player project. “Blu-ray” and “Blu-ray Disc” are trademarks of the Blu-ray Disc Association; WittyBluray isn't a licensed or certified Blu-ray product and uses no Blu-ray logo. AACS-encrypted discs are refused, BD+ isn't run, nothing is decrypted, and no media comes with it: you're responsible for having the rights to what you open. Any third-party names here only describe what it works with, and belong to their owners. It's provided “as is”, with no warranty; see LICENSE. Local law applies to how you use it. This isn't legal advice.

Releasing

A version tag builds a program for every platform, signs the checksum list, and publishes a release that servers can install.

Versions move in small steps as work lands. go run github.com/wittywilla/wittymodule/cmd/wittymodule@v0.3.0 bump . raises it everywhere it is written (add -part minor for a bigger step). A bump isn't a release: nothing is tagged or published until you tag it. CI fails when code changed since the last tag and the version didn't, because tags never move.

To release:

  1. Check that version in module.json is the one to publish, with the bump committed.
  2. Tag that commit and push the tag: git tag vX.Y.Z, then git push origin vX.Y.Z. A tag with a suffix, such as v1.2.0-beta, is published as a prerelease.
  3. Watch the Actions tab. The signing step uses the WMS_SIGNING_KEY secret of the release environment, and nothing is published without it.

To take a version back, run the withdraw workflow from the Actions tab. It adds the version to a signed list on the release tagged withdrawals, which servers read.

Licensed under Apache-2.0: see LICENSE and NOTICE.

Documentation

Index

Constants

View Source
const (
	UOMenuCall      = 1 << 63
	UOTitleSearch   = 1 << 62
	UOChapterSearch = 1 << 61
	UOTimeSearch    = 1 << 60
	UOSkipToNext    = 1 << 59
	UOSkipBack      = 1 << 58
	UOPlay          = 1 << 57
	UOStop          = 1 << 56
	UOPauseOn       = 1 << 55
	UOPauseOff      = 1 << 54
	UOStillOff      = 1 << 53
	UOForward       = 1 << 52
	UOBackward      = 1 << 51
	UOResume        = 1 << 50
	UOMoveUp        = 1 << 49
	UOMoveDown      = 1 << 48
	UOMoveLeft      = 1 << 47
	UOMoveRight     = 1 << 46
	UOSelect        = 1 << 45
	UOActivate      = 1 << 44
	UOSelectActive  = 1 << 43
	UOPrimaryAudio  = 1 << 42
	UOAngle         = 1 << 40
	UOPopupOn       = 1 << 39
	UOPopupOff      = 1 << 38
	UOPGEnable      = 1 << 37
	UOPGChange      = 1 << 36
	UOSecVideoOn    = 1 << 35
	UOSecVideo      = 1 << 34
	UOSecAudioOn    = 1 << 33
	UOSecAudio      = 1 << 32
	UOPiPPG         = 1 << 30
)

User operation mask bits (UOMask). A set bit means the operation is forbidden while the playlist or item plays.

View Source
const (
	PSRIGStream       = 0  // selected IG (menu) stream, 1-based
	PSRAudio          = 1  // selected primary audio stream, 1-based (0xff = none chosen yet)
	PSRPG             = 2  // bits 0..11: PG/text subtitle stream, 1-based (0xfff = none); bits 16..27: PiP subtitle stream; bit 31: subtitles shown; bit 30: PiP subtitles shown
	PSRAngle          = 3  // selected angle, 1-based
	PSRTitle          = 4  // current title, 1-based (0xffff while first play runs)
	PSRChapter        = 5  // current chapter, 1-based (0xffff when unknown)
	PSRPlaylist       = 6  // current playlist number
	PSRPlayItem       = 7  // current play item
	PSRTime           = 8  // presentation time, 45 kHz
	PSRNavTimer       = 9  // navigation timer, seconds
	PSRButton         = 10 // selected button id (0xffff = none)
	PSRPage           = 11 // current menu page id
	PSRStyle          = 12 // user style number
	PSRParental       = 13 // parental level (the viewer's age; 255 = no limit)
	PSRSecondary      = 14 // bits 0..7: secondary audio; bits 8..15: secondary video; bits 30, 31: shown
	PSRAudioCap       = 15 // player audio capability
	PSRAudioLang      = 16 // preferred audio language, three letters packed
	PSRPGLang         = 17 // preferred subtitle language
	PSRMenuLang       = 18 // preferred menu language
	PSRCountry        = 19 // country code
	PSRRegion         = 20 // region: 1 = A, 2 = B, 4 = C
	PSROutputPref     = 21 // bit 0: the user prefers 3D output
	PSRStereoStatus   = 22 // bit 0: 3D output is on now
	PSRDisplayCap     = 23 // the display's 3D abilities and width
	PSR3DCap          = 24
	PSRUHDCap         = 25
	PSRUHDDisplayCap  = 26
	PSRHDRPref        = 27
	PSRSDRConv        = 28
	PSRVideoCap       = 29 // bit 0: secondary video in HD; bit 1: 25 and 50 Hz video
	PSRTextCap        = 30 // text subtitle abilities
	PSRProfile        = 31 // player profile (bits 16..23) and version (bits 0..15)
	PSRBackupTitle    = 36
	PSRBackupChapter  = 37
	PSRBackupPlaylist = 38
	PSRBackupItem     = 39
	PSRBackupTime     = 40
	PSRBackupButton   = 42
	PSRBackupPage     = 43
	PSRBackupStyle    = 44
)

Player status registers the engine uses.

View Source
const (
	Profile1v10 = 0x00000100 // the first players
	Profile1v11 = 0x00010110 // Bonus View: secondary streams and local storage
	Profile2v20 = 0x00030200 // BD-Live: network access
	Profile3v20 = 0x00080200 // audio-only players
	Profile5v24 = 0x00130240 // 3D
	Profile6v30 = 0x00000300 // Ultra HD
)

Player profiles as PSR31 carries them. A disc's program reads this to decide what to offer: 3D, BD-Live, secondary video.

View Source
const MaxStructureBytes = 16 << 20

MaxStructureBytes bounds how much of any .bdmv/.mpls/.clpi file is read.

View Source
const NoButton = 0xffff

NoButton means "none" in button references.

View Source
const NoSound = 0xff

NoSound is the button sound id meaning "none".

Variables

View Source
var ManifestJSON []byte

ManifestJSON is this module's manifest (docs/MODULES.md, "The manifest").

Functions

This section is empty.

Types

type AngleClip

type AngleClip struct {
	Clip  string
	Codec string
	STCID int
}

AngleClip is one angle's clip.

type BDJApp added in v0.3.0

type BDJApp struct {
	Control      int // 1 = starts by itself, 2 = another application starts it
	Type         int // 1 = BD-J
	Org          uint32
	ID           uint16
	Priority     int
	Binding      int
	Visibility   int
	Names        map[string]string // by language
	Icon         string
	BaseDir      string // the JAR file's name, without .jar
	ClassPath    string
	InitialClass string
	Params       []string
}

BDJApp is one application of the title.

type BDJCacheItem added in v0.3.0

type BDJCacheItem struct {
	Dir  bool // a folder rather than a JAR
	Name string
	Lang string // "*.*" = always; "%%%" = when no language matches
}

BDJCacheItem is a JAR file or folder to load before the title starts.

type BDJObject added in v0.3.0

type BDJObject struct {
	Name    string
	Version string
	// DefaultFont names a font in AUXDATA ("" = none). HAViConfig is the
	// graphics configuration the applications start with.
	DefaultFont     string
	HAViConfig      int
	MenuCallMask    bool
	TitleSearchMask bool
	Cache           []BDJCacheItem
	// Playlists the applications may play. AccessToAll allows every playlist
	// on the disc; AutostartFirst plays the first one as the title starts.
	Playlists      []int
	AccessToAll    bool
	AutostartFirst bool
	Apps           []BDJApp
	KeyInterest    uint32 // the 11 remote keys the title wants, top bit first
	// FileAccess lists the folders the applications may read ("." = all).
	FileAccess []string
}

BDJObject is one .bdjo file.

func ParseBDJObject added in v0.3.0

func ParseBDJObject(name string, b []byte) (*BDJObject, error)

ParseBDJObject parses one .bdjo file.

func (*BDJObject) Autostart added in v0.3.0

func (o *BDJObject) Autostart() []*BDJApp

Autostart lists the applications that start with the title.

type BOG

type BOG struct {
	DefaultValid int
	Buttons      []Button
}

BOG is a button overlap group: buttons that share a place on screen, of which one (the valid one) is shown at a time.

type Button

type Button struct {
	ID             int
	NumericSelect  int // the number key that selects it, or NoButton
	AutoAction     bool
	X, Y           int
	Up, Down       int // neighbours by button id, NoButton when none
	Left, Right    int
	Normal         StateImages
	Selected       StateImages
	Activated      StateImages
	SelectedSound  int
	ActivatedSound int
	Commands       []Command
}

Button is one menu button.

type ButtonPage

type ButtonPage struct {
	Button, Page  uint32
	SetButton     bool
	SetPage       bool
	PageEffectOff bool
}

ButtonPage is SET_BUTTON_PAGE: change the menu's page and/or button.

type ButtonState

type ButtonState int

ButtonState picks which picture of a button to draw.

const (
	ButtonNormal ButtonState = iota
	ButtonSelected
	ButtonActivated
)

type Clip

type Clip struct {
	Name    string // five digits
	Version string
	// StreamType: 1 = a normal transport stream. ApplicationType: 1 = main
	// movie, 2 = time-based slideshow, 3 = browsable slideshow pictures, 4 =
	// browsable slideshow audio, 5 = IG menu, 6 = text subtitles, 7 = other
	// sub-path streams (secondary audio or video).
	StreamType, ApplicationType int
	TSRate                      int    // bytes per second of the transport stream
	Packets                     uint32 // source packets (192 bytes each)
	STC                         []STCSequence
	Programs                    []Program
	EPMaps                      []EPMap
}

Clip is one .clpi file.

func ParseClip

func ParseClip(name string, b []byte) (*Clip, error)

ParseClip parses one .clpi file.

func (*Clip) Duration

func (c *Clip) Duration() float64

Duration is the clip's length in seconds from its time bases.

func (*Clip) EndPTS added in v0.3.0

func (c *Clip) EndPTS(stc int) uint32

EndPTS is where a time base ends (45 kHz), or 0 when the clip does not say.

func (*Clip) EntryAfter added in v0.3.0

func (c *Clip) EntryAfter(pid uint16, stc int, pts uint32) (e EPEntry, ok bool)

EntryAfter is the first entry point after a time on a video stream, within that time base; ok is false when there is none.

func (*Clip) EntryAt added in v0.3.0

func (c *Clip) EntryAt(pid uint16, stc int, pts uint32) (e EPEntry, ok bool)

EntryAt is SPNAt within one time base. A clip with several (the clock restarts mid-file, as when studios join separately encoded reels) has the same times more than once, and its entries are not in time order overall, so a play item's time only means something inside its own time base. stc -1 searches the whole map. A stream with no map of its own uses the clip's first one (audio-only clips map their audio).

func (*Clip) SPNAt

func (c *Clip) SPNAt(pid uint16, pts uint32) (e EPEntry, ok bool)

SPNAt returns the entry point at or before the time (45 kHz) in the stream, so a player can start reading there. ok is false when the clip has no entry-point map for that stream.

func (*Clip) STCRange added in v0.3.0

func (c *Clip) STCRange(stc int) (from, to uint32, found bool)

STCRange is the source packets of a time base; found is false when the clip has only one, or no such number.

func (*Clip) Size

func (c *Clip) Size() int64

Size is the clip's length in bytes.

func (*Clip) Stream

func (c *Clip) Stream(pid uint16) *ClipStream

Stream finds a stream by PID.

func (*Clip) VideoPID

func (c *Clip) VideoPID() uint16

VideoPID is the clip's main video stream, or 0.

type ClipStream

type ClipStream struct {
	PID    uint16
	Coding byte
	Format int
	Rate   int
	Aspect int // video: 2 = 4:3, 3 = 16:9
	Lang   string
	// HEVC video: DynamicRange 0 = SDR, 1 = HDR10, 2 = Dolby Vision; ColorSpace 1 = BT.709, 2 = BT.2020.
	DynamicRange, ColorSpace int
}

ClipStream is one elementary stream as the clip describes it.

type Command

type Command struct {
	Op       uint32
	Dst, Src uint32
}

Command is one 12-byte HDMV navigation command, as stored.

type Disc

type Disc struct {
	Source       Source
	Label        string
	Index        *Index
	MovieObjects []MovieObject
	Playlists    map[int]*Playlist
	Clips        map[string]*Clip
	// Encrypted is set when the disc's streams are scrambled (AACS or
	// otherwise). The engine never decrypts anything: such discs are refused
	// for playback. An AACS folder alone does not count, because a decrypted
	// copy usually keeps it; what matters is whether the video is readable.
	Encrypted bool
	// AACSFolder: the disc has an AACS folder. BDPlus: it has a BD+ program
	// (BDSVM). The engine does not run BD+ either; on such a copy some of the
	// picture may be damaged by design, which only the disc's own conversion
	// repairs.
	AACSFolder, BDPlus bool
	// Damaged names structures that could not be read from the disc or their
	// backups, and which were done without.
	Damaged []string
	// Recording: a BDAV or similar recording with no disc program; each clip
	// was made a playlist.
	Recording bool
	// Stereo3D: the disc has 3D (MVC) content: an SSIF folder, a dependent
	// view stream, or the index's 3D flag.
	Stereo3D bool
	// BDJ: the disc's first play, top menu or a title is a BD-J (Java)
	// program. Those run in a separate process when the server has Java (see
	// bdj.go); otherwise the disc plays from its playlists.
	BDJ bool
	// contains filtered or unexported fields
}

Disc is an opened Blu-ray.

func Open

func Open(p string) (*Disc, error)

Open opens an image file or a disc folder (the folder that contains BDMV, or BDMV itself).

func (*Disc) BDJObject added in v0.3.0

func (d *Disc) BDJObject(name string) (*BDJObject, error)

BDJObject reads a BD-J object by name, from its backup copy if it is damaged.

func (*Disc) Clip

func (d *Disc) Clip(name string) *Clip

Clip returns a clip's information by name.

func (*Disc) ClipExtents

func (d *Disc) ClipExtents(name string) ([]FileExtent, error)

ClipExtents returns the byte extents of a clip's stream file.

func (*Disc) ClipLead added in v0.3.0

func (d *Disc) ClipLead(clip string, video uint16, from uint32, only ...uint16) float64

ClipLead says how long before the first picture a stretch of a clip's earliest packet lies, in seconds: usually sound, stored ahead of its picture. A demuxer puts an input on its timeline by that packet, so whoever joins clips must allow for it. video is the picture's PID; 0 when nothing can be told. only, when given, limits which streams count.

func (*Disc) Close

func (d *Disc) Close() error

Close releases the image.

func (*Disc) ExportProgram added in v0.3.0

func (d *Disc) ExportProgram(dst string, maxBytes int64) error

ExportProgram copies the disc's program files (not its video) into a folder laid out as the disc is, for a BD-J runtime that reads them as files. Every name is checked: a disc cannot place a file outside dst.

func (*Disc) LoadMenu

func (d *Disc) LoadMenu(clip string, pid uint16, limit uint32) (*Menu, error)

LoadMenu reads the IG stream with the PID from a clip. For in-mux menus (the IG stream inside the title's clip) `limit` packets are scanned (0 = the whole clip); menu clips are small and read whole.

func (*Disc) MainPlaylist

func (d *Disc) MainPlaylist() *Playlist

MainPlaylist finds the feature. Longest wins, with care, because longest is what some discs try to defeat: copy-protection schemes add hundreds of playlists that loop a clip, name clips that are not there, run past a clip's end, or shuffle the real film's clips into nonsense. So a playlist counts each stretch of a clip only once and is out if it reads what cannot be read. Among those near the longest, the one the disc's program names wins, then the one whose clips follow on from each other in time (a shuffled copy has the same length but its seams do not meet), then the one with chapters. A disc with no video at all (a music disc) picks by sound.

func (*Disc) Playlist

func (d *Disc) Playlist(n int) *Playlist

Playlist returns a playlist by number.

func (*Disc) PlaylistDuration

func (d *Disc) PlaylistDuration(pl *Playlist) float64

PlaylistDuration is the playlist's length in seconds.

func (*Disc) ReadPID

func (d *Disc) ReadPID(clip string, pid uint16, from, to uint32, fn PESHandler) error

ReadPID reads the PES packets of one PID from a clip, from source packet `from` up to (not including) `to` (0 = the end).

func (*Disc) ReadProgramFile added in v0.3.0

func (d *Disc) ReadProgramFile(rel string, max int64) ([]byte, error)

ReadProgramFile reads a file of the disc's program by its path under BDMV.

func (*Disc) Sounds added in v0.3.0

func (d *Disc) Sounds() *Sounds

Sounds reads the disc's button sounds; nil when it has none.

func (*Disc) Subtitles

func (d *Disc) Subtitles(clip string, pid uint16, from, to uint32) (*SubtitleWindow, error)

Subtitles decodes the PG stream `pid` of a clip between two times (45 kHz; to = 0 means the end). The clip is read from the entry point at or before `from`, so a long movie is never scanned whole.

func (*Disc) SubtitlesIn added in v0.3.0

func (d *Disc) SubtitlesIn(clip string, pid uint16, stc int, from, to uint32) (*SubtitleWindow, error)

SubtitlesIn is Subtitles within one time base of the clip (-1 = all). The read starts a little before `from`, since a picture is stored ahead of the time it shows.

func (*Disc) TextSubtitles added in v0.3.0

func (d *Disc) TextSubtitles(clip string, pid uint16, charCode int) ([]TextCue, error)

TextSubtitles reads a text subtitle clip whole (they are small). charCode is the stream's character coding from the playlist.

type EPEntry

type EPEntry struct {
	PTS uint32 // 45 kHz
	SPN uint32 // source packet number; byte offset = SPN * 192
	// AngleChange marks the packet as a point where a seamless angle change
	// may happen.
	AngleChange bool
}

EPEntry is one entry point: a packet at which decoding can start.

type EPMap

type EPMap struct {
	PID     uint16
	Entries []EPEntry // in time order
}

EPMap maps presentation times to source packet numbers for one stream.

type Effect added in v0.3.0

type Effect struct {
	DurationSec float64
	Palette     int
	Objects     []compObject
}

Effect is one step of a transition: pictures placed in windows, for a time.

func (*Effect) GobDecode added in v0.3.0

func (e *Effect) GobDecode(b []byte) error

GobDecode reads an effect and checks it.

func (Effect) GobEncode added in v0.3.0

func (e Effect) GobEncode() ([]byte, error)

GobEncode sends an effect with where its pictures go.

type EffectSequence added in v0.3.0

type EffectSequence struct {
	Windows []Window
	Effects []Effect
}

EffectSequence is a page transition: a list of timed compositions.

type Effects

type Effects struct {
	NavTimer      *NavTimer
	ButtonPage    *ButtonPage
	EnableButton  []uint32
	DisableButton []uint32
	PopupOff      bool
	Still         *bool
	OutputMode3D  *bool
	StreamChange  bool // audio, subtitle, IG or angle registers changed
	// NavTimerOff: SET_NV_TIMER with a time of 0 cancelled the timer.
	NavTimerOff bool
}

Effects collects what SET_SYSTEM commands asked for during a run; the player applies them.

type FileExtent

type FileExtent struct {
	Path   string `json:"path"`
	Offset int64  `json:"offset"`
	Length int64  `json:"length"`
}

FileExtent is a byte range of a stream file: inside the image, or a file on disk when the disc is a folder.

type Group

type Group int

Group is a command's group.

const (
	GroupBranch Group = iota
	GroupCompare
	GroupSet
)

type Index

type Index struct {
	Version    string
	Stereo3D   bool // the disc prefers 3D output when the player can
	HasContent bool // the disc says it holds 3D content
	// DynamicRange is the initial dynamic range of an Ultra HD disc.
	DynamicRange int
	// VideoFormat and FrameRate are the disc's main video, as its menus
	// expect: 1 = 480i, 2 = 576i, 3 = 480p, 4 = 1080i, 5 = 720p, 6 = 1080p,
	// 7 = 576p; frame rates 1 = 23.976, 2 = 24, 3 = 25, 4 = 29.97, 6 = 50, 7 = 59.94.
	VideoFormat, FrameRate int
	FirstPlay, TopMenu     IndexObject
	Titles                 []Title
}

Index is BDMV/index.bdmv.

func ParseIndex

func ParseIndex(b []byte) (*Index, error)

ParseIndex parses index.bdmv.

type IndexObject

type IndexObject struct {
	Kind        ObjectKind
	Interactive bool   // the object has a menu (an IG stream or BD-J UI) rather than just playing
	MovieObject int    // HDMV: the movie object to run
	BDJName     string // BD-J: the object's name (BDMV/BDJO/<name>.bdjo)
}

IndexObject is one entry of the index: first play, top menu or a title.

type Instr

type Instr struct {
	Raw      Command
	Group    Group
	Sub      int // branch: 0 goto, 1 jump, 2 play; set: 0 set, 1 set system
	Opt      int // branch option, compare option or set option
	Operands int
	ImmDst   bool
	ImmSrc   bool
	Dst, Src uint32
}

Instr is a decoded command.

func Decode

func Decode(c Command) Instr

Decode decodes a command.

func (Instr) Name

func (in Instr) Name() string

Name is the command's mnemonic.

func (Instr) String

func (in Instr) String() string

String is a readable form, e.g. "EQ GPR4094, 3".

type Mark

type Mark struct {
	Type     int
	Item     int    // index into Items
	Time     uint32 // 45 kHz ticks into the clip, in the item's time base
	PID      uint16 // the stream it applies to, 0xffff for all
	Duration uint32
}

Mark is a chapter (Type 1, "entry mark") or a link point (Type 2).

type Menu struct {
	Width, Height int
	// Popup menus (UIModel 1) stay hidden until the user's Popup key; always-on
	// menus (0) show at once.
	Popup bool
	// Timeout and SelectionTimeout are the stream times (seconds, 0 = none)
	// when the menu ends and when selection ends and the default activated
	// button runs. UserTimeout is how long a pop-up stays with no key pressed.
	Timeout, SelectionTimeout, UserTimeout float64
	Pages                                  []Page
	// contains filtered or unexported fields
}

Menu is one IG stream.

func (m *Menu) Draw(img *image.NRGBA, page *Page, b *Button, state ButtonState) bool

Draw paints one button in a state into img (the menu's full frame): the first picture of the state's animation.

func (m *Menu) DrawEffect(seq *EffectSequence, i int) *image.NRGBA

DrawEffect paints one step of a transition on a full frame.

func (m *Menu) DrawFrame(img *image.NRGBA, page *Page, b *Button, state ButtonState, frame int) bool

DrawFrame paints picture `frame` of a button state's animation (frames wrap, so a looping highlight can be drawn for any frame number).

func (m *Menu) GobDecode(b []byte) error

GobDecode reads a menu and checks it.

func (m *Menu) GobEncode() ([]byte, error)

GobEncode sends a menu with its palettes and pictures.

func (m *Menu) Objects() int

Objects and Palettes count what the stream carried (for diagnostics).

func (m *Menu) Page(id int) *Page

Page returns a page by id.

func (m *Menu) Palettes() int
func (m *Menu) Rect(b *Button) image.Rectangle

Rect is a button's place on screen, from its picture.

func (m *Menu) Render(page *Page, buttons []*Button, selected int) *image.NRGBA

Render draws a whole page with one button selected. Buttons are those Visible returns; the result is transparent where there are no buttons.

type MovieObject

type MovieObject struct {
	ResumeIntention bool // playback resumes in this object after a menu call
	MenuCallMask    bool // the user's menu key is ignored while it runs
	TitleSearchMask bool // the user's title search is ignored while it runs
	Commands        []Command
}

MovieObject is one program.

func ParseMovieObjects

func ParseMovieObjects(b []byte) ([]MovieObject, error)

ParseMovieObjects parses MovieObject.bdmv.

type Nav struct {
	// contains filtered or unexported fields
}

Nav runs a disc.

func NewNav

func NewNav(d *Disc, o NavOptions) *Nav

NewNav makes a navigator for the disc. An Ultra HD disc gets an Ultra HD player: such discs ask, and refuse to start on anything else.

func (n *Nav) Clone() *Nav

Clone copies the navigator, to explore a disc without disturbing it.

func (n *Nav) Forbids(uo uint64) bool

Forbids says whether the playing playlist or item forbids a user operation (a UO constant).

func (n *Nav) LoopsAtEnd(st *Step) bool

LoopsAtEnd says whether the disc's program starts this same playlist again when it ends. Such a menu plays as one seamless loop; anything else (a menu that moves on by itself) must be reported as ended.

func (n *Nav) MenuAllowed() bool

MenuAllowed says whether the disc lets the viewer call the menu now: the movie object or the playing playlist and item can forbid it.

func (n *Nav) MenuCall() *Step

MenuCall is the user's Menu key: the top menu. When the disc's program means the playing object to be resumed (its resume-intention flag), it is suspended so RESUME can return; otherwise it ends here. A disc that masks the key sees nothing happen.

func (n *Nav) NavTimerFired() *Step

NavTimerFired is called by the player when the SET_NV_TIMER timeout of the last Step has passed with no user action.

func (n *Nav) PlayPlaylist(pl *Playlist, item int, t uint32) *Step

PlayPlaylist plays a playlist directly, outside the disc's program: for "play the movie" from a library, and for discs whose program needs BD-J. When the playlist ends, nothing follows (PlaylistEnded stops).

func (n *Nav) PlayTitle(t int) *Step

PlayTitle starts a title from the title list (1-based), as the user's title search does.

func (n *Nav) PlaylistEnded() *Step

PlaylistEnded is called by the player when the playlist of the last Step has played to its end: the disc's program continues after PLAY_PL.

func (n *Nav) PressButton(cmds []Command) *Step

PressButton runs a menu button's commands (from the IG stream). A button may change the menu (page, selected button), start another playlist, end the menu (TERMINATE_PL) or jump elsewhere.

func (n *Nav) Registers() *Registers

Registers exposes the player's registers (read, or set by the player for stream choices through SetAudio and friends).

func (n *Nav) Resume() *Step

Resume returns to what a call or menu call suspended.

func (n *Nav) SetAngle(a int)
func (n *Nav) SetAudio(s int)

SetAudio and SetSubtitle record the user's stream choices (1-based; a subtitle stream of 0 hides subtitles).

func (n *Nav) SetChapter(c int)

SetChapter records the chapter the player is in (1-based).

func (n *Nav) SetMenuState(page, button int)

SetMenuState records the page and button on show, which a disc's commands read to find out what was pressed.

func (n *Nav) SetSubtitle(s int, shown bool)
func (n *Nav) SetTime(item int, t uint32)

SetTime tells the navigator where playback is, for resume and the disc's own program (PSR8).

func (n *Nav) SkipItem(delta int) (st *Step, ok bool)

SkipItem moves within an item-by-item playlist (a slideshow), one way or the other; ok is false when the playlist does not play that way or has no such item.

func (n *Nav) Start() *Step

Start begins as if the disc were just inserted: the first-play object.

func (n *Nav) Timer() *NavTimer

Timer is the navigation timer running now, or nil. The player starts its clock when this changes and calls NavTimerFired when it runs out.

type NavOptions struct {
	Registers RegisterOptions
}

NavOptions configure the player the navigator simulates.

type NavTimer struct {
	Seconds uint32
	Object  int
}

NavTimer is SET_NV_TIMER: run a movie object after some seconds (at most 300).

type Object

type Object struct {
	ID            int
	Width, Height int
	Pixels        []byte // Width*Height palette indexes
}

Object is one run-length-coded picture, as indexes into a palette.

type ObjectKind

type ObjectKind int

ObjectKind says what kind of program an index entry runs.

const (
	ObjectNone ObjectKind = iota
	ObjectHDMV            // a movie object in MovieObject.bdmv
	ObjectBDJ             // a BD-J (Java) object
)

func (ObjectKind) String

func (k ObjectKind) String() string

type PESHandler

type PESHandler func(payload []byte, pts uint64) bool

PESHandler receives one PES packet's payload and 90 kHz presentation time; it returns false to stop reading.

type Page

type Page struct {
	ID               int
	UOMask           uint64
	DefaultSelected  int // button id, or NoButton
	DefaultActivated int // a button that runs when the selection times out, or NoButton
	Palette          int
	// AnimationRate is the video frames per animation frame of the buttons'
	// state animations (0 = no animation).
	AnimationRate int
	BOGs          []BOG
	// In and Out are the page's transition effects, played as it opens and
	// closes.
	In, Out EffectSequence
}

Page is one menu page.

func (*Page) Button

func (p *Page) Button(id int) *Button

Button finds a button on a page.

func (*Page) Visible

func (p *Page) Visible(enabled, disabled map[int]bool) []*Button

Visible lists the buttons shown on the page: each group's valid button, as the group defaults say, overridden by `valid` (button ids enabled by ENABLE_BUTTON) and `hidden` (disabled ones).

type Palette

type Palette [256]color.RGBA

Palette is 256 colours. Entries a segment does not set are transparent.

type PlayItem

type PlayItem struct {
	Clip  string // the clip's five-digit name, e.g. "00005"
	Codec string // "M2TS"
	// ConnectionCondition says how this item joins the previous one: 1 =
	// seamless (same clip continues), 5 = seamless across clips, 6 = a break
	// (the player may pause briefly).
	ConnectionCondition int
	STCID               int
	In, Out             uint32 // 45 kHz ticks into the clip
	UOMask              uint64
	RandomAccess        bool
	// StillMode: 0 = none, 1 = a still of StillTime seconds after the item,
	// 2 = a still until the user acts.
	StillMode int
	StillTime int
	// Angles lists the clips of a multi-angle item; the first is the main
	// angle (the same as Clip).
	Angles           []AngleClip
	SeamlessAngles   bool
	DifferentAudios  bool
	Video, Audio, PG []Stream
	IG, SecAudio     []Stream
	SecVideo, PiPPG  []Stream
	DV               []Stream // Dolby Vision enhancement layers
}

PlayItem is one stretch of a clip.

func (*PlayItem) Duration

func (p *PlayItem) Duration() float64

Duration is the item's length in seconds.

type Playlist

type Playlist struct {
	Number       int
	Version      string
	PlaybackType int // 1 = sequential, 2 = random, 3 = shuffle
	// PlaybackCount is how many items a random or shuffle playlist plays.
	PlaybackCount int
	UOMask        uint64 // user operations the disc forbids (see UO constants)
	RandomAccess  bool   // the user may not jump around (chapter search, time search) when false
	// AudioMix: the disc mixes button sounds and secondary audio into the
	// primary audio. LosslessBypass: it allows lossless output unmixed.
	// RightEyeBase: on a 3D playlist the base (2D) view is the right eye.
	AudioMix, LosslessBypass, RightEyeBase bool
	Items                                  []PlayItem
	SubPaths                               []SubPath
	Marks                                  []Mark
}

Playlist is one .mpls file.

func ParsePlaylist

func ParsePlaylist(number int, b []byte) (*Playlist, error)

ParsePlaylist parses one .mpls file.

func (*Playlist) SubClip added in v0.3.0

func (pl *Playlist) SubClip(s Stream) string

SubClip finds the clip a stream outside the main path is in: its sub-path and the numbered clip of that sub-path's first item.

type Program

type Program struct {
	StartSPN uint32
	PMTPID   uint16
	Streams  []ClipStream
}

Program is one program of the transport stream and its streams.

type RegisterOptions

type RegisterOptions struct {
	AudioLang, SubtitleLang, MenuLang string // three-letter codes, e.g. "eng"
	Country                           string // two letters, e.g. "US"
	Region                            int    // 1 = A, 2 = B, 4 = C; 0 = A
	Parental                          int    // 0 = no limit
	Stereo3D                          bool   // the display can show 3D
	UHD                               bool   // an Ultra HD player (for Ultra HD discs, which ask)
}

RegisterOptions set the player's identity: languages, region, 3D.

type Registers

type Registers struct {
	GPR [4096]uint32
	PSR [128]uint32
	// Rand returns a number in [0,1) for RND; tests and diagnostic tools set
	// it to make a run repeatable. nil uses the system generator.
	Rand func() float64
}

Registers: 4096 general-purpose registers the disc may set freely, and 128 player status registers (PSRs) that describe the player and the playback state, which the disc reads and the player and SET_SYSTEM commands write.

func NewRegisters

func NewRegisters(o RegisterOptions) *Registers

NewRegisters makes a player's register file for the options. Registers nobody has chosen yet start at the "none" values the format defines: a disc sees 0xff for the audio stream until a stream is selected, and its program can tell a first visit to a menu from a later one that way.

func (*Registers) Clone

func (r *Registers) Clone() *Registers

Clone copies the registers.

func (*Registers) Run

func (r *Registers) Run(cmds []Command, pc int, o RunOptions, fx *Effects) Result

Run executes commands from pc until one changes the player's course, or the end. Compare commands that are false skip the next command.

type Result

type Result struct {
	Kind     ResultKind
	Object   int // JUMP/CALL_OBJECT
	Title    int // JUMP/CALL_TITLE
	Playlist int
	Item     int // PLAY_PL_PI, LINK_PI; -1 otherwise
	Mark     int // PLAY_PL_PM, LINK_MK; -1 otherwise
	PC       int // the command after the one that stopped the run
	Err      error
}

Result is what a run of commands asks the player to do.

type ResultKind

type ResultKind int

ResultKind says why a run of commands stopped.

const (
	ResultEnd        ResultKind = iota // ran off the end (or BREAK)
	ResultJumpObject                   // run another movie object
	ResultJumpTitle                    // go to a title (0 = top menu, 0xffff = first play)
	ResultCallObject                   // run another movie object, resuming here after
	ResultCallTitle                    // a title, resuming here after
	ResultResume                       // back to what was suspended by a call
	ResultPlay                         // play a playlist (Playlist; Item or Mark when set)
	ResultTerminate                    // stop the playing playlist
	ResultLinkItem                     // jump within the playing playlist to a play item
	ResultLinkMark                     // jump within the playing playlist to a mark
	ResultError
)

type RunOptions

type RunOptions struct {
	MaxSteps int // 0 = 1000000; a disc's program cannot loop for ever
	// Button: the commands belong to a menu button, not a movie object. Some
	// commands only mean something there (LINK, TERMINATE_PL, POPUP_OFF,
	// stills), and changing the page ends the button's commands.
	Button bool
}

RunOptions limit a run.

type STCSequence

type STCSequence struct {
	ID         int // the number play items name it by
	PCRPID     uint16
	StartSPN   uint32
	Start, End uint32 // presentation times, 45 kHz
}

STCSequence is a stretch of the clip with one continuous clock.

type SoundClip added in v0.3.0

type SoundClip struct {
	Channels int
	Rate     int
	// contains filtered or unexported fields
}

SoundClip is one sound, by its place in the file (the id buttons name).

type Sounds added in v0.3.0

type Sounds struct {
	Clips []SoundClip
	// contains filtered or unexported fields
}

Sounds is a disc's sound.bdmv.

func ParseSounds added in v0.3.0

func ParseSounds(b []byte) (*Sounds, error)

ParseSounds parses sound.bdmv.

func (*Sounds) GobDecode added in v0.3.0

func (s *Sounds) GobDecode(b []byte) error

GobDecode reads a disc's button sounds and checks that each lies in their data.

func (*Sounds) GobEncode added in v0.3.0

func (s *Sounds) GobEncode() ([]byte, error)

GobEncode sends a disc's button sounds.

func (*Sounds) WAV added in v0.3.0

func (s *Sounds) WAV(id int) ([]byte, bool)

WAV returns one clip as a WAV file, which every browser plays.

type Source

type Source interface {
	ReadFile(name string, max int64) ([]byte, error) // name is relative to the disc root, e.g. BDMV/index.bdmv
	Extents(name string) ([]FileExtent, error)
	List(dir string) ([]string, error) // file names in a folder of the disc
	Describe() string
	Close() error
}

Source abstracts an image or a BDMV folder.

type StateImages

type StateImages struct {
	Start, End int // object ids, NoButton when none
	Repeat     bool
}

StateImages is the range of pictures of one button state (an animation from Start to End; the player shows the first).

func (StateImages) Frames

func (st StateImages) Frames() int

Frames is how many pictures a button state animates through (0 = none).

type Step

type Step struct {
	Kind     StepKind
	Reason   string
	Playlist *Playlist
	Item     int    // where to start: the play item index
	Time     uint32 // and the time in it (45 kHz ticks, in the clip's time base); 0 = the item's IN
	// ItemOnly: play just this item, then report PlaylistEnded; the navigator
	// says which item comes next. Set for random and shuffle playlists, items
	// with a still, and playlists whose items do not share one set of streams.
	ItemOnly bool
	// StillSec is how long the picture holds after what this step plays: 0 =
	// not at all, -1 = until the viewer acts.
	StillSec float64
	// Menu is set when the playlist has an IG (menu graphics) stream: its
	// PID, and the clip it comes from when it is in a sub-path.
	Menu    bool
	IGPID   uint16
	IGClip  string // "" when the IG stream is in the play item's own clip
	Title   int    // PSR4 at this step (0xffff during first play)
	Object  int    // the movie object that asked for this
	Effects *Effects
	// BDJ names the BD-J object of a StepUnsupported step.
	BDJ string
}

Step is the navigator's instruction to the player.

type StepKind

type StepKind string

StepKind is what the player should do.

const (
	StepPlay        StepKind = "play"
	StepStop        StepKind = "stop"
	StepUnsupported StepKind = "unsupported" // a BD-J object (Step.BDJ names it): run it if the player can, else fall back to the main feature
	StepStay        StepKind = "stay"        // nothing changes (a button only changed menu state)
)

type Stream

type Stream struct {
	Kind string // video, audio, pg (subtitles), ig (menu), sec-audio, sec-video, pip-pg
	// EntryType says where the stream is: 1 = in this item's clip, 2 = in a
	// sub-path's clip, 3 = in a sub-path (text subtitles), 4 = in a sub-path
	// clip with its own PID.
	EntryType int
	PID       uint16
	SubPath   int
	SubClip   int
	Coding    byte // MPEG-TS stream type: 0x1b H.264, 0x24 HEVC, 0xea VC-1, 0x02 MPEG-2, 0x20 MVC; 0x80 LPCM, 0x81 AC-3, 0x82 DTS, 0x83 TrueHD, 0x84 E-AC-3, 0x85 DTS-HD, 0x86 DTS-HD MA; 0x90 PG, 0x91 IG, 0x92 text
	Format    int  // video: 1 480i 2 576i 3 480p 4 1080i 5 720p 6 1080p 7 576p 8 2160p; audio: 1 mono 3 stereo 6 multi-channel 12 stereo+multi
	Rate      int  // video frame rate (see Index.FrameRate); audio: 1 48 kHz, 4 96 kHz, 5 192 kHz, 12 48/192, 14 48/96
	Lang      string
	CharCode  int // text subtitles: character coding
	// UHD (HEVC) video: DynamicRange 0 = SDR, 1 = HDR10, 2 = Dolby Vision; ColorSpace 1 = BT.709, 2 = BT.2020; HDR10Plus when the stream carries HDR10+ metadata.
	DynamicRange int
	ColorSpace   int
	HDR10Plus    bool
}

Stream is one selectable stream of a play item.

func (Stream) CodingName

func (s Stream) CodingName() string

CodingName is a readable name for the stream's coding.

type SubPath

type SubPath struct {
	// Type: 2 = primary audio of a browsable slideshow, 3 = IG menu, 4 = text
	// subtitles, 5 = out-of-mux synchronous (secondary audio/video), 6 =
	// out-of-mux asynchronous PiP, 7 = in-mux synchronous PiP, 8 = 3D
	// dependent view (MVC), 9 = 3D dependent view with PiP.
	Type   int
	Repeat bool
	Items  []SubPlayItem
}

SubPath is a sequence of sub play items with streams that play alongside the main path: out-of-mux menu graphics, secondary audio or video, picture-in-picture, text subtitles, or a 3D dependent view.

type SubPlayItem

type SubPlayItem struct {
	Clip                string
	Codec               string
	ConnectionCondition int
	STCID               int
	In, Out             uint32
	SyncItem            int    // the main path's play item this one is synchronised with
	SyncStart           uint32 // and the time in it (45 kHz)
	MultiClips          []AngleClip
}

SubPlayItem is one stretch of a clip in a sub-path.

type Subtitle

type Subtitle struct {
	Start, End uint32 // 45 kHz, in the clip's time base; End 0 = until the next
	X, Y       int    // on the video frame
	Image      *image.NRGBA
	Forced     bool // the disc wants it shown even with subtitles off (a translation of on-screen text)
}

Subtitle is one subtitle picture and when it shows.

type SubtitleWindow

type SubtitleWindow struct {
	Width, Height int
	Subtitles     []Subtitle
}

SubtitleWindow is what Subtitles returns: the pictures and the frame size they are placed on.

type TextCue added in v0.3.0

type TextCue struct {
	Start, End uint32 // 45 kHz, in the clip's time base
	Forced     bool
	Style      TextStyle
	Text       string // lines separated by \n
}

TextCue is one dialog: its words, when, and in what style.

type TextStyle added in v0.3.0

type TextStyle struct {
	ID            int
	X, Y, W, H    int // the region on the video frame
	Background    color.RGBA
	BoxX, BoxY    int // the text box, relative to the region
	BoxW, BoxH    int
	Flow          int // 1 = left to right, 2 = right to left, 3 = top to bottom
	HAlign        int // 1 = left, 2 = centre, 3 = right
	VAlign        int // 1 = top, 2 = middle, 3 = bottom
	LineSpace     int
	Bold, Italic  bool
	Outline       bool
	FontSize      int
	Color         color.RGBA
	OutlineColor  color.RGBA
	OutlineWeight int
}

TextStyle is a region style of the dialog style segment.

type Title

type Title struct {
	Number int // 1-based, as JUMP_TITLE names them
	// Access says what the user may do while this title plays: 0 = anything,
	// 1 = no title search, 2 = no title search and no menu call.
	Access int
	Object IndexObject
}

Title is a disc title as the player's title list shows it.

type Window

type Window struct {
	ID         int
	X, Y, W, H int
}

Window is a rectangle of the screen that compositions draw into.

Directories

Path Synopsis
Package bdj runs a disc's BD-J applications.
Package bdj runs a disc's BD-J applications.
Package cli holds the commands of the standalone wittybluray tool.
Package cli holds the commands of the standalone wittybluray tool.
cmd
wittybluray command
Command wittybluray inspects Blu-ray images and BDMV folders with the WittyBluray engine.
Command wittybluray inspects Blu-ray images and BDMV folders with the WittyBluray engine.
wittybluray-module command
Command wittybluray-module is WittyBluray as a helper process, so a new version can reach a server without a new server.
Command wittybluray-module is WittyBluray as a helper process, so a new version can reach a server without a new server.
Package helper is WittyBluray's side of running as a helper process: one opened disc and its navigator, answering the server's calls.
Package helper is WittyBluray's side of running as a helper process: one opened disc and its navigator, answering the server's calls.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL