Contents

1 Getting started ......................................................................................................................4

1.1 Installing the SDK ..................................................................................................................4

1.2 SDK folder structure .............................................................................................................4

1.3 Install 3rd party HMD SDKs ..................................................................................................5

1.3.1 Oculus Rift: .............................................................................................................................5

1.3.2 HTC Vive: ................................................................................................................................5

1.3.3 GearVR: ...................................................................................................................................5

1.3.4 Daydream (GVR) on Android: ...............................................................................................5

2 Development requirements ................................................................................................6

2.1 For Android: ...........................................................................................................................6

2.1.1 Build Android sample applications: ....................................................................................6

2.2 For Windows: ..........................................................................................................................6

2.2.1 Build Windows sample applications: ...................................................................................6

2.3 For iOS: ...................................................................................................................................6

2.3.1 Build iOS sample applications: ............................................................................................6

3 Supported video and audio formats ..................................................................................7

3.1 Video: ......................................................................................................................................7

3.2 Audio: ......................................................................................................................................7

3.3 Streaming: ..............................................................................................................................7

3.3.1 Videos with a single video track: .........................................................................................7

3.3.2 Videos with two video tracks (not valid for streaming) ...................................................8

4 Recommended devices ........................................................................................................8

4.1 Android: ..................................................................................................................................8

4.2 PC: ...........................................................................................................................................8

4.3 iOS: ..........................................................................................................................................9

5 Using the SDK ........................................................................................................................9

6 Creating an SDK instance .....................................................................................................9

7 Analytics .................................................................................................................................10

4/20/2017 2017 Nokia

2 / 17
8 Setting up the audio .............................................................................................................10

9 Setting up video rendering ..................................................................................................11

10 Starting and controlling playback .......................................................................................12

11 Rendering the video and audio ...........................................................................................13

12 SDK shutdown .......................................................................................................................14

13 OZO Player App .....................................................................................................................14

13.1 OZO Player App Build Instructions .....................................................................................15

14 OZO Player App Use & Customization ...............................................................................15

15 Creating a custom HMD device implementation ..............................................................16

16 Nokia license agreement ......................................................................................................17

4/20/2017 2017 Nokia

3 / 17
1 Getting started
The OZO Player SDK enables 3D 360 video and audio content playback across all major platforms,
allowing you to focus on creating unrivaled VR content. It is a true multi-platform C++ SDK
enabling creation of applications for playback of stereoscopic and monoscopic 360 video with
true 3D audio, with or without a head-mounted display (HMD).

This document details the software and hardware requirements, installation procedure and
provides a basic overview on how to use the SDK to develop your applications. For more details,
please take a look at the different example applications provided.

1.1 Installing the SDK

Installers are provided for Windows and Mac.

On Windows the default install location for the SDK is:

C:\Nokia\OZOPlayerSDK

On Mac the default location is:

Applications/Nokia/OZOPlayerSDK/

1.2 SDK folder structure

The SDK directory structure contains four directories on the highest level:

3rdParty: Contains the placeholder folders for 3rd party HMD SDKs.
Documentation: Contains the official SDK documentation.
OZOPlayerApp: Contains the OZO Player Application.
Samples: Contains basic samples on how to use the SDK with different platforms
SDK: Contains the OZO Player SDK headers and libraries, HMD implementations and a
small cross platform application framework used by the OZO Player Application.

If you're integrating the SDK to an existing application, then it's easiest to start from the simple
example applications located in the Samples folder. Those contain only the very basic things you
need to do in order to use the SDK but still demonstrate the regular flow very well.

If you want a more complete example of an application using the SDK, then you should take a look
at the OZO Player App, which includes also an user interface for browsing and selecting video
experiences as well as basic control user interfaces.

4/20/2017 2017 Nokia

4 / 17
1.3 Install 3rd party HMD SDKs

If you want to use an HMD device with the samples or the reference player, you need to download
the HMD SDKs from the vendor websites. After downloading them, you should extract the zip files
into the correct folders. Currently the OZO Player SDK has example implementation for Oculus
Rift, GearVR, Google DayDream/GVR and HTC Vive / OpenVR. The SDK has been tested with the
HMD SDKs versions visible in the folder paths.

1.3.1 Oculus Rift:

3rdParty/ovr_sdk_win_1.11.0_public

After extracting the zip, you should run the fix_oculus.bat which will rebuild the Oculus SDK
static library to fix a runtime issue with the latest Oculus SDK release

1.3.2 HTC Vive:

