BD-to-AVP 3D Blu-ray Disc to Apple Vision Pro README

Introduction

BD-to-AVP is a macOS app for turning your 3D Blu-ray movies into spatial videos you can watch on Apple Vision Pro. Give it a supported 3D Blu-ray disc, disc image, or existing video file, choose where the finished video should go, and the app prepares a spatial version while preserving the movie's stereoscopic depth. For physical discs, MakeMKV is still required to read and extract the title; existing MKV, MTS, and M2TS files do not need that extra step.

Most people should use the default MV-HEVC output, Apple's native spatial-video format. You can also choose optional 4K AI upscaling and subtitle processing, but both add time and temporary-storage needs. An experimental AV1 export targets M5 Apple Vision Pro and custom-player workflows; M2 Apple Vision Pro is unsupported, and physical M5 stereo qualification remains pending.

Behind the scenes, the app uses FFmpeg, MakeMKV, and a bundled native MVC decoder helper for video extraction, audio transcoding, and video stream merging to convert MPEG-4 MVC 3D video to MV-HEVC 3D video. It also injects 360° metadata for spatial media playback.

The default MV-HEVC videos play directly in the Files or Screenlit app on the AVP. See the feasibility record before choosing experimental AV1 output.

Screenshots

GUI install

For a normal Stable install of 3D Blu-ray to Vision Pro, download GitHub Latest from the releases page. Open the DMG file and drag the app to your Applications folder. Beta 3 is a prerelease rather than GitHub Latest; use only its exact tagged release as described below.

The GUI app does not install Homebrew or modify your shell setup. Runtime tools are bundled into the app where possible. MakeMKV remains an external requirement for reading Blu-ray discs; install the current macOS version from the MakeMKV website before converting discs.

The production interface starting with the 0.3.0 release line requires Apple Silicon and macOS 26 or later. Stable 0.2.143 remains the last desktop build for macOS 14 through 25.

Beta 3 manual bootstrap

Published v0.3.0-beta.3 is a one-time manual-download seed, not an update that currently shipped Stable or RC clients can discover. Those clients can select only Stable or RC, so they cannot select the Beta route or receive Beta 3 through Sparkle. Download that exact GitHub Release DMG, drag it into /Applications, and replace the existing production app.

Before replacing the app, quit the production app and every retired Preview variant, then copy ~/Library/Application Support/3D Blu-ray to Vision Pro/profiles.json to a safe location outside that folder if it exists. Separate bundle identities do not isolate this profile file: historical Preview and production builds can read and write the same path. After installing Beta 3, do not edit profiles in a retired Preview app. The DMG uses the production bundle identifier com.shinycomputers.bd-to-avp, so it replaces/upgrades the production app rather than creating another app beside it. The retired Beta 1 and Beta 2 Preview apps use separate immutable identities; they remain separate and cannot Sparkle-update into Beta 3.

After Beta 3 is installed, its Update Route control offers Stable, RC, Beta, and Alpha. The Beta 3 appcast item is eligible only on Beta and Alpha; Stable and RC exclude it. Existing Stable or RC selections remain in place until you explicitly choose another route. Choosing Stable later does not downgrade the installed Beta 3 app—it waits for a newer eligible Stable build.

Beta 4 (0.3.0b4, build 149) through Beta 8 (0.3.0b8, build 153) and Beta 10 (0.3.0b10, build 155) are published and immutable. Beta 9 (0.3.0b9, build 154) failed after production signing but before DMG creation and is permanently burned without publication. RC 1 (0.3.0rc1, build 158), RC 2 (0.3.0rc2, build 159), and RC 3 (0.3.0rc3, build 160) are published and immutable. RC 3 passed its updater, accessibility, subtitle-recovery, diagnostics, network-output, cleanup, and reporter field checks; its targeted qualification retains one native release-note check whose issue category is explicitly not applicable because the immutable source notes contain no issue URL. All links present in those notes passed, so RC 3's signed qualification is complete.

See Distribution Policy for the current GUI release artifact and dependency policy.

See Production Release Routes for Stable, RC, Beta, and Alpha update eligibility, version mapping, and publication policy.

See Direct Pipeline Contracts for the automatic minimum-materialization behavior and the durable --keep-files stage contracts.

See AV1 Stereo Feasibility for the standards evidence, Apple metadata probe, and boundaries between native MV-HEVC spatial output and software AV1 stereo export.

Terminal install or update (power users)

The formula in the custom third-party cbusillo/tap repository is the preferred terminal install. It installs the locked CLI dependencies and FFmpeg while intentionally omitting the PySide6 GUI. Use the signed release DMG for the desktop app.

Custom Homebrew tap

brew tap cbusillo/tap
brew trust cbusillo/tap
brew install bd-to-avp
bd-to-avp --help

