FinVR is made for the classic smartphone VR headset, the kind you can pick up for cheap, not the fancy high-priced standalone rigs. You insert your phone, put it on, and you are in VR. A controller is highly encouraged. FinVR works with anything that has buttons and pairs with Android: PlayStation, Xbox, Switch controllers, the budget controllers that came with your headset, even those killer Android TV remotes.

Some headsets are open on top, giving you access to your phone's volume buttons while inserted. FinVR maps the most important controls there, so you are good to go. But if your headset encloses the phone like a cage with no access, you will want a controller.

FinVR also supports the media buttons some headsets have, the on-screen touch button, and the play/pause/skip controls on bluetooth earbuds. Since settings sometimes need tweaking during playback, the better your controller, the smoother the ride. FinVR tries to support every input out there, but at the end of the day it is limited by what your equipment reports.

If your headset came with a budget controller, or if you own an Android-compatible gamepad or Android TV remote, you are in luck! Head over to the Controller Help page to learn how to connect them.

When assigning your buttons, focus on the essentials first. Player Settings (Open/Close/Next/Prev Setting, Setting+/−) bindings let you tweak essential visuals during calibration, and more during a play session. You will need to set those. You also want Play/Pause and Recenter View. These are all you need to get up and running. The rest is nice to have for later, but you can take your time with those.

On the controller overview page, you can live-test your setup: press any button on your controller and the assigned command will light up. Help links are scattered throughout the process, so if anything feels unclear, give them a tap and get a feel for what you are doing.

Calibration is where you turn a screen into a headset that actually fits. To get started, head to Settings and tap the calibration entry. Once in Calibration Mode, your volume buttons are your best friends — as long as you can reach them inside the headset. If not, a configured controller is the way to go.

• Volume+ (short press): Re-centers the image.
• Volume+ (long press): Opens the settings menu.

While settings are open:

• Volume+ / Volume− (short press): tweak the active setting.
• Volume+ / Volume− (long press): Cycle to the next or previous setting.
• Volume− (long press): Resets all settings back to defaults.

A configured controller can do all of this too, and honestly it is often the easier way.

If any of the settings sound confusing, hop over to the Terminology page for a full breakdown.

These adjustments are a one-shot deal. Set your IPD and CA (if you enabled it) once, and forget about them. You know they are correct when the whole grid image — from the corners to the center, and the settings menu itself — is readable, sharp, and free of double vision.

Keep in mind that the IPD setting in the menu is not the only thing that fixes double vision. It works together with the hardware slider on your headset that adjusts the lens distance. Both need to match your eyes. From that point on, if something feels off while watching a 3D video, adjust with FOV and the hardware slider. The calibration settings stay put.

With your headset calibrated, you are ready to play. Head to Let's Play in the app and choose your media source or server.

Play local files, a URL from network, or from your configured Jellyfin servers.

FinVR can also serve as an external player for your already configured Jellyfin app or any web video casting app, anywhere where you can select Open with…

Configure your server from the home screen, browse your library, and start playback. That is it. FinVR can also act as an external player for another Jellyfin client app if you prefer browsing there, but for best experience the server should be authenticated within FinVR — otherwise some features like retrieving playlists or saving playback position will be restricted.

Budget controllers, the ones bundled with a headset or bought for cheap, have hardware that only knows a button was pressed, not for how long. Long press works on the D-Pad only; regular buttons are short press only.

Premium gamepads (8Bitdo, Xbox, and similar) report everything properly. Every button supports short, long, and double press, giving you the full range of assignable actions.

Budget controllers must be in Gamepad Mode (Mode C) before FinVR can use all their buttons. How to switch depends on the model:

• Long press @ (or circle) and press C while the device is on.
• Or: power it on by pressing Power + C together.

If you see a mouse cursor on screen, you are in the wrong mode. Other modes may appear to work, but some buttons will trigger Android system actions (Back, Home) and interfere with the app. FinVR cannot fix that. Switch to Gamepad Mode.

