How to Use Jellyfin on Apple Vision Pro with Lumair

Lumair connects Apple Vision Pro to your personal Jellyfin server, letting you browse a library, select a version, play compatible files, keep Jellyfin watch progress, and download selected movies, episodes, or seasons for offline viewing.

Lumair does not include media. You are responsible for having the rights to the media you add to Jellyfin and play in Lumair. Lumair is not affiliated with Jellyfin.

To use this workflow, you need a running Jellyfin server, a Jellyfin account, and a server address that Apple Vision Pro can reach. On your home network, this can be a local address. Away from home, use a remote address that you have configured to reach your server securely.

Lumair can also open compatible local files through the Files app. Lumair can browse, stream, and download compatible video directly from SMB servers on the local network. It does not claim NFS, DLNA, WebDAV, Plex, or Emby support. Lumair plays compatible decrypted 2D and 3D Blu-ray ISO disc images but does not open BDMV folders, bypass DRM, or rip discs. For local files, use Files to select a compatible file that is already available on the device or a location exposed through Files. Apple documents how to view and organize files on Apple Vision Pro in its Files guide.

Connect Lumair to Your Jellyfin Server

Connect Lumair with the same server address and Jellyfin account that you use for your library.

1. Install and open Lumair on Apple Vision Pro.
2. Choose the option to connect a Jellyfin server.
3. Enter your server address, including the protocol and port when your setup requires them.
4. Sign in with your Jellyfin username and password.
5. Wait for the libraries available to that account to load.

Lumair sends the address and credentials to your Jellyfin server for authentication. Your Jellyfin account determines which libraries Lumair can see, which watched status it reads, and which items it can download.

Use a local server address only while the Vision Pro can reach that local network. For playback outside your home, enter the remote address that you already use for Jellyfin. Lumair does not configure router rules, reverse proxies, certificates, remote access, or Jellyfin server security.

If Lumair cannot connect, check the address in a browser or another Jellyfin client first. Confirm that the Jellyfin server is running, the Vision Pro has network access, and the address matches the network you are using. Then confirm that the username and password belong to an account with access to the expected libraries.

Browse, Search, Filter, and Choose a Version

After Lumair loads your Jellyfin libraries, browse by library type and open a title. You can use search when you know the title, person, or series name. Filters help narrow larger libraries by the options exposed for that library, such as media type, watched state, genre, or other Jellyfin metadata.

For a show, open the series, choose a season, then select an episode. For a movie, open its detail page. Lumair displays the metadata and available actions supplied by Jellyfin.

When Jellyfin has multiple versions of a title, choose the version before playback. A library might contain a standard version, an HDR version, a 3D version, or files with different audio and subtitle tracks. Select the version you intend to play, then choose the audio and subtitle options that fit the file.

File names, extensions, codec labels, bitrates, containers, and file sizes do not guarantee playback. Test the version you plan to watch. A file can differ in video profile, audio, subtitle format, metadata, or server delivery behavior even when it appears similar to another file.

How Lumair Plays Jellyfin Media

Lumair uses more than one delivery path because Jellyfin and Vision Pro handle different media types in different ways.

For ordinary Jellyfin versions, Lumair requests the Jellyfin-provided HLS playback path. HLS is an HTTP streaming format used by Apple playback frameworks and can represent media that Jellyfin delivers directly or prepares for the client. Apple describes HLS requirements in its HLS Authoring Specification.

For selected compatible H.264 MVC Matroska files, Lumair uses its authenticated static byte-range path instead of the ordinary Jellyfin HLS path. This path gives Lumair access to the selected original source file in ranges while preserving Jellyfin authentication. Lumair decodes compatible MVC video and converts it on the device to stereo MV-HEVC for the visionOS system player. Apple documents the conversion of side-by-side 3D video to multiview HEVC and spatial video through AVFoundation here.

MVC playback in Lumair involves on-device conversion. It is not direct MVC playback and it is not no-conversion playback. Compatibility depends on the source file and its streams, so test a representative file before planning a long viewing session.

Jellyfin Direct Play, Remux, Direct Stream, and Transcode

These Jellyfin terms describe how Jellyfin prepares or delivers a file. They are separate from Lumair’s own handling after it receives media.

• Direct Play means Jellyfin sends the original file without changing its media streams. The client must support the file’s container, video, audio, subtitles, and other playback requirements.
• Remux means Jellyfin repackages compatible streams into a different container without re-encoding the video or audio streams.
• Direct Stream transcodes audio while leaving the original video untouched, according to Jellyfin’s current documentation.
• Transcode means Jellyfin converts one or more streams to formats the playback device can use. This requires server processing and can depend on the server’s hardware, configuration, and network capacity.

Jellyfin documents client codec support and server transcoding in its codec support documentation and transcoding documentation.

