JWPlayerController

@interface JWPlayerController : NSObject

A class that encapsulates JW Player and provides control over the playback as well as holds the state of the player and notifies about status updates.

Accessing Player Controller Attributes */

  • Player view.

    Note

    to be added to the application view hierarchy.

    Declaration

    Objective-C

    @property (nonatomic, retain, readonly, nullable) UIView *view;
  • The object that acts as the delegate of the JWPlayerController.

    Note

    The delegate must adopt the JWPlayerDelegate protocol. The delegate is not retained.

    See

    JWPlayerDelegate

    Declaration

    Objective-C

    @property (nonatomic, weak, readwrite, nullable) id<JWPlayerDelegate> delegate;
  • The object that acts as the analyticsDelegate of the JWPlayerController. Data provided by this object can be used by 3rd-party analytics libraries.

    Note

    The analyticsDelegate must adopt the JWAVPlayerAnalyticsDelegate protocol. The analyticsDelegate is not retained.

    See

    JWAVPlayerAnalyticsDelegate

    Declaration

    Objective-C

    @property (nonatomic, weak, readwrite, nullable) id<JWAVPlayerAnalyticsDelegate>
        analyticsDelegate;
  • The JWDrmDataSource is adopted by an object that mediates the application’s data model and key server. The data source provides the JWPlayerController object with the data needed to reproduce encrypted content.

    Note

    The drmDataSource must adopt the JWDrmDataSource protocol. The drmDataSource is not retained.

    See

    JWDrmDataSource

    Declaration

    Objective-C

    @property (nonatomic, weak, readwrite, nullable) id<JWDrmDataSource>
        drmDataSource;
  • The object that acts as a playlist item delegate to the JWPlayerController. The playlistItemDelegate will be notified when a playlist item is about to transition. At this point the playlistItemDelegate can choose to either proceed with the playlist item’s load, make modifications to it, load an entirely different item, or skip the item’s load.

    Note

    The playlistItemDelegate is used for intercepting item loads. To be notified when a playlistItem successfully loads, use the JWPlayerController’s delegate.

    Note

    The delegate must adopt the JWPlaylistItemDelegate protocol. The delegate is not retained.

    See

    JWPlaylistItemDelegate

    Declaration

    Objective-C

    @property (nonatomic, weak, readwrite, nullable) id<JWPlaylistItemDelegate>
        playlistItemDelegate;
  • Deprecated

    Use JWFriendlyAdObstructions class instead.

    An interface for exposing experimental features.

    Note

    These features are very likely to be deprecated in the future, and will either be entirely dropped or replaced.

    Declaration

    Objective-C

    @property (nonatomic, readonly)
        DEPRECATED_MSG_ATTRIBUTE("Use JWFriendlyAdObstructions class instead.")
            JWExperimentalAPI *experimentalAPI;
  • Returns the version of google IMA framework compatible with the JWPlayer SDK.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly) NSString *_Nonnull googleIMAVersion;
  • Returns the version of google ChromeCast framework compatible with the JWPlayer SDK.

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly) NSString *_Nonnull googleChromeCastVersion;
  • Returns current state of the player.

    Note

    Can be idle, playing, paused and buffering, error, complete.

    Declaration

    Objective-C

    @property (nonatomic, readonly) JWPlayerState state;
  • Metadata associated with the current video. Usually includes dimensions and duration of the video.

    Note

    becomes available shortly after the video starts playing. There is a notification JWMetaDataAvailableNotification posted right after metadata is available.

    Declaration

    Objective-C

    @property (nonatomic, retain, readonly, nullable) NSDictionary *metadata;
  • Dimensions of the current video. Becomes available shortly after the video starts to play as a part of metadata.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGSize naturalSize;
  • JWConfig object that was used to setup the player.

    Note

    Check JWConfig documentation for more info.

    Declaration

    Objective-C

    @property (nonatomic, retain, readonly) JWConfig *_Nonnull config;
  • Returns the current PlaylistItem’s filled buffer, as a percentage (0 to 100) of the total video’s length.

    Note

    This only applies to progressive downloads of media (MP4/FLV/WebM and AAC/MP3/Vorbis); streaming media (HLS/RTMP/YouTube/DASH) do not expose this behavior.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSUInteger buffer;
  • Enable the built-in controls by setting them true, disable the controls by setting them false.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite) BOOL controls;
  • When enabled, the user will be able to control playback of the current video (play, pause, and when applicable next/previous) from the device’s Lock Screen and some information (title, playback position, duration, poster image) will be presented on the lockscreen. Defaults to YES.

    Note

    In order for the lock screen controls to appear, background audio must be enabled and the audio session must be set to AVAudioSessionCategoryPlayback.

    Note

    Instantiating more than one player simultaneously can potentially cause undesirable behavior regarding lock screen controls, as they are enabled by default for each player. To enable lock screen controls for only a specific player: after all the players have been instantiated, explicitly set ‘displayLockScreenControls’ to YES on the desired player, and make sure ‘displayLockScreenControls’ is set to NO for the undesired player(s).

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
        BOOL displayLockScreenControls;
  • Returns the region of the display not used by the controls. You can use this information to ensure your visual assets don’t overlap with the controls.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGRect safeRegion;

