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
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:
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.
Apple’s documentation warns,
An app should create only a single instance of the
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
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
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.
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.
NYT360Video works on iOS 8+.
NYT360Video may be fetched and built via Carthage. To install it, simply add the following line to your
Then, following the instructions for integrating Carthage frameworks into your app, link the
NYT360Video framework into your project.
NYT360Video is available through CocoaPods. To install it, simply add the following line to your Podfile:
- 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
NYT360ViewControlleris 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.
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.
- Fork this repository
- Create your feature branch:
git checkout -b my-awesome-new-feature
- Commit your changes:
git commit -m 'Add some awesome feature'Please split your commits up logically, and be sure to write good commit messages.
- Push to your branch:
git push origin my-awesome-new-feature
- Submit a pull request to this repository
NYT360Video is released under the Apache 2.0 license.