0
# Utility Functions
1

2
Video.js provides comprehensive utility modules for DOM manipulation, time handling, browser detection, string processing, and more, organized into logical namespaces.
3

4
## Capabilities
5

6
### DOM Utilities
7

8
Comprehensive DOM manipulation utilities for cross-browser compatibility.
9

10
```javascript { .api }
11
/**
12
 * DOM manipulation utilities namespace
13
 */
14
videojs.dom: {
15
  /**
16
   * Check if value is a DOM element
17
   * @param value - Value to check
18
   * @returns True if DOM element
19
   */
20
  isEl(value: any): boolean;
21
  
22
  /**
23
   * Check if value is a text node
24
   * @param value - Value to check
25
   * @returns True if text node
26
   */
27
  isTextNode(value: any): boolean;
28
  
29
  /**
30
   * Create DOM element with properties
31
   * @param tagName - Element tag name
32
   * @param properties - Element properties and attributes
33
   * @param attributes - Element attributes
34
   * @param content - Element content
35
   * @returns Created element
36
   */
37
  createEl(tagName: string, properties?: object, attributes?: object, content?: string): Element;
38
  
39
  /**
40
   * Find element by CSS selector
41
   * @param selector - CSS selector
42
   * @param context - Search context (default: document)
43
   * @returns Found element or null
44
   */
45
  $(selector: string, context?: Element): Element | null;
46
  
47
  /**
48
   * Find all elements by CSS selector
49
   * @param selector - CSS selector
50
   * @param context - Search context (default: document)
51
   * @returns NodeList of found elements
52
   */
53
  $$(selector: string, context?: Element): NodeList;
54
}
55
```
56

57
**Usage Examples:**
58

59
```javascript
60
// Element creation
61
const button = videojs.dom.createEl('button', {
62
  className: 'vjs-custom-button',
63
  textContent: 'Click Me'
64
}, {
65
  'data-id': 'custom-btn',
66
  'aria-label': 'Custom Button'
67
});
68

69
// Element queries
70
const player = videojs.dom.$('.video-js');
71
const controls = videojs.dom.$$('.vjs-control', player);
72

73
// Element checks
74
if (videojs.dom.isEl(button)) {
75
  console.log('Is a DOM element');
76
}
77
```
78

79
### CSS Class Management
80

81
Cross-browser CSS class manipulation utilities.
82

83
```javascript { .api }
84
/**
85
 * Add CSS class to element
86
 * @param element - Target element
87
 * @param className - Class name to add
88
 */
89
addClass(element: Element, className: string): void;
90

91
/**
92
 * Remove CSS class from element
93
 * @param element - Target element
94
 * @param className - Class name to remove
95
 */
96
removeClass(element: Element, className: string): void;
97

98
/**
99
 * Toggle CSS class on element
100
 * @param element - Target element
101
 * @param className - Class name to toggle
102
 * @param predicate - Force add (true) or remove (false)
103
 */
104
toggleClass(element: Element, className: string, predicate?: boolean): void;
105

106
/**
107
 * Check if element has CSS class
108
 * @param element - Target element
109
 * @param className - Class name to check
110
 * @returns True if class exists
111
 */
112
hasClass(element: Element, className: string): boolean;
113
```
114

115
**Usage Examples:**
116

117
```javascript
118
const element = videojs.dom.$('.video-js');
119

120
// Class manipulation
121
videojs.dom.addClass(element, 'vjs-custom-theme');
122
videojs.dom.removeClass(element, 'vjs-default-skin');
123
videojs.dom.toggleClass(element, 'vjs-fullscreen');
124

125
// Class checking
126
if (videojs.dom.hasClass(element, 'vjs-playing')) {
127
  console.log('Player is playing');
128
}
129
```
130

131
### Element Attributes
132

133
Utilities for managing element attributes and properties.
134

135
```javascript { .api }
136
/**
137
 * Set multiple attributes on element
138
 * @param element - Target element
139
 * @param attributes - Object with attribute key-value pairs
140
 */
141
setAttributes(element: Element, attributes: object): void;
142

143
/**
144
 * Get element attributes as object
145
 * @param element - Target element
146
 * @returns Object with attribute key-value pairs
147
 */
148
getAttributes(element: Element): object;
149

150
/**
151
 * Get computed styles for element
152
 * @param element - Target element
153
 * @param property - Specific property to get
154
 * @returns Computed style value or CSSStyleDeclaration
155
 */
156
computedStyle(element: Element, property?: string): string | CSSStyleDeclaration;
157
```
158