3rdParty/openvr-1.0.6

1.3.3 GearVR:

3rdParty/ovr_sdk_mobile_1.5.0

1.3.4 Daydream (GVR) on Android:

3rdParty/gvr-android-sdk-1.40.0

To install the GVR SDK for iOS, you need to have CocoaPods installed and then run the command
"pod install --verbose" in the build folder for the project that you want to build.

For the iOS sample the folder is:

Samples/VideoPlayback/IOS/GVR/

And the for the iOS version of the OZO Player App the folder is:

OZOPlayerApp/Build/IOS/GVR/

4/20/2017 2017 Nokia

5 / 17
2 Development requirements
2.1 For Android:

Android Studio 2.1 or newer, https://developer.android.com/studio/index.html

Android SDK 5.1.1 or newer
Android NDK 11c or newer

2.1.1 Build Android sample applications:

(instructions for OZOPlayerApp for Android are later in this document)

1. The Android sample apps are located under: Samples/VideoPlayback/Android

2. If you are building the GearVR sample, you need to place your oculus signatures in the
folder GearVR/assets/
3. And if you have copied the HMD SDKs as instructed above, open the project in Android
Studio and build.

2.2 For Windows:

Visual Studio 2013 or 2015

Oculus Rift SDK and runtime if developing for Oculus Rift
HTC Vive SDK and runtime if developing for HTC Vive

2.2.1 Build Windows sample applications:

(instructions for OZOPlayerApp for Windows are later in this document)

1. The Windows sample apps are located under Samples/VideoPlayback/Windows

2. If you have installed the HMD SDKS as instructed above, open the project in Visual Studio
and build

2.3 For iOS:

XCode 7.3 or newer

iOS SDK 9.3 or newer
CocoaPods, https://cocoapods.org/

2.3.1 Build iOS sample applications:

(instructions for OZOPlayerApp for iOS are later in this document)

4/20/2017 2017 Nokia

6 / 17
 1. Go to the Sample project folder using Terminal (Samples/VideoPlayback/IOS/GVR/)
2. Run "pod install --verbose" to download GVR SDK CocoaPods
If you do not have Cocoapods installed, see https://cocoapods.org/
3. Open VideoPlayback workspace and build application normally

3 Supported video and audio formats

3.1 Video:

H.264 / AVC up to a single UHD stream on mobile, 2 x UHD on Windows. Windows and
Android also have preliminary support for single stream H.265 / HEVC streams.

3.2 Audio:

AAC-LC in 1.0, 2.0, 4.0, 5.0, 5.1, 7.0, and 8.0 channel configurations at 48kHz
Further, advanced 3D spatial OZO Audio format is also supported. It is the audio
technology included in MP4VR clips created by OZO Creator.
First order Ambisonics are supported in the format they are exported from OZO Creator.

3.3 Streaming:

MPEG-DASH Live profile (urn:mpeg:dash:profile:isoff-live:2011). Other MPEG-DASH profiles

are partly supported when using SegmentTemplate and/or SegmentTimeline.
HLS (HTTP Live Streaming): H.264 & AAC packaged in MPEG-2 TS, preliminary support for
fMP4

Videos should follow these conventions on naming and used projections:

3.3.1 Videos with a single video track:

*_TB.* for top-bottom stereoscopic with left eye content on top and right eye content
on bottom
*_BT.* for top-bottom stereoscopic with right eye content on top and left eye content
on bottom
*_LR.* for left-right stereoscopic
*_RL.* for right-left stereoscopic
*_M.* for monoscopic
"*_ID.*" for regular 2D non-360 video

4/20/2017 2017 Nokia

7 / 17
3.3.2 Videos with two video tracks (not valid for streaming)

*_2LR.* for videos with the left eye as the first track and right eye as the second
*_2RL.* for videos with the right eye as the first track and left eye as the second

For offline files the name should be at the end of the filename before the filename extension, i.e.
example_file_TB.mp4

For streams it should be in the MPD filename, e.g.

http://192.168.0.0/dash/stream_TB.mpd or if the used server allows it, given as a
parameter using ?, e.g. http://192.168.0.0/dash/stream.mpd?_TB. . Please note that
giving it as a parameter might have some unwanted effects on the server side.

Videos which dont follow the convention are assumed to be monoscopic equirectangular
panoramas.

4 Recommended devices
Criteria for recommendation is the ability to playback a single UHD streams at 30 frames per
second either from a local file or from a DASH stream without performance issues. The SDK is
compatible with lower end as well but the highest quality experiences may not function smoothly
or heat the device quite fast.

