Boxset

Your movie collection on one Blu-ray, with a menu made for it.
Add your movies, pick a theme, press Build. Boxset does the rest.

Boxset turns a folder of movie files into a Blu-ray disc with a real, themed menu: a main menu, a film list, a page for every film and scene selection built from each film's own chapters. It works out how to fit every film on the disc at the best quality that fits, renders every menu screen, encodes the films, and writes a disc that plays in an ordinary Blu-ray player, remote and all.

---

Contents

• Highlights
• What you need
• Install
• Quick start
• Using Boxset
  • Films
  • Disc space and picture quality
  • Menu
  • Build
  • Burning and testing
  • Projects and where files go
• Themes
• What's on the finished disc
• Supported files and limits
• Command line
• Project file reference
• Troubleshooting
• How it works
• Building from source
• Credits and licences

---

Highlights

• Drop in your movies. Files or whole folders. Title and year are read from the file name (Fast.Five.2011.1080p.BluRay.mkv becomes Fast Five, 2011), and each film's length, chapters and audio are read from the file itself.
• See the fit before you build. A live disc diagram shows each film's share of the disc and the picture quality your chosen disc size allows.
• Menus with character. Themes decide every screen, button and transition. Two are built in, and new ones install with a double-click.
• Click through the real menus first. The menu preview is the actual rendered disc menu, driven with the arrow keys exactly as your remote will drive it.
• Languages and subtitles come along. Every audio track and subtitle track of a film goes on the disc, chosen with the remote's Audio and Subtitle buttons.
• Blu-ray rips aren't encoded twice. A film whose picture came straight off a Blu-ray is copied as it is: no quality lost, and done in minutes.
• One button to build. Menus, encoding, the disc structure and a disc image, with live progress and a time estimate. Stop whenever you like; finished films are kept.
• Plays in standard players. Menus use the standard Blu-ray menu system (HDMV), not Java, and every menu is checked against Blu-ray rules before anything is built.
• Nothing extra to install. FFmpeg is bundled, and disc images and burning use Windows' own tools.

_{The menu preview, driven with the arrow keys and Enter like a remote.}

What you need

Need	Details
Computer	Windows 10 or 11, 64-bit. A recent multi-core processor makes encoding much faster.
Your movies	Video files you already have: MKV, MP4, M4V, MOV, AVI, M2TS, TS, WMV, WebM, VOB or MPG. Boxset doesn't rip or decrypt discs.
Free disk space	Roughly the size of the disc you're making, plus the same again if you also make a disc image (see disk space).
To burn	A Blu-ray burner and blank discs: BD-R / BD-RE for 25 and 50 GB, BD-R XL for 100 GB.
To watch	Any standard Blu-ray player. 100 GB discs need a player that supports BDXL.

Microsoft Edge WebView2, which draws the app's window, is built into Windows 11 and most up-to-date Windows 10 PCs. The installer adds it if it's missing.

Install

1. Download BoxsetSetup-<version>.exe from the latest release.
2. Run it. The installer isn't code-signed yet, so Windows SmartScreen may say Windows protected your PC. Choose More info → Run anyway.
3. Open Boxset from the Start menu.

The installer also sets up file types: double-clicking a .boxset project opens it in Boxset, and double-clicking a .boxtheme theme pack installs it. Uninstall from Settings → Apps; your projects in Documents are left alone.

Quick start

1. Films. Drop your movie files (or a folder of them) into the window. Fix any titles that need it and drag the films into the order you want on the disc.
2. Menu. Pick a theme, set its options (title, colours, story order), and press Render menus. Click through the result with the arrow keys and Enter.
3. Build. Press Build disc and leave Boxset running. When it's done, press Burn to disc, or use the disc folder or image however you like.

Burn your first disc to a rewritable BD-RE and try it in your player before using write-once discs.

---

Using Boxset

The window has three tabs, one per step: Films, Menu and Build. Everything you change is saved automatically.

1. Films

Adding films. Drag files or folders from File Explorer into the window, or use Add files / Add folder. A folder adds the video files inside it (not its subfolders). The same file can't be added twice.

Titles and years. Boxset reads them from the file name, ignoring the usual release tags:

File name	Title	Year
The.Fast.and.the.Furious.2001.1080p.BluRay.x264.mkv	The Fast and the Furious	2001
2 Fast 2 Furious (2003).mkv	2 Fast 2 Furious	2003
Fast Five (2011) [1080p] REMUX.mkv	Fast Five	2011
Blade.Runner.2049.2017.2160p.UHD.mkv	Blade Runner 2049	2017
1917.2019.1080p.mkv	1917	2019