159
**Usage Examples:**
160

161
```javascript
162
const element = videojs.dom.$('.video-js');
163

164
// Set attributes
165
videojs.dom.setAttributes(element, {
166
  'data-setup': '{}',
167
  'controls': true,
168
  'preload': 'metadata'
169
});
170

171
// Get attributes
172
const attrs = videojs.dom.getAttributes(element);
173
console.log('Element attributes:', attrs);
174

175
// Get computed styles
176
const width = videojs.dom.computedStyle(element, 'width');
177
console.log('Element width:', width);
178
```
179

180
### Element Content Management
181

182
Utilities for managing element content and structure.
183

184
```javascript { .api }
185
/**
186
 * Empty element of all content
187
 * @param element - Target element
188
 */
189
emptyEl(element: Element): void;
190

191
/**
192
 * Append content to element
193
 * @param element - Target element
194
 * @param content - Content to append (string, Element, or array)
195
 */
196
appendContent(element: Element, content: string | Element | Array<string | Element>): void;
197

198
/**
199
 * Insert content into element
200
 * @param element - Target element
201
 * @param content - Content to insert
202
 * @param position - Insert position
203
 */
204
insertContent(element: Element, content: string | Element, position?: number): void;
205
```
206

207
### Time Utilities
208

209
Comprehensive time and TimeRanges utilities for media handling.
210

211
```javascript { .api }
212
/**
213
 * Time utilities namespace
214
 */
215
videojs.time: {
216
  /**
217
   * Create TimeRanges object
218
   * @param start - Start time or array of ranges
219
   * @param end - End time
220
   * @returns TimeRanges object
221
   */
222
  createTimeRanges(start: number | Array<[number, number]>, end?: number): TimeRanges;
223
  
224
  /**
225
   * Format time in seconds to readable string
226
   * @param seconds - Time in seconds
227
   * @param guide - Guide time for formatting decisions
228
   * @returns Formatted time string (e.g., "1:23" or "1:23:45")
229
   */
230
  formatTime(seconds: number, guide?: number): string;
231
  
232
  /**
233
   * Set custom time formatting function
234
   * @param customFormatter - Custom formatting function
235
   */
236
  setFormatTime(customFormatter: (seconds: number, guide?: number) => string): void;
237
  
238
  /**
239
   * Reset time formatting to default
240
   */
241
  resetFormatTime(): void;
242
}
243
```
244

245
**Usage Examples:**
246

247
```javascript
248
// Create time ranges
249
const buffered = videojs.time.createTimeRanges([[0, 30], [60, 90]]);
250
console.log('Buffered ranges:', buffered.length);
251

252
// Format time display
253
const currentTime = 125.5;
254
const duration = 3600;
255
console.log('Time:', videojs.time.formatTime(currentTime, duration)); // "2:05"
256

257
// Custom time formatter
258
videojs.time.setFormatTime((seconds) => {
259
  const mins = Math.floor(seconds / 60);
260
  const secs = Math.floor(seconds % 60);
261
  return `${mins}m ${secs}s`;
262
});
263

264
console.log(videojs.time.formatTime(125)); // "2m 5s"
265

266
// Reset to default
267
videojs.time.resetFormatTime();
268
```
269

270
### Browser Detection
271

272
Comprehensive browser and platform detection utilities.
273

274
```javascript { .api }
275
/**
276
 * Browser detection utilities namespace
277
 */
278
videojs.browser: {
279
  // Browser detection flags
280
  IS_CHROME: boolean;
281
  IS_FIREFOX: boolean;
282
  IS_SAFARI: boolean;
283
  IS_EDGE: boolean;
284
  IS_IE: boolean;
285
  
286
  // Platform detection flags  
287
  IS_IOS: boolean;
288
  IS_ANDROID: boolean;
289
  IS_WINDOWS: boolean;
290
  IS_MAC: boolean;
291
  
292
  // Device type flags
293
  IS_MOBILE: boolean;
294
  IS_TABLET: boolean;
295
  IS_DESKTOP: boolean;
296
  IS_SMART_TV: boolean;
297
  
298
  // Feature detection
299
  TOUCH_ENABLED: boolean;
300
  BACKGROUND_SIZE_SUPPORTED: boolean;
301
  
302
  // Version information
303
  CHROME_VERSION: number;
304
  FIREFOX_VERSION: number;
305
  SAFARI_VERSION: number;
306
  IOS_VERSION: number;
307
  ANDROID_VERSION: number;
308
}
309
```
310