In Gamepad Mode you typically get buttons A, B, C, D plus the D-Pad or joystick: 4 buttons for short press, 4 D-Pad directions for both short and long press, up to 12 assignable actions in total.

Any premium controller connects and works correctly from the start. Their hardware reports how long a button is held, so every button including triggers and bumpers supports short, long, and double press.

One thing to watch: premium controllers can have multiple input modes. If buttons start triggering unexpected system actions (Home, Back), check that your controller is in the correct mode. The manual is probably in a drawer somewhere.

PlayStation Controllers

DualSense (PS5)

• Press and hold the Create button (left of the touchpad) and the PS button together until the light bar blinks.
• On your Android device, go to Settings > Bluetooth and select "DualSense" or "Wireless Controller" from the list.

DualShock 4 (PS4)

• Press and hold the SHARE button and the PS button together until the light bar flashes.
• On your Android device, go to Settings > Bluetooth and select "DualShock 4" or "Wireless Controller" from the list.

Wired Connection

You can also connect directly with a cable:

• DualSense (PS5): USB-C to USB-C cable.
• DualShock 4 (PS4): USB-C to USB-C or micro-USB cable with an OTG adapter.

Xbox Controllers

• Press the Xbox button to turn the controller on.
• Hold the sync button on top until the light flashes rapidly.
• On your Android device, go to Settings > Connected devices > Pair new device and select "Xbox Wireless Controller".

FinVR supports Bluetooth Smart TV remotes built for Android TV. And of all the controller types, these actually have the widest range of buttons: number keys 0–9, mute, menu, dedicated app shortcuts, teletext, media controls, and more depending on the model.

The directional pad in the center counts as the D-Pad. OK/Select is assignable. TV remotes are Premium devices. Their hardware properly reports press duration, so every assignable button supports short, long, and double press.

The following are handled exclusively by Android and cannot be assigned by any app: Power, Back, Home, and Assistant. There may be others depending on the remote, but if a button can be consumed, FinVR will let you assign it.

Android maps all the following to the same D-Pad input, and FinVR has to go along with it:

• The direction buttons on budget VR controllers
• The joystick on budget VR controllers and premium gamepads
• The directional pad on premium gamepads
• The directional pad in the center of a TV remote

They all produce the same four directions and are assigned per controller, just like any other button.

If you are using the Live Input Monitor and notice that pressing your physical 'A' button shows a generic number or, even weirder, a completely different button name like "D-Pad Up," don't panic. Your controller isn't possessed, and FinVR isn't broken.

Bluetooth controllers are notorious for being "creative" with the signals they send. Some budget remotes pretend to be keyboards, others use non-standard layouts, and some just flat-out lie to Android about which button is which.

FinVR doesn't trust these labels any more than you do. We just listen for the unique signal your device sends, regardless of what the device thinks that button is called. Once you assign that "liar" to a real command like Play/Pause, the monitor will stop showing the generic labels and show the beautiful command icon you chose instead.

Buttons in FinVR are smart; they change what they do based on what you are doing. Commands are split into three main teams:

• Player Controls are the basics like Play, Pause, and Seeking. These work everywhere, whether you are in the headset or using the handheld player.
• Player Settings are special. They only wake up when the settings menu is open. This means you can use the same button for volume when the menu is closed and for scrolling through options when it is open.
• VR Player Controls are for the immersive stuff. They only trigger when you are actually watching inside your VR headset.

We also have Calibration Controls for when you are in the cockpit. You can assign these specifically for calibration mode, but they usually borrow your Player Settings choices by default. It is all about giving you the most control with the fewest buttons!

To assign a command, tap it in the list, and FinVR then waits for your input:

• Short press the button → assigned as short press.
• Hold for 0.6 s → assigned as long press.
• Double tap the button → assigned as double press.

Long press is detected when the button is held for 0.6 seconds. Double press is detected when you tap twice within 0.2 seconds. Budget controllers support short press only (except for the D-Pad). Premium controllers and TV remotes support all three interaction tiers on every button.