MakeMKV remains a separate optional install for Blu-ray disc input. Install the current macOS version from the MakeMKV website; existing MKV, MTS, and M2TS sources do not require it.

The manual PyPI path remains available for power users who prefer to manage their own Python environment and FFmpeg.

Prerequisites

Ensure the following are installed on your Mac (if using the terminal/PyPI version):

• Apple Silicon Mac: A Mac with Apple Silicon, such as the M1, M1 Pro, or M1 Max
• macOS Sonoma: macOS 14 or later.
• Python 3.12: The supported Python runtime for the PyPI package.
• Homebrew: The missing package manager for macOS (or Linux).
• FFmpeg: A complete, cross-platform solution to record, convert, and stream audio and video.
• MakeMKV: Required only for reading Blu-ray discs and extracting titles.

Current release note: BD_to_AVP still uses MakeMKV for Blu-ray title extraction. By default, existing MKV/MTS/M2TS sources are reused in place, MVC video streams directly into the bundled native Apple Silicon splitter, and AAC transcoding avoids an intermediate PCM file. --keep-files restores the durable source copy, extracted MVC .h264, and PCM boundaries for inspection, stage resume, and external workflows. Native MVC splitting supports 8-bit Blu-ray 3D MVC sources only. Disc image sources using durable MVC input are probed for up to 30 seconds before splitting; if the multi-threaded native splitter is unstable for that stream, BD_to_AVP continues in slower single-threaded mode. The bundled splitter also recovers malformed streams that leave terminal incomplete-frame dependencies instead of waiting indefinitely for work that cannot complete.

Runtime tool lookup prefers explicit BD_TO_AVP_<TOOL>_PATH environment overrides, bundled tools in bd_to_avp/bin, tools already available in PATH, and finally the legacy /opt/homebrew/bin location. The GUI app uses bundled tools where available; the terminal/PyPI version still expects power users to install command-line tools themselves.

Manual terminal/PyPI dependency setup

These steps are for terminal/PyPI users who manage their own command-line tools. GUI users should use the release DMG and install MakeMKV from the MakeMKV website.

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install the external command-line dependencies.
brew install ffmpeg python@3.12

# Install the current macOS MakeMKV build from https://www.makemkv.com/.
# The app bundle is detected automatically from /Applications/MakeMKV.app.

# Ensure Python 3.12 is correctly installed then create a virtual environment
python3.12 -m pip install --upgrade pip
python3.12 -m venv ~/.bd_to_avp_venv

# Activate the virtual environment and install BD_to_AVP
source ~/.bd_to_avp_venv/bin/activate
pip install bd_to_avp

# Run the command from the virtual environment
bd-to-avp --help

PyPI GUI extra

The signed release DMG is the supported GUI install. PyPI users who intentionally want the legacy Python GUI can add the optional dependency and then launch without arguments:

pip install "bd_to_avp[gui]"
bd-to-avp

As long as you provide no arguments, the GUI will open.

The GUI locks configuration load/save actions while a job is active so each run uses the settings captured at startup. Choosing Stop Processing requests a cooperative stop and keeps the button in a stopping state until the worker exits. When a disc, ISO, or Blu-ray folder contains multiple MVC titles, the macOS app can convert the main movie, every detected 3D video, or a custom selection. Multi-title selections run serially and preserve completed outputs if a later video needs attention. For source-folder jobs, accepted MKV or subtitle error continuations resume the failed source and then continue through the original batch queue. Audio and subtitle language choices are independent. The native app defaults built-in and new profile options to Preferred Language Only with English selected. Existing version-4 custom profiles retain their stored choice, while version-1 through version-3 profiles migrate to All Languages to preserve their historical behavior. Preferred-only mode retains every audio stream whose metadata language matches the selected language; if none match, the app keeps the source-default audio stream or the first stream and shows a warning. Titles are not used to guess audio language.

Audio-language filtering can reduce output payload when tracks are omitted, but this feature does not establish the cause of the output-size report in issue #202 and does not claim to fix any separately reported media-specific stall. Those observations remain separate diagnostic work.

Terminal Usage

Navigate to the tool's directory in your terminal and execute the command with the required and optional parameters:

Command Syntax

bd-to-avp --source <source> [--source-folder <source-folder>] [options]

Parameters

