NYT360Video

360º video playback from The New York Times

NYT360Video plays spherical 360º video, allowing the user to explore the video via pan gestures and the iOS device’s gyroscope. The video can be played from a file or network stream, via a standard AVPlayer instance.

It provides no user interface for playback controls (like a play/pause button); it is intended to be embedded in your own video player implementation.

At the Times we use NYT360Video to support playback of our own content:

Usage

NYT360ViewController is the entry point for the library. Initialize it with an AVPlayer instance and your application’s motion manager. (Motion management is discussed in the next section.)

Once it’s initialized, embed your NYT360ViewController instance in your view hierarchy via view controller containment.

The Example application demonstrates how to set this up.

Motion Management

Apple’s documentation warns,

An app should create only a single instance of the CMMotionManager class.

To cope with this limitation, NYT360Video doesn’t have to create its own CMMotionManager instance to receive device motion updates. Instead, you’ll inject a motion manager when you create a NYT360ViewController.

The expectations for this motion manager are set by the NYT360MotionManagement protocol; see the header for a detailed description of those requirements.

If your application doesn’t use CMMotionManager elsewhere, you can simply use the NYT360MotionManager singleton provided with this library to fulfill these requirements.

Otherwise, if your app has a motion manager already, you’ll need to make it conform to NYT360MotionManagement and use it when creating a NYT360ViewController.

Managing Gesture Interactions

You may want to restrict the gesture-based interactions with NYT360ViewController in certain cases in your application — for example, when embedded in a vertically-scrolling view, NYT360ViewController should not intercept vertical pan gestures. There are a few ways to accomplish this with NYT360Video.

First, NYT360ViewController provides properties to configure which axes of movement are allowed. (This would be the simplest way to solve the example problem set out above.)

The library exposes its pan gesture recognizer as a property on NYT360ViewController for more advanced integration with other gesture recognizers. And finally, the type NYT360CameraPanGestureRecognizer is introduced so that host applications can more easily configure interaction with other gesture recognizers, without having to refer to specific instances of an NYT360Video gesture recognizer.

Requirements

NYT360Video works on iOS 8+.

Installation

Carthage

NYT360Video may be fetched and built via Carthage. To install it, simply add the following line to your Cartfile:

github "NYTimes/ios-360-videos"

Then, following the instructions for integrating Carthage frameworks into your app, link the NYT360Video framework into your project.

CocoaPods

NYT360Video is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'NYT360Video'

Known Issues

• iOS 10 CoreAudio Crash - On devices running iOS 10 (at least as of Beta 7), host applications will crash if the device is locked while an NYT360ViewController is visible (whether paused or not). The crash is caused by a CoreAudio exception. A workaround that appears to work for some, though not all, apps is to enable the background audio capability in the host application’s plist. An extended discussion of the issue can be found in issue #37.

See also this project’s issue tracker.

Contributing

Contributions are welcomed via GitHub’s pull request system. As a note:

• Contributions which include unit tests, where feasible, are likely to be merged more easily.
• Pull requests which add player UI are unlikely to be accepted. We consider that to be a separate responsibility; this library aims to provide only lower-level 360º-specific playback functionality.

1. Fork this repository
2. Create your feature branch: git checkout -b my-awesome-new-feature
3. Commit your changes: git commit -m 'Add some awesome feature' Please split your commits up logically, and be sure to write good commit messages.
4. Push to your branch: git push origin my-awesome-new-feature
5. Submit a pull request to this repository

Version History

See CHANGELOG.md.

License

NYT360Video is released under the Apache 2.0 license.