Managing Video Quality Levels */

Managing Closed Captions */

  • The index of the caption object in captions list currently used by the player.

    Note

    index 0 stands for no caption.

    See

    captionsList

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
        NSUInteger currentCaptions;
  • List of all the captions supplied in the config

    Note

    Use currentCaptions to activate one of the captions programmatically. Object at index 0 is “off”.

    See

    currentCaptions

    Declaration

    Objective-C

    @property (nonatomic, retain, readonly)
        NSArray<JWTrack *> *_Nonnull captionsList;

Managing Audio Tracks */

  • The index of the currently active audio track.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
        NSUInteger currentAudioTrack;
  • Array with audio tracks from the player.

    Declaration

    Objective-C

    @property (nonatomic, retain, readonly) NSArray *_Nonnull audioTracks;

Managing Playlists */

  • The index of the currently active item in the playlist.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
        NSInteger playlistIndex;
  • Returns the playlist item at a specific index.

    Declaration

    Objective-C

    - (nonnull JWPlaylistItem *)getPlaylistItem:(NSInteger)index;
  • Returns the playlist.

    Declaration

    Objective-C

    - (nonnull NSArray<JWPlaylistItem *> *)getPlaylist;

Initializing Player Controller Object */

  • Inits the player with config object in JWConfig format.

    Declaration

    Objective-C

    - (nullable instancetype)initWithConfig:(nonnull JWConfig *)config;

    Parameters

    config

    JWConfig object that is used to setup the player.

  • Inits the player with config object in JWConfig format and sets the object that acts as the delegate of the JWPlayerController.

    Declaration

    Objective-C

    - (nullable instancetype)initWithConfig:(nonnull JWConfig *)config
                                   delegate:(nullable id<JWPlayerDelegate>)delegate;

    Parameters

    config

    JWConfig object that is used to setup the player.

    See

    JWPlayerDelegate

    delegate

    The object that acts as the delegate of the jwPlayerController.

  • Inits the player with a JWConfig object and sets the object that acts as a DRM data source, as well as the delegate of the JWPlayerController.

    See

    JWPlayerDelegate, JWDrmDataSource

    Declaration

    Objective-C

    - (nullable instancetype)initWithConfig:(nonnull JWConfig *)config
                                   delegate:(nullable id<JWPlayerDelegate>)delegate
                              drmDataSource:
                                  (nullable id<JWDrmDataSource>)drmDataSource;

    Parameters

    config

    JWConfig object that is used to setup the player.

    delegate

    The object that acts as the delegate of the jwPlayerController.

    drmDataSource

    The object that acts as a data source for reproducing drm encrypted content.

  • Unavailable

    Undocumented

    Declaration

    Objective-C

    - (instancetype)init NS_UNAVAILABLE;

Managing Playback */

  • Starts to play video from current position.

    Note

    If there is a paused ad, this method will resume the ad playback.

    Declaration

    Objective-C

    - (void)play;
  • Pauses video.

    Note

    If there is an ad playing, this method will pause the ad playback.

    Declaration

    Objective-C

    - (void)pause;
  • Stops the player (returning it to the idle state) and unloads the currently playing media file.

    Declaration

    Objective-C

    - (void)stop;
  • Tells the player to immediately play the next playlist item.

    Declaration

    Objective-C

    - (void)next;
  • See

    duration

    Declaration

    Objective-C

    - (void)seek:(NSInteger)position;

    Parameters

    position

    Time in the video to seek to

  • Playback position of the current video.

    Note

    gets updated as the video plays. JWPlaybackProgressNotification is posted every time position changes. KVO compliant.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGFloat position;
  • Duration of the current video. Becomes available shortly after the video starts to play as a part of metadata.

    Declaration

    Objective-C

    @property (nonatomic, readonly) CGFloat duration;
  • The volume of the JWPlayerController’s audio. At 0.0 the player is muted, at 1.0 the player’s volume is as loud as the device’s volume.

    Note

    This property should be used to control the volume of the player (including Google IMA ads) relative to other audio output, not for volume control by viewers. This property will have no effect when casting. Viewers can control volume when casting by changing the device’s volume.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite) CGFloat volume;
  • The rate at which media is being reproduced.

    Note

    Setting this property to 1.0 will play the media at its natural rate. Ability to set a different value is limited to the rates supported by the media item; if an unsupported rate is requested, playbackRate will not change. Rates between 0.0 and 1.0 will slow forward, rates greater than 1.0 will fast forward, rates between 0.0 and -1.0 will slow reverse, and rates lower than -1.0 will fast reverse. This property will have no effect when ads are being played, or when casting. Cannot be set to 0; to pause playback, please call the pause method.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite) CGFloat playbackRate;