For ordinary Lumair playback, Jellyfin’s HLS path may involve any of these server-side decisions. Lumair does not relabel a Jellyfin Direct Play, Remux, Direct Stream, or Transcode result as its own format process.

For compatible MVC MKV playback, Lumair’s authenticated static byte-range path and on-device MVC-to-MV-HEVC conversion are Lumair-specific handling. Jellyfin still provides the authenticated source access, while Lumair prepares the compatible MVC video for the visionOS system player.

Compatible Local Playback, HEVC, HDR, and MVC

Lumair can open compatible local files through Files, browse and play compatible media from SMB, and play compatible media from Jellyfin.

Compatible MP4, MOV, and M4V files that AVFoundation handles use native playback. Apple Vision Pro supports video playback through its system capabilities, subject to the format and file characteristics involved. See Apple’s Vision Pro technical specifications and its guide to playing shows and movies.

For compatible HEVC MKV files, Lumair remuxes the file while preserving the original HEVC base video. Lumair may prepare Dolby Vision when that is safe for the source. When it is not safe, Lumair uses the source HDR10 base layer where available. This behavior depends on the specific file and profile. Do not assume every Dolby Vision, HEVC, MKV, HDR10, or HDR file will play in the same way.

For compatible H.264 MVC video in MKV, Lumair decodes MVC and converts it on device to stereo MV-HEVC for the visionOS system player. Choose the 3D version in Jellyfin when a title has multiple versions, then test a short section for correct playback before watching the full title.

Lumair plays compatible decrypted 2D and 3D Blu-ray ISO disc images. It does not open BDMV folders or encrypted disc images. For unsupported disc sources, prepare media you are permitted to use as a compatible file before adding it to Jellyfin or opening it with Files.

Sync Jellyfin Watch Progress

Lumair syncs playback progress with the connected Jellyfin account. Start a title, stop playback, and return to the same title while connected to the same server and account. Jellyfin can then show the saved position in Lumair and other clients that use that account’s watched-state data.

Progress is account-scoped. If you connect with a different Jellyfin user, that account has its own watched status and resume position. A local setting on the Vision Pro does not merge separate Jellyfin accounts.

Before relying on resume behavior for a trip or a long series, test it with one title. Start playback, stop after several minutes, return to the library, and confirm that the resume position appears under the same account.

Download Movies, Episodes, and Seasons

Lumair can download selected Jellyfin movies, episodes, and seasons to app-managed storage on Apple Vision Pro.

1. Connect to your Jellyfin server in Lumair.
2. Open a movie, an episode, or a season.
3. Select the version you want, when versions are available.
4. Choose the download action.
5. Keep the Vision Pro connected until the download completes.
6. Play the downloaded item before travel.

Lumair downloads the selected original source file unchanged. It does not create a smaller offline transcode for the download. Embedded audio, video, chapter, and subtitle tracks remain in the downloaded source file. Separate external subtitle files are not bundled with the download.

Downloads are account-scoped. Lumair associates downloaded items with the Jellyfin server and account that requested them. If you sign out while that account has downloads, Lumair warns with the item count and size, then cancels and deletes only that account’s downloads before clearing its credentials.

App-managed storage also means downloaded items are managed inside Lumair rather than appearing as ordinary files for use by unrelated apps. Check available Vision Pro storage before downloading a season, especially when the original files are large.

Test every downloaded item before travel. A completed transfer confirms that the source file reached the device. Playback still depends on the file’s compatibility with Lumair and the visionOS playback path. Apple’s Travel Mode guide covers using Apple Vision Pro while traveling.

Troubleshooting

Lumair cannot connect to Jellyfin

Verify the server address, network access, username, and password. Try the same address from another device on the same network. If you use a local address, connect the Vision Pro to the home network. If you use a remote address, verify that it works outside the home network.

A title buffers or does not start

Try another version of the title. Check whether Jellyfin is Direct Playing, remuxing, Direct Streaming, or transcoding the file, then review server load and network conditions. Jellyfin transcoding can require substantial server resources depending on the source and selected streams.

An MVC MKV does not play in 3D

Confirm that you selected the intended 3D version. The file must be a compatible H.264 MVC Matroska source. Lumair plays compatible decrypted 2D and 3D Blu-ray ISO disc images but does not open BDMV folders, bypass DRM, or rip discs. Test another compatible MVC MKV if available, because an MVC label alone does not establish compatibility.

A download completed but does not play

Test the selected source file while connected before downloading it. Downloads preserve the original source file, so an incompatible source remains incompatible offline. Check that you downloaded the intended version and that the full transfer completed.

Progress does not resume

Confirm that Lumair is connected to the same Jellyfin server and signed in with the same Jellyfin account used during playback. Give the server a moment to receive the progress update, then reopen the title.

Lumair includes a 5-minute playback preview for every video. Full Playback is a $14.99 US one-time purchase. App Store pricing can vary by storefront.

Download Lumair free on the App Store.