If you're using Apollo Client or other GraphQL clients for URL signing, use useQuery instead of useLazyQuery to avoid abort errors:

`tsx
import React from "react"
import { S3Config, WontumPlayerReact } from "@obipascal/player"
import { useQuery } from "@apollo/client"
import { GET_MEDIA_SIGNED_URL } from "@/graphql/queries/media.queries"

interface VideoPlayerProps {
videoUrl: string
}

function VideoPlayer({ videoUrl }: VideoPlayerProps) {
// ✅ Use useQuery with skip option instead of useLazyQuery
const { refetch } = useQuery(GET_MEDIA_SIGNED_URL, {
skip: true, // Don't run on mount
fetchPolicy: "no-cache", // Always fetch fresh signed URLs
})

const url = new URL(videoUrl)

const s3config: S3Config = {
cloudFrontDomains: [url.hostname],
withCredentials: true, // Enable cookies for CloudFront signed cookies
signUrl: async (resourceUrl: string) => {
try {
const { data } = await refetch({
signingMediaInput: {
resourceUrl,
isPublic: false,
type: "COOKIES",
},
})

console.log("Signed URL result:", data)
// For cookie-based signing, return the original URL
// The server sets cookies in the response
return resourceUrl
} catch (error) {
console.error("Failed to sign URL:", error)
throw error
}
},
}

return (
src={videoUrl}
width="100%"
height="500px"
autoplay={false}
controls
s3Config={s3config}
theme={{
primaryColor: "#3b82f6",
accentColor: "#60a5fa",
}}
/>
)
}
`

Why useQuery with skip instead of useLazyQuery?

- useLazyQuery creates a new AbortController on each call, which can be aborted during React lifecycle
- useQuery with skip: true and refetch persists across renders, avoiding abort issues
- The SDK includes retry logic for AbortErrors, but using useQuery prevents them entirely

🔒 CloudFront & S3 Integration

This player supports three video hosting scenarios. Choose the one that fits your needs:

$3

When to use: Your videos are publicly accessible and don't require user authentication.

Setup: Just provide the video URL!

`typescript
import { WontumPlayer } from "@obipascal/player"

const player = new WontumPlayer({
src: "https://d1234567890.cloudfront.net/video/playlist.m3u8",
container: "#player",
})
`

✅ That's it! No backend needed. Works for public S3 buckets or CloudFront distributions.

---

$3

When to use: You want to restrict video access to authorized users (e.g., paid courses, premium content).

How it works:

1. User logs into your app
2. Your backend verifies the user and sets CloudFront signed cookies
3. Player automatically sends these cookies with every video request
4. CloudFront checks the cookies and allows/denies access

Frontend Setup:

`typescript
import { WontumPlayer } from "@obipascal/player"

// STEP 1: Call your backend to set signed cookies BEFORE creating the player
async function initializePlayer() {
// This endpoint sets CloudFront cookies in the browser
await fetch("/api/auth/video-access", {
credentials: "include", // Important: include cookies
})

// STEP 2: Create player - it will automatically use the cookies
const player = new WontumPlayer({
src: "https://media.yourdomain.com/videos/lesson-1/playlist.m3u8",
container: "#player",
s3Config: {
cloudFrontDomains: ["media.yourdomain.com"], // Your CloudFront domain
withCredentials: true, // Enable cookies for all HLS requests (required for CloudFront signed cookies)
signUrl: async (url) => {
// This function is called when player needs to access a video
// Call your backend to refresh/set cookies if needed
const response = await fetch("/api/auth/sign-url", {
method: "POST",
headers: { "Content-Type": "application/json" },
credentials: "include",
body: JSON.stringify({ url }),
})

if (!response.ok) {
throw new Error("Failed to authenticate video access")
}

// Backend sets cookies, return the URL
return url
},
},
})
}

initializePlayer()
`

Backend Setup (Node.js/Express):