Managing Full Screen */

  • The setter toggles the player’s fullscreen mode; the getter returns a boolean value that determines whether the video is in full screen.

    Warning

    Note: If your app uses fullscreen mode, and will run on iPads running iOS 11 or higher, select Requires full screen in the General tab of your target’s settings to avoid unwanted triggering of Split View mode.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite) BOOL fullscreen;
  • A Boolean value that determines whether the video should go to full screen mode when the device rotates to landscape.

    Note

    Make sure your app supports landscape to make this property work.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
        BOOL forceFullScreenOnLandscape;
  • A Boolean value that determines whether the video should rotate to landscape when the fullscreen button is pressed.

    Note

    Make sure your app supports landscape to make this property work.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
        BOOL forceLandscapeOnFullScreen;

Custom Buttons */

  • Adds a custom button to the player’s control bar.

    Note

    Buttons are added to the righthand-side grouping of icons in the control bar. Buttons are added all the way to the left of the grouping, except if there is a logo in the control bar. In this case, buttons will be added to the right of the logo. Multiple buttons are added from right to left in the order they are entered.

    See

    JWButton

    Declaration

    Objective-C

    - (void)addButton:(nonnull JWButton *)button;
  • Removes a custom button from the control bar.

    See

    JWButton

    Declaration

    Objective-C

    - (void)removeButton:(nonnull JWButton *)button;

External Metadata */

  • Returns the external metadata applied to the current playlist item.

    See

    JWPlaylistItem, JWConfig

    Declaration

    Objective-C

    - (nonnull NSArray<JWExternalMetadata *> *)getExternalMetadata;
  • Sets external metadata to the current playlist item. Will not apply to the subsequent playlist items. @discussion We recommend using this method to add external metadata to playlist items loaded from a related feed. For items loaded in the config’s playlist, set the external metadata directly on the playlist item before setting up the player.

    Note

    Capped at 5 metadata instances; the instances in excess will be excluded

    Note

    If you wish to apply the same external metadata to all playlist items, set the external metadata on the JWConfig.

    See

    JWPlaylistItem, JWRelatedConfig

    Declaration

    Objective-C

    - (void)setExternalMetadata:
        (NSArray<JWExternalMetadata *> *_Nonnull)externalMetadata;

Loading New Media */

  • Loads a new playlist into the player.

    Declaration

    Objective-C

    - (void)load:(nonnull NSArray<JWPlaylistItem *> *)playlist;

    Parameters

    playlist

    An array containing playlist items.

  • Loads a new playlist feed into the player.

    Declaration

    Objective-C

    - (void)loadFeed:(nonnull NSString *)feedUrl;

    Parameters

    feedUrl

    A URL referencing the location of an RSS/XML/JSON file

Injecting Ads */

  • Immediately starts to play an ad using the vast plugin.

    Note

    Usually used to inject an ad in streams where you can’t schedule an ad. If you wish to play the ad with the Google IMA Client, please use playAd:onClient: instead and specify JWAdClientGoogima as your ad client.

    Declaration

    Objective-C

    - (void)playAd:(nonnull NSString *)tag;

    Parameters

    tag

    Xml file with info about the ad.

  • Immediately starts to play an ad.

    Note

    Usually used to inject an ad in streams where you can’t schedule an ad.

    See

    JWAdClient

    Declaration

    Objective-C

    - (void)playAd:(nonnull NSString *)tag onClient:(JWAdClient)adClient;

    Parameters

    tag

    Xml file with info about the ad.

    adClient

    Set to JWAdClientGoogima if you wish to use google IMA; set to JWAdClientVast if not. Setting to nil defaults to vast. Note: Due to the fact that Google IMA’s iOS SDK is still in Beta mode, we suggest using the vast plugin.

  • Used to pause or resume ad playback.

    Note

    If the state is YES, ad playback will be paused.

    Declaration

    Objective-C

    - (void)pauseAd:(BOOL)state;

    Parameters

    state

    Indicates whether or not the ad playback should be paused.

  • If set to YES will open Safari after the user clicks the ad.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite)
        BOOL openSafariOnAdClick;

Related */

  • Opens the related overlay. This will pause content if it is currently playing.

    Declaration

    Objective-C

    - (void)openRelatedOverlay;
  • Closes the related plugin overlay. This will resume content.

    Declaration

    Objective-C

    - (void)closeRelatedOverlay;

Accessing SDK Info */

  • Version of underlying web player

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly) NSString *_Nonnull playerVersion;
  • Player edition based on the provided JW License key

    Declaration

    Objective-C

    @property (nonatomic, copy, readonly) NSString *_Nonnull playerEdition;
  • Version of the iOS SDK

    Declaration

    Objective-C

    + (nonnull NSString *)SDKVersion;
  • Version of the iOS SDK, truncated. (i.e.: if SDKVersion returns 1.001, SDKVersionToMinor returns 1.).

    Declaration

    Objective-C

    + (nonnull NSString *)SDKVersionToMinor;
  • Sets the Player Key programmatically instead of having to type it into the application’s info.plist. We recommend setting the key in the AppDelegate’s application:didFinishLaunchingWithOptions: method.

    Note

    If a different key is entered in the info.plist, the key set with this method will supersede. Use this method before instantiating the JWPlayerController, ideally in the AppDelegate’s application:didFinishLaunchingWithOptions: method.

    Declaration

    Objective-C

    + (void)setPlayerKey:(nonnull NSString *)key;