Some buttons are reserved by Android and cannot be captured by any app, including FinVR. These typically include Back, Home, Assistant, and the Power button on Bluetooth TV remotes. Others may exist depending on the device or firmware.

FinVR does its best to consume every available input, but system-reserved buttons are off the table by design.

If your controller is in the wrong mode, budget or premium, some buttons may be remapped to Home or Back by the controller firmware, causing the app to close unexpectedly. That is a mode issue, not a FinVR bug.

The Live Input Monitor on the controller overview page shows every button press your controller sends, in real time. It will display the button name as reported by your hardware and the command it is currently assigned to, if any.

Use it to verify your controller is connected and working, or to see what a button actually reports before you assign it. A button showing "Unconfigured Button" means it is being detected but is not assigned to anything yet. If a button shows a different name than expected, you have found a liar — that is what the Helpful Liars section is for.

Tap-triggered commands from Bluetooth earbuds, like single-tap play/pause or double-tap skip, do not show up in the Live Input Monitor. The monitor only displays controller button events, and those gestures are handled differently by Android. The commands still work in the player; you just will not see them light up here.

Any regular video plays on a large virtual screen locked in space around you. Look around freely and the picture stays exactly where it is.

For 3D content, FinVR supports Left/Right, Top/Bottom, and Full Side-by-Side (FSBS) with true stereoscopic rendering: each eye sees its own image, giving real depth to every scene. The format is detected automatically, so most videos just work. You can manually switch between 3D, 2D VR, and Handheld mode at any time. If the depth looks reversed, cycle the Stereo Layout to a (Swapped) version for an instant fix.

When Volume Key VR Shortcuts is enabled, the Vol+ and Vol− keys stop being just volume and become a set of quick controls you can hit without touching the screen.

Player controls (settings closed):

• Vol+ (tap): Recenters your view
• Vol− (tap): Opens the settings panel
• Long Vol+: Jumps to the previous video
• Long Vol−: Skips to the next video

In-settings navigation (settings open):

• Vol+ / Vol−: Adjusts the currently selected setting
• Long Vol+ / Long Vol−: Moves to the next or previous setting

In other words, you can browse and adjust settings by feel, with one hand, without ever pulling up the screen. Useful when the headset is already on your face and a full overlay feels like too much, or when the headset is flipped open on top and you just want quick access without putting it back on.

In Handheld mode, the keys behave normally and just control playback volume.

FinVR can detect some 3D videos automatically, but not all of them. For reliable detection, check out Organizing your Library for naming tips.

To switch manually, there are two controls you can assign to your controller:

Stereo Layout cycles through Left/Right, Top/Bottom, and their swapped variants. If the depth feels inverted, the swapped version fixes it instantly.

Switch Projection toggles between Cinema, Dome 180°, Fisheye (180°, 190°, 200°, 220°), and 360° Sphere. A dedicated Toggle Rear View command flips the 360° view by 180 degrees.

Some VR headsets have a physical button that fires a touch event. Without Headset Lock, every press would open the on-screen controls — not ideal when you are in the middle of a scene. Lock mode repurposes that touch into something useful:

• Single tap plays or pauses
• Double tap skips to the next video
• Triple tap goes back to the previous one
• Long press recenters your view

You can toggle Headset Lock from the lock icon in the overlay (only visible in Headset mode). Once locked, a confirmation appears: "Headset lock enabled. Swipe to unlock."

Need the full overlay back? Swipe anywhere on the screen to unlock and bring up the controls.

Locking also fixes the screen orientation, so lying on your side — or attempting a handstand — won't accidentally spin your view. As soon as you unlock, it goes back to normal sensor-based orientation.

You know the trick: hold your finger in front of your nose and look at something across the room. Suddenly you have two fingers, right? Congratulations, your eyes work.

The same thing happens in VR. When you watch a scene and two big jellyfish drift right in front of the lens — your eyes converge at that close distance. That is what they are supposed to do. Then you pull up the settings or the playback speed display, and those on-screen elements appear right where you are looking, at a different depth than where your eyes are currently focused. So they show up double.