`typescript
import express from "express"
import { getSignedCookies } from "@aws-sdk/cloudfront-signer"
import fs from "fs"

const app = express()

// STEP 1: Create endpoint that sets CloudFront signed cookies
app.get("/api/auth/video-access", (req, res) => {
// Check if user is logged in (your authentication logic)
if (!req.user) {
return res.status(401).json({ error: "Not authenticated" })
}

// Define what resources user can access
const policy = {
Statement: [
{
Resource: "https://media.yourdomain.com/*", // All videos on this domain
Condition: {
DateLessThan: {
"AWS:EpochTime": Math.floor(Date.now() / 1000) + 3600, // Expires in 1 hour
},
},
},
],
}

// Generate CloudFront signed cookies
const cookies = getSignedCookies({
keyPairId: process.env.CLOUDFRONT_KEY_PAIR_ID!, // Your CloudFront key pair ID
privateKey: fs.readFileSync("./cloudfront-private-key.pem", "utf8"), // Your private key
policy: JSON.stringify(policy),
})

// Set the three required cookies
res.cookie("CloudFront-Policy", cookies["CloudFront-Policy"], {
domain: ".yourdomain.com", // Use your domain
path: "/",
secure: true, // HTTPS only
httpOnly: true, // Prevent JavaScript access
sameSite: "none",
})

res.cookie("CloudFront-Signature", cookies["CloudFront-Signature"], {
domain: ".yourdomain.com",
path: "/",
secure: true,
httpOnly: true,
sameSite: "none",
})

res.cookie("CloudFront-Key-Pair-Id", cookies["CloudFront-Key-Pair-Id"], {
domain: ".yourdomain.com",
path: "/",
secure: true,
httpOnly: true,
sameSite: "none",
})

res.json({ success: true })
})

// STEP 2: Optional endpoint for on-demand signing (called by signUrl function)
app.post("/api/auth/sign-url", (req, res) => {
const { url } = req.body

// Verify user is authorized
if (!req.user) {
return res.status(401).json({ error: "Not authenticated" })
}

// You can add additional authorization logic here
// For example, check if user has access to this specific video

// Refresh cookies (same code as above)
const policy = {
Statement: [
{
Resource: "https://media.yourdomain.com/*",
Condition: {
DateLessThan: {
"AWS:EpochTime": Math.floor(Date.now() / 1000) + 3600,
},
},
},
],
}

const cookies = getSignedCookies({
keyPairId: process.env.CLOUDFRONT_KEY_PAIR_ID!,
privateKey: fs.readFileSync("./cloudfront-private-key.pem", "utf8"),
policy: JSON.stringify(policy),
})

res.cookie("CloudFront-Policy", cookies["CloudFront-Policy"], {
domain: ".yourdomain.com",
path: "/",
secure: true,
httpOnly: true,
sameSite: "none",
})

res.cookie("CloudFront-Signature", cookies["CloudFront-Signature"], {
domain: ".yourdomain.com",
path: "/",
secure: true,
httpOnly: true,
sameSite: "none",
})

res.cookie("CloudFront-Key-Pair-Id", cookies["CloudFront-Key-Pair-Id"], {
domain: ".yourdomain.com",
path: "/",
secure: true,
httpOnly: true,
sameSite: "none",
})

res.json({ success: true })
})
`

AWS CloudFront Setup:

1. Create a CloudFront key pair in AWS Console → CloudFront → Key pairs
2. Download the private key file
3. Set up environment variables:
`bash
CLOUDFRONT_KEY_PAIR_ID=APKA...
`
4. Configure your CloudFront distribution to require signed cookies

---

$3

When to use: Videos are in private S3 buckets without CloudFront.

How it works:

1. Your backend generates temporary presigned URLs for S3 objects
2. Player uses these URLs to access videos
3. URLs expire after a set time (e.g., 1 hour)

Frontend Setup:

`typescript
import { WontumPlayer } from "@obipascal/player"

const player = new WontumPlayer({
src: "s3://my-bucket/videos/lesson-1/playlist.m3u8", // S3 URI
container: "#player",
s3Config: {
getPresignedUrl: async (s3Key) => {
// Call your backend to generate presigned URL
const response = await fetch("/api/s3/presigned-url", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ key: s3Key }),
})

if (!response.ok) {
throw new Error("Failed to get presigned URL")
}

const data = await response.json()
return data.url // Return the presigned URL
},
},
})
`

