Skip to main content
Skip table of contents

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

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

Disconnection/off

Notification: OTVOutputDeviceDisconnected
Type: digital

Notification: OTVOutputDeviceDisconnected
Type: mirroring

Notification: OTVOutputDeviceDisconnected
Type: airplay

Notification: OTVOutputDeviceDisconnected
Type: recording

AppleTV

Connection/on

Notification: OTVOutputDeviceConnected
Type: digital

Not supported

Not supported

Not supported

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.


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.