NAGRA CONNECT Player

Known limitations

The player acts differently depending on which platform it is run on (iOS or Android).
Also, the information provided by the player's API does not allow for the accurate reporting of certain events.

Therefore, the following statements must be taken into account when integrating the player:

• On Android, if the user pauses the stream during a stall, the stall end won't be detected until the user unpauses the stream. This might produce stalls that are longer than expected.
• On iOS / tvOS, if the user seeks in the stream, the onWaiting event is not triggered. This prevents rebufferings to be detected.

1. Attach the player

When creating the player instance, attach it to the current session.

// Create your player object with a ref variable
this.otvplayer = {
    ref: undefined // mandatory
};

// Create an event object will at least these listeners
this.events = {
    onLoadStart: () => {

    },
    onLoad: () => {

    },
    onProgress: () => {

    },
    onPlay: () => {

    },
    onPlaying: () => {

    },
    onPaused: () => {

    },
    onWaiting: () => {

    },
    onSeek: () => {

    },
    onError: () => {

    },
    onSelectedBitrateChanged: () => {

    }
};

// Attach your player to the current session
session.attachPlayer(this.otvplayer, this.events);

// Create your CONNECT Player component with all events and set the player ref
const [isDisplayed, setIsDisplayed] = React.useState(false);

...

{isDisplayed && (
    <OTVPlayer
        ref={(otvplayer) => {
            this.otvplayer.ref = otvplayer;
        }}
        source={this.source}
        style={[styles.player.container]}
        autoplay={true}
        onLoadStart={this.events.onLoadStart}
        onLoad={this.events.onLoad}
        onProgress={this.events.onProgress}
        onPlay={this.events.onPlay}
        onPlaying={this.events.onPlaying}
        onPaused={this.events.onPaused}
        onWaiting={this.events.onWaiting}
        onSeek={this.events.onSeek}
        onError={this.events.onError}
        onSelectedBitrateChanged={this.events.onSelectedBitrateChanged}
    />
)}

2. Start a streaming session

The getURL method is used to get the actual streaming URL and start the streaming session. This method is also the starting point of the analytics calculation, for instance the startup time starts from this method.

The returned URL can be different for every video session. In case of using a Broadpeak CDN or a nanoCDN, it includes a unique token. It can be used only once per session object, once called the session is actually started.

When getURL returns an error, it means no streaming URL can be found. It has to trigger a specific behaviour on the application (error message, dialog...) and stopStreamingSession has to be called. Find more details about getURL errors on the session errors page.

It is recommended to perform this call on a different thread than the main thread, the method runs HTTP requests.

info

This method has to be called even for non-Broadpeak content URLs. In this case, the method will return the same URL.

// Get the stream URL from SmartLib
session.getURL(contentURL)
    .then(result => {
        if (!result.isError()) {
            this.source = {
                src: result.getURL()
            };

            setIsDisplayed(true);
        } else {
            // Stop the session
            session.stopStreamingSession();

            // Process the loading error
        }
    });
});

3. Stop a streaming session

The stopStreamingSession method must be called each time the session is stopped:

• end users: when the playback is stopped by a user action
• loading errors: when the streaming session cannot be started through the getURL method
• player errors: when the player triggers a non-recoverable error during the playback (as a decoding error)
• application or any others actions: when the app is killed

// Stop the session
session.stopStreamingSession();
this.otvplayer.ref.stop();

If the player generates a non-recoverable error during the playback (as a decoding error), call stopStreamingSession to stop the session.

this.events = {
    ...
        
    onError: () => {
        session.stopStreamingSession();
    },
    
    ...
};