• --source: Source for a single disc number, MKV file path, or ISO image path (required).
• --source-folder: Source folder path. This option will recurively scan for image files or mkv files. Will take precedence over --source if both are provided.
• --fx-upscale: Upscale video to 4K resolution using fx-upscale (disabled by default).
• --remove-original: Remove the original source after processing completes successfully.
• --overwrite: Overwrite existing output file.
• --keep-files: Use durable stage boundaries and keep retained intermediates. This affects retention only; it does not change the selected audio policy. An explicit --remove-original still removes the selected source after a successful conversion.
• --output-root-folder: Output folder path. Defaults to the current directory.
• --audio-mode: Audio handling mode: automatic, convert_aac, or pcm (default: automatic). Automatic copies qualified AAC audio to an owned M4A, and converts the whole selected set to AAC if any selected stream is unqualified.
• --transcode-audio: Legacy alias for --audio-mode convert_aac.
• --audio-bitrate: Audio bitrate for AAC conversion in kb/s do not include unit (default: "384").
• --audio-preferred-language: Keep every audio track matching this language metadata. Accepts ISO 639 alpha-2, alpha-3/B, and alpha-3/T codes. Omit it to keep all audio languages.
• --left-right-bitrate: Bitrate for left and right views in Mb/s do not include unit (default: "20").
• --mv-hevc-quality: Quality factor for MV-HEVC encoding (default: "75").
• --fov: Horizontal field of view for MV-HEVC (default: "90").
• --frame-rate: Video frame rate (auto-detected if not provided).
• --resolution: Video resolution (auto-detected if not provided).
• --swap-eyes: Swap left and right views (disabled by default).
• --start-stage: Start processing at a specific stage.
• --output-commands: Output commands used to console.
• --software-encoder: Use software encoder for MV-HEVC encoding (disabled by default).
• --skip-subtitles: Skip subtitle extraction (disabled by default).
• --continue-on-error: Continue processing after an error (disabled by default).
• --language-code: Preferred subtitle language (default: eng). Accepts ISO 639 alpha-2, alpha-3/B, and alpha-3/T codes. Subtitle and audio language choices are independent.
• --remove-extra-languages: Remove subtitle languages other than --language-code (disabled by default).
• --no-keep-awake: Prevent the system from sleeping during processing (disabled by default).
• --version: Show the version number and exit.

Stage Names

• CREATE_MKV
• EXTRACT_MVC_AND_AUDIO
• EXTRACT_SUBTITLES
• CREATE_LEFT_RIGHT_FILES
• UPSCALE_VIDEO
• COMBINE_TO_MV_HEVC
• TRANSCODE_AUDIO (Prepare Audio)
• CREATE_FINAL_FILE
• MOVE_FILES

Examples

Process a Blu-ray disc:

bd-to-avp --source disc:0 --output-root-folder /path/to/output

Process an ISO image:

bd-to-avp --source /path/to/movie.iso --output-root-folder /path/to/output

Process an MKV file:

bd-to-avp --source /path/to/movie.mkv --output-root-folder /path/to/output --transcode-audio

Upscale Quality

For most users, the default values of 75 HEVC Quality and 75 Upscale Quality provides a good tradeoff of preserving all the details of the original film, the extra details generated by the upscaler, while also keeping the size of the resulting video manageable.

If you would like to change the default quality, here are some recommended alternative settings sorted by final output size, with some notes about the quality of the results.

HEVC Quality values below 65 are not recommended when upscaling. At that quality level, you are essentially upscaling compression artifacts. Keeping the video in 1080p and increasing the HEVC Quality will result in a better viewing experience.

Note on Blu-ray drives

If your BD drive does not seem to be compatible with your M-series Mac, it's possible that the error is related to the region code, which BDs handle differently than DVDs.

Solution

• Connect your BD drive to your Mac via USB. Using a dongle often yields better results than a direct connection.
• Insert a DVD (not a Blu-ray) into the drive and open the DVD Player.
• If prompted, select a region code for the DVD.
• Eject the DVD and insert a Blu-ray disc. Your Mac should now recognize the Blu-ray discs.

This method has been effective in resolving compatibility issues.

Contribution

Contribute to the project by submitting pull requests or opening issues for bugs and feature requests.

Acknowledgements

Big thanks to:

• sturmen on the Doom9 forums, for an encoding guide using FRIM Decoder as well as creating the spatial-media-kit-tool
• Vargol on GitHub, for making the JM reference software build properly on macOS as well as an example script that was a useful reference
• steverice for h264-tools
• Thibault Raffaillac, Celticom/TVLabs, and Jens Duttke for edge264-mvc, used by the bundled native MVC splitter. The BSD license notice is included in bd_to_avp/resources/notices/edge264-mvc-LICENSE_BSD.txt. The pinned source revision directly supports Annex B MVC input from stdin and FIFOs, nonzero failure exits, bounded no-progress recovery, and terminal incomplete-frame recovery. scripts/build_edge264_macos.py reproduces the unsigned binary with the pinned release Xcode, SDK, and baseline arm64 architecture flags. App packaging re-signs that Mach-O as part of the containing application signature. bd_to_avp/resources/notices/edge264-mvc-build.json is the source of truth for the source revision, build toolchain, deployment target, linkage, and reproducible unsigned binary checksum.