Types

Component Props

VideoProps

interface VideoProps extends Omit<HTMLProps<HTMLVideoElement>, "onEnded"> {
  id: string;
  progressBar?: boolean;
  allowPlayPause?: boolean;
  allowFullscreen?: boolean;
  allowPictureInPicture?: boolean;
  volume?: number;
  theme?: VideoTheme;
  lang?: SupportedLanguage;
  analytics?: boolean;
  analyticsPage?: Page;
  heatmap?: boolean;
  hotSegments?: boolean;
  resumeProgress?: boolean;
  userId?: string;
  userProperties?: Record<string, string>;
  chapters?: boolean;
}

type VideoTheme = "default" | "minimal" | "hover" | "feed" | "hideUI";

type SupportedLanguage = "en" | "de" | "es" | "fr" | "it" | "pl" | "ru" | "tr" | "uk";

type Page = "feed" | "standalone" | "profile";

VideoProps also inherits most standard HTML video props such as className, muted, autoPlay, loop, playsInline, and most DOM event handlers. onEnded is excluded from the public <Video /> props surface; use usePlayback().ended inside the player scope when you need end-of-playback state for custom UI.

VideoPlayerProps

interface VideoPlayerProps {
  children?: ReactNode;
}

VideoPlayer establishes a player scope for detached controls — render a <Video> and sibling hook consumers as children to share a single player instance without prop wiring.

ImageProps

interface ImageProps extends HTMLProps<HTMLImageElement> {
  id?: string;
  alt?: string;
  analytics?: boolean;
  analyticsPage?: Page;
  className?: string;
}

FeedProps

interface FeedProps extends HTMLProps<HTMLDivElement> {
  feedId: string;
  lang?: SupportedLanguage;
  feedFont?: FontFamilyKey;
}

type FontFamilyKey =
  | "monospace_serif"
  | "proportional_serif"
  | "monospace_sans"
  | "proportional_sans"
  | "casual"
  | "cursive"
  | "small_caps";

Hook Types

Player-Scoped Hooks

These hooks read state from the enclosing player scope. Call them inside a component rendered within <Video> or <VideoPlayer> — they take no arguments and automatically bind to the current player.

interface UseMediaSettingsResult {
  muted: boolean;
  volume: number;
  previousVolume: number;
  mute: () => void;
  unmute: () => void;
  toggleMute: () => void;
  setVolume: (volume: number) => void;
}

declare function useMediaSettings(): UseMediaSettingsResult;

interface UsePlaybackResult {
  paused: boolean;
  loading: boolean;
  ended: boolean;
  hasInteracted: boolean;
  playbackRate: number;
  play: () => Promise<void>;
  pause: () => void;
  togglePlay: () => Promise<void>;
  setPlaybackRate: (playbackRate: number) => void;
  pauseOthers: () => void;
}

declare function usePlayback(): UsePlaybackResult;

interface UsePlayerProgressResult {
  currentTime: number;
  duration: number;
  progress: number;
  buffered: number;
  seekTo: (seconds: number) => void;
  seekBy: (deltaSeconds: number) => void;
}

declare function usePlayerProgress(): UsePlayerProgressResult;

interface UsePlayerUIResult {
  controlsVisible: boolean;
  isFullscreen: boolean;
  isPictureInPicture: boolean;
  showControls: () => void;
  hideControls: () => void;
  toggleFullscreen: () => Promise<void>;
  togglePictureInPicture: () => Promise<void>;
}

declare function usePlayerUI(): UsePlayerUIResult;

interface UsePlayerTracksResult {
  audioTrack: number;
  availableAudioTracks: {
    index: number;
    label: string;
    language: string;
    kind: string;
  }[];
  subtitleTrack: number;
  availableSubtitleTracks: {
    index: number;
    label: string;
    language: string;
    kind: string;
  }[];
  setAudioTrack: (trackIndex: number) => void;
  setSubtitleTrack: (trackIndex: number) => void;
}

declare function usePlayerTracks(): UsePlayerTracksResult;

Global Hook

interface UseGlobalPlayerSettingsResult {
  muted: boolean;
  volume: number;
  playbackRate: number;
  preferredQuality: number | undefined;
  preferredAudioLanguage: string | undefined;
  preferredSubtitleLanguage: string | undefined;
  setMuted: (muted: boolean) => void;
  setVolume: (volume: number) => void;
  setPlaybackRate: (rate: number) => void;
  setPreferredQuality: (quality: number | undefined) => void;
  setPreferredAudioLanguage: (language: string | undefined) => void;
  setPreferredSubtitleLanguage: (language: string | undefined) => void;
  pauseAll: () => void;
}

declare function useGlobalPlayerSettings(): UseGlobalPlayerSettingsResult;

To pause every other player relative to the current scope, use the scoped pauseOthers() returned from usePlayback().

DOM Progress Helper

useProgressBar is a lower-level hook for a raw HTMLVideoElement. For the public Video component, prefer usePlayerProgress() when building custom controls.

interface UseProgressBarProps {
  video: HTMLVideoElement | null;
}

declare function useProgressBar(props: UseProgressBarProps): {
  progress: number;
  isDragging: boolean;
  handleDragStart: (event: MouseEvent | TouchEvent) => void;
};

Data Types

VideoData

Represents video metadata returned from the API.

interface VideoData {
  id: string;
  file: FileData;
  poster: ImageData;
  duration: number;
  width: number;
  height: number;
  codec: string;
  bitrate: number;
  framerate: string;
  hdr: boolean;
  chapters?: Chapter[];
}

interface Chapter {
  title: string;
  start_time_sec: number;
  end_time_sec: number;
  duration_label: string;
}

ImageData

Represents image metadata returned from the API.

interface ImageData {
  id: string;
  thumbhash: string;
  width: number;
  height: number;
  attached_to_video: boolean;
  file: FileData;
}

FeedPost

Represents a post within a feed.

interface FeedPost {
  id: string;
  projectId: string;
  creatorId: string;
  type: "image" | "video";
  feedId: string;
  description: string;
  image?: ImageData;
  video?: VideoData;
  createdAt: string;
  updatedAt: string;
}

interface FeedPostsResponse {
  posts: FeedPost[];
  total: number;
  offset: number;
  limit: number;
}

FileData

Represents file metadata for videos and images.

interface FileData {
  id: string;
  project_id: string;
  format: string;
  url: string;
  name: string;
  size: number;
  status: FileStatus;
  created_at: Date;
  updated_at: Date;
}

type FileStatus = "uploading" | "uploaded" | "processing" | "ready" | "error";

Analytics Types

ContentViewEvent

Event structure for content view tracking.

interface ContentViewEvent {
  _type: "content_views";
  timestamp?: number;
  content_id: string;
  content_type: "video" | "image";
  view_type: "start" | "watch" | "end";
  watch_duration_ms: number;
  page: Page;
  feed_id?: string;
  post_id?: string;
  video_position_ms?: number;
  video_total_duration_ms?: number;
  device_id?: string;
  country?: string;
}

VideoHeatmap

Viewer engagement heatmap data.

interface VideoHeatmap {
  video_id: string;
  total_duration_ms: number;
  data: number[];
}

HotSegment

Represents a high-engagement segment of a video.

interface HotSegment {
  start_second: number;
  end_second: number;
  multiplier: number;
}

On This Page