BD_to_AVP

This repository contains the full Mac converter and the Vision Pro movie player:

| App | Platform | Purpose | | --- | --- | --- | | 3D Blu-ray to Vision Pro | macOS | Convert supported sources into spatial movies and share completed movies with a paired headset. | | Shiny 3D Cinema | visionOS | Choose and play completed movies from Files or a compatible Mac's shared folders. |

Use the Movie Sharing beta quick start to install both apps, share a folder and pair the headset. The player guide covers supported formats and developer workflows. The repository, CLI, Xcode targets, bundle IDs and saved-data paths retain their established BD_to_AVP/BDToAVPPlayer identities; they do not need to match the public app names.

Introduction

The Mac app turns 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

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.

Prerelease testers evaluating the new repetition-first setup workflow should use the Conversion Setup Beta Test Guide so feedback covers the same setup, repeat-run, editing, conflict, queue, and rollback scenarios.

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.

Runtime tool lookup prefers explicit BD_TO_AVP__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 [email protected]
Install the current macOS MakeMKV build from https://www.makemkv.com/.
The app bundle is detected automatically from /Applications/MakeMKV.app
or /Applications/MakeMKV/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.

The native app uses one persistent queue workspace for composition, review, execution, and results. Use Add Sources…, the queue's Add menu, or drag and drop to append files, folders, disc images, Blu-ray folders, movie folders, and inserted discs without replacing work already in the queue. Select a waiting video and use Edit… to change its Profile and conversion settings, or Change… to choose its destination.

Choose Configure Source… from the Add Sources menu when you want to inspect one source before admitting it. That secondary sheet restores Preview plus main, all-video, and custom title selection without replacing the main queue workspace. Add to Queue, Start Queue, and a reviewed Preview all save their selected drafts to the durable queue before queue execution begins.

If a source and Profile require a route-quality choice, the item is persisted immediately as Needs a Choice and the available resolution appears in its detail pane. The queue will not start while any item still needs that choice, so later videos cannot run ahead of unresolved work. Remembered choices remain scoped to the matching source and Profile and can be forgotten from the resolution prompt. Editing a waiting row can also park that row as **Needs a Choice** instead of losing the unresolved route-quality decision.

Waiting videos can be selected, edited, dragged into a new order, or arranged from the menu bar's Queue menu and the sidebar's Arrange menu. The Queue menu also provides source and detected-disc admission, Start Queue or Resume Queue, Pause After Current, Stop Current, selected-item Remove, and Undo Remove. Arrangement commands include Move Up (⌘⌥↑), Move Down (⌘⌥↓), and Convert Next (⌘⌥↩); Add Sources… uses ⌘O. Command titles and availability track the same durable queue state as the sidebar, and Queue actions disable when another app scene such as Settings is active. Locked rows explain why they cannot move, edit, or be removed, while active and completed settings remain locked. Work restored after an app restart never starts automatically; interrupted or stopped videos require an explicit Resume Queue, Restart Safely, or recovery choice. Pause After Current lets the active video finish without starting another, while Stop Current cancels only the active video and leaves pending work waiting for an explicit resume. Runtime failures and recovery decisions remain parked according to their existing queue policy.

The sidebar includes a compact Results strip once durable outcomes exist, with count buttons for completed, failed, and needs-action items. Needs action groups choices, interrupted work, and recovery decisions separately from failed items; selecting a count jumps to the first matching queued item.

Queue notifications are optional and default off in Settings. The app can notify when a queue run finishes and/or when a queued item first needs attention during that run. macOS notification text is count-only: source names, file paths, destinations, technical details, and failure text stay inside the app.

The queue also shows a coarse storage forecast grouped by destination. Each forecast separates estimated output, peak temporary/working space, retained intermediates, a visible safety margin, and total peak space. Forecasts use known source duration and route information when available; content-dependent or artifact-based routes remain explicitly unestimated rather than turning an assumption into a capacity block. The safety margin is 10% of peak working space, rounded up to whole GiB and clamped between 2 GiB and 20 GiB.

Immediately before each queued item starts inspecting or converting, the app rechecks that its destination exists, is a writable directory, and has enough confirmed free space for the coarse total peak estimate. Unknown or conflicting capacity readings are advisory and do not block an item. A disconnected or read-only destination parks only that item with a retryable reconnect/check- writable message; known insufficient space parks the item with required and available coarse sizes and pauses the remaining queue. Reconnect the volume or free space and retry the parked item, or change its destination and resume the queue. The queue-level forecast covers remaining not-yet-active work; held route-quality and recovery choices are listed as unestimated until resolved.

Use Start Later… to arm one editable, cancellable off-peak window for the queue. The app must remain open: it does not schedule a system wake and does not keep the Mac awake merely because a window is armed. If the Mac wakes while the window is still open, the queue starts late; reopening the app after the start time or evaluating after the end marks the window missed and never starts it automatically. A video already running may finish after the end, but no new video starts outside the window. Sources are rechecked at launch time, and missing removable media or the wrong physical disc is parked while unrelated available work continues.

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

• --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

• --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

• --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,

• --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

• --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 | Upscale Quality | Min Processing Space Needed | Final Size | Notes | |--------------|-----------------|-----------------------------|------------|-------------------------------------------------------------------------------------------------------------| | 85 | 85 | ~ 225 GB | ~ 95 GB | These settings are arguably "too" high. Only for those obsessed with maintaining the best possible quality. | | 85 | 50 | ~ 130 GB | ~ 62 GB | A reasonable choice for "Best Quality" encoding. | | 75 | 75 | ~ 100 GB | ~ 47 GB | The default setting. | | 75 | 50 | ~ 75 GB | ~ 37 GB | Provides a good trade-off for minimizing storage space while retaining quality throughout the process. | | 65 | 65 | ~ 75 GB | ~ 32 GB | Compression artifacting is very visible in dark scenes or on fast-moving objects, but is otherwise okay. |

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.

Contribution

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

Acknowledgements

Big thanks to:

• [sturmen][sturmen] on the Doom9 forums, for [an encoding guide][sturmen-guide] using FRIM Decoder as well as

• [Vargol][vargol] on GitHub, for making

• [steverice][steverice] for [h264-tools][ldecod]
• Thibault Raffaillac, Celticom/TVLabs, and Jens Duttke for [edge264-mvc][edge264-mvc], used by the bundled native MVC

[MakeMKV]: https://www.makemkv.com/

[FFmpeg]: https://ffmpeg.org/

[jm-reference]: https://iphome.hhi.de/suehring/

[ldecod]: https://github.com/steverice/h264-tools

[spatial-media-kit-tool]: https://github.com/sturmen/SpatialMediaKit

[MP4Box]: https://github.com/gpac/gpac/wiki/MP4Box

[sturmen]: https://forum.doom9.org/member.php?u=224594

[sturmen-guide]: https://forum.doom9.org/showthread.php?p=1996846#post1996846

[vargol]: https://github.com/Vargol

[vargol-tools]: https://github.com/Vargol/h264-tools

[vargol-guide]: https://github.com/Vargol/h264-tools/wiki/Conversion-script-for-MVC-3D-blu-ray-extracted-by--MakeMKV

[steverice]: https://github.com/steverice

[h264-tools]: https://github.com/steverice/h264-tools

[edge264-mvc]: https://github.com/jens-duttke/edge264-mvc

[Homebrew]: https://brew.sh/

[Python]: https://www.python.org/

[Mac]: https://www.apple.com/mac/

[macOS Sonoma]:https://apps.apple.com/us/app/macos-sonoma/id6450717509?mt=12

[releases page]: https://github.com/cbusillo/BD_to_AVP/releases