Backend Setup (Node.js):

`typescript
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3"
import { getSignedUrl } from "@aws-sdk/s3-request-presigner"

const s3Client = new S3Client({
region: "us-east-1",
credentials: {
accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
},
})

app.post("/api/s3/presigned-url", async (req, res) => {
const { key } = req.body

// Verify user is authorized to access this video
if (!req.user) {
return res.status(401).json({ error: "Not authenticated" })
}

try {
// Generate presigned URL
const command = new GetObjectCommand({
Bucket: "my-bucket",
Key: key, // e.g., "videos/lesson-1/playlist.m3u8"
})

const url = await getSignedUrl(s3Client, command, {
expiresIn: 3600, // URL valid for 1 hour
})

res.json({ url })
} catch (error) {
console.error("Error generating presigned URL:", error)
res.status(500).json({ error: "Failed to generate presigned URL" })
}
})
`

---

$3

| Method | Best For | Complexity | Performance |
| ---------------------- | ---------------------------------------------- | ----------- | ------------ |
| Public Videos | Free content, marketing videos | ⭐ Easy | ⚡ Fast |
| CloudFront Cookies | ⭐ Recommended for paid courses, premium | ⭐⭐ Medium | ⚡⚡ Fastest |
| S3 Presigned URLs | Direct S3 access, simple private video hosting | ⭐⭐ Medium | ⚡ Good |

💡 Tip: Use CloudFront with signed cookies for production. It's more secure and performant for HLS videos (which have many file segments).

📝 Subtitle Support

$3

`typescript
const player = new WontumPlayer({
src: "https://media.example.com/video/playlist.m3u8",
container: "#player",
subtitles: [
{
label: "English",
src: "https://example.com/subtitles/en.vtt",
srclang: "en",
default: true, // Default track
},
{
label: "Spanish",
src: "https://example.com/subtitles/es.vtt",
srclang: "es",
},
{
label: "French",
src: "https://example.com/subtitles/fr.vtt",
srclang: "fr",
},
],
})
`

$3

`typescript
// Enable specific subtitle track by index
player.enableSubtitles(0) // Enable first track (English)

// Disable all subtitles
player.disableSubtitles()

// Toggle subtitles on/off
player.toggleSubtitles()

// Get all subtitle tracks
const tracks = player.getSubtitleTracks()
console.log(tracks)
// [
// { label: 'English', src: '...', srclang: 'en', default: true },
// { label: 'Spanish', src: '...', srclang: 'es' }
// ]

// Check if subtitles are enabled
const enabled = player.areSubtitlesEnabled()
console.log(enabled) // true or false
`

$3

`typescript
player.on("subtitlechange", (event) => {
console.log("Subtitle changed:", event.data.track)
})
`

⚙️ Settings & Controls

$3

Keep controls visible at all times:

`typescript
const player = new WontumPlayer({
src: "https://media.example.com/video/playlist.m3u8",
container: "#player",
stickyControls: true, // Controls always visible
})
`

Users can also toggle sticky controls from the settings menu in the player UI.

$3

10-second skip buttons with circular arrow icons are automatically included:

`typescript
// Programmatic skip
player.skipForward(10) // Skip 10 seconds forward
player.skipBackward(10) // Skip 10 seconds backward

// Custom skip duration
player.seek(player.getCurrentTime() + 30) // Skip 30 seconds forward
`

$3

Clicking anywhere on the video toggles play/pause automatically.

$3

Modern vertical volume slider with popup interface - hover over volume button to adjust.

📊 Analytics

Track video engagement and quality metrics with HTTP endpoints or real-time WebSocket/Socket.IO streaming:

Features:

- ✅ HTTP endpoint support for traditional analytics
- ✅ Native WebSocket support for real-time streaming
- ✅ Socket.IO support with full TypeScript types
- ✅ Dual streaming (HTTP + Socket simultaneously)
- ✅ Event transformation and filtering
- ✅ Auto-reconnection with configurable delays
- ✅ Quality of Experience (QoE) metrics included in every event

$3