311
**Usage Examples:**
312

313
```javascript
314
// Browser-specific behavior
315
if (videojs.browser.IS_SAFARI) {
316
  console.log('Safari-specific optimizations');
317
}
318

319
if (videojs.browser.IS_MOBILE) {
320
  console.log('Mobile interface adjustments');
321
  player.addClass('vjs-mobile');
322
}
323

324
// Version-based features
325
if (videojs.browser.CHROME_VERSION >= 70) {
326
  console.log('Modern Chrome features available');
327
}
328

329
// Feature detection
330
if (videojs.browser.TOUCH_ENABLED) {
331
  player.addClass('vjs-touch-enabled');
332
}
333
```
334

335
### Object Utilities
336

337
Utilities for object manipulation and property management.
338

339
```javascript { .api }
340
/**
341
 * Object utilities namespace
342
 */
343
videojs.obj: {
344
  /**
345
   * Deep merge objects
346
   * @param target - Target object
347
   * @param sources - Source objects to merge
348
   * @returns Merged object
349
   */
350
  merge(target: object, ...sources: object[]): object;
351
  
352
  /**
353
   * Define lazy property that's computed on first access
354
   * @param object - Target object
355
   * @param key - Property key
356
   * @param getValue - Function to compute value
357
   * @param setValue - Function to set value (optional)
358
   */
359
  defineLazyProperty(object: object, key: string, getValue: () => any, setValue?: (value: any) => void): void;
360
  
361
  /**
362
   * Check if value is a plain object
363
   * @param value - Value to check
364
   * @returns True if plain object
365
   */
366
  isObject(value: any): boolean;
367
}
368
```
369

370
**Usage Examples:**
371

372
```javascript
373
// Merge configuration objects
374
const defaultOptions = { controls: true, autoplay: false };
375
const userOptions = { autoplay: true, volume: 0.8 };
376
const finalOptions = videojs.obj.merge({}, defaultOptions, userOptions);
377
// Result: { controls: true, autoplay: true, volume: 0.8 }
378

379
// Lazy properties for expensive computations
380
const obj = {};
381
videojs.obj.defineLazyProperty(obj, 'expensiveValue', () => {
382
  console.log('Computing expensive value...');
383
  return performExpensiveOperation();
384
});
385

386
// Value computed only when first accessed
387
console.log(obj.expensiveValue);
388
```
389

390
### String Utilities
391

392
String processing utilities for text manipulation.
393

394
```javascript { .api }
395
/**
396
 * String utilities namespace
397
 */
398
videojs.str: {
399
  /**
400
   * Convert string to title case
401
   * @param str - Input string
402
   * @returns Title case string
403
   */
404
  toTitleCase(str: string): string;
405
  
406
  /**
407
   * Convert string to lower case
408
   * @param str - Input string
409
   * @returns Lower case string
410
   */
411
  toLowerCase(str: string): string;
412
  
413
  /**
414
   * Compare strings in title case
415
   * @param str1 - First string
416
   * @param str2 - Second string
417
   * @returns True if equal in title case
418
   */
419
  titleCaseEquals(str1: string, str2: string): boolean;
420
}
421
```
422

423
### Number Utilities
424

425
Number processing and validation utilities.
426

427
```javascript { .api }
428
/**
429
 * Number utilities namespace
430
 */
431
videojs.num: {
432
  /**
433
   * Clamp number between min and max values
434
   * @param number - Input number
435
   * @param min - Minimum value
436
   * @param max - Maximum value
437
   * @returns Clamped number
438
   */
439
  clamp(number: number, min: number, max: number): number;
440
}
441
```
442

443
### URL Utilities
444

445
URL parsing and manipulation utilities.
446

447
```javascript { .api }
448
/**
449
 * URL utilities namespace
450
 */
451
videojs.url: {
452
  /**
453
   * Parse URL into components
454
   * @param url - URL string to parse
455
   * @returns Parsed URL components
456
   */
457
  parseUrl(url: string): UrlComponents;
458
  
459
  /**
460
   * Check if URL is cross-origin
461
   * @param url - URL to check
462
   * @param winLoc - Window location (optional)
463
   * @returns True if cross-origin
464
   */
465
  isCrossOrigin(url: string, winLoc?: Location): boolean;
466
  
467
  /**
468
   * Get absolute URL from relative URL
469
   * @param url - Relative URL
470
   * @returns Absolute URL
471
   */
472
  getAbsoluteURL(url: string): string;
473
}
474
```
475

