# OTSubscriberKit Class Reference

Inherits from | NSObject
Declared in | OTSubscriberKit.h

## Overview

An OTSubscriberKit (subscriber) object renders media data bound to an OTStream. The OTSubscriberKit class lets you set a custom video renderer for the video stream. Use this class if you are interested in providing your own video processing and rendering implementation. Otherwise, use the OTSubscriber class, which includes a pre-built video processor and renderer.

The stream property references the stream that you have subscribed to. The OTSubscriberKit class includes methods that let you disable and enable local audio and video playback for the subscribed stream.

## Getting basic information about a Subscriber

### `session`

The OTSession object that owns this subscriber. An instance will have one and only one OTSession associated with it, and this property is immutable.

`@property (readonly) OTSession *session`

#### Declared In

`OTSubscriberKit.h`

### `stream`

The stream this subscriber is bound to. Any media channels on the stream should be available for display/playback with this instance.

`@property (readonly) OTStream *stream`

#### Declared In

`OTSubscriberKit.h`

### `delegate`

The OTSubscriberKitDelegate object that serves as a delegate, handling basic events for this OTSubscriber object.

`@property (nonatomic, weak) id<OTSubscriberKitDelegate> _Nullable delegate`

#### Discussion

See also [OTSubscriberKit audioLevelDelegate], [OTSubscriberKit networkStatsDelegate], and [OTSubscriberKit rtcStatsReportDelegate].

#### Declared In

`OTSubscriberKit.h`

## Working with audio and video

### `audioLevelDelegate`

Periodically receives reports of audio levels for this subscriber.

`@property (nonatomic, weak) id<OTSubscriberKitAudioLevelDelegate> _Nullable audioLevelDelegate`

#### Discussion

This is a separate delegate object from that set as the [OTSubscriberKit delegate] property (the OTSubscriberKitDelegate object).

If you do not set this property, the audio sampling subsystem is disabled.

#### Declared In

`OTSubscriberKit.h`

### `captionsDelegate`

The delegate for receiving captions for this subscriber’s stream.

`@property (nonatomic, weak) id<OTSubscriberKitCaptionsDelegate> _Nullable captionsDelegate`

#### Declared In

`OTSubscriberKit.h`

### `subscribeToAudio`

Whether to subscribe to the stream’s audio.

`@property (nonatomic) BOOL subscribeToAudio`

#### Discussion

The default value is YES.

Setting this property has no effect if the [OTStream hasAudio] property is set to NO.

#### Declared In

`OTSubscriberKit.h`

### `subscribeToVideo`

Whether to subscribe to the stream’s video.

`@property (nonatomic) BOOL subscribeToVideo`

#### Discussion

The default value is YES.

Setting this property has no effect if the [OTStream hasVideo] property is set to NO.

#### Declared In

`OTSubscriberKit.h`

### `subscribeToCaptions`

Whether to subscribe to captions.

`@property (nonatomic) BOOL subscribeToCaptions`

#### Discussion

The default value is the captions value of the stream’s publisher [OTStream hasCaptions]

#### Declared In

`OTSubscriberKit.h`

### `captionsTranslationLanguage`

The preferred caption translation language for this subscriber.

`@property (nonatomic, copy, nullable) NSString *captionsTranslationLanguage`

#### Discussion

This setting only takes effect when captions are enabled. Set this to a supported BCP-47 language code to receive translated captions, or set to `nil` to disable translation. The default value is `nil` (no translation configured).

Supported language codes are defined in the server API spec.

If the language code is not supported, the value will not be applied. Read this property back after setting it to verify the language was correctly accepted.

This is a private beta feature.

#### Declared In

`OTSubscriberKit.h`

### `videoRender`

The video renderer for this instance.

`@property (nonatomic, strong) id<OTVideoRender> _Nullable videoRender`

#### Declared In

`OTSubscriberKit.h`

### `preferredResolution`

The preferred resolution for the subscriber’s stream.

`@property (nonatomic) CGSize preferredResolution`

#### Discussion

Limiting the video resolution and frame rate (see [OTSubscriberKit preferredFrameRate]) reduces the network and CPU usage on the subscribing client. You may want to use lower resolution based on the dimensions of subscriber’s video in the app. You may want to use a lower frame rate or resolution for subscribers to a stream that is less important (and smaller) than other streams.

This method only applies when subscribing to a stream that uses the scalable video feature. Scalable video is available:

- Only in sessions that use the OpenTok Media Router (sessions with the media mode set to routed)

- Only for streams published by clients that support scalable video (see the documentation for the scalable video feature).

In streams that do not use scalable video, calling this method has no effect.

Note: The resolution of scalable video streams automatically adjusts for each subscriber, based on network conditions and CPU usage, even if you do not call this method. Call this method if you want to limit the resolution for this subscriber.

Not every resolution is available to a subscriber. When you set the preferred resolution, the OpenTok iOS SDK picks the best resolution available that matches your constraints. The resolutions available depend on the maximum resolution the Publisher sets for the stream, which is set as the [OTStream videoDimensions] property for the stream. Each of the resolutions available for a stream will use the same aspect ratio.

#### Declared In

`OTSubscriberKit.h`

### `preferredFrameRate`

The preferred frame rate for the subscriber’s stream.

`@property (nonatomic) float preferredFrameRate`

#### Discussion

