External device detection

To test the features and view the example code, please see the Apple (FPS) SDK 5 Example Code Quick Start guide.

Connecting Apple devices to external devices can provide the means to view or capture video content. Here, external devices are any of the following:

HDMI adaptor allowing the display to an external TV screen
Screen mirroring
Airplay
Screen recording functionality (iOS/iPadOS)

The external device detection feature provides notifications when such external devices are connected and disconnected from an iOS, iPadOS and tvOS device.

Example code

To enable this feature, you must first initialise the class OTVOutputDeviceMonitor with an OTVAVPlayer instance.

CODE

OTVOutputDeviceMonitor(player: otvPlayer)

To ensure the lifecycle, your code must retain the OTVOutputDeviceMonitor instance. You must set their instance to nil to stop device detection on their OTVPlayer instance. If there are multiple player instances, each one must be attached to its own instance of OTVOutputDeviceMonitor.

Several types of connections are monitored and reported in the notifications OTVOutputDeviceConnected and OTVOutputDeviceDisconnected. Each one is captured in the OTVOutputDeviceType enumeration:

APPLESCRIPT

@objc public enum OTVOutputDeviceType: Int {
  /**
   Digital output consists of HDMI output from HDMI adapters.
   These can be connected to iOS,iPadOS and tvOS devices.
   */
  case digital = 1
  /**
   Airplay output can be setup between an iOS/iPadOS device to a tvOS device.
   */
  case airplay = 2
  /**
   Screen recording can be activated by an iOS/iPadOS device by clicking the recording button from the control panel
   */
  case recording = 3
  /**
   mirroring output can be setup between an iOS/iPadOS device to a tvOS device.
   */
  case mirroring  = 4
  /**
   This is an unknown type of output.
   */
  case unknown = 5
}

To detect when an external device is connected or disconnected, your code must listen for two notifications:

CODE

 NotificationCenter.default.addObserver(self,
                                         selector: #selector(monitoringOutputDeviceConnectionStatus(_:)),
                                         name: .OTVOutputDeviceConnected, object: nil)

 NotificationCenter.default.addObserver(self,
                                         selector: #selector(monitoringOutputDeviceDisconnectionStatus(_:)),
                                         name: .OTVOutputDeviceDisconnected, object: nil)

Your code should handle the notifications for OTVOutputDeviceConnected and OTVOutputDeviceDisconnected by following these examples:

APPLESCRIPT

 @objc func monitoringOutputDeviceConnectionStatus(_ notification: Notification) {
    if let outputDeviceType: OTVOutputDeviceType = notification.userInfo?["outputDeviceType"] as? OTVOutputDeviceType {
      switch outputDeviceType {
      case .digital:
        print("Output Device Monitor: Digital output connected")
      case .airplay:
        print("Output Device Monitor: Airplay output connected")
      case .recording:
        print("Output Device Monitor: Screen being captured")
      case .mirroring:
        print("Output Device Monitor: Screen being mirrored")
      case .unknown:
        print("Unknown output connected")
      @unknown default:
        print("Unknown event")
      }
    }
  }


@objc func monitoringOutputDeviceDisconnectionStatus(_ notification: Notification) {
    if let outputDeviceType: OTVOutputDeviceType = notification.userInfo?["outputDeviceType"] as? OTVOutputDeviceType {
      switch outputDeviceType {
      case .digital:
        print("Output Device Monitor: Digital output disconnected")
      case .airplay:
        print("Output Device Monitor: Airplay output disconnected")
      case .recording:
        print("Output Device Monitor: Screen not being captured")
      case .mirroring:
        print("Output Device Monitor: Screen not being mirrored")
      case .unknown:
        print("Unknown output disconnected")
      @unknown default:
        print("Unknown event")
      }
    }
  }

The table below outlines the expected behaviour for the output types on iOS/iPadOS and tvOS devices. Analogue output devices are not supported.

Device	Case / Expected Behavior
Device	Action	Digital output device	Mirroring	Airplay	Screen Recording
iPhone/iPad	Connection/on	Notification: `OTVOutputDeviceConnected` Type: `digital`	Notification: `OTVOutputDeviceConnected` Type: `mirroring`	Notification: `OTVOutputDeviceConnected` Type: `airplay`	Notification: `OTVOutputDeviceConnected` Type: `recording`
iPhone/iPad	Disconnection/off	Notification: `OTVOutputDeviceDisconnected` Type: `digital`	Notification: `OTVOutputDeviceDisconnected` Type: `mirroring`	Notification: `OTVOutputDeviceDisconnected` Type: `airplay`	Notification: `OTVOutputDeviceDisconnected` Type: `recording`
AppleTV	Connection/on	Notification: `OTVOutputDeviceConnected` `T`ype: `digital`	Not supported	Not supported	Not supported
AppleTV	Disconnection/off	Notification: `OTVOutputDeviceDisconnected` Type: `digital`	Not supported	Not supported	Not supported

Once OTVOutputDeviceMonitor is initialised, your code will receive notifications whenever the output device is connected and disconnected. If a connection is started before the class is initialised and remains connected, an OTVOutputDeviceConnected will be fired.

The same applies when the application goes into the background or comes into the foreground on the device. If the output is stopped or started in the background, a corresponding notification will be fired, but only when returning to the foreground. For example, if you have initialised OTVOutputDeviceMonitor and the app is sent to the background, the end-user begins screen recording on the device. When the application returns to the foreground, a notification will be fired for OTVOutputDeviceConnected of type recording.