This is not a bug. It is not a limitation of FinVR. It is your biology reminding you that it is older than screens and does not care about your VR experience. The on-screen overlays are rendered right on the glass, your eyes are busy looking at the jellyfish — the math does not work out.

If it happens, try looking at something farther away in the scene and bring up the settings there. It will snap right back to single. Or just dismiss the overlay and enjoy the show.

If diplopia happens with near objects in the scene itself (not just the overlays), your FOV may be set too low or the headset lenses may need adjusting — or both.

If you give FinVR high resolution content above 4K to play, it will — no matter what — try to give you the best experience with smooth play, even if your device usually does not support such resolutions. There are some mad scientist techniques in place to make this possible — you may however notice audio delays, though FinVR will try to compensate.

Whenever FinVR enters High-Res Ultra Play mode, it will notify you with a short on-screen message. Your phone will get warm, and the battery will drain faster — think of it as your device hitting the gym. Harmless, but it will need a breather afterward.

Some video files have the audio track slightly out of step with the picture. If the sound hits before the lip movement, you can dial in a delay directly from the player settings (available for Pro). Adjust in 50 millisecond steps up to half a second. The change applies immediately, so you can tweak until it lines up.

This fixes a fixed offset in the source file. It will not correct desync caused by High-Res Ultra Play. In that mode, FinVR does its best to keep audio in sync, but smooth playback takes priority. Those resolutions push your phone past what its decoder was built for.

Blurry view. Usually a hardware thing, not a software glitch. First, check if the phone screen is clean; a smudged lens is the most common cause. Then adjust the forward lens distance slider on the headset (the one that moves the lenses closer to or farther from your face, not the IPD slider between them). A millimeter or two (about 1/16 of an inch) makes all the difference.

Double vision that won't go away. If diplopia sticks around after tweaking FOV, IPD, and the lens distance slider, the phone may not be centered properly in the headset. Reseat it and run through Calibration again.

Video looks green or discolored. Some source files report HDR support but aren't actually encoded for it. Disabling HDR in Player Settings brings the colors right back. It is the file, not FinVR.

Inverted depth. If the 3D scene feels like objects pop inward instead of outward, switch to a swapped stereo layout. Right/Left or Bottom/Top flips it around instantly.

Pimples from VR. Yes, that can happen. Loosen the straps; too much pressure on sensitive skin causes irritation. Clean the headset regularly with isopropyl alcohol. Nothing stronger or the cushions will break down. Wash your face before using it, and consider buying protective VR mask covers. They come in packs and are easy to swap in.

The handheld player is a full-featured video player with a clean, touch-friendly overlay. You get a seek bar with live timestamps, seek buttons that accelerate the longer you hold them, playback speed control, scale modes (Fit Height, Fit Width, Fit Screen), a sleep timer, and a full playlist browser. Controls stay out of your way and auto-hide during playback. A single tap brings everything back.

For 3D videos, the handheld player lets you pan around the scene by dragging your finger across the screen. You can also cycle through the stereo layouts (Left/Right, Top/Bottom, and their swapped variants) using the Stereo Layout toggle. This also makes it easy to preview 3D content on a regular screen.

Scaling mode changes how the video fits on your screen without distorting the picture. Fit Height scales the video to match the screen height, cropping the sides if needed. Fit Width fills the screen width, leaving black bars top and bottom. Fit Screen stretches the video to fill every pixel.

Try switching between them if the video has odd borders or looks squished. The correct setting depends on the source, not on FinVR.

The sleep timer (available for Pro) stops playback automatically after a set time. You can choose from several durations or set it to stop at the end of the current video or the entire playlist. A small notification will confirm your choice.

When the timer runs out, FinVR gently dims the screen and fades the audio over 3 minutes, so you drift off naturally. What happens at the end depends on the Sleep: Standby Mode setting: with it on, the screen goes dark and the screen lock is released so your phone can go to sleep on its own. With it off, the player closes.

