Create an Android Cardboard 360 Video Viewer

Augmented and virtual reality, while still relatively new, have quickly become popular for apps, including for gaming and education. Previously, I showed you how to install Cardboard using the Android SDK and how to create a panoramic image viewer. This post will show you how to use 360-degree video in your apps.

Image of beach scene with Google Cardboard


Before you start building your video viewer app, you will need to clone the Cardboard Android SDK onto your computer via Git. You can find instructions for this in the previous article of this series.

For our sample, create a new Android project with a minimum SDK of API 19 (KitKat) and use the Empty Activity template.

Once your base project is created, you will need to copy the common, commonwidget and videowidget folders from the Cardboard SDK to the root of your project. Once those directories are moved over, you will need to include them as modules in your project by editing your settings.gradle file to look like the following snippet. 

Finally, include these and other required libraries in your project by adding the following lines to your app module's build.gradle file under the dependencies node.

You'll notice that we added the Protocol Buffers library from Google, which helps manage runtime resources on the device, and ExoPlayer, which is a Google-created video player library that the VrVideoView component is built on. Both of these libraries are required by the Cardboard SDK in order to function, and you may have noticed that the ExoPlayer version used is from the first release, not the second, so may cause conflicts if you use ExoPlayer v2 in your own projects.

Next, we'll want to update our activity_main.xml file for our sample project to include a VrVideoView, a SeekBar, and a Button that we will work with later.

Once you're done setting up the Cardboard libraries and have created the layout that we will use, it's time to jump into the Java code.

Working With Cardboard and VR Video

Before we can start writing all of the code that controls playback state, position, and loading in your 360 video file, we will need to determine the source of our video. For this tutorial we will simply create an assets folder under the main directory, and place a 360 video there. While there are a few sources for 360 videos online, I have included a short public domain video from Sea World returning a sea turtle to the ocean in the accompanying GitHub project for this tutorial. 

Initializing and Structure

Now that you have a video file to play, open up your MainActivity class.

You will first need to declare and initialize the View items that are defined by the layout file, as well as two boolean values to keep track of muted and play/pause state. In addition, we will place an OnClickListener on our volume Button object.

Next, create a new inner class that extends VrVideoEventListener. This class will have five methods that we can implement for our simple video viewer.

You will also need to implement SeekBar.OnSeekBarChangeListener in your class and create the method stubs for that interface.

Once you have created this new inner class and SeekBar implementation, associate them with your VrVideoView and SeekBar, respectively, at the end of the initViews() method that was defined above.

There's one more piece of setup that needs to be taken care of. You will need to handle the Android activity lifecycle by supporting the onPause(), onResume() and onDestroy() methods to pause or resume rendering in the VrVideoView, or to completely shut it down. You will also need to keep track of the pause state in these methods.

Now that the initial setup of our tutorial class is completed, we can move on to the more interesting topic: loading a video, controlling playback, and customizing the user experience.

Starting and Controlling VrVideoView

Because loading a 360 video can take anywhere from a fraction of a second to several seconds, you will want to handle loading your video through a background task. Let's start by creating a new AsyncTask that will create a new VrVideoView.Options object, set the input type to match our video's formatting (in the case of this tutorial, TYPE_MONO), and then load our video from the assets directory.

Next, go into your onCreate() method and create a new instance of this task, and then call execute() to start it. While there's some more that should be done to properly maintain this task, we'll just use it locally in this method for simplicity and not worry about AsyncTask lifecycle considerations.

At this point, you should be able to run your application and watch the 360 video play in the Cardboard video view. Now that that's working, let's add in some utility for our user. Return to the ActivityEventListener object that you created earlier in this tutorial, as we will want to flesh out some of the methods. When the video has successfully loaded, we need to set the max value for our SeekBar, as well as keep track of the play/pause state of our video.

As the video plays, we will update that SeekBar through onNewFrame(), and reset the video to the initial position in onCompletion(). Lastly, in onClick(), we will trigger our play/pause toggle method.

While updating our SeekBar based on playback is important, we will also want to allow the user to change where they are in the video by interacting with the SeekBar. We can do this using the SeekBar.OnSeekBarChangeListener interface that we implemented earlier.

To round off our VrVideoView controls, we will need to implement the play/pause and volume toggle methods.

At this point, you should have a fully working and interactive 360 video player working in your app. 

360 video player shown in app

However, if you rotate your device, you may notice the unwanted behavior of the video completely restarting. We can fix this by working with Android's onSaveInstanceState() and onRestoreInstanceState() to save and reset the state of our VrVideoView.

Now, when the device is rotated, your video should return to its original position and your user can continue with their uninterrupted experience.


While there are a few small details that need to be handled to use the Cardboard SDK's VrVideoView, the difficult parts, such as actual playback and optimization, are handled for you by a component that's easy to implement. 

You should now be able to add 360 videos to your media apps, providing your users with an interesting feature that enriches their experience. In the next tutorial of this series, we will focus on Google's new VR experience called Daydream, and how to use the paired controller with your apps.

In the meantime, check out some of our other tutorials on Android virtual reality and augmented reality!



Related Articles