MediaKit.js Complete Documentation

1. Quick-Start

Basic Setup

html
Copy
<!-- Load the library -->
<script src="https://cdn.mediathrive.com/js/mediakit.js"></script>

<!-- Add player container -->
<div data-mediathrive>
  <div class="mediakit-audio-player"></div>
  <div class="mediakit-video-player"></div>
</div>

The script automatically calculates the correct manifest URL for the current page and loads it. If the URL returns 404, no player is shown.

---

2. Complete Container Attributes

Core Attributes

Player Container Configuration

Ads Configuration (NEW)

Example with All Options

html
Copy
<div
  data-mediathrive
  data-manifest="https://cdn.mediathrive.com/custom/manifest.json"
  data-log-level="DEBUG"
  data-ads="true"
  data-ad-account="12345678,87654321"
  data-description-url="https://example.com/article"
  data-audio-div="custom-audio-container"
  data-video-div="custom-video-container"
>
  <div class="custom-audio-container"></div>
  <div class="custom-video-container"></div>
</div>

---

3. Complete Player API

Global Object: window.MTMediaKit

Initialization Methods

Player Management

Constants

javascript
Copy
MTMediaKit.LOG_LEVELS = {
  ERROR: 0,
  WARN: 1,
  INFO: 2,
  DEBUG: 3
}

---

4. Audio Player Instance API

Once you have a player instance via getInstance():

Playback Control

javascript
Copy
const player = MTMediaKit.getInstance('player-id');

player.play(episode);        // Play specific episode
player.pause();              // Pause playback
player.toggle(episode);      // Toggle play/pause
player.seek(timeInSeconds);  // Seek to position
player.seekBy(seconds);      // Seek forward/backward
player.playbackRate(rate);  // Set speed (0.5, 1.0, 1.25, 1.5, 2.0)

Audio Management

javascript
Copy
player.toggleMute();              // Toggle mute
player.isPlaying(episode);        // Check if playing
player.changeSource(newAudio);    // Change source
player.setAutoplayEnabled(bool);  // Enable/disable autoplay
player.clearAutoplayError();      // Clear autoplay error

UI Control

javascript
Copy
player.openPlaylist();    // Open playlist
player.togglePlaylist();  // Toggle playlist visibility

---

5. Complete Events System

Audio Events

Progress Events

Ad Events (NEW)

Event Listeners

javascript
Copy
// Using MediaPlayerManager
const manager = MediaPlayerManager.getInstance();
manager.on('audio-started', (event) => {
  console.log('Audio started:', event.detail);
});

// Using DOM events
document.addEventListener('audio-progress', (e) => {
  console.log(`Progress: ${e.detail.progress}%`);
});

---

6. Multi-Language Support (NEW)

MediaKit supports 35 languages with automatic detection and CDN-based loading:

Supported Languages

• Arabic: AE, SA
• European: Bulgarian, Czech, Danish, German, Greek, Spanish (ES, MX), Finnish, French (CA, FR), Croatian, Italian, Dutch, Polish, Portuguese (BR, PT), Romanian, Russian, Slovak, Swedish
• English: AU, CA, GB, US
• Asian: Chinese, Japanese, Korean, Hindi, Indonesian, Malay, Filipino, Tamil
• Other: Turkish, Ukrainian

Language Configuration

The language is automatically detected from the domain's theme configuration. Translations are loaded from:

https://cdn.mediathrive.com/sdk/translation/{language}.json

---

7. Theme & Branding System (NEW)

MediaKit includes a sophisticated theming system that adapts to different domains:

Theme Structure

javascript
Copy
{
  domain: "example.com",
  logos: {
    primary: "https://cdn.example.com/logo.png"
  },
  colors: {
    primary: "#0000FF",
    accent: "#00FF00"
  },
  language: "en-US",
  features: {
    podcast: true  // Enable podcast features
  }
}

Features

• Automatic theme loading based on domain
• Custom colors and logos per domain
• Feature flags for enabling/disabling functionality
• Fallback to MediaThrive default theme

---

8. Analytics & Tracking (NEW)

MediaKit includes built-in analytics:

Automatic Event Tracking