4.1 Android:

Verified to work on:

Galaxy S7
Galaxy S7 Edge
Pixel & Pixel XL

Devices with Android 5.1.1 or newer and hardware equivalent or greater of the Galaxy S7 should
also work.

For phones with lower performance, the video files should be scaled down to match the hardware
specification. Also with adaptive bitrate streaming, the SDK may block certain resolutions on
certain devices.

4.2 PC:

Windows 10
GTX 970 / R9 290 equivalent or greater
Intel i5-4590 equivalent or greater

4/20/2017 2017 Nokia

8 / 17
 8GB+ RAM

4.3 iOS:

iPhone 6S or newer with iOS 9.3

Older devices may work with reduced performance

5 Using the SDK

The main steps in using the SDK are:

1. Creating the SDK instance

2. Setting up the audio playback
3. Setting up the rendering
4. Starting and controlling the playback
5. Rendering the video and audio with the correct orientation
6. SDK shutdown and releasing of resources

More detailed API descriptions are in the API reference document.

If you're integrating the SDK to an existing app, then the best examples are the simple sample
apps located in the Samples folder since those contain only the very basic things you need to do
in order to use the SDK.

If you want a more complete example of an application using the SDK, then you should take a look
at the OZO Player App.

6 Creating an SDK instance

An SDK instance is created by calling the create method of the IOZOPlayer class.

OZO::PlatformParameters platformParameters;

// Fill the plaftorm parameters with platform specific information

OZO::AnalyticsParameters analyticsParameters;

analyticsParameters.licenseID = "ENTER_YOUR_LICENCE_ID_HERE"

OZO::IOZOPlayer* ozoPlayer = OZO::IOZOPlayer::create(graphicsAPI,

&platformParameters, &analyticsParameters);

4/20/2017 2017 Nokia

9 / 17
To create the instance, you need to specify which graphics API should be used by the SDK.
Currently OpenGL, OpenGL ES and DX11 are supported. You also need to provide a struct with
platform specific initialization information, such as default storage location of videos. Further, you
need to specify parameters for analytics for details see next section.

Creating the SDK instance also creates the interfaces for controlling audio (IAudio), rendering
(IRenderer) and playblack (IPlaybackControls).

7 Analytics
When creating SDK instance, you also need to specify parameters for analytics
(AnalyticsParameters).

The struct contains two parameters: a flag to enable/disable analytics and licenseID string.

The licenseID string is mandatory. If you're using the Free version of the SDK, the licenseID
should be the package ID of the application (in the form: com.companyname.applicationname). It
should be the same package ID / bundle ID than the application has for Android or iOS,
respectively. For Windows the same pattern should be followed.

If you are using the paid version of the SDK, then use the licenseID provided by Nokia.

Analytics are enabled by default. It depends on the license type if the flag to disable it is functional
and hence if the application can disable analytics.

Analytics is used to improve user experience of OZO Player SDK. It requires that your application is
able to access Internet, and hence may require to specify platform specific permission / capability.

Nokia does not collect any personally identifiable data, and all privacy aspects described in the
license agreement apply.

8 Setting up the audio

The SDK provides two options for audio playback:

The first option is direct routing where the SDK itself handles audio playback all the way from the
file to the speakers. With direct routing you can allow exclusive mode which will allow the
application to run the audio playback at a better latency. However it will mean that other apps
can't access the audio hardware.

bool_t allowExclusiveModeInAudio = false;

4/20/2017 2017 Nokia

10 / 17
 OZO::Result::Enum result = ozoPlayer->getAudio()-
>initializeAudioWithDirectRouting(allowExclusiveModeInAudio);

The second option is custom routing where the user of the SDK implements the last step of the
audio playback. In this case the user must implement the AudioObserver interface to receive the
PCM audio buffers from the SDK. This requires you to also implement other related functionality,
e.g. responding to elapsed time queries to maintain AV-sync.

Our recommendation is to use direct routing unless you need for one reason or another access
the audio output yourself.

If you need to implement a custom audio routing solution, please contact our support for further
instruction.

9 Setting up video rendering

For rendering, you can either use the HMD device implementations provided by the SDK or create
your own.

If you use the implementations provided by the SDK, you just need to create an instance of the
HMD you wish to use and initialize it. The HMD implementation will create all the render targets
internally.