`typescript
const player = new WontumPlayer({
src: "https://example.com/video.m3u8",
container: "#player",
analytics: {
enabled: true,
endpoint: "https://your-analytics-endpoint.com/events",
sessionId: "session_123",
userId: "user_456",
videoId: "video_789",
},
})

// Get analytics metrics
const metrics = player.analytics.getMetrics()
console.log(metrics)
// {
// sessionId: 'session_123',
// totalPlayTime: 120000,
// totalBufferTime: 2000,
// bufferingRatio: 0.017,
// rebufferCount: 3,
// seekCount: 5,
// eventCount: 42
// }
`

$3

Stream analytics events in real-time using native WebSocket for live dashboards and monitoring:

`typescript
const player = new WontumPlayer({
src: "https://example.com/video.m3u8",
container: "#player",
analytics: {
enabled: true,
userId: "user_456",
videoId: "video_789",
// Native WebSocket configuration
webSocket: {
type: "websocket", // Specify native WebSocket
connection: "wss://analytics.example.com/stream",
// Optional: Transform events before sending
transform: (event) => ({
type: event.eventType,
video_id: event.videoId,
user_id: event.userId,
timestamp: event.timestamp,
metrics: event.data,
}),
// Optional: Handle errors
onError: (error) => {
console.error("Analytics WebSocket error:", error)
},
// Optional: Connection opened
onOpen: (event) => {
console.log("Analytics WebSocket connected")
},
// Optional: Connection closed
onClose: (event) => {
console.log("Analytics WebSocket disconnected")
},
// Auto-reconnect on disconnect (default: true)
autoReconnect: true,
// Reconnect delay in milliseconds (default: 3000)
reconnectDelay: 3000,
},
},
})
`

$3

For Socket.IO-based real-time analytics (requires socket.io-client to be loaded):

`typescript
// Option 1: Let the SDK create the Socket.IO connection
const player = new WontumPlayer({
src: "https://example.com/video.m3u8",
container: "#player",
analytics: {
enabled: true,
userId: "user_456",
videoId: "video_789",
webSocket: {
type: "socket.io",
connection: "https://analytics.example.com", // Socket.IO server URL
options: {
path: "/socket.io/",
transports: ["websocket", "polling"],
auth: {
token: "your-auth-token",
},
reconnection: true,
reconnectionDelay: 1000,
},
eventName: "video_analytics", // Event name to emit (default: "analytics")
transform: (event) => ({
event: event.eventType,
video: event.videoId,
user: event.userId,
data: event.data,
}),
onConnect: () => {
console.log("Socket.IO connected")
},
onDisconnect: (reason) => {
console.log("Socket.IO disconnected:", reason)
},
onError: (error) => {
console.error("Socket.IO error:", error)
},
},
},
})
`

`typescript
// Option 2: Use existing Socket.IO connection
import { io } from "socket.io-client"

const socket = io("https://analytics.example.com", {
auth: {
token: "your-auth-token",
},
})

const player = new WontumPlayer({
src: "https://example.com/video.m3u8",
container: "#player",
analytics: {
enabled: true,
userId: "user_456",
videoId: "video_789",
webSocket: {
type: "socket.io",
connection: socket, // Use existing Socket.IO instance
eventName: "analytics",
},
},
})
`

$3

`typescript
// Create your own WebSocket connection
const ws = new WebSocket("wss://analytics.example.com/stream")

// Configure authentication or custom headers before connecting
ws.addEventListener("open", () => {
// Send authentication message
ws.send(
JSON.stringify({
type: "auth",
token: "your-auth-token",
}),
)
})

const player = new WontumPlayer({
src: "https://example.com/video.m3u8",
container: "#player",
analytics: {
enabled: true,
userId: "user_456",
videoId: "video_789",
webSocket: {
type: "websocket",
connection: ws, // Use existing connection
transform: (event) => ({
// Custom format for your backend
action: "video_event",
payload: {
event: event.eventType,
data: event.data,
},
}),
},
},
})
`

$3

Send analytics to both HTTP endpoint and real-time socket simultaneously:

