Advanced Usage

This reference covers the full API surface of the InkryptVideos SDK: player properties, actions, events, chapters, watermarks, and delegate-based event handling.


InkPlayerState: Live Playback State

InkPlayerState is the primary interface for reading playback state and issuing commands. You receive it via the onPlayerStateReady callback on InkryptVideoPlayerView.

Properties

PropertyTypeDescription
isPlayingBooltrue if the player is actively playing
isLoadingBooltrue if the player is buffering or initializing
isFullScreen@Published BoolRead or write to toggle full-screen mode
seekDurationFloat64Current playback position in seconds
videoLengthCMTime?Total duration of the loaded video
currentChapterVideoChapter?The chapter active at the current playback position
selectedQualityString?Active quality level (e.g. "720"), or nil for Auto
selectedRateFloatCurrent playback speed (default: 1.0)
volumeFloatCurrent volume, from 0.0 (muted) to 1.0 (full)

Methods

MethodSignatureDescription
play()() -> VoidResume playback
pausePlayer()() -> VoidPause playback
seek(to:)(Float64) -> VoidSeek to a position in seconds
reset()() -> VoidStop and unload the current video

Playback Control

// Resume playback 
playerState.play()

// Pause playback 
playerState.pausePlayer() 

// Seek to a specific position (in seconds) 
playerState.seek(to: 90.0) // Jump to 1:30 

// Stop and unload the video 
playerState.reset()

Full Screen

Full screen is controlled via the isFullScreen property on InkPlayerState. It is a @Published property, so SwiftUI views that read it will re-render when it changes.

// Enable full screen 
playerState.isFullScreen = true 

// Disable full screen 
playerState.isFullScreen = false 

// Toggle 
playerState.isFullScreen.toggle()

The player handles orientation locking and the transition animation automatically.


Playback Speed

// Read current speed 
let speed = playerState.selectedRate // e.g. 1.0 

// Set speed (accepted: 0, 0.5, 0.75, 1.0, 1.25, 1.5, 1.75, 2.0) 
playerState.selectedRate = 1.5

The player's built-in controls also include a speed selector, so users can adjust playback speed from within the UI without any additional code.


Volume Control

// Read current volume 
let vol = playerState.volume // Float from 0.0 to 1.0 

// Set volume 
playerState.volume = 0.5 // 50% 
playerState.volume = 0.0 // Mute 
playerState.volume = 1.0 // Full volume

Seeking

// Seek to an exact position in seconds 
playerState.seek(to: 300.0) // Jump to 5:00

Rewind (−5 s) and fast-forward (+5 s) are available through the built-in player controls (double-tap or the on-screen buttons) and are not exposed as programmatic API.


Quality Selection

Quality switching is handled by the built-in player controls. You can read the currently active quality level programmatically:

// Currently selected quality label (e.g. "720"); nil means "Auto" 
let currentQuality = playerState.selectedQuality

The full list of available quality options and bitrates is not part of the public API — it is managed internally and surfaced in the built-in quality selector UI.


Chapters

Chapters divide a video into named segments. They appear in the player's chapter menu and can be used for programmatic navigation.

VideoChapter Properties

PropertyTypeDescription
titleStringThe chapter name
startUInt64Start time in seconds
startTimeCMTimeStart time as CMTime
startInTimeFormatStringStart time formatted as HH:mm:ss or mm:ss

Working with Chapters

// Chapter at the current playback position (nil if none or not yet loaded)
let nowPlaying = playerState.currentChapter

The chapter list and chapter-based navigation are managed by the built-in player UI. Programmatic access is limited to reading the currently active chapter via playerState.currentChapter.


Watermark

The watermark is a floating text overlay displayed on top of the video. Its configuration is set server-side via the OTP/license system, it cannot be set by client code.

Watermark Properties

PropertyTypeDescription
textString?The text shown on the player screen
alphaDouble?Opacity: 0.0 (invisible) to 1.0 (fully opaque)
colorString?Hex color with # prefix, e.g. #FFFFFF
sizeFloat?Font size of the watermark text
intervalInt64?Milliseconds between each repositioning of the watermark

Note: The watermark configuration is set server-side and is not accessible programmatically. The player renders it automatically once the FairPlay license response is received.


Player Events

InkryptVideoPlayerView Callbacks

These are the recommended way to respond to player events. All callbacks are optional.

InkryptVideoPlayerView(
    params: params,
    onPlayerStateReady: { state in 
        // Called once when the player is initialized and ready.
        // The state object is valid for this video session. 
        // When params.update() is called, this callback fires again with a new state. 
        self.playerState = state 
    },
    onReloadPressed: { errorCode, errorMessage in 
        // Called when the user taps "Retry" on the built-in error screen. 
        // Return new InkPlayerParams to reload with a different video/OTP. 
        // Return nil to retry with the same params. 
        return nil 
    }, 
    onError: { errorCode, errorMessage in 
        // Called whenever a playback or initialization error occurs. 
        // Use for logging, monitoring, or showing supplementary UI. 
        print("Error \(errorCode ?? -1): \(errorMessage ?? "unknown")") 
    } 
)

Analytics Identifiers

The SDK automatically tracks analytics. Two static identifiers are exposed for correlation with your own system:

// Unique per device — persisted across app launches in UserDefaults 
let userId: String? = InkPlayer.userId 
// Current SDK version 
let version: String? = InkPlayer.sdkVersion

Note: The per-session sessionId is tracked internally by the SDK and appears in the InkryptVideos analytics dashboard, but is not part of the public API.