Getting Started Guide: SPIN Play SDK

XR Lab

SPIN SDK Diagram.jpg

Learn how to build VR apps for streaming 360 video using the Open Projection Format (OPF) with the SPIN Play SDK Getting Started Guide.

 

Requirements

Version 1.2 of the SPIN Play SDK is compatible with Unity 5.5 and later, and video playback is supported on:

  • Windows 10 (both 32/64-bit native and UWP for Windows Mixed Reality) for Oculus Rift, HTC Vive, and Windows MR devices like the Acer and HP HMDs
  • Android 6.0 “Marshmallow” and later for Gear VR, Daydream, and Cardboard

Playback should work with other Unity-supported HMDs with little-to-no modification. Future versions of this SDK will add support for additional platforms and devices.

 

Prerequisites

If you’re building for Android, make sure that you’ve set up and configured Unity for Android development. If you’re using the Samsung Gear VR for testing, also be sure to login to your Oculus developer account, and use the OSIG Generator to create a signature file for your device.

For Windows Mixed Reality, make sure that you’re running the Windows 10 Creators Update (version 1703) or later and have installed version 10.0.15063.0 or later of the Windows 10 SDK.

 

First Project

Let’s create a custom player that streams Open Projection Format video to a VR head mounted display.

First, start Unity and click New to create a new project. Give the project a name, like MyProject, then click the Create Project button.

SPIN Play SDK 02.png

 

Player Configuration

While not specific to the SPIN Play SDK, each platform in Unity requires its own unique configuration. Follow the steps below for your target platform.

Windows Native

For Windows 32/64-bit native development targeting an Oculus Rift or HTC Vive, pull down the File menu and select Build Settings... Confirm that PC, Mac & Linux Standalone is selected (there should be a small Unity icon to the right of the text). If it isn’t, select the entry, then click the Switch Platform button. Verify that the Target Platform is set to Windows, then close the Build Settings window.

Universal Windows Platform

Windows Mixed Reality requires a Universal Windows Platform app, also known as UWP. To configure the project to build a UWP app, pull down the File menu and select Build Settings... Choose Windows Store, then click the Switch Platform button.

Make sure that the SDK is set to Universal 10, and switch the Target device to PC. You can check to see if you’re using the correct version of the UWP SDK by clicking the UWP SDK dropdown. Confirm that version 10.0.15063.0 or later is listed.

To stream video from the internet, we need to add a capability to our app. Click the Player Settings... button, then, in the Inspector, expand the Publishing Settings section. Find InternetClient in the list of Capabilities, and click to select it. Close the Build Settings window.

Android

To configure the project to build an Android app, pull down the File menu and select Build Settings... Choose Android, then click the Switch Platform button.

To view the project in VR, we need to add a VR SDK. Click the Player Settings... button, then, in the Inspector, check the Virtual Reality Supported checkbox. Next, click the + button, and add at least one SDK to the list.

To build and deploy an Android project, Unity requires a unique Package Name. Find Package Name under the Identification heading, and change it to something like com.pixvana.myproject. Close the Build Settings window.

Import the SDK

Before you can use the SPIN Play SDK, it needs to be imported into your project. To import the SDK, select Import Package, then Custom Package… from the Unity Assets menu.

SPIN Play SDK 03.png

From the Import Package… window, navigate to the folder that contains the SPINPlaySDK.unitypackage file. Select the file, then click Open.

SPIN Play SDK 04.png

Unity will display a window that lists the files that are contained in the SDK. Click the Import button to import all of the files into your project.

SPIN Play SDK 05.png

After Unity has imported all of the files, the SPIN Play SDK Settings window appears. This window makes it easy to configure your project to support 360° video using a head mounted display. To accept the recommended settings, click the Accept All button.

SPIN Play SDK 06.png

A window should confirm that all settings have been applied. Click OK to continue.

The SPIN Play SDK uses two Unity layers to support stereo playback. To create the layers, choose Edit Layers… from the Layers dropdown menu.

SPIN Play SDK 08.png

Click the small triangle to expand the Layers section, then add two new User Layers in any of the available slots. Name the first layer Left and the second layer Right.

SPIN Play SDK 08.png

To play streaming OPF video, the SPIN Play SDK requires the coordination of four components:

  • A CameraRig component controls two cameras for monoscopic and stereoscopic playback.
  • An Hmd component provides an abstract way to interact with head mounted displays. It reports information like current head orientation and position.
  • A Player component understands how to stream standard MP4 and MPEG-DASH media and render video frames to a Unity texture.
  • A Projector component parses OPF files and coordinates with the CameraRig, Hmd, and Player to set up and orient projection geometry.