`typescript
const player = new WontumPlayer({
src: "https://example.com/video.m3u8",
container: "#player",
analytics: {
enabled: true,
endpoint: "https://api.example.com/analytics", // HTTP fallback/storage
webSocket: {
type: "socket.io",
connection: "https://realtime.example.com", // Real-time monitoring
eventName: "video_analytics",
},
userId: "user_456",
videoId: "video_789",
},
})
`

$3

The SDK automatically tracks these events:

- Session: session_start, session_end
- Playback: play, pause, ended, playing
- Buffering: buffering_start, buffering_end, waiting, stalled
- Seeking: seeking, seeked
- Quality: qualitychange, renditionchange
- Errors: error
- User Actions: Volume changes, fullscreen, playback rate changes

Each event includes Quality of Experience (QoE) metrics:

- sessionDuration - Total session time
- totalPlayTime - Actual video play time
- totalBufferTime - Time spent buffering
- bufferingRatio - Buffer time / play time ratio
- rebufferCount - Number of rebuffer events
- seekCount - Number of seek operations

$3

For React applications, use the useAnalytics hook for automatic lifecycle management:

`tsx
import { useAnalytics } from "@obipascal/player"
import { useEffect } from "react"

function VideoAnalyticsDashboard() {
const { trackEvent, getMetrics, connected, sessionId } = useAnalytics({
enabled: true,
endpoint: "https://api.example.com/analytics",
videoId: "video-123",
userId: "user-456",
webSocket: {
type: "socket.io",
url: "https://analytics.example.com",
auth: { token: "your-auth-token" },
eventName: "video_event",
},
})

// Track custom events
const handleShareClick = () => {
trackEvent("share_clicked", {
platform: "twitter",
videoTime: 125.5,
})
}

const handleBookmark = () => {
trackEvent("bookmark_added", {
timestamp: Date.now(),
})
}

// Display metrics
useEffect(() => {
const interval = setInterval(() => {
const metrics = getMetrics()
console.log("Session Metrics:", metrics)
}, 5000)

return () => clearInterval(interval)
}, [getMetrics])

return (


- ✅ Automatic lifecycle management (initialization and cleanup)
- ✅ WebSocket/Socket.IO connection status monitoring
- ✅ Track custom events with trackEvent()
- ✅ Access metrics with getMetrics()
- ✅ Access all events with getEvents()
- ✅ Session ID available immediately

API Reference

$3

#### Constructor Options

`typescript
interface WontumPlayerConfig {
src: string // Video source URL (HLS manifest)
container: HTMLElement | string // Container element or selector
autoplay?: boolean // Auto-play on load (default: false)
muted?: boolean // Start muted (default: false)
controls?: boolean // Show controls (default: true)
poster?: string // Poster image URL
preload?: "none" | "metadata" | "auto" // Preload strategy
theme?: PlayerTheme // Custom theme
s3Config?: S3Config // S3/CloudFront configuration
analytics?: AnalyticsConfig // Analytics configuration
hlsConfig?: Partial // HLS.js config override
subtitles?: SubtitleTrack[] // Subtitle tracks
stickyControls?: boolean // Keep controls always visible
}

interface S3Config {
signUrl?: (url: string) => Promise // Sign URL and set cookies
cloudFrontDomains?: string[] // CloudFront domains (e.g., ['media.example.com'])
withCredentials?: boolean // Enable cookies for HLS requests (default: false, required for CloudFront signed cookies)
region?: string // S3 region
endpoint?: string // Custom S3 endpoint
}

interface AnalyticsConfig {
enabled?: boolean // Enable analytics tracking
endpoint?: string // HTTP endpoint for analytics events
webSocket?: WebSocketAnalyticsHandler | SocketIOAnalyticsHandler // Real-time streaming
sessionId?: string // Session identifier
userId?: string // User identifier
videoId?: string // Video identifier
}

// Native WebSocket Configuration
interface WebSocketAnalyticsHandler {
type: "websocket"
connection: WebSocket | string // WebSocket instance or URL
transform?: (event: AnalyticsEvent) => any // Transform before sending
onError?: (error: Event) => void
onOpen?: (event: Event) => void
onClose?: (event: CloseEvent) => void
autoReconnect?: boolean // Default: true
reconnectDelay?: number // Default: 3000ms
}