Click any title or year to edit it. Press Enter or click away to save.

Order. New films are sorted by year, which is release order for most collections. Drag the handle at the left of a row to set your own order. Once you've reordered by hand, Boxset stops sorting.

Chapters. Chapters come from the file and give the disc its scene selection. Many downloads have none, so for those Boxset adds one every few minutes, like a retail disc, and moves each onto the nearest cut between shots (within 12 seconds) so a chapter never starts mid-shot. The Chap. column shows these as, for example, 18 added. Choose how often under the film list (every 3 to 10 minutes, 5 by default), or Don't add any for no scene selection. Finding the cuts takes about a minute per film, the first time the menus are rendered or the disc is built; the result is remembered. Films shorter than 8 minutes don't get chapters added.

Film details. The arrow at the end of a row opens more:

• Setting or tagline, shown on the film's page by some themes (the Tachometer theme shows it as the film's location).
• Mark as a spin-off, which themes can label (both built-in themes do).
• Any extra fields the current theme asks for.
• The file's location, resolution, frame rate and size, plus Remove from disc.

Status. While a file is being read, its row shows Reading…. A dot at the end of a row means something needs attention:

Dot	Meaning	Examples
Amber	Boxset will handle it, but you should know	24 fps plays 0.1% slower, at 23.976; HDR colour is converted to SDR; a file with no audio gets silence
Red	This file can't go on the disc as it is; the build is blocked until it's removed	an unusual frame rate such as 15 or 48 fps; a file that can't be read

Disc space and picture quality

The disc on the right of the Films tab is drawn to scale. Data is written from the centre outwards, so each film is a ring whose area matches its share of the disc. Hover over a film to highlight its ring.

Pick the disc type underneath: BD-25, BD-50 or BD-100. The big number is how much of that disc your films will really use, and the figure beside it is the space still free.

How much space a film takes. Boxset encodes at a steady picture quality, so a film only takes the data its scenes need: quiet, clean films take far less than grainy, detailed ones. To know the real figure, Boxset test-encodes twelve 3-second samples from across each film in the background, with the disc's own settings, which takes a minute or so per film and lands within about 10% of the finished size. Until a film is measured, its size shows as "about" a rough figure worked out from the file, and a line under the disc says how many films are still being measured. Measurements are remembered, so each file is only measured once.

Save space

The Save space switch under the disc types encodes every film at a lighter quality setting (x264 CRF 23 instead of 19). Films take a third to a half less space, and the sizes on the disc update once the films have been measured at the new setting.

What it costs, honestly:

• Film grain is smoothed over. Grain is expensive to keep, so it's the first thing to go, and the biggest saving comes from it. Grainy films look a little cleaner and softer than your file.
• Hard scenes can break up. Dark scenes, smoke, fog, water, confetti and fast camera moves are where you may see soft blocks or banding (visible steps in smooth gradients like a night sky).
• It shows most on good sources. A high-quality rip has fine detail and grain to lose. A download that was already heavily compressed has little left to lose, so the difference is hard to see there.
• It can't be turned on for one film. It applies to the whole disc. Switching it after a build means encoding the films again.

In testing on 1080p clips re-compressed to about 2 Mbps HEVC, like a typical download, Save space made the films 36% smaller on clean animation and 46% smaller with film grain added, and the median frame stayed within about 3 dB PSNR of the standard setting (43 dB against the source; a common rule of thumb is that above 40 dB differences are hard to spot in motion). That's a measurement on test clips, not a promise for every film: if you care about a particular film's grain or dark scenes, leave it off.

When to use it: to fit more films on a smaller disc without the video limit dropping, or when your files are compressed downloads anyway. When not to: high-quality rips of films you care about, especially grainy or dark ones, when they fit without it.

The video limit. So everything is guaranteed to fit, each disc type also sets a limit on how much video data a film can use:

1. 1.5 GB is set aside for menus and the file system.
2. About 5% goes to the Blu-ray stream format itself.
3. Every film gets 448 kbps Dolby Digital audio.
4. Everything left becomes video, shared evenly by running time, capped at 30 Mbps.

Films that need less than the limit simply use less, which is the space you see as free. Video limit per film shows the limit and Picture quality shows what it means. When your films need less than the limit throughout, the disc doesn't hold them back and quality shows as Same as your files. Otherwise:

