Advanced Usage

This page is the full API reference for the SDK. It covers all configurable parameters, player controls, and read-only properties exposed by the public classes.


InkInitParams

Use InkInitParams.Builder to configure a playback session before passing it to the player via setParams().

val params = InkInitParams.Builder()
    .setVideoId("YOUR_VIDEO_ID")   // Required
    .setOtp("YOUR_OTP")            // Required
    .setAutoplay(true)
    .setInitialAspectRatio(16f / 9f)
    .setTolerateDeveloperMode(false)
    .setSetupDelayMs(0L)
    .build()

Builder Methods

MethodTypeDefaultRequiredDescription
setVideoId(videoId)String—YesThe Video ID from your Inkrypt Dashboard.
setOtp(otp)String—YesOne-time password used to authenticate the DRM license request.
setAutoplay(autoplay)BooleanfalseNoWhen true, playback starts automatically as soon as the player is ready.
setInitialAspectRatio(ratio)Float16/9NoAspect ratio used to size the player before the video metadata loads. Useful to prevent layout jumps on slow connections.
setTolerateDeveloperMode(tolerate)BooleanfalseNoWhen true, the SDK will not block playback if Developer Mode or USB Debugging is enabled on the device. Use during development only — remove before releasing to production.
setSetupDelayMs(delayMs)Long (ms)0NoAdds an intentional delay before the player begins its setup sequence (license fetch, DRM init, etc.). Use this when starting the player prematurely during app start or restart where the app is not fully ready to load, due to remnants of uncleared resources from a previous session that have not finished clearing by the time playback starts. Has no effect when 0.
build()——YesReturns the final InkInitParams instance.

InkPlayerFragment

InkPlayerFragment is the primary UI component. It hosts the video surface, built-in controls (play/pause, seek bar, quality selector, chapters), and the error overlay.

Obtain a reference to it via AndroidViewBinding (Kotlin/Compose) or getSupportFragmentManager().findFragmentById() (Java/XML) as shown in Basic Usage.

Player Actions

MethodReturnsDescription
setParams(params: InkInitParams)—Loads a new video. Can be called multiple times to swap the currently playing video.
play()—Resumes playback if the player is paused.
pause()—Pauses playback.
toggleFullscreen()—Toggles between fullscreen and normal mode. Locks orientation to landscape on enter and portrait on exit.
enterFullScreen(lockScreen: Boolean)—Enters fullscreen. Pass true to lock orientation to landscape; false to leave orientation management to the system.
exitFullScreen(lockScreen: Boolean)—Exits fullscreen. Pass true to lock orientation to portrait; false to leave orientation management to the system.

Player Properties

Property / MethodReturnsDescription
playerSession / getPlayerSession()InkPlayerSession?The currently active playback session. Returns null before the player has been initialized with setParams().
isPlaying()Booleantrue if the player is actively playing content.
isLoading()Booleantrue while the player is buffering or loading the manifest.
getVideoLength()Long (ms)Total duration of the loaded media in milliseconds. Returns 0 if no media is loaded.
getCurrentSeekPosition()Long (ms)Current playhead position in milliseconds.
getCurrentChapter()VideoChapter?The chapter that contains the current playhead position. Returns null if the video has no chapters.
getSelectedVideoQuality()String?Currently selected quality label (e.g. "720p", "480p"). Returns null when Adaptive/Auto quality is active.

Static Methods

MethodReturnsDescription
InkPlayerFragment.getSdkVersion()StringThe current SDK version string (e.g. "3.0.73").

InkPlayerSession

InkPlayerSession exposes additional controls and read-only state for the active playback session. Obtain an instance from inkPlayer.playerSession after setParams() has been called.

val session = inkPlayer?.playerSession

Session Properties

PropertyTypeDescription
sessionIdString (UUID)Unique identifier for the current session. Useful for correlating support tickets or error reports.
currentParamsInkInitParamsThe InkInitParams that were used to start this session.
chaptersList<VideoChapter>?All chapter markers defined for the current video. Returns null or empty list if the video has no chapters.

Session Actions

MethodDescription
seek(position: Long)Seeks to the specified position in milliseconds.
restart()Seeks to position 0 and resumes playback.
reload()Tears down and re-initializes the current playback session with the same InkInitParams. Useful for recovering from certain error states.
updatePlaybackSpeed(speed: Float?)Sets the playback speed. 1.0f is normal speed. Typical values: 0.5, 0.75, 1.0, 1.25, 1.5, 2.0.
setChapter(chapter: VideoChapter)Seeks to the start position of the given chapter and marks it as the active chapter.

Chapter Lookup

MethodReturnsDescription
getCurrentChapter()VideoChapter?The chapter that contains the current playhead position.
getChapterAtPosition(position: Long)VideoChapter?The chapter that contains the specified position in milliseconds.

VideoChapter

Represents a named time span within the video.

PropertyTypeDescription
startLong (seconds)Start position of the chapter in seconds (not milliseconds).
titleStringDisplay name of the chapter.

Note: Chapter positions are specified in seconds, but seek() and most other player methods use milliseconds. When jumping to a chapter manually, the SDK converts internally via chapter.start * 1000.


InkPlayerFragmentV34

InkPlayerFragmentV34 is a subclass of InkPlayerFragment that hooks into the screenshot detection API added in Android 14 (API 34). Whenever a screenshot is taken while the player is active, the SDK reports the event to Inkrypt's servers automatically.

Use it exactly like InkPlayerFragment — just change the class name in your player_fragment.xml:

android:name="com.inkryptvideos.android.InkPlayerFragmentV34"

Requirements: Requires minSdk >= 34. All methods, properties, and behaviors of InkPlayerFragment are fully inherited.


InkPlayerActivity (Optional Extra)

InkPlayerActivity is an abstract AppCompatActivity subclass that adds one convenience on top of the standard FragmentActivity setup: it automatically calls enterFullScreen() / exitFullScreen() on orientation changes, so you do not have to handle that yourself.

This is not the primary integration path - hosting InkPlayerFragment inside a plain FragmentActivity is the recommended approach. Use InkPlayerActivity only if automatic orientation-driven fullscreen is something you specifically want.

class MainActivity : InkPlayerActivity() {
  private var inkPlayer: InkPlayerFragment? = null

  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)
    inkPlayer = supportFragmentManager
      .findFragmentById(R.id.ink_player_fragment) as InkPlayerFragment
    setPlayer(inkPlayer!!)
  }

}
MethodDescription
setPlayer(player: InkPlayerFragment)Registers the fragment that InkPlayerActivity will manage for automatic fullscreen transitions.

Note: InkPlayerActivity only accepts setContentView(Int) (resource ID). Calling setContentView(View) or setContentView(View, LayoutParams) throws UnsupportedOperationException.


Development Tips

Bypassing Developer Mode Detection

By default, the SDK blocks playback when Developer Mode or USB Debugging is enabled on the device. To suppress this during development:

val params = InkInitParams.Builder()
    .setVideoId("YOUR_VIDEO_ID")
    .setOtp("YOUR_OTP")
    .setTolerateDeveloperMode(true)   // Remove this before release!
    .build()

Delaying Session Setup

If you start the player during app launch or restart and the app is not fully ready — for example, resources from a previous session have not finished clearing by the time playback begins — add a short delay before the player initializes:

val params = InkInitParams.Builder()
    .setVideoId("YOUR_VIDEO_ID")
    .setOtp("YOUR_OTP")
    .setSetupDelayMs(500L)   // Wait 500ms before beginning the setup sequence
    .build()