// Socket.IO Configuration
interface SocketIOAnalyticsHandler {
type: "socket.io"
connection: Socket | string // Socket.IO instance or URL
options?: Partial // Socket.IO options
eventName?: string // Event name to emit (default: "analytics")
transform?: (event: AnalyticsEvent) => any
onError?: (error: Error) => void
onConnect?: () => void
onDisconnect?: (reason: string) => void
}
`

#### Methods

`typescript
// Playback control
player.play(): Promise
player.pause(): void
player.seek(time: number): void

// Volume control
player.setVolume(volume: number): void // 0-1
player.mute(): void
player.unmute(): void

// Playback rate
player.setPlaybackRate(rate: number): void // 0.5, 1, 1.5, 2, etc.

// Quality control
player.setQuality(qualityIndex: number): void
player.getQualities(): QualityLevel[]

// Fullscreen
player.enterFullscreen(): void
player.exitFullscreen(): void

// Picture-in-Picture
player.enterPictureInPicture(): Promise
player.exitPictureInPicture(): Promise
player.togglePictureInPicture(): Promise

// State
player.getState(): PlayerState

// Events
player.on(eventType: PlayerEventType, callback: (event: PlayerEvent) => void): void
player.off(eventType: PlayerEventType, callback: (event: PlayerEvent) => void): void

// Cleanup
player.destroy(): void
`

#### Events

`typescript
type PlayerEventType =
| "play"
| "pause"
| "ended"
| "timeupdate"
| "volumechange"
| "ratechange"
| "seeked"
| "seeking"
| "waiting"
| "canplay"
| "loadedmetadata"
| "error"
| "qualitychange"
| "fullscreenchange"
| "pictureinpictureenter"
| "pictureinpictureexit"
`

$3

#### WontumPlayerReact

`tsx
src="https://example.com/video.m3u8"
width="100%"
height="500px"
autoplay={false}
muted={false}
controls={true}
poster="https://example.com/poster.jpg"
onReady={(player) => console.log("Player ready", player)}
onPlay={() => console.log("Playing")}
onPause={() => console.log("Paused")}
onEnded={() => console.log("Ended")}
onTimeUpdate={(time) => console.log("Time:", time)}
onVolumeChange={(volume, muted) => console.log("Volume:", volume, muted)}
onError={(error) => console.error("Error:", error)}
theme={{
primaryColor: "#3b82f6",
accentColor: "#60a5fa",
fontFamily: "Inter, sans-serif",
}}
analytics={{
enabled: true,
videoId: "video_123",
userId: "user_456",
}}
/>
`

Important: Changing Video Source

The WontumPlayerReact component properly handles video source changes. When you update the src prop, the player will:

- ✅ Clean up the previous player instance completely
- ✅ Remove all DOM elements (controls, progress bars)
- ✅ Reinitialize with the new video source
- ✅ Maintain control visibility and functionality

`tsx
function VideoModal() {
const [currentVideo, setCurrentVideo] = useState("video1.m3u8")

return (
src={currentVideo} // ✅ Simply change the src - no need for React key tricks!
width="100%"
height="100%"
controls
stickyControls
/>
)
}
`

Advanced: Using updateSource() for Better Performance

For even better performance when changing sources, you can use the updateSource() method via the onReady callback:

`tsx
function VideoPlayer() {
const [videos] = useState(["https://example.com/video1.m3u8", "https://example.com/video2.m3u8", "https://example.com/video3.m3u8"])
const [currentIndex, setCurrentIndex] = useState(0)
const playerRef = useRef(null)

const handleReady = (player: WontumPlayer) => {
playerRef.current = player
}

const switchVideo = async (index: number) => {
if (playerRef.current) {
// Use updateSource for efficient source changes (no full reinitialization)
await playerRef.current.updateSource(videos[index])
setCurrentIndex(index)
}
}

return (


`tsx
function CustomPlayer() {
const { containerRef, player, state } = useWontumPlayer({
src: "https://example.com/video.m3u8",
controls: false, // Build custom controls
})

return (