MediaKit.JS

Learn how to install and configure MediaThrive.js on your website.

Overview

The MediaThrive MediaKit provides a JavaScript library that simplifies the integration of audio and video content into your website. With features such as automated media embedding, manifest-based content configuration, and a flexible audio/video player, the MediaKit enables seamless integration of MediaThrive's powerful content tools.

Configuration

Including the MediaKit Library

Before using any MediaThrive features, you need to include the MediaKit JavaScript library in your HTML. Add the following script tag to your HTML file, preferably in the <head> section or just before the closing </body> tag:

<script src="https://cdn.mediathrive.com/js/mediakit.js"></script>

Once the script is loaded, you can then use the MediaThrive container elements and APIs in your page.

Container Attributes

The MediaKit can be configured using data attributes on the container element:

<div
    data-mediathrive
    data-manifest="https://cdn.mediathrive.com/news/example/manifest.json"
    data-log-level="DEBUG"
    data-videosrc="https://example.com/video.m3u8"
    data-demo
>
  <div class="mediakit-audio-player"></div>
  <div class="mediakit-video-player"></div>
</div>

Available Attributes:

data-manifest: URL to the manifest JSON file
data-log-level: Controls logging verbosity (ERROR, WARN, INFO, DEBUG)
data-videosrc: URL to the video source (for video player)
data-demo: Enable demo mode to load a random manifest from the demo collection

Demo Mode

The MediaKit includes a demo mode that loads a random manifest from a predefined collection. This is useful for testing and demonstration purposes.

To enable demo mode, add the data-demo attribute to your container:

<div
    data-mediathrive
    data-demo
>
    <div class="mediakit-audio-player"></div>
    <div class="mediakit-video-player"></div>
</div>

When demo mode is enabled:

The MediaKit fetches a collection of manifests from https://cdn.mediathrive.com/demo.json
A random manifest is selected from the collection
The player is initialized with the selected manifest

This allows you to quickly test the MediaKit with real content without needing to specify a manifest URL.

CDN Loading for Video Player

For optimized performance, the MediaKit loads video.js and its plugins from a CDN only when needed, significantly reducing the initial bundle size. This feature has the following benefits:

Reduced Initial Load Time: The main MediaKit bundle is significantly smaller
On-Demand Loading: Video.js is only loaded when a video player is detected on the page
Parallel Resource Loading: Loading from CDN allows for parallel downloading from multiple domains

The video player components are loaded from the following CDN sources:

video.js from jsdelivr.net
Supporting plugins for HLS and quality selection

During loading, a visual indicator displays the status to users. If loading fails (e.g., due to network issues), an error message is shown and proper error logging is recorded.

Manifest File

The MediaKit relies on a manifest JSON file to define available media content. The structure is as follows:

{
  "audio": {
    "en": {
      "summary": {
        "src": "https://cdn.mediathrive.com/audio/summary.mp3",
        "audio_type": "audio/mpeg"
      },
      "detailed": {
        "src": "https://cdn.mediathrive.com/audio/detailed.mp3",
        "audio_type": "audio/mpeg"
      }
    },
    "es": {
      "summary": {
        "src": "https://cdn.mediathrive.com/audio/spanish-summary.mp3",
        "audio_type": "audio/mpeg"
      }
    }
  }
}

Dynamic URL Hashing

If the data-manifest attribute is omitted, the library generates a manifest URL dynamically using MD5 hashes of the domain and current URL.

Features

1. Automated Content Embedding

Media is embedded dynamically based on the manifest or current URL context.

2. Flexible Audio/Video Player

Play, Pause, Rewind, Forward controls.
Playlist Support.
Language Selection.

3. Performance Optimizations

Supports ES module output for modern browsers.
Configurable cache-control headers for optimal delivery.

Event System

The MediaKit provides a robust event system that allows you to hook into various player events and respond to them in your application.

Available Events

Player Lifecycle Events

audio-started: Emitted when audio playback starts
audio-paused: Emitted when audio playback is paused
audio-ended: Emitted when audio playback reaches the end

Progress Events

audio-progress: Emitted during playback with current progress information (at 10% intervals)
Specific milestone events: audio-progress-0, audio-progress-10, audio-progress-20, etc. up to audio-progress-100

Usage Examples

// Get the MediaPlayerManager instance
const manager = window.MTMediaKit.playerManager;

// Listen for playback start
manager.addEventListener('audio-started', () => {
  console.log('Audio playback has started');
});

// Track progress at 10% intervals
manager.addEventListener('audio-progress', (event) => {
  console.log(`Playback progress: ${event.detail.progress}%`);
  console.log(`Current time: ${event.detail.currentTime} seconds`);
  console.log(`Total duration: ${event.detail.duration} seconds`);
});

// Execute code at specific milestones
manager.addEventListener('audio-progress-50', () => {
  console.log('Audio is halfway complete!');
  // Perhaps show a survey or feedback form
});

manager.addEventListener('audio-progress-100', () => {
  console.log('Audio playback complete!');
  // Maybe show related content recommendations
});

// Using the shorthand methods
manager.on('audio-paused', () => console.log('Audio paused'));

Event Data Structure

All events provide a detail object with relevant information:

{
  playerId: "mt-player-abc123", // Unique ID of the player
  currentTime: 45,              // Current playback position in seconds
  duration: 90,                 // Total duration in seconds
  progress: 50                  // Progress percentage (0-100)
}

Logging System

The MediaKit includes a centralized logging system that allows you to control the verbosity of logs across the application.

Log Levels

The following log levels are available, in order of severity:

ERROR (3): Only critical errors that prevent functionality
WARN (2): Warnings about potential issues
INFO (1): General information about operations (default)
DEBUG (0): Detailed debugging information

Setting the Log Level

You can set the log level in several ways:

1. Using the data-log-level attribute

The simplest way to control logging is to set the data-log-level attribute on your MediaThrive container:

<div 
    data-mediathrive 
    data-log-level="DEBUG"
    data-manifest="https://example.com/manifest.json"
>
    <div class="mediakit-audio-player"></div>
    <div class="mediakit-video-player"></div>
</div>

Valid values for data-log-level are:

"ERROR" - Only show errors
"WARN" - Show warnings and errors
"INFO" - Show info, warnings, and errors (default)
"DEBUG" - Show all logs, including debug information
Numeric values 0 (DEBUG) through 3 (ERROR)

2. During initialization

// Set log level during initialization
window.MT_LOG_LEVEL_CONFIG = window.MTMediaKit.LOG_LEVELS.DEBUG;

3. Using the setLogLevel method

// Get the MediaKit instance
const mediaKit = window.MTMediaKit;

// Set log level to show only errors
mediaKit.setLogLevel(mediaKit.LOG_LEVELS.ERROR);

// Set log level to show all debug information
mediaKit.setLogLevel(mediaKit.LOG_LEVELS.DEBUG);

4. Setting the global variable directly

// Set log level to show warnings and errors only
window.MT_LOG_LEVEL = 2; // WARN level

Using the Logger in Custom Code

If you're extending the MediaKit or integrating with it, you can use the same logging system:

import { LOG_LEVELS, logDebug, logInfo, logWarn, logError } from 'mediathrive-mediakit/lib/logger';

// Log at different levels
logError('This is an error message');
logWarn('This is a warning message');
logInfo('This is an info message');
logDebug('This is a debug message', { someData: 'value' });