• Media loaded events
• Play, pause, and progress tracking
• Session completion
• Team account and media UUID tracking

Event Format

javascript
Copy
{
  event: "play|pause|start|auto_percent|session_end",
  team_account_id: "12345",
  media: "audio-uuid",
  url_hash: "page-hash",
  media_type: "audio",
  percent: "25"  // For progress events
}

---

9. Advanced Features

Ads Integration (NEW)

html
Copy
<!-- Enable ads with default settings -->
<div data-mediathrive data-ads="true">
  <div class="mediakit-audio-player"></div>
</div>

<!-- Custom ad configuration -->
<div 
  data-mediathrive 
  data-ads="true"
  data-ad-account="your-account-id"
  data-ad-tag="https://your-vast-url.com"
>
  <div class="mediakit-audio-player"></div>
</div>

Podcast Mode (NEW)

• Automatically activated after 3 consecutive audio plays
• Enhanced UI for podcast listening
• Persistent playback preferences

Autoplay Handling

• Smart autoplay permission handling
• User-friendly permission prompts
• Fallback for blocked autoplay

Progress Persistence

• Saves playback position
• Resume from last position
• Cross-session support

Up Next Notification

• Shows next content suggestion
• Auto-advance capability
• User preference persistence

---

10. Complete Example

html
Copy
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>MediaKit Complete Example</title>
  <script src="https://cdn.mediathrive.com/js/mediakit.js"></script>
</head>
<body>
  <h1>MediaKit Examples</h1>

  <!-- Basic Player -->
  <div data-mediathrive data-manifest="https://example.com/manifest.json">
    <div class="mediakit-audio-player"></div>
  </div>

  <!-- Player with Ads -->
  <div 
    data-mediathrive 
    data-ads="true"
    data-log-level="DEBUG"
  >
    <div class="mediakit-audio-player"></div>
  </div>

  <!-- Player with Custom Configuration -->
  <div 
    data-mediathrive
    data-ads="true"
    data-ad-account="12345678"
    data-log-level="INFO"
  >
    <div class="mediakit-audio-player"></div>
    <div class="mediakit-video-player"></div>
  </div>

  <script>
    // Access the global API
    const MT = window.MTMediaKit;
    
    // Set log level
    MT.setLogLevel(MT.LOG_LEVELS.DEBUG);
    
    // Listen to events
    document.addEventListener('audio-started', (e) => {
      console.log('Audio started:', e.detail);
      
      // Access player instance
      const player = MT.getInstance(e.detail.playerId);
      
      // Control playback
      setTimeout(() => {
        player.playbackRate(1.5); // Speed up
      }, 5000);
    });
    
    // Track progress
    document.addEventListener('audio-progress', (e) => {
      console.log(`Progress: ${e.detail.progress}%`);
    });
    
    // Handle ads
    document.addEventListener('ad-started', (e) => {
      console.log('Ad playing:', e.detail);
    });
  </script>
</body>
</html>

---

11. Manifest File Structure

MediaKit uses JSON manifests to define content. Here's the complete structure:

json
Copy
{
  "audio": {
    "en": {
      "src": "https://example.com/audio-en.mp3",
      "type": "audio/mpeg",
      "uuid": "unique-audio-id",
      "language": "en-US",
      "title": "Episode Title",
      "description": "Episode description"
    },
    "es": {
      "src": "https://example.com/audio-es.mp3",
      "type": "audio/mpeg",
      "uuid": "unique-audio-id-es",
      "language": "es-ES"
    }
  },
  "video": {
    "src": "https://example.com/video.m3u8",
    "type": "application/x-mpegURL",
    "poster": "https://example.com/poster.jpg"
  },
  "metadata": {
    "title": "Article Title",
    "author": "Author Name",
    "publicationDate": "2024-01-01",
    "description": "Article description",
    "url": "https://example.com/article"
  },
  "suggestion": {
    "title": "Next Article Title",
    "url": "https://example.com/next-article"
  }
}

---

12. Styling & Customization

CSS Namespace

All MediaKit styles are namespaced under [data-mediathrive]:

