mk3d-fs-to-spatial

Script that will take a frame-sequential mk3d 3D video and convert it to Apple Spatial Video. The mk3d file can be created with MakeMKV or similar.

Prerequisites

You will need an Apple Silicon-based Mac running macOS Sonoma (see caveats).

You must also have the following installed and configured on your system:

• ffmpeg, most easily installed with homebrew
• ldecod (part of the JM H.264/AVC reference software), Mac binaries available on GitHub
• spatial-media-kit-tool
• mp4box, part of the GPAC framework

You will also need sufficient disk space to store the intermediate files and the final Spatial video.

CLI Options

Option	Example use	Description
-x --software	--software	Use libx265 software encoder (slower, higher quality). This is the default encoder. Since the libx265 conversion is lossless, there is no quality to specify.
-t --hardware	--hardware	Use hevc_videotoolbox hardware encoder (faster, lower quality). Specify quality with --hevc-quality.
-q --hevc-quality	--hevc-quality 50	Quality to use with hevc_videotoolbox (1 to 100, 100 is highest quality/bitrate; default 50) Larger target quality (especially above 50) will use lots of disk space.
-s --spatial-quality	--spatial-quality 50	Quality to use with spatial-media-kit-tool (1 to 100, 100 is highest quality/bitrate; default 50) This will have the largest impact on the bitrate/size of the final spatial video.
-a --audio-bitrate	--audio-bitrate 512k	Compress audio with AAC at this bitrate using aac_at to save space. If omitted, lossless LPCM audio will be used instead.
-k --keep-intermediate-files	--keep-intermediate-files	Instead of removing intermediate files when they are no longer needed, leave them on disk. Good to use when you are testing so you can run a later step without redoing all previous steps. Makes the process require more total disk space.
-v --verbose	--verbose	Enable verbose output. Not too noisy, good to enable to see what's going on.

Caveats

This script has been tested on these configurations:

• Apple Silicon M2 Mac running macOS 14.3.1

It might on Intel-based Macs, as well as other versions of macOS Sonoma, but your mileage may vary. If you get it working on your machine, please submit a PR to update this list!

This will not work on Linux or any other non-Apple OS, as the Spatial video encoding relies on APIs only available in macOS.

Acknowledgements

Big thanks to:

• sturmen on the Doom9 forums, for a 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