Video limit per film	Shown as
20 Mbps and up	Close to a retail disc
12–20 Mbps	Excellent
8–12 Mbps	Very good
5–8 Mbps	Good
3–5 Mbps	Fair, some softness
under 3 Mbps	Heavily compressed

As a rule of thumb, this is how many hours of film fit at each limit:

Disc	20 Mbps	12 Mbps	8 Mbps	5 Mbps
BD-25	2.4 h	4.0 h	5.9 h	9.1 h
BD-50	5.0 h	8.3 h	12.2 h	18.9 h
BD-100	10.2 h	16.8 h	24.7 h	38.3 h

These are worst cases, for films that need the whole limit. The 11-film collection in the screenshots is 23 hours long: a limit of about 1.7 Mbps on a BD-25, 4.0 Mbps on a BD-50 and 8.5 Mbps on a BD-100.

Audio tracks, subtitles and copying

Three more switches sit under Save space. New projects start with all three on; projects made with earlier versions of Boxset keep them off until you turn them on, so opening one never re-encodes films you've already built.

• Every audio track. Each film's other languages and commentaries go on the disc (up to 8 per film), and the remote's Audio button switches between them. Off, only the first track is included. Each extra track takes a little of the disc: about 0.15 GB per hour for stereo, 0.2 GB for 5.1.
• Subtitles. Each film's subtitles go on the disc (up to 8 per film), off until you choose one with the remote's Subtitle button. Boxset reads text subtitles inside the file (SRT, ASS, MP4 text), subtitle files beside it with the same name (Fast Five (2011).en.srt), and Blu-ray picture subtitles (PGS) made for 1080p. Text is drawn in a plain white font with a black outline, at the bottom of the picture; ASS styling and positions aren't kept.
• Copy what's already Blu-ray. A film whose picture is already exactly what a Blu-ray holds (typically an untouched Blu-ray rip, or "remux") is copied, not encoded again, and its Dolby Digital and DTS sound is copied with it. DTS-HD keeps its DTS core, the part every player can decode. Downloads and re-encodes look similar but almost never qualify, and are encoded as usual. A film is only copied when it fits the disc's per-film limit; open a film's details to see what will happen to it.

2. Menu

Theme. The list on the left shows every installed theme with a preview. A theme that's meant for a different number of films says so on its card.

Settings. The panel on the right shows the selected theme's own settings: titles, colours, switches, music, and a Story order for collections whose story runs in a different order from their release order. Settings are saved per project.

Render menus. Builds every screen from your actual films and chapters, including a frame from every chapter for scene selection. An 11-film collection makes around 50 screens and takes a minute or two; themes with moving backgrounds take longer. Afterwards Changed since last render appears whenever you edit something the menus depend on, including replacing a picture or song you chose in the settings. Press Render again to bring them up to date; it always renders from scratch. A build also renders when something changed.

• Stop rendering (in place of Render while it runs) stops within a moment, even partway through recording a moving background. The previous menus are kept.
• Clear menus deletes the rendered menus, for a completely fresh start. Chapter frames are kept, because they only depend on the films.

Preview. The picture in the middle is the rendered disc menu, and it behaves like the disc:

Key	Remote button
Arrow keys	Up, down, left, right
Enter	OK
Backspace or Esc	Back (previous menu)
Home	Top Menu

You can also click a button directly, or jump to any screen with the drop-down above the picture. Choosing something that plays a film shows a card saying what would play and which menu the player returns to afterwards. Finish film takes you there.

3. Build

Build disc (on this tab, or at the top right of any tab) runs everything:

Step	What happens	Time
Check films	Re-reads every file and plans the disc space	Seconds
Render menus	Renders the menus, or skips this if nothing changed	Up to a few minutes
Encode films	Converts each film to Blu-ray video and audio	The long part (see below)
Write the disc	Builds the Blu-ray folder: menus, chapters, playlists	A minute or two
Disc image	Optional: one .iso file ready to burn (Windows)	A few minutes

Options (on the Build tab, before you start):