If you dont use the SDKs implementations, you need to setup the eye surfaces for the renderer.
The eye surface contains the render target with the render target handle and size information,
the eye position which is used to decide whether left or right eye content is rendered, and the
projection for the view. The render target handle should be created by calling the

createNativeRenderTarget method of IOZOPlayer.

uint32_t viewPortWidth; // Fill this with your viewport width

uint32_t viewPortHeight; // Fill this with your viewport height

GLuint color; // Set this to your render target GL texture

RenderTextureDesc colorTextureDesc;

colorTextureDesc.format = RenderTextureFormat::R8G8B8A8;

colorTextureDesc.width = width;

colorTextureDesc.height = height;

colorTextureDesc.ptr = &color;

4/20/2017 2017 Nokia

11 / 17
 OZO::RenderSurface surface;

OZO::Matrix44 projectionMatrix; // Fill this with your projection

OZO::Matrix44 eyeTranslation; // Fill this with your eye translation

surface->handle = ozoPlayer()->getRenderer()-
>createRenderTarget(&colorTextureDesc, NULL);

surface->viewport.x = 0;

surface->viewport.y = 0;

surface->viewport.width = width;

surface->viewport.height = height;

surface->eyePosition = OZO::EyePosition::LEFT;

surface->projection = projectionMatrix;

surface->eyeTransform = eyeTranslation

We have provided HMD implementations for the following devices:

HTC Vive and Oculus Rift on Windows

GearVR and DayDream / Google VR on Android
Google VR on iOS

10 Starting and controlling playback

The interface IPlaybackControls contains the controls for loading a new video, either a local
file or a compatible DASH or HLS stream, controlling the playback and also getting duration
information about the loaded video.

The state of the video playback can be fetched using the getPlaybackState method

OZO::IPlaybackControls *playbackControls = ozoPlayer-

>getPlaybackControls();

OZO::VideoPlaybackState::Enum state = playbackControl-

>getVideoPlaybackState();

4/20/2017 2017 Nokia

12 / 17
Calling loadVideo loads the video file but doesnt start playback.

State changes for loadVideo:

IDLE -> (sync) LOADING -> (async) PAUSED/STREAM_ERROR/CONNECTION_ERROR

playbackControl->loadVideo("storage://some_video.mp4");

Calling play starts/resumes the video playback and the playback can be paused or seeked with
pause and seek. Play and pause are synchronous. Calling play directly after loadVideo will
block the calling thread until the video is loaded.

State changes for play:

LOADING/PAUSED -> (sync) BUFFERING/PLAYING
State changes for pause:
PLAYING/BUFFERING -> (sync) PAUSED

playbackControl->play();

playbackControl->pause();

Calling stop will stop the playback and release resources associated with the loaded video. Hence
a new LoadVideo call is needed to play the same file again.

State changes for stop:

ANY STATE -> (sync) IDLE

playbackControl->stop();

11 Rendering the video and audio

During playback the video can be rendered to the eye surfaces using the methods in the
IRenderer interface.

At this point you should call the IAudio method for updating the head transformation to ensure
that video and audio are directionally in sync.

OZO::IHMDDevice* hmd;

OZO::HeadTransform headTransform = hmd->getHeadTransform();

ozoPlayer->getAudio()->setHeadTransform(headTransform);

To render the video frames, you should call renderSurfaces with the current HeadTransform
and all the RenderSurfaces you want to update. To ensure that all the surfaces are

4/20/2017 2017 Nokia

13 / 17
timesynched, call this only once per rendering cycle so that all the surfaces are listed in a single
call.

uint8_t eyeCount = hmd->getEyeCount();

uint8_t surfaceCount = hmd->getRenderSurfaceCount();

uint8_t numRenderSurfaces = eyeCount * surfaceCount;

ozoPlayer->getRenderer()->renderSurfaces(headTransform, hmd-
>getRenderSurfaces(), numRenderSurfaces);

The output of the renderer is an equirectangular image which should be used as an input for the
HMD reverse distortion rendering.

When rendering without an HMD, you can render the renderer output directly on screen and it
should look correct. The SDK provides a default renderer HMDDevice implementation for each
platform which can be used to draw directly on screen without an HMD.

If youre using the HMD implementations provided by the SDK, call the submit method of the HMD
to render the eye buffers on the device.

12 SDK shutdown
To shutdown the SDK, destroy the IOZOPlayer instance by calling the destroy method of
IOZOPlayer. Do not try to destroy any of the SDK interfaces by calling delete directly as this will
most likely result in a crash. The HMD device implementations can be deleted normally.

