Professional Documents
Culture Documents
3.3.2 Videos with two video tracks (not valid for streaming) ...................................................8
7 Analytics .................................................................................................................................10
2 / 17
8 Setting up the audio .............................................................................................................10
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.
C:\Nokia\OZOPlayerSDK
Applications/Nokia/OZOPlayerSDK/
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 / 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.
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
3rdParty/openvr-1.0.6
1.3.3 GearVR:
3rdParty/ovr_sdk_mobile_1.5.0
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.
Samples/VideoPlayback/IOS/GVR/
And the for the iOS version of the OZO Player App the folder is:
OZOPlayerApp/Build/IOS/GVR/
5 / 17
2 Development requirements
2.1 For Android:
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
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:
*_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
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
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:
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
8 / 17
8GB+ RAM
4.3 iOS:
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.
OZO::PlatformParameters platformParameters;
OZO::AnalyticsParameters analyticsParameters;
analyticsParameters.licenseID = "ENTER_YOUR_LICENCE_ID_HERE"
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.
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.
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.
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
RenderTextureDesc colorTextureDesc;
colorTextureDesc.format = RenderTextureFormat::R8G8B8A8;
colorTextureDesc.width = width;
colorTextureDesc.height = height;
colorTextureDesc.ptr = &color;
11 / 17
OZO::RenderSurface surface;
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
The state of the video playback can be fetched using the getPlaybackState method
12 / 17
Calling loadVideo loads the video file but doesnt start playback.
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.
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.
playbackControl->stop();
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;
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
13 / 17
timesynched, call this only once per rendering cycle so that all the surfaces are listed in a single
call.
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);
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
#ifdef NDEBUG
return ".\\Storage\\";
#else
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.
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.
16 / 17
For more detailed examples, please take a look at any of the HMD device implementation that
come with the SDK.
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.
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.
17 / 17