• Speed, with a small gauge beside it. Each setting's button shows how much of the disc your films would take with it ("about" until they've been measured), and the trade-off is written under the one you pick:

  Speed	Encodes with	Compared with Best quality
  Best quality (default)	Your processor, x264 "medium"	The baseline: slowest, best picture for the space
  Faster	Your processor, x264 "veryfast"	About 2.5× faster. In testing, files came out 13–15% smaller with slightly less fine detail (1.2–1.5 dB PSNR lower)
  Graphics card	NVIDIA NVENC, Intel Quick Sync or AMD AMF, whichever works on your PC	Usually several times faster, and the processor is left mostly free (it still reads and scales the video). Films get about 30% more space for a similar picture, because hardware encoders need more bits than x264

  About Graphics card, honestly: x264 has a dedicated Blu-ray mode; graphics card encoders don't, so Boxset sets the Blu-ray rules by hand (High profile at level 4.1, four slices, a key frame at least every second, at most three B-frames, and the disc's bitrate limits). Discs made this way should play, but they haven't been checked against every player, so burn a BD-RE and try it in yours first. Also:

  • Boxset tests your card when it starts, by encoding a few frames with the real settings. If none works, the option is greyed out.
  • The card encodes at a set average bitrate: what x264 measured the film needs, plus 30%, within the disc's limit. That's why its sizes are known in advance; the finished films usually land within a few percent of the figure shown.
  • Films at 25 or 29.97 fps are encoded with Faster instead, because Blu-ray stores them as 1080i, which only x264 can make here.
  • If the card fails on a film (a driver problem, say), Boxset says so in the build details and encodes that film with Faster, so the build still finishes.
  • On AMD cards, chapter points land on the nearest key frame, up to half a second from the exact time, because AMD's encoder can't place key frames on request.

• Also make a disc image (.iso) for burning. On by default.

• Quick test build, low quality. Encodes much faster at much lower quality. Use it to check menus and navigation on a real player before committing to a full build.

How long encoding takes. With Best quality or Faster, it depends almost entirely on your processor. A modern desktop encodes 1080p faster than real time; an older laptop may be slower than real time. Boxset shows the speed (for example 1.8×) and a time estimate once a film has started.

Stopping and resuming. Cancel build stops straight away. Films that finished are kept, and the next build picks up from the first unfinished film.

What makes Boxset encode a film again:

Change	Re-encodes?
Editing titles, years or other details	No
Reordering films	No
Changing the theme or any theme setting	No (menus only)
Replacing a film's file, or editing the file	That film
Adding or removing films, or changing the disc size	Usually all of them, because each film's share of the disc changes
Switching between quick test and full quality, changing Speed, or turning Save space on or off	All of them

