Basic Usage

This guide assumes you have already added the SDK to your project. If not, see Setting Up the SDK first.


How the SDK Works

The SDK has three main types you will use in almost every integration:

TypeRole
InkPlayerParamsTells the player which video to load (Video ID + OTP)
InkryptVideoPlayerThe Flutter widget that renders the native video player
InkryptVideoPlayerControllerProvides programmatic controls (play, pause, seek, etc.)

The typical flow is:

1. Add InkryptVideoPlayer to your widget tree
        ↓
2. onPlayerCreated fires — save the controller reference
        ↓
3. Call controller.setParams(...) to load a video
        ↓
4. Use the controller to read state or issue playback commands

Step 1: Import the SDK

In any Dart file where you use the player, add:

import 'package:inkrypt_video_player/inkrypt_video_player.dart';

This single import exposes all public types:
InkryptVideoPlayer, InkryptVideoPlayerController, InkPlayerParams, PlayerState, VideoChapter, InkryptPlayerError.


Step 2: Add the Player Widget

InkryptVideoPlayer is a StatefulWidget that embeds the native video player view. Add it anywhere in your widget tree.

The onPlayerCreated callback fires once the native view is ready, providing you with a controller reference.

import 'package:flutter/material.dart';
import 'package:inkrypt_video_player/inkrypt_video_player.dart';

class VideoScreen extends StatefulWidget {
  const VideoScreen({super.key});

  @override
  State<VideoScreen> createState() => _VideoScreenState();
}

class _VideoScreenState extends State<VideoScreen> {
  InkryptVideoPlayerController? _controller;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: InkryptVideoPlayer(
        onPlayerCreated: (controller) {
          _controller = controller;
        },
      ),
    );
  }
}

The widget renders with a black background and defaults to a 16:9 aspect ratio. It fills the full available width.


Step 3: Load a Video

Call controller.setParams(...) inside onPlayerCreated (or any time later) to load a video.

InkPlayerParams requires a videoId and an otp:

onPlayerCreated: (controller) {
  _controller = controller;
  controller.setParams(
    InkPlayerParams(
      videoId: 'YOUR_VIDEO_ID',
      otp: 'YOUR_OTP',
    ),
  );
},

What is a Video ID? Each video you upload to the InkryptVideos platform gets a unique identifier, visible in the dashboard.

What is an OTP? An OTP (One-Time Password) is a short-lived token that grants playback access to a specific video. Generate it from the InkryptVideos dashboard immediately before playback. Using an expired OTP will result in a playback error.


Loading a Video at Widget Creation

If you know the video params before the widget is created, pass them via initialParams. The player will load the video immediately once the native view is ready, no setParams call needed.

InkryptVideoPlayer(
  initialParams: InkPlayerParams(
    videoId: 'YOUR_VIDEO_ID',
    otp: 'YOUR_OTP',
    autoPlay: true,
  ),
  onPlayerCreated: (controller) {
    _controller = controller;
    // Video is already loading — controller is available for further commands
  },
),

Switching Videos

To load a different video after the player is already running, call setParams again at any time. The player stops the current video and begins loading the new one.

Future<void> _loadNextVideo() async {
  await _controller?.setParams(
    InkPlayerParams(
      videoId: 'NEXT_VIDEO_ID',
      otp: 'NEXT_VIDEO_OTP',
      autoPlay: true,
    ),
  );
}

Accessing Player State

All controller methods are async, they communicate with the native layer and return a Future.

Reading Individual Values

// Is the player currently playing?
final isPlaying = await _controller?.isPlaying;         // bool

// Total video duration (in seconds)
final duration = await _controller?.videoLength;        // num?

// Current playback position (in milliseconds)
final position = await _controller?.currentPosition;    // num?

// Active chapter, if any
final chapter = await _controller?.currentChapter;      // VideoChapter?

Reading All State at Once

playerState fetches all four values in a single call:

final state = await _controller?.playerState;
// state.isPlaying       — bool
// state.videoLength     — num? (seconds)
// state.currentPosition — num? (milliseconds)
// state.currentChapter  — VideoChapter?


Complete Example

A minimal video player that loads a video and displays a play/pause toggle:

import 'package:flutter/material.dart';
import 'package:inkrypt_video_player/inkrypt_video_player.dart';

class BasicVideoPlayer extends StatefulWidget {
  const BasicVideoPlayer({super.key});

  @override
  State<BasicVideoPlayer> createState() => _BasicVideoPlayerState();
}

class _BasicVideoPlayerState extends State<BasicVideoPlayer> {
  InkryptVideoPlayerController? _controller;
  bool _isPlaying = false;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Video Player')),
      body: Column(
        children: [
          InkryptVideoPlayer(
            onPlayerCreated: (controller) {
              _controller = controller;
              controller.setParams(
                InkPlayerParams(
                  videoId: 'YOUR_VIDEO_ID',
                  otp: 'YOUR_OTP',
                  autoPlay: true,
                ),
              );
            },
          ),
          IconButton(
            iconSize: 48,
            icon: Icon(_isPlaying ? Icons.pause : Icons.play_arrow),
            onPressed: () async {
              if (_isPlaying) {
                await _controller?.pause();
              } else {
                await _controller?.play();
              }
              final playing = await _controller?.isPlaying ?? false;
              setState(() => _isPlaying = playing);
            },
          ),
        ],
      ),
    );
  }
}