Tap the button to cycle through options. Long-press it to turn the timer off immediately.

FinVR is a fully fledged streaming player, and pretty generous with what you give it. It will parse any video URLs from the address you provide. No matter what, it will search for valid sources and add it to the playlist. Video feeds, direct video links, whatever you have — it will play.

You can also reach FinVR through Android's "Open with…" from your browser, file manager, or any video casting app that lets you pick an external player. If the app on your phone can find the stream, FinVR can play it.

Every URL you play through Network Stream gets saved automatically. Same goes for videos opened via "Open with…" from your browser or file manager. FinVR catches those too. Tap any entry to play it straight away, no typing required.

Swipe left on an entry to remove it, or use Clear History at the bottom to start fresh.

One thing to keep in mind: this is your personal stream history, not your Jellyfin library. Jellyfin has its own watch history. This is specifically for manually entered addresses and links you opened from outside the app.

FinVR connects to your Jellyfin media server and turns it into a seamless viewing queue. It picks up your current folder or TV series automatically, resumes from where you left off, advances to the next video when one ends, and lets you jump to any item in the queue from the playlist panel, the volume buttons, the headset touch button, or through the controller.

Jellyfin servers on your local network are detected automatically — just tap one to log in. If a server is hidden, you can enter its address manually.

After logging in, you can give your server a custom name if you want. That is the whole setup.

Need to log out or change the name later? Long-press the server card to bring up those options.

Tap an authenticated server to launch the MediaBrowser. It is built for speed: a clean file-system style view without thumbnails, so navigating even large libraries feels instant.

The player controls and overlays show:

• Resume indicator — the last saved playback time appears right next to the playtime
• Video format icon — the detected projection and 3D layout are shown at a glance
• Continue Watching — a dedicated folder collects your last played videos

The player remembers your projection and stereo layout choice for each video. Play it once, set it up how you like, and next time it loads right back to those settings. No manual switching.

FinVR parses filenames and folder names to detect the video format automatically. Just include one or more tags in the name and FinVR will recognize them.

Stereo Layout

If the depth looks inverted, cycle the Stereo Layout to the swapped version. No renaming needed just for that.

Projection

Tags work in filenames and folder names alike. Folder tags apply to every file inside.

Each tag just needs to be a recognizable token — no spaces inside the tag itself, but punctuation around it is fine. For example, St. Peter's Basilica - Vatican Tour 360 SBS.mp4 will correctly trigger both 360° and side-by-side detection. Same for folders: a directory named Vatican_Sights_360 applies the 360° tag to every video inside.

Added new videos to your server? No need to open the Jellyfin dashboard. From the home screen of the MediaBrowser, long-press any library folder to bring up the library options sheet. Hit Scan Library and Jellyfin will start indexing that library for new content.

A few things worth knowing:

• The folder icon turns into a spinner while the scan runs, so you always know which library is being indexed.
• A progress bar appears in the sheet as Jellyfin reports completion percentage.
• You can queue multiple libraries — they will scan one after the other. Tap Cancel in the sheet to remove a library from the queue before its turn.
• The refresh button in the toolbar becomes a spinner for the duration of the scan of that library. It does not block navigation — feel free to browse while it runs.
• When the scan finishes, the library list refreshes automatically.

Not sure which file to open? Long-press any video in the MediaBrowser to open a preview sheet. It shows the video's projected thumbnail, format details, file size, resolution, and duration — everything you need to pick the right one.

From the sheet you can also navigate to the previous or next video in the current folder with the arrow buttons, so you can flip through your library without going back to the list.

A few projection-specific notes:

• For 360° and fisheye content, the preview thumbnail is interactive. Drag it to look around and check the framing before you commit to watching.
• For side-by-side content, the preview shows the left eye only, so it looks like a normal image instead of a double-wide distorted one.
• If a video has no thumbnail on the server, the preview area says so.

Short for Field of View, the angle of your virtual screen. On the Cinema mode, FOV makes the screen wider, while Zoom adjusts how far away it feels. Together they let you dial in the perfect view.

