Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/NYTimes/ios-360-videos

NYT360Video plays 360-degree video streamed from an AVPlayer on iOS.
https://github.com/NYTimes/ios-360-videos

Last synced: 3 months ago
JSON representation

NYT360Video plays 360-degree video streamed from an AVPlayer on iOS.

Awesome Lists containing this project

README 

        
# NYT360Video

[![Version](https://img.shields.io/cocoapods/v/NYT360Video.svg?style=flat)](http://cocoapods.org/pods/NYT360Video)

[![License](https://img.shields.io/cocoapods/l/NYT360Video.svg?style=flat)](http://cocoapods.org/pods/NYT360Video)

[![Platform](https://img.shields.io/cocoapods/p/NYT360Video.svg?style=flat)](http://cocoapods.org/pods/NYT360Video)

[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)



## 360º video playback from The New York Times



NYT360Video plays [spherical 360º video](https://en.wikipedia.org/wiki/360-degree_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:



![Animation of 360º video playback in the Times’ iPhone app](Documentation/360.gif)



## Usage



[`NYT360ViewController`](https://github.com/NYTimes/ios-360-videos/blob/develop/Sources/NYT360ViewController.h) is the entry point for the library. [Initialize](https://github.com/NYTimes/ios-360-videos/blob/68c522d51d6c88ddd705e4febbb480de825cdc5d/Sources/NYT360ViewController.h#L67) 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](https://www.objc.io/issues/1-view-controllers/containment-view-controller/).



[The Example application demonstrates](https://github.com/NYTimes/ios-360-videos/blob/develop/NYT360VideoExample/ViewController.m) 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](https://github.com/NYTimes/ios-360-videos/blob/develop/Sources/NYT360MotionManagement.h); 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](https://github.com/NYTimes/ios-360-videos/blob/develop/Sources/NYT360MotionManager.h) to fulfill these requirements.



Otherwise, if your app has a motion manager already, you’ll need to make it conform to [`NYT360MotionManagement`](https://github.com/NYTimes/ios-360-videos/blob/develop/Sources/NYT360MotionManagement.h) 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](https://github.com/NYTimes/ios-360-videos/blob/68c522d51d6c88ddd705e4febbb480de825cdc5d/Sources/NYT360ViewController.h#L111) 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](https://github.com/Carthage/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](https://github.com/Carthage/Carthage#if-youre-building-for-ios-tvos-or-watchos), link the `NYT360Video` framework into your project.



### CocoaPods



NYT360Video is available through [CocoaPods](http://cocoapods.org). 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](https://github.com/nytimes/ios-360-videos/issues/37).



_See also [this project’s issue tracker](https://github.com/NYTimes/ios-360-videos/issues)._



## 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](https://github.com/NYTimes/ios-360-videos/fork)

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](https://www.dzombak.com/blog/2015/10/Writing-good-commit-messages.html)._

4. Push to your branch: `git push origin my-awesome-new-feature`

5. Submit a [pull request](https://github.com/NYTimes/ios-360-videos/pulls) to this repository



## Version History



See [CHANGELOG.md](CHANGELOG.md).



## License



NYT360Video is released under the [Apache 2.0 license](LICENSE.md).