476
### Function Utilities
477

478
Function-related utilities for binding and manipulation.
479

480
```javascript { .api }
481
/**
482
 * Function utilities namespace
483
 */
484
videojs.fn: {
485
  /**
486
   * Bind function to context (deprecated - use native bind)
487
   * @param context - Context to bind to
488
   * @param fn - Function to bind
489
   * @param uid - Unique identifier
490
   * @returns Bound function
491
   */
492
  bind_(context: any, fn: Function, uid?: number): Function;
493
  
494
  /**
495
   * Create GUID/UUID
496
   * @returns Unique identifier string
497
   */
498
  newGUID(): string;
499
}
500
```
501

502
### Logging Utilities
503

504
Comprehensive logging system with levels and namespaces.
505

506
```javascript { .api }
507
/**
508
 * Main logging function
509
 * @param messages - Messages to log
510
 */
511
videojs.log(...messages: any[]): void;
512

513
/**
514
 * Create named logger
515
 * @param name - Logger name
516
 * @returns Logger function
517
 */
518
videojs.createLogger(name: string): LoggerFunction;
519

520
// Logging levels
521
videojs.log.level: LogLevel;
522
videojs.log.debug: LoggerFunction;
523
videojs.log.info: LoggerFunction;
524
videojs.log.warn: LoggerFunction;
525
videojs.log.error: LoggerFunction;
526
```
527

528
**Usage Examples:**
529

530
```javascript
531
// Basic logging
532
videojs.log('Player initialized');
533

534
// Create named logger
535
const pluginLogger = videojs.createLogger('MyPlugin');
536
pluginLogger('Plugin action performed');
537

538
// Set log level
539
videojs.log.level('warn'); // Only show warnings and errors
540

541
// Different log levels
542
videojs.log.debug('Debug information');
543
videojs.log.info('Informational message');
544
videojs.log.warn('Warning message');
545
videojs.log.error('Error message');
546
```
547

548
### Deprecated Utilities
549

550
Legacy utility methods maintained for backward compatibility.
551

552
```javascript { .api }
553
// Deprecated DOM methods (use videojs.dom.* instead)
554
videojs.isEl(element): boolean; // Use videojs.dom.isEl
555
videojs.createEl(tagName, props): Element; // Use videojs.dom.createEl
556
videojs.addClass(element, className): void; // Use videojs.dom.addClass
557

558
// Deprecated time methods (use videojs.time.* instead)
559
videojs.createTimeRange(start, end): TimeRanges; // Use videojs.time.createTimeRanges
560
videojs.formatTime(seconds): string; // Use videojs.time.formatTime
561

562
// Deprecated object methods (use videojs.obj.* instead)
563
videojs.mergeOptions(obj1, obj2): object; // Use videojs.obj.merge
564
```
565

566
## Types
567

568
```javascript { .api }
569
interface UrlComponents {
570
  protocol: string;
571
  hostname: string;
572
  port: string;
573
  pathname: string;
574
  search: string;
575
  hash: string;
576
  host: string;
577
}
578

579
interface LoggerFunction {
580
  (...messages: any[]): void;
581
  level?: LogLevel;
582
}
583

584
type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'off';
585

586
interface TimeRanges {
587
  readonly length: number;
588
  start(index: number): number;
589
  end(index: number): number;
590
}
591

592
// Utility namespaces
593
interface DomUtils {
594
  isEl(value: any): boolean;
595
  createEl(tagName: string, properties?: object): Element;
596
  addClass(element: Element, className: string): void;
597
  removeClass(element: Element, className: string): void;
598
  hasClass(element: Element, className: string): boolean;
599
  $(selector: string, context?: Element): Element | null;
600
  $$(selector: string, context?: Element): NodeList;
601
}
602

603
interface TimeUtils {
604
  createTimeRanges(start: number | Array<[number, number]>, end?: number): TimeRanges;
605
  formatTime(seconds: number, guide?: number): string;
606
  setFormatTime(formatter: (seconds: number, guide?: number) => string): void;
607
  resetFormatTime(): void;
608
}
609

610
interface ObjectUtils {
611
  merge(target: object, ...sources: object[]): object;
612
  defineLazyProperty(object: object, key: string, getValue: () => any): void;
613
  isObject(value: any): boolean;
614
}
615
```