In 3D projection modes (Dome, Fisheye, 360° Sphere), Zoom steps aside. It works by moving a flat plane, and once the image wraps around you, that concept doesn't translate. FOV handles everything and creates a zoom-like effect all by itself.

Mind the extremes: set FOV too low and the image sits uncomfortably close, causing double vision. Crank it too high and you will need a giraffe neck to navigate the view. The sweet spot is somewhere in between.

Short for Inter-Pupillary Distance, the gap between your two eyes. IPD is set once in Calibration and then left alone. While watching, use the physical IPD slider on your headset for fine-tuning.

The goal in Calibration: adjust until the on-screen toasts and the corners of the calibration grid are sharp and single-vision. If you see double or feel eye strain, nudge it until everything locks into place.

Short for Directional Pad, the cross-shaped button with Up, Down, Left, and Right. On many controllers the joystick also works as a D-Pad, giving you a second set of directions to assign. In FinVR you can map a different action to each direction, just like any other button.

Side-by-Side (SBS) is a 3D video format where the left-eye and right-eye images sit next to each other in a single video frame. Your headset sends each half to the correct eye, and — just like that — you've got 3D depth. Full Side-by-Side (FSBS) is the high-quality version: instead of squeezing the images to fit, it keeps the full resolution for each eye, so everything looks much sharper.

There's also Top/Bottom, which is the same idea but stacked vertically. It's not as common, but FinVR handles it just fine — including those "swapped" videos where the left and right eye views are flipped.

A Fisheye projection maps the video onto a dome that curves around your head — imagine sitting under a giant glass bowl. Instead of a flat screen, the image is already there when you turn your head.

FinVR supports Fisheye at 180°, 190°, 200°, and 220°. Anything past 220° and the encoding starts to blur at the edges — standard video formats just aren't built for that much warp.

Fisheye is not the same as 360° Sphere. Sphere wraps the full scene around you (all directions, like standing inside a bubble), while Fisheye covers a forward-facing dome at very wide angles. Think of Fisheye as an ultra-wide lens on steroids and Sphere as strapping a 360 camera to your forehead.

Short for High Dynamic Range, a video format with a broader range of brightness and color than standard video. On devices that support it, FinVR Pro decodes HDR10 content in handheld and headset mode, giving you deeper blacks and richer colors.

The HDR icon at the top right of the jellyfish, as well as the playback toggle in the settings, only appear on supported devices. If you see them, your device is good to go. You can usually leave it on. Note that you'll only see a difference with videos that were both shot and encoded in HDR.

That rainbow-colored halo around high-contrast edges? That is Chromatic Aberration, and it has nothing to do with FinVR. It is a physical property of every lens, especially the budget-friendly plastic ones most headsets use. Not a bug, just physics being physics.

FinVR can fix it. Hop into Calibration and use CA Horizontal and CA Vertical to turn the correction up or down. If one side of the image clears up faster than the other, adjust CA Center X and CA Center Y to match your lens geometry.

Not sure if you need it? Look at the edges and corners of the screen, text labels, or grid lines in Calibration. If they look like they were printed by a slightly drunk printer, you have CA.

It started when I was gifted a smartphone VR headset. I soon wanted one thing: space documentaries on a giant virtual screen, served from my Jellyfin library. The store had nothing that quite fit my needs.

So I started building a simple external 2D-VR player for Jellyfin. Soon I discovered that VR on a smartphone was not simple at all. I realized there was a whole VR universe out there. Fancy lenses. Complex projections. Esoteric video formats. Controllers — I bought too many of them.

What started as a small project quickly filled every spare moment for much longer than I anticipated.

I am an experienced developer, but this still tested my patience. I studied and learned a lot while building my ideal player. My standards for software are high, and there were moments I didn't think this would ever get finished.

The goal for FinVR was that it looked good, worked hands-free inside the headset, handled 2D and 3D video properly, and treated Jellyfin as a first-class feature, not an afterthought.

That goal is finally a reality. I can watch my space documentaries now. And so can you.