This is the first alpha release of unwarpvr, a command-line ffmpeg-based video filter that reverses the distortion and chromatic abberation introduced by the Oculus Rift software to compensate for lens distortion. This allows you to record videos during normal play (see recording instructions), then unwarp them for the purpose of viewing on your monitor or sharing online:

You do not need to install anything else beforehand, just click on the GREEN BUTTON at the bottom of this page. This release supports only videos generated by applications compiled with the latest Oculus SDK version 0.4.2 (although you can try it on other videos if you wish).

Sample command lines

Basic example

Cropped side-by-side view, no scaling:

ffmpeg-unwarpvr -i in.mp4 -vf unwarpvr=1920:1080 -c:a copy -c:v libx264 -crf 18 -pix_fmt yuv420p out.mp4

• -i in.mp4 : specifies the input file
• -vf unwarpvr : applies the unwarpvr video filter
• 1920:1080 : the desired output resolution
• -c:a copy : use the "copy" audio codec which preserves the original audio stream
• -c:v libx264 : use the H.264 video encoder (same codec used by YouTube)
• -crf 18 : video encoding quality (smaller numbers = higher quality, bigger file)
• -pix_fmt yuv420p : saves file size and ensures compatibilty with some video editors like Adobe Premiere Pro
• out.mp4 : output filename

If you receive an error that your Oculus user profile can't be found/parsed, or you changed your eye relief dial setting since recording, you must manually specify your original eye relief dial setting at time of recording (0-10, 10 is farthest out):

ffmpeg-unwarpvr -i in.mp4 -vf unwarpvr=1920:1080:eye_relief_dial=3 -c:a copy -c:v libx264 -crf 18 -pix_fmt yuv420p out.mp4

Testing on samples

If you want to test your settings by rendering just the first frame of your video, do this:

ffmpeg-unwarpvr -i in.mp4 -vf unwarpvr=1920:1080 -ss 0 -vframes 1 -f image2 out.png

You can also test on the first few seconds of your video using "-t":

ffmpeg-unwarpvr -i in.mp4 -vf unwarpvr=1920:1080 -t 10 -c:a copy -c:v libx264 -crf 18 -pix_fmt yuv420p out.mp4

Other examples

Left/right eyes swapped for cross-eyed viewing:

ffmpeg-unwarpvr -i in.mp4 -vf unwarpvr=1920:1080:swap_eyes=1 -c:a copy -c:v libx264 -crf 18 -pix_fmt yuv420p out.mp4

Height stretched by a factor of 2 for full compatibility with YouTube 3D mode (see how to upload with YouTube 3D enabled) and some 3D video players:

ffmpeg-unwarpvr -i in.mp4 -vf unwarpvr=1920:1080:scale_height=2 -c:a copy -c:v libx264 -crf 18 -pix_fmt yuv420p out.mp4

To get the full uncropped original render targets including fuzzy borders, use the render target resolution (2364x1461 for default Unity apps, adjusted slightly to make the height even):

ffmpeg-unwarpvr -i in.mp4 -vf unwarpvr=2364:1462 -c:a copy -c:v libx264 -crf 18 -pix_fmt yuv420p out.mp4

To render a 720p mono view (there's no point going to 1080p with a standard DK2 video), use this:

ffmpeg-unwarpvr -i in.mp4 -vf unwarpvr=1280:720:left_eye_only=1:scale_width=1.2:scale_height=1.2 -c:a copy -c:v libx264 -crf 18 -pix_fmt yuv420p out.mp4

If you want a bit more field of view in your cropped view, you can shrink by a little bit (the left/right edges will be slightly darkened by the fuzzy borders):

ffmpeg-unwarpvr -i in.mp4 -vf unwarpvr=1920:1080:scale_width=0.9:scale_height=0.9 -c:a copy -c:v libx264 -crf 18 -pix_fmt yuv420p out.mp4

Downscaling and antialiasing

If you want a reduced-resolution version, which will render faster and be smaller and quicker to upload, just lower the resolution and proportionally lower the scale parameters (e.g. 1280/1920 = 0.6667):

ffmpeg-unwarpvr -i in.mp4 -vf unwarpvr=1280:720:scale_width=0.6667:scale_height=0.6667 -c:a copy -c:v libx264 -crf 18 -pix_fmt yuv420p out.mp4
ffmpeg-unwarpvr -i in.mp4 -vf unwarpvr=854:480:scale_width=0.4448:scale_height=0.4444 -c:a copy -c:v libx264 -crf 18 -pix_fmt yuv420p out.mp4

To add antialiasing, conversely, you can increase the output resolution and proportionally increase the scaling factors (e.g. both by a factor of 2), then add a scale filter to lower the resolution afterwards:

ffmpeg-unwarpvr -i in.mp4 -sws_flags lanczos+accurate_rnd+full_chroma_int -vf "unwarpvr=3840:2160:scale_width=2.0:scale_height=2.0 , scale=1920:1080" -c:a copy -c:v libx264 -crf 18 -pix_fmt yuv420p out.mp4

The sws_flags options improve the quality of downscaling.

Options

• Output resolution: You must always specify output resolution. If the output resolution is smaller than the render target (2364x1461 for Unity apps), the center of each eye view will be cropped out. If the output resolution is larger than the render target, each eye view will be centered against a black background.
• left_eye_only=1: Renders only left eye. (preserves aspect ratio, does not stretch single eye view)
• swap_eyes=1: Swaps left/right eye views, or if left_eye_only is given, does right eye only instead.
• scale_width: Scales width of output so it no longer matches original render target resolution (1.0 for no scaling, < 1.0 to shrink, > 1.0 to stretch).
• scale_height: Scales height of output so it no longer matches original render target resolution.
• eye_relief_dial: Setting of eye relief dial at time of recording (0-10, 10 is farthest out). By default this will be set from the current setting of your locally installed Oculus Runtime default user.

Technical/performance notes

Build: This release is a custom build of the ffmpeg command-line video editing tool based on the latest master version of ffmpeg, but with the new filter added. It is a static Windows binary.

Eye relief effect: Eye relief only affects chromatic abberation, not distortion, with the Oculus SDK 0.4.2. Even then the effect is minor and hard to see.

Why yuv420p? By default the filter outputs in yuv444p format. The yuv420p pixel format option is needed for Premiere Pro compatibility but not for YouTube - however it does improve filesize and YouTube uses this pixel format anyway, so there's no reason not to always use it.

Performance: The current implementation is CPU-based (multithreaded over frames), and its performance is directly based on the number of pixels being rendered in the output. So 720p renderings will be faster, while 1080p are slower, and full render target renderings slower still than that. On my machine (Intel Core i7 4770K, overclocked to 4.0 GHz) 1080p videos render at about 27 frames per second (FPS), close to real-time. Others report rates closer to 10 FPS. A GPU-based OpenCL implementation to dramatically improve performance is planned.