When the build finishes, the Build tab offers Show disc folder, Make disc image (if you didn't make one) and Burn to disc.

Burning and testing

Choosing the burner. The Burner drop-down on the Build tab (shown when Also make a disc image is on, and again when the disc is ready) lists the disc drives Windows can see. Drives that can't write Blu-ray are listed but can't be picked. Boxset remembers your choice, and the line under it says what's in the drive:

Shown	Meaning
🟢 Blank BD-R in the drive, 25.0 GB. Ready to burn.	Good to go
🟡 No disc in the drive.	Put one in and press Refresh
🔴 The disc is too small, already written, or not a Blu-ray	Burn to disc stays off until you change the disc and press Refresh

A BD-RE with data on it needs erasing first: in File Explorer, select the drive and choose Erase this disc. Boxset finds drives with Windows' own burning service (IMAPI2), so any burner Windows can burn with works.

Burn to disc opens the image in Windows Disc Image Burner, which comes with Windows, with your chosen drive already selected. Tick Verify disc after burning if you like, and press Burn.

The disc folder (build\disc, containing BDMV) also works with other tools:

• ImgBurn: Write files/folders to disc, choosing the disc folder, or Write image file to disc with the .iso.
• Playing on your PC: open the .iso or the disc folder in a Blu-ray player app. VLC's support for Blu-ray menus is limited, so a menu that misbehaves there may still be fine on a real player.

The first time, burn to a BD-RE (rewritable) disc and try every menu on your actual player. Each player model can differ slightly, so if a menu misbehaves on yours, please report it with the player's make and model.

Projects and where files go

Each collection is a project. The first film you add saves a new project to Documents\Boxset\<collection name>\, and every change after that saves on its own. Rename the collection by clicking its name at the top left. The Project menu next to it has New collection, Open project…, Save project as…, Show project folder and your recent projects.

Documents\Boxset\The Fast Saga\
├─ The Fast Saga.boxset         the project (films, theme, settings)
└─ build\
   ├─ disc\BDMV\...             the finished disc, ready to burn
   ├─ THE_FAST_SAGA.iso         the disc image, if you made one
   ├─ clips\                    encoded films, kept so rebuilds are quick
   ├─ menus\                    rendered menu screens and buttons
   └─ thumbs\                   chapter frames for scene selection

Your original movie files are never changed or moved.

Other locations:

What	Where
App settings and recent projects	%APPDATA%\Boxset\settings.json
Installed theme packs	%APPDATA%\Boxset\themes\
The app itself	C:\Program Files\Boxset\

Disk space

The encoded films in build\clips and the finished disc in build\disc share the same data, so a build needs about one disc's worth of free space on the drive holding the project. A disc image adds another disc's worth. On drives formatted as exFAT or FAT32 the films and disc can't share data, which adds one more. When you're done with a collection, you can delete its build folder; the project file is all you need to build it again.

---

Themes

A theme decides everything you see on the disc: how many screens there are, what's on them, how the buttons look in each state, and where every button leads. Boxset comes with two.

Tachometer

Night-street racing. A dial numbered 1 to N counts the films; each film's page swings the needle to its number and shows where it sits in the series.

Main menu	Film list
Film page	Scene selection

Settings: both title lines, accent colour (five presets or any colour), scene selection on or off, and story order, which adds a Timeline order button. Fits: 2 to 12 films.

Marquee

An old movie palace: velvet curtains, a marquee with chasing bulbs (a looping video background), a letterboard film list, admission-ticket film pages and 35 mm film-strip scene selection.

Film list	Film page	Scene selection

Settings: both marquee lines, animated lights on or off, main menu music (MP3, WAV, FLAC or M4A, looped), and story order, which adds a Story order ticket. Fits: 1 to 11 films.

The chapter frames in these screenshots are abstract stand-ins. On your disc they're frames from your own films.

Installing theme packs

Themes are shared as .boxtheme files. Double-click one, or use Install theme pack at the bottom of the Menu tab's theme list. Installed packs appear in the list straight away and are kept in %APPDATA%\Boxset\themes\. Installing a pack with the same name replaces the old one.

To remove a pack, point at its card in the theme list and choose Remove, then Remove? to confirm. A project that was using it switches to a built-in theme. The built-in themes can't be removed, and themes in a project's own themes folder are left for you to delete yourself, since they're your files.

Warning

A theme pack contains program code that runs on your PC when menus are rendered. Only install theme packs from people you trust.

The same goes for themes in a project's own themes folder. The first time you open a project whose folder has one, the Menu tab lists those themes and asks before using them; nothing in the folder runs until you choose Allow. Projects you make in the app don't ask.

Making your own

Themes are written in Python, drawing screens either with code or as ordinary web pages in HTML and CSS, so a menu can look like anything a web page can. Boxset supplies the films, chapters and frame grabs, and checks the result against Blu-ray menu rules before anything is built. The full guide is in THEMES.md.

---

What's on the finished disc

• Inserting the disc goes straight to the theme's main menu. There are no warnings or logos first. The remote's Top Menu button returns there from anywhere.
• Every film is its own title, with all of its original chapters, so the remote's chapter skip works during playback.
• Playlists that the theme defines, such as play all in release order or story order, play several films back to back.
• When a film ends, the player goes wherever the theme says. Both built-in themes go back to that film's page.
• Video is H.264 High profile at level 4.1, the standard Blu-ray format, at 1920 × 1080. Every chapter starts on a key frame, so chapter jumps are instant.
• Audio is Dolby Digital: 5.1 at 448 kbps when the source has 5.1 or more, otherwise stereo at 192 kbps. Tracks that are already Dolby Digital are copied untouched. With Every audio track on, each film carries all of its tracks.
• Subtitles are standard Blu-ray picture subtitles (PGS), off until chosen.
• Menus use HDMV interactive graphics, the menu system every Blu-ray player supports. Backgrounds can be still pictures or looping video, with optional music.

Supported files and limits

	Supported	Notes
File types	MKV, MP4, M4V, MOV, AVI, M2TS, TS, WMV, WebM, VOB, MPG/MPEG	Anything FFmpeg can read, with one of the extensions on the left
Frame rates	23.976, 24, 25, 29.97, 30, 50, 59.94, 60 fps	24 and 30 fps play 0.1% slower (at 23.976 and 29.97) with every frame kept, the way films are put on disc. 25 and 29.97 fps are stored the way Blu-ray requires (as 1080i). 50, 59.94 and 60 fps keep every other frame, so fast motion is a little less smooth
Resolution	Anything	Scaled to fit 1920 × 1080, with black bars to keep the shape
4K and HDR	Scaled down to 1080p	HDR10 and HLG colour is converted to standard (SDR). Dolby Vision files that also carry HDR10 (most do) convert the same way; Dolby Vision alone can't be converted, so use another version of those films
Audio	Up to 8 tracks per film	Encoded to Dolby Digital unless already Dolby Digital (or, for copied films, DTS)
Subtitles	Text (SRT, ASS, MP4 text, WebVTT) and 1080p Blu-ray picture subtitles (PGS), up to 8 per film	DVD picture subtitles (VobSub), 4K PGS, and text in scripts that need shaping (Arabic, Hebrew, Thai, Indic scripts) are left out, with a note in the build log. Forced subtitles aren't shown automatically
Chapters	From the file	Files without chapters get a single chapter, and scene selection is skipped for them. Chapters closer than 5 seconds together are merged
Disc types	BD-25, BD-50, BD-100	Single-disc collections only
Films per disc	Set by the theme	Tachometer 2–12, Marquee 1–11

Rules every menu follows, because players require them (Boxset checks these for every theme):

• Buttons can't overlap, including any glow around them.
• Every button must be fully on screen.
• A menu can have at most 255 buttons.
• Button graphics use at most 256 colours per menu. Boxset reduces them automatically, so themes keep gradients and photos in the background, which has full colour.
• Every button must lead somewhere that exists.

---

Command line

The installer includes boxset-cli.exe next to Boxset.exe. It does the same work without the window, using a .boxset project made in the app. It isn't added to PATH, so run it by its full path:

& "C:\Program Files\Boxset\boxset-cli.exe" build "$env:USERPROFILE\Documents\Boxset\The Fast Saga\The Fast Saga.boxset"

Command	What it does
boxset-cli check <project>	Reads every film and prints its length, frame rate, chapters and audio, the disc-space plan (with the sizes the app has measured, or rough figures until it has), and anything that needs fixing
boxset-cli themes <project>	Lists the available themes (* marks the project's)
boxset-cli menus <project>	Renders every menu screen and checks them against Blu-ray rules
boxset-cli preview <project>	Saves build\menus_preview.jpg, a contact sheet of every screen
boxset-cli build <project>	Runs the whole build

Option	For	Effect
--theme NAME	menus	Try another theme without changing the project
--force	menus	Render again even if nothing changed
--iso	build	Also make a disc image (Windows)
--fast	build	Quick, low-quality test build
--skip-encode	build	Rebuild the disc from films that are already encoded
--refresh	check	Re-read every file instead of using what's remembered

Boxset.exe <project> opens a project in the app, and Boxset.exe <file>.boxtheme installs a theme pack.

Project file reference

A .boxset file is plain JSON, so you can edit it by hand or generate it with a script. Paths can be absolute or relative to the project file.

{
  "name": "The Fast Saga",
  "disc_label": "THE_FAST_SAGA",
  "disc_size": "BD-100",
  "audio_kbps": 448,
  "save_space": false,
  "speed": "quality",
  "auto_chapters": 5,
  "audio_tracks": "all",
  "subtitles": "all",
  "keep_streams": true,
  "theme": "tachometer",
  "theme_options": {
    "title_small": "THE COMPLETE",
    "title_big": "SAGA",
    "accent": "#FF6B1A",
    "scene_selection": true,
    "timeline_order": [1, 2, 4, 5, 6, 3, 7, 8, 9, 10, 11]
  },
  "build_dir": "build",
  "films": [
    {"file": "D:/Rips/Fast Five (2011).mkv", "title": "Fast Five", "year": 2011, "place": "Rio de Janeiro"},
    {"file": "D:/Rips/Hobbs.and.Shaw.2019.mkv", "title": "Hobbs & Shaw", "year": 2019, "spinoff": true}
  ]
}

Key	Meaning
name	The collection's name in the app
disc_label	The disc's volume name: up to 32 letters, digits and underscores. Follows the name unless you set it
disc_size	BD-25, BD-50 or BD-100
audio_kbps	Dolby Digital bitrate for 5.1 audio (default 448)
save_space	true encodes films smaller, with some loss of fine detail (see Save space). Default false
speed	quality (default), fast or gpu; see Build
auto_chapters	Minutes between chapters added to films whose files have none; 0 adds none. Default 5
audio_tracks	all puts every audio track of each film on the disc; first only the first. Left out: first
subtitles	all puts each film's subtitles on the disc; off none. Left out: off
keep_streams	true copies picture and sound that are already what a Blu-ray holds, without re-encoding. Left out: false
theme	The theme's folder name, as listed by boxset-cli themes
theme_options	The theme's settings (see each theme). timeline_order lists film numbers in story order
build_dir	Where build output goes, relative to the project file
films	In disc order. file and title are required; year, place and spinoff are optional, and themes may read extra keys

Troubleshooting

Windows says "Windows protected your PC" when I run the installer

The installer isn't code-signed yet, so SmartScreen doesn't recognise it. Choose More info → Run anyway. Only do this with an installer downloaded from this repository's Releases page.

The app window is blank or won't open

Boxset's window needs Microsoft Edge WebView2. The installer adds it when it's missing, but if that was skipped, install the Evergreen Runtime from Microsoft and open Boxset again. As a fallback, boxset-cli.exe gui --browser opens the same app in your web browser.

A film shows a red dot or "Can't use"

Open the film's details (the arrow at the end of its row) to see the reason. Usually it's an unusual frame rate (Boxset takes 23.976, 24, 25, 29.97, 30, 50, 59.94 and 60 fps), or a damaged or incomplete file. Convert the file with another tool, or remove it from the project.

The picture looks washed out or grey

Boxset converts HDR10 and HLG colour to standard (SDR) as it encodes. Two cases it can't: a Dolby Vision file with no HDR10 layer (the film's details say so; use another version), and a build from source with an FFmpeg that lacks the zscale filter (the build log says so; the installer's FFmpeg has it). A film encoded by an earlier version of Boxset is re-encoded with the conversion the next time you build.

My subtitles or second audio track are missing

Turn on Every audio track and Subtitles on the Films tab; projects made before those switches existed start with them off. Then press the remote's Audio or Subtitle button during the film: subtitles are always off until chosen. If a subtitle track is still missing, the build log says why. DVD-style picture subtitles and a few scripts (see Supported files and limits) can't be carried yet.

The menu doesn't appear, or a button does nothing, on my player

Try the disc in a Blu-ray player app on your PC to see whether it's the disc or the player. Make a Quick test build and burn it to a BD-RE, so you can test changes cheaply. Then please open an issue with your player's make and model, the theme, and what happens. Player behaviour varies, and reports are how Boxset gets better at it.

My player won't read a BD-100 disc

100 GB discs are BDXL, which older players don't support. Use a BD-50 (Boxset will lower the bitrate to fit), or split the collection into two projects.

Encoding is very slow

Encoding is processor-heavy. Close other demanding programs, and leave the PC plugged in and awake. You can cancel and continue later without losing finished films. To check menus quickly first, use Quick test build.

The build stopped with a disk space error

Free up space on the drive holding the project (see disk space), or move the project folder to a bigger drive and open it from there, then build again. Finished films are kept.

Making the disc image failed

The disc folder is still complete. Burn build\disc with ImgBurn's Write files/folders to disc, or try Make disc image again from the Build tab. The Details section on the Build tab shows the error message.

My antivirus flagged Boxset

Unsigned apps packaged with PyInstaller occasionally trigger false positives. The installer is built by GitHub Actions from the code in this repository, and you can follow every build under Actions. If it happens, please report it to your antivirus vendor as a false positive, and let us know in an issue.

---

How it works

flowchart LR
  A["Your movie files"] --> B["Read files<br>length, chapters, audio"]
  B --> C["Plan the disc<br>bitrate per film"]
  B --> D["Chapter frames"]
  D --> E["Theme renders menus<br>Python or HTML"]
  E --> F["Check Blu-ray rules<br>overlaps, colours, links"]
  C --> G["Encode films<br>FFmpeg + x264"]
  F --> H["Write the disc<br>bdmvkit"]
  G --> H
  H --> I["Disc image<br>UDF 2.50"]
  I --> J["Burn<br>Windows Disc Image Burner"]

Loading

Part	Job
boxset/probe.py	Reads each file with ffprobe: duration, frame rate, chapters, audio, subtitles, HDR, and whether the picture is already Blu-ray video
boxset/settings.py	A project's settings: defaults and checks, shared by the app and the build
boxset/budget.py	Shares the disc between films
boxset/tracks.py	Decides how each film goes on the disc: copied or encoded, which audio and subtitle tracks, frame rate, HDR conversion
boxset/subs.py	Draws text subtitles as Blu-ray picture subtitles
boxset/core.py	The theme interface: films and chapters in; menus, buttons, actions and playlists out. Also checks every menu against Blu-ray rules
boxset/html.py	Renders HTML/CSS theme screens with Microsoft Edge (via Playwright): background, each button in three states, and looping video backgrounds
boxset/pipeline.py	The build: read, plan, render, encode (with progress and cancelling), write the disc
boxset/iso.py	Disc images with Windows' built-in disc writer (IMAPI2)
boxset/gui/	The app: a local, token-protected server and the interface, shown in an Edge WebView2 window
bdmvkit	Writes the Blu-ray structure: interactive menu graphics, navigation commands, playlists and clip information

The app only listens on 127.0.0.1, and every request must carry a random key created each time Boxset starts. Other programs and websites can't drive it or read your files through it.

Updates. When it starts, the app asks GitHub once whether a newer release exists and, if so, shows a note with a link. Nothing is downloaded or installed, and nothing about you or your films is sent. To switch the check off, add "check_updates": false to %APPDATA%\Boxset\settings.json.

Building from source

Run from source:

git clone https://github.com/RamenNuudlss/Boxset.git
cd Boxset
pip install -r requirements.txt
python -m boxset                  # the app
python -m boxset --browser        # the app in a browser tab
python -m boxset build "path/to/project.boxset" --fast

You need Python 3.11 or newer and FFmpeg on PATH. HTML themes use Microsoft Edge or Chrome through Playwright. If neither is installed, run playwright install chromium.

Run the tests:

pip install -r requirements-dev.txt
python -m pytest tests

The tests that encode a few seconds of video are skipped when FFmpeg isn't installed.

Make the installer locally (Windows):

pip install -r requirements-dev.txt
pyinstaller --noconfirm packaging/boxset.spec       # dist\Boxset\
# put ffmpeg.exe and ffprobe.exe in dist\Boxset\bin\
& "${env:ProgramFiles(x86)}\Inno Setup 6\ISCC.exe" packaging\installer.iss

Releases are built by GitHub Actions on Windows: every push to main makes an installer you can download from the run's page, and publishing a release with a v* tag (for example v0.1.0) attaches BoxsetSetup-0.1.0.exe to it. The workflow packages the app with PyInstaller, bundles FFmpeg, fetches the WebView2 installer, runs the tests and a quick check that the packaged app starts, and builds the installer with Inno Setup. Pull requests get the same run, without a release.

Everything the build downloads is pinned: Python packages to exact versions in requirements.txt, FFmpeg to a version and checksum at the top of the workflow, GitHub Actions to exact commits. The WebView2 installer has no versioned address, so its Microsoft signature is checked instead. To update any of them, change the pin on purpose.

Code signing is optional. Add two repository secrets, WINDOWS_CERT_PFX (your code-signing certificate as a base64-encoded .pfx) and WINDOWS_CERT_PASSWORD, and the workflow signs Boxset.exe, boxset-cli.exe and the installer. Without them the build is unsigned, as before.

Testing a disc's navigation: tests/libbluray_nav.py opens a built disc with libbluray (the engine inside VLC, Kodi and mpv), presses remote buttons, and saves what the player draws:

python tests/libbluray_nav.py build/disc out/ down enter enter enter

Layout:

boxset/            the app and engine
  themes/          built-in themes (one folder each)
  gui/             the app window: api.py, server.py, web/
  fonts/           fonts used by the built-in themes
packaging/         PyInstaller spec, installer script, icon
tests/             unit tests, short real encodes, and the disc navigation script
docs/images/       screenshots for this page
THEMES.md          writing themes

---

Credits and licences

Boxset is built on:

• FFmpeg and x264 for reading and encoding video
• bdmvkit for the Blu-ray disc structure
• Pillow, Playwright and pywebview
• Fonts: Archivo, Barlow, Barlow Condensed, Bebas Neue, Courier Prime and Limelight, all under the SIL Open Font License

Licences for everything bundled with Boxset are listed in THIRD_PARTY_NOTICES.md. The installer includes FFmpeg under the GPL; its source is available from gyan.dev, the build Boxset bundles.

Boxset itself is released under the MIT licence: use it, change it and share it freely, keeping the copyright notice.

Boxset works with video files you already have. It doesn't rip, copy or decrypt discs. Please respect copyright law where you live.