css
Copy
[data-mediathrive] {
  /* Your custom styles */
  --mt-primary-color: #0066cc;
  --mt-accent-color: #00aa66;
}

[data-mediathrive] .mediakit-audio-player {
  /* Audio player specific styles */
}

Tailwind Classes

Internal components use Tailwind with mtk: prefix to avoid conflicts:

• mtk:flex
• mtk:bg-white
• mtk:text-sm
• etc.

---

13. Browser Support

Minimum Requirements

• Chrome 80+
• Firefox 75+
• Safari 13+
• Edge 80+

Features

• ES6+ JavaScript
• Shadow DOM for style isolation
• Web Audio API for audio playback
• Media Source Extensions for video
• LocalStorage for preferences

---

14. Performance Optimization

Lazy Loading

• Video.js loads only when video content is present
• Translations load on-demand
• Theme data cached for 24 hours

Bundle Size

• Core audio player: ~250KB (minified + gzipped)
• Video player addon: ~150KB (loaded on demand)
• IMA SDK for ads: ~100KB (loaded when ads enabled)

Caching Strategy

• Manifest data: 1 year cache
• Theme data: 24-hour cache
• Translation files: Browser cache
• Media files: CDN optimized

---

15. Security Considerations

Content Security Policy (CSP)

Required CSP directives:

html
Copy
<meta http-equiv="Content-Security-Policy" content="
  script-src 'self' https://cdn.mediathrive.com https://imasdk.googleapis.com;
  connect-src 'self' https://cdn.mediathrive.com https://pubads.g.doubleclick.net;
  media-src *;
  img-src *;
">

CORS Requirements

• Manifest files must have proper CORS headers
• Media files need Access-Control-Allow-Origin
• Analytics endpoints require CORS support

---

16. Troubleshooting Guide

Common Issues and Solutions

Player Not Visible

✓ Verify data-mediathrive attribute is present
✓ Check browser console for errors
✓ Confirm manifest URL returns valid JSON (404 is OK if no content)
✓ Check log level for debugging info

No Audio/Video

✓ Verify media URLs in manifest are accessible
✓ Check CORS headers for cross-domain content
✓ Confirm correct MIME types for media files
✓ Test with data-demo for known working content

Ads Not Playing

✓ Ensure data-ads="true" is set (ads are off by default)
✓ Check browser console for IMA SDK errors
✓ Verify ad account has valid campaigns
✓ Test with default account first

Autoplay Issues

✓ Browser policies may block autoplay
✓ MediaKit shows permission prompt automatically
✓ User interaction required for first play

Styling Problems

✓ Use CSS namespacing under [data-mediathrive]
✓ Check for conflicting global styles
✓ Tailwind classes use mtk: prefix

Language Not Loading

✓ Check theme configuration for language setting
✓ Verify translation file exists on CDN
✓ Falls back to English if translation missing

---

17. Migration Guide

From Version 1.x to 2.x

• Change data-use-default-ads to data-ads
• Update event listeners from MediaThrive to MTMediaKit
• Audio player API methods now on instance, not global

From Custom Players

1. Add MediaKit script tag
2. Wrap existing containers with data-mediathrive
3. Map your manifest to MediaKit format
4. Update event listeners to MediaKit events
5. Test with data-demo first

---

18. API Reference Quick Links

Most Used Methods

javascript
Copy
// Initialize
MTMediaKit.init();

// Get player
const player = MTMediaKit.getInstance('player-id');

// Control playback
player.play();
player.pause();
player.seek(30);

// Listen to events
document.addEventListener('audio-started', handler);
document.addEventListener('audio-progress', handler);

Most Used Attributes

html
Copy
<!-- Basic -->
<div data-mediathrive data-manifest="url.json"></div>

<!-- With ads -->
<div data-mediathrive data-ads="true"></div>

<!-- Debug mode -->
<div data-mediathrive data-log-level="DEBUG"></div>

<!-- Demo content -->
<div data-mediathrive data-demo></div>

---

Support & Resources

• Email: [email protected]

---

Last Updated: August 2025
Version: 2.0.0
License: Proprietary - MediaThrive Inc.

Happy streaming with MediaKit! 🎵 📺