To add all four of these components to a scene, right-click somewhere in Unity’s Hierarchy window, select SPIN Play SDK from the pop-up menu, then Projector.

SPIN Play SDK 10.png

Click the Projector in the Hierarchy window to select it, then in the Inspector, enter the following address into the projector’s Source Url field:

http://media.pixvana.com/tests/opf/frustum01/index.opf

SPIN Play SDK 11.png

To play video content from SPIN Studio, open the Experiences tab in SPIN Studio, select the target media, and copy the OPF URL. Next, enter the OPF URL into the projector’s Source Url field in your Unity project. To learn more about setting up a free SPIN Studio account, refer to Getting Started with SPIN Studio.

Export_SDK.png

If you’re targeting Windows native or UWP, press the Play button above the Scene window to start your project. After a few moments, you should see streaming OPF video playing within the Unity editor. You can also watch the video in your HMD.

If you’re targeting Android, there is no current support for running in the Unity editor. Pull down the File menu, select Build & Run, then click the Build And Run button. Enter a file name like MyProject, then select Save to view the project on your device.

Player Controls

Now that we know how to stream video, let’s add some player controls. The SPIN Play SDK comes with an example ControlsCanvas prefab that makes it easy to add pause, play, seek, and timeline functionality to your project.

First, click the small triangle to the left of the SPINPlaySDK folder in the Unity Project window to expand its contents. Then, select the Prefabs folder.

SPIN Play SDK 14.png

To add the prefab to the scene, click and drag the ControlsCanvas prefab (looks like a blue cube) to the Hierarchy window, then let go.

SPIN Play SDK 15.png

Now that we’ve added the prefab to our scene, we need to let the PlayerControls know which Player it should control. Click the triangle to the left of the ControlsCanvas to expand it. Do the same thing with the ControlsPanel. Finally, select the PlayerControls.

To assign the Player, click the small dot to the right of the Player setting in the Inspector to show the Select PlayerBase pop-up window. Double-click the Projector entry to connect it to the Player component that is part of our Projector.

SPIN Play SDK 16.png


Windows

For Windows native or UWP, press the Play button in the Unity editor to start the project. You should see a translucent user interface control on top of the video that includes a play/pause button along with a timeline. Use the following keys on your keyboard to control playback:

  • Press the spacebar to pause or play the video.
  • Press the right arrow key to seek forward 10 seconds.
  • Press the left arrow key to seek backward 10 seconds.
  • Press the Esc key to exit (note that this will not work when running in the editor).

The player controls will automatically fade out after five seconds of inactivity. Simply press one of the control keys to show it again.

SPIN Play SDK 17.png


Android

For Android only, we need to import either the Oculus Utilities for Unity (Gear VR) or the Google VR SDK for Unity (Daydream or Cardboard) to add support for touchpads and controllers. After downloading the appropriate SDK, pull down the Assets menu, select Import Package, then Custom Package. Navigate to the folder that contains the downloaded SDK, select the file, then click Open. Click the Import button to add all of the files to the project.

Now, we need to let the SPIN Play SDK know that we’ve added third-party support. To do that, expand the Scripts folder in the Project window, select the Extras folder, then double-click the ControllerManager.cs script to open it in your editor.

At the top of the file, uncomment the #define for the correct third-party SDK. Choose File, then Save to save the change.

Next, we need to add the ControllerManager to our Unity scene. Return to Unity, and drag the ControllerManager.cs script from the Project window to the ControlsCanvas in the Hierarchy window, then let go.

Finally, pull down the File menu, and select Build & Run to test the project on your device. You should see a translucent user interface control on top of the video that includes a play/pause button along with a timeline.

  • Tap the Gear VR touchpad or press the center of the Daydream touchpad to pause or play the video.
  • Swipe forward on the Gear VR touchpad or press the right side of the Daydream touchpad to seek forward 10 seconds.
  • Swipe backward on the Gear VR touchpad or press the left side of the Daydream touchpad to seek backward 10 seconds.

The player controls will automatically fade out after five seconds of inactivity. Touch anywhere on the touchpad or Daydream controller to show them again.

 

Next Steps

The SPIN Play SDK contains two example scenes that illustrate basic streaming functionality. The example scenes can be found in the Scenes subfolder.

  • Example1 demonstrates a player based on the prior tutorial. Change the Projector’s Source Url property to play a different OPF stream.
  • Example2 demonstrates a programmatic approach to playing OPF streams. Look at the Example2.cs script in the Scripts/Examples folder for details.

Be sure to reference the full SPIN Play SDK class documentation for more information on all available classes, properties, and methods.

XR Lab