Limiting the frame rate and video resolution (see [OTSubscriberKit preferredResolution]) reduces the network and CPU usage on the subscribing client. You may want to use lower resolution based on the dimensions of subscriber’s video in the app. You may want to use a lower frame rate or resolution for subscribers to a stream that is less important (and smaller) than other streams.

This method only applies when subscribing to a stream that uses the scalable video feature. Scalable video is available:

- Only in sessions that use the OpenTok Media Router (sessions with the media mode set to routed)

- Only for streams published by clients that support scalable video (see the documentation for the scalable video feature).

In streams that do not use scalable video, calling this method has no effect.

Note: The frame rate for scalable video streams automatically adjusts for each subscriber, based on network conditions and CPU usage, even if you do not call this method. Call this method if you want to limit the frame rate for this subscriber.

The frame rates available are based on the value of the maximum frame rate available for the stream. When you set the preferred frame rate for the subscriber, the OpenTok iOS SDK picks the best frame rate available that is closest to the `preferredFrameRate` setting, based on the client’s bandwidth and CPU constraints.

The actual frame rates available depend, dynamically, on network and CPU resources available to the publisher.

#### Declared In

`OTSubscriberKit.h`

### `audioVolume`

The audio volume, between 0 and 100, of the subscriber. When setting the value, if it is not in this range, it will be clamped to it.

`@property (nonatomic) double audioVolume`

#### Discussion

The default value is 100.

#### Declared In

`OTSubscriberKit.h`

## Getting audio and video statistics

### `networkStatsDelegate`

The OTSubscriberKitNetworkStatsDelegate object that periodically receives subscriber quality statistics.

`@property (nonatomic, weak) id<OTSubscriberKitNetworkStatsDelegate> _Nullable networkStatsDelegate`

#### Discussion

This delegate object is sent messages reporting the following:

- Total audio and video packets lost
- Total audio and video packets received
- Total audio and video bytes received

This is a separate delegate object from that set as the [OTSubscriberKit delegate] property (the OTSubscriberKitDelegate object).

Also see [OTSubscriberKit rtcStatsReportDelegate].

#### Declared In

`OTSubscriberKit.h`

### `rtcStatsReportDelegate`

The OTSubscriberKitRtcStatsReportDelegate that reports RTC stats for the subscriber. The [OTSubscriberKitRtcStatsReportDelegate subscriber:rtcStatsReport:] message is sent in reponse to calling the [OTSubscriberKit getRtcStatsReport] method.

`@property (nonatomic, weak) id<OTSubscriberKitRtcStatsReportDelegate> _Nullable rtcStatsReportDelegate`

#### Declared In

`OTSubscriberKit.h`

## Initializing a Subscriber

### `– initWithStream:delegate:`

Initializes a subscriber and binds it to an OTStream instance. Once initialized, the instance is permanently bound to the stream.

`- (_Nullable id)initWithStream:(nonnull OTStream *)stream delegate:(nullable id<OTSubscriberKitDelegate>)delegate`

#### Parameters

`stream` | The OTStream object to bind this instance to.
`delegate` | The delegate (OTSubscriberKitDelegate) that will handle events generated by this instance.

#### Discussion

The OpenTok iOS SDK supports a limited number of simultaneous audio-video streams in an app:

- In a relayed session, the limit is two streams. An app can have up to two subscribers, or one publisher and one subscriber.

- In a routed session, an app can support one audio-video publisher, one audio-video subscriber, and up to three additional subscribed audio-only streams simultaneously.

(For information on relayed and routed sessions see the documentation on the media mode of a session.)

Initializing a subscriber causes it to start streaming data from the OpenTok server, regardless of whether the view of the subscriber object is added to a superview.

You can stream audio only (without subscribing to the video stream) by setting the [OTSubscriberKit subscribeToVideo] property to NO immediately after initializing the OTSubscriber object. You can stream video only (without subscribing to the audio stream) by setting the [OTSubscriberKit subscribeToAudio] property to NO immediately after initializing the OTSubscriber object.

When the subscriber connects to the stream, the [OTSubscriberKitDelegate subscriberDidConnectToStream:] message is sent.

For an OTSubscriber object, when the first frame of video has been decoded, the [OTSubscriberDelegate subscriberVideoDataReceived:] message is sent.

If the subscriber fails to connect to the stream, the [OTSubscriberKitDelegate subscriber:didFailWithError:] message is sent.

#### Declared In

`OTSubscriberKit.h`

### `– getRtcStatsReport:`

Gets the RTC stats report for the subscriber. This is an asynchronous operation. Set the [OTSubscriberKit rtcStatsReportDelegate] property and implement the [OTSubscriberKitRtcStatsReportDelegate subscriber:rtcStatsReport:] method prior to calling this method. When the stats are available, the implementation of the [OTSubscriberKitRtcStatsReportDelegate subscriber:rtcStatsReport:] message is sent.

`- (void)getRtcStatsReport:(OTError *_Nullable *_Nullable)error`

#### Parameters

`error` | Set if an error occurs synchronously while processing the request. The `OTSubscriberErrorCode` enum (defined in the OTError.h file) defines values for the `code` property of this object. This object is NULL if no error occurs. Also see [OTSubscriberKit networkStatsDelegate] and [OTPublisherKit getRtcStatsReport].

#### Declared In

`OTSubscriberKit.h`