flat2vr

🎞️ Turn flat video into headset-ready stereo depth 🥽

flat2vr is a Python CLI for video creators and VR viewers who want to turn ordinary 2D footage into stereoscopic Full Side-by-Side video for headsets such as Meta Quest 3. Point it at a video and run the conversion on an NVIDIA Docker host or Modal; it returns an HEVC .mp4 with the source audio retained.

The Python distribution is named flat2vr-cli; it installs the flat2vr command and flat2vr import package.

The lightweight client stays local. CUDA, FFmpeg, DepthCrafter depth estimation, and M2SVid view synthesis run inside the same pinned GPU container on either backend.

Install

flat2vr requires Python 3.11 or newer and uses uv for its local environment.

git clone https://github.com/tsilva/flat2vr-cli.git
cd flat2vr-cli
uv sync

Run uv run flat2vr --help to inspect the CLI.

Commands

# Check a local or API-addressed NVIDIA Docker host, then convert a video.
uv run flat2vr doctor --backend docker
uv run flat2vr convert input.mp4

# Convert on a remote Docker host over SSH.
uv run flat2vr convert input.mp4 -o output_Full_SBS.mp4 \
  --docker-ssh gpu.example.com --docker-sudo

# Build the pinned GPU image explicitly.
uv run flat2vr build

To use Modal instead of Docker:

uv sync --extra modal
uv run modal setup
uv run flat2vr modal deploy
uv run flat2vr doctor --backend modal
uv run flat2vr convert input.mp4 --backend modal

Tune the conversion or run the test suite:

uv run flat2vr convert input.mp4 -o output_Full_SBS.mp4 \
  --disparity 0.05 --depth-steps 5 --output-height 1024 --quality 19

uv run python -m unittest discover -s tests -v

Notes

  • The default output is <input>_Full_SBS.mp4. Select SBS/LR or 3D SBS mode manually if your player does not infer the layout from the filename.
  • At the default output height, a 16:9 source produces an approximately 3584×1024 frame containing two full-resolution eye views.
  • --encoder auto prefers NVENC and retries with CPU libx265 if NVENC fails.
  • The first conversion populates the persistent flat2vr-models cache with roughly 13 GB of model data. Later jobs reuse it.
  • Docker can run locally, through a Docker API endpoint, or over SSH. Modal uses the same pinned container plus flat2vr-models and flat2vr-jobs volumes.
  • Successful Modal jobs remove their uploaded input and generated output after download. Failed job files are retained for diagnosis.
  • The result provides binocular depth, not six-degree-of-freedom geometry. You can watch the 3D image, but you cannot move around its objects.
  • Source revisions, Python environments, model revisions, and model hashes are pinned for reproducible conversions.

Architecture

flat2vr architecture

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for engtiagosilva from gravatar.com engtiagosilva

Requires

Python >=3.11

Provides Extra

modal

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

flat2vr_cli-0.1.3.tar.gz (7.9 MB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

flat2vr_cli-0.1.3-py3-none-any.whl (156.4 kB view details)

Uploaded Python 3

File details

Details for the file flat2vr_cli-0.1.3.tar.gz.

File metadata

  • Download URL: flat2vr_cli-0.1.3.tar.gz
  • Upload date:
  • Size: 7.9 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for flat2vr_cli-0.1.3.tar.gz
Algorithm Hash digest
SHA256 67d04f3f60cecdd37233a8591f9f31cc4deeaaa331bc2efe25d21905ec45d6b5
MD5 91eefe6c0845d84f0863cbfe7f31ceca
BLAKE2b-256 089b598c79a2425486f3ac65a1c52790ce09c4be36ffce2f535595ad9ca18af3

See more details on using hashes here.

Provenance

The following attestation bundles were made for flat2vr_cli-0.1.3.tar.gz:

Publisher: release.yml on tsilva/flat2vr-cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file flat2vr_cli-0.1.3-py3-none-any.whl.

File metadata

  • Download URL: flat2vr_cli-0.1.3-py3-none-any.whl
  • Upload date:
  • Size: 156.4 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for flat2vr_cli-0.1.3-py3-none-any.whl
Algorithm Hash digest
SHA256 2e990394dac934e69e6ca540dbbbaca8d5b473addf4266bce000f53e1540f093
MD5 9f1eec974525664a2a1b406a106878f7
BLAKE2b-256 6d34fa08c220c753c0c808620c41101df7585914323b4fa4122142f931ca871e

See more details on using hashes here.

Provenance

The following attestation bundles were made for flat2vr_cli-0.1.3-py3-none-any.whl:

Publisher: release.yml on tsilva/flat2vr-cli

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.3 This release

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page