OZO::IOZOPlayer::destroy(ozoPlayer);

13 OZO Player App

The SDK comes with a cross platform application which uses the SDK to provide basic playback
functionality for both offline and streaming videos as well as a user interface running inside HMD
for selecting and controlling the playback. The UI includes a virtual space where thumbnails for
available videos are drawn. You may customize the app for your own needs either by just quickly
changing the graphics or by doing larger modifications.

4/20/2017 2017 Nokia

14 / 17
13.1 OZO Player App Build Instructions

If you want to build the app using an HMD, you need to first follow the steps in the "Install 3rd
party HMD SDKs" chapter of this document.

After copying the correct SDKs, you will find project files for each of the platforms under
OZOPlayerApp/Build.

If you're building the app for GearVR, you can copy your oculus signature files under
OZOPlayerApp/Assets.

If you're using GVR on iOS, you need to install the GVR SDK using CocoaPods

1. 1.) Go to the project folder using Terminal (OZOPlayerApp/Build/IOS/GVR/)

2. 2.) Run "pod install --verbose" to download GVR SDK CocoaPods
If you do not have Cocoapods installed, see https://cocoapods.org/
3. 3.) Open the generated XCode workspace

14 OZO Player App Use & Customization

The app will list all the video files from the provided target folder.

The default target folders are:

Android: apps private folder.

iOS: the assets folder
Windows:
- If you are using the release build of the app outside Visual Studio, then the default
location is a folder named storage on the same level as the application executable.
- If you are running a debug build of the app in Visual Studio, the default location is
under Samples/Assets
- If you are running a release build of the app in Visual Studio, the default location is a
folder named storage on the same level as what is set as your Visual Studio root
execution path (by default the location of the project file)

To change the default location, you may edit the OZOPlayerApp.cpp

const char* OZOPlayerApp::getApplicationStoragePath() const

#ifdef NDEBUG

return ".\\Storage\\";

#else

4/20/2017 2017 Nokia

15 / 17
 return "..\\..\\..\\Samples\\Assets\\";

#endif

For streaming, you should create a file with the filename extension .playlist and have the
stream URL as a single line of text inside that file. E.g.
http://192.168.0.1/files/video.mpd

The app will show the videos either as a list or as a collection of thumbnails. To give a video a
thumbnail, create a 400x400 color PNG file which has the same name as the video file (except for
the filename extension which should be .png). If no thumbnail is provided, then a default image will
be used as the thumbnail.

The graphics used by the app are stored under OZOPlayerApp/assets. From there you can
change the branding logos and the background image.

Also you should remember to rename the application and change the application ID as needed.

15 Creating a custom HMD device implementation

You may create your own custom HMD device implementation by implementing the IHMDDevice
interface.

In order to ensure consistency with the HMD devices provided by the SDK, you should implement
your custom HMD in the following way:

1. Constructor of the HMD device detects whether the HMD runtime is installed on computer
and if the device is plugged in or not.
2. The initialize method should reserve all the resources required by the HMD and set the
HMD device to a state where it can start to render frames.

The update method should update all state information of the HMD, including the head tracking
information. If the HMD has not been initialized yet, the update method should recheck if the HMD
is plugged in.

The getHeadtransform method should return the head transform cached during the last
update call.

The recenterPose method should reset the yaw of the head tracking, either by calling the HMD
framework to do it or by manually applying an offset.

SubmitFrame method should render the content currently in the eye surface buffers on the
device.

4/20/2017 2017 Nokia

16 / 17
For more detailed examples, please take a look at any of the HMD device implementation that
come with the SDK.

Open source and third party software

This release includes certain open source and third party software. Please see
https://ozo.nokia.com/ozo_en/ozo-player-sdk-licensing-terms for applicable copyright and other
notices, permissions and acknowledgements.

16 Nokia license agreement

Copyright 2016-2017 Nokia Technologies Ltd. and/or its subsidiary(-ies).

This OZO Player SDK software, including the accompanying documentation, is protected by
copyright controlled by Nokia Technologies Ltd. All rights reserved. Unless you have signed an
individually negotiated license agreement with Nokia, the license terms applicable to your use of
this software are available at: https://ozo.nokia.com/ozo_en/ozo-player-sdk-product-license-
agreements. If you have signed an individually negotiated license agreement with Nokia, the terms
contained in that license agreement shall govern your use of this software.

4/20/2017 2017 Nokia

17 / 17