Developer Quickstart

🚀 Setup

# Clone repository
git clone github.com/MatthiasPeltzer/vidply.git
cd vidply

# Install dependencies
npm install

# Build production files
npm run build

# Start dev server
npm run dev

Dev server runs at localhost

📁 Directory Structure

vidply/
├── build/                       # Build scripts
│   ├── build.js                 # TypeScript bundling (esbuild → ESM + IIFE)
│   ├── build-css.js             # CSS build (clean-css)
│   ├── watch.js                 # Watch mode
│   └── clean.js                 # Clean dist
├── demo/                        # Demo pages
│   ├── demo.html                # Main demo
│   ├── playlist-audio.html      # Audio playlist demo
│   ├── playlist-video.html      # Video playlist demo
│   ├── hls-test.html            # HLS streaming demo
│   ├── dash-test.html           # DASH streaming demo
│   └── single-player-dash.html  # Single DASH player demo
├── dist/                        # Built files (generated)
│   ├── prod/vidply.esm.min.js   # ES Module (production)
│   ├── legacy/vidply.min.js     # IIFE (production)
│   ├── types/index.d.ts         # TypeScript declarations
│   └── vidply.min.css           # Styles (production)
├── docs/                        # Documentation
├── src/                         # Source code (strict TypeScript)
│   ├── core/
│   │   └── Player.ts            # Main Player class
│   ├── controls/
│   │   ├── ControlBar.ts        # Control bar UI (incl. download button, buffering spinner)
│   │   ├── CaptionManager.ts    # Caption handling
│   │   ├── KeyboardManager.ts   # Keyboard shortcuts
│   │   ├── SettingsDialog.ts    # Settings menu
│   │   └── TranscriptManager.ts
│   ├── features/
│   │   └── PlaylistManager.ts   # Playlist support
│   ├── i18n/
│   │   ├── i18n.ts              # i18n system
│   │   ├── translations.ts      # Translation loader
│   │   └── languages/           # Built-in languages
│   │       ├── en.ts
│   │       ├── de.ts
│   │       ├── es.ts
│   │       ├── fr.ts
│   │       └── ja.ts
│   ├── icons/
│   │   └── Icons.ts             # SVG icon definitions
│   ├── renderers/
│   │   ├── HTML5Renderer.ts     # Native HTML5 video/audio
│   │   ├── YouTubeRenderer.ts   # YouTube iframe API
│   │   ├── VimeoRenderer.ts     # Vimeo Player API
│   │   ├── SoundCloudRenderer.ts# SoundCloud Widget API
│   │   ├── HLSRenderer.ts       # hls.js integration + native iOS bridge
│   │   └── DASHRenderer.ts      # dash.js integration
│   ├── styles/
│   │   └── vidply.css           # Main stylesheet
│   ├── types/                   # Shared TypeScript types
│   │   ├── options.ts           # PlayerOptions
│   │   └── globals.d.ts         # Ambient declarations (Hls, dashjs, …)
│   ├── utils/
│   │   ├── DOMUtils.ts          # DOM helpers
│   │   ├── EventEmitter.ts      # Event system
│   │   ├── TimeUtils.ts         # Time formatting
│   │   ├── FocusUtils.ts        # Focus management
│   │   ├── MenuUtils.ts         # Menu helpers
│   │   ├── StorageManager.ts    # localStorage wrapper
│   │   └── ...
│   └── index.ts                 # Main entry point
├── index.html                   # Development page
├── tsconfig.json                # Strict TypeScript config
├── package.json
└── server.js                    # Dev server

⚡ NPM Scripts

🏗️ Build System

TypeScript bundles (esbuild)

build/build.js consumes the TypeScript sources directly (esbuild handles transpilation) and produces:

Features:

• Code splitting (renderers loaded on demand)
• Tree shaking
• Source maps (development)
• Minification (production)

Type declarations (tsc)

npm run build:types runs tsc --emitDeclarationOnly against tsconfig.build.json and emits:

CSS (clean-css)

build/build-css.js produces:

🎯 Architecture

Core Components

Player
├── ControlBar           # UI controls
│   ├── PlayButton
│   ├── ProgressBar
│   ├── VolumeControl
│   ├── DownloadButton    # opt-in via downloadButton/downloadUrl
│   ├── PipButton         # native PiP, or pin/unpin custom floating player when floating: true
│   ├── SettingsButton
│   └── FullscreenButton
├── BufferingOverlay     # Centered loading spinner (.vidply-loading)
├── CaptionManager       # Captions/subtitles
├── KeyboardManager      # Keyboard shortcuts
├── TranscriptManager    # Interactive transcript
├── FloatingPlayerManager # Custom in-page miniplayer ("own PiP"), opt-in via floating: true
├── Renderer             # Media playback
│   ├── HTML5Renderer
│   ├── YouTubeRenderer
│   ├── VimeoRenderer
│   ├── SoundCloudRenderer
│   ├── HLSRenderer       # hls.js + native iOS TextTrack bridge
│   └── DASHRenderer
└── PlaylistManager      # Playlist handling

Event Flow

User Action → KeyboardManager/ControlBar → Player → Renderer → DOM
                                              ↓
                                         EventEmitter → External Listeners

Renderer Selection

// src/core/Player.ts
selectRenderer(src: string): RendererCtor {
  if (isYouTubeUrl(src)) return YouTubeRenderer;
  if (isVimeoUrl(src)) return VimeoRenderer;
  if (src.includes('soundcloud.com')) return SoundCloudRenderer;
  if (isHLSUrl(src)) return HLSRenderer;   // hls.js (or native HLS on iOS/iPadOS)
  if (isDASHUrl(src)) return DASHRenderer;
  return HTML5Renderer;
}

 

The HLS renderer self-decides whether to use hls.js (Chrome / Firefox / Edge / desktop Safari) or the native <video> HLS support (iOS / iPadOS where MSE is unavailable). On the native path it bridges the browser's TextTrack API into VidPly's caption / transcript / quality UI so feature parity is preserved.

 

📝 Adding Features

New Control Button

1. Add to ControlBar (src/controls/ControlBar.ts):

createMyButton(): HTMLButtonElement {
  const button = document.createElement('button');
  button.className = 'vidply-button vidply-my-button';
  button.setAttribute('aria-label', i18n.t('player.myButton'));
  button.innerHTML = Icons.myIcon;
  button.addEventListener('click', () => this.player.myAction());
  return button;
}

2. Add icon (src/icons/Icons.ts):

export const Icons = {
  // ...existing icons
  myIcon: `<svg>...</svg>`,
} as const;

3. Add translation (src/i18n/languages/en.ts):

export default {
  player: {
    // ...existing
    myButton: 'My Button',
  }
};

4. Add to Player API (src/core/Player.ts):

myAction(): void {
  this.emit('myaction');
}

New Renderer

1. Create renderer (src/renderers/MyRenderer.ts):

import type { Player } from '../core/Player';

export class MyRenderer {
  constructor(public player: Player) {}

  async init(): Promise<void> { /* ... */ }
  async load(src: string): Promise<void> { /* ... */ }
  play(): void { /* ... */ }
  pause(): void { /* ... */ }
  seek(time: number): void { /* ... */ }
  setVolume(vol: number): void { /* ... */ }
  getCurrentTime(): number { /* ... */ }
  getDuration(): number { /* ... */ }
  destroy(): void { /* ... */ }
}

2. Register in Player:

import { MyRenderer } from '../renderers/MyRenderer';

// In selectRenderer()
if (isMyServiceUrl(src)) return MyRenderer;

New Language

1. Create language file (src/i18n/languages/pt.ts):

export default {
  player: {
    play: 'Reproduzir',
    pause: 'Pausar',
    // ... all translations
  }
};

2. Register (src/i18n/translations.ts):

import pt from './languages/pt';

export const translations = {
  en, de, es, fr, ja,
  pt,
};

🎨 CSS Architecture

Variables

:root {
  /* Colors */
  --vidply-primary-color: #3b82f6;
  --vidply-background: rgba(0, 0, 0, 0.8);
  --vidply-text-color: #ffffff;
  
  /* Sizing */
  --vidply-button-size: 40px;
  --vidply-icon-size: 20px;
  
  /* Spacing */
  --vidply-gap-sm: 4px;
  --vidply-gap-md: 8px;
  --vidply-gap-lg: 12px;
}

BEM Naming

.vidply-player { }           /* Block */
.vidply-player--fullscreen { } /* Modifier */
.vidply-controls { }         /* Block */
.vidply-controls__left { }   /* Element */
.vidply-button { }           /* Block */
.vidply-button--active { }   /* Modifier */

Accessibility

/* High contrast mode */
@media (forced-colors: active) {
  .vidply-button {
    border: 1px solid currentColor;
  }
}

/* Focus visible */
.vidply-button:focus-visible {
  outline: 2px solid var(--vidply-primary-color);
  outline-offset: 2px;
}

/* Touch targets */
.vidply-button {
  min-width: 44px;
  min-height: 44px;
}

🧪 Testing

Manual Testing

1. Open localhost after npm run dev
2. Test demos:
   • demo/demo.html - Full features
   • demo/playlist-audio.html - Audio playlists
   • demo/playlist-video.html - Video playlists
   • demo/hls-test.html - HLS streaming
   • demo/dash-test.html - DASH streaming

Accessibility Testing

• Keyboard: Navigate using only keyboard
• Screen reader: Test with NVDA/VoiceOver
• High contrast: Enable Windows HCM
• Mobile: Test touch interactions

Browser Testing

🔌 Plugin System

EventEmitter

// Player extends EventEmitter
player.on('play', () => console.log('Playing'));
player.on('pause', () => console.log('Paused'));
player.on('timeupdate', (time) => console.log(time));

// Custom events
player.emit('mycustomevent', { data: 'value' });

Available Events

🐛 Debugging

Enable Debug Mode

const player = new Player('#video', { debug: true });

Console Logging

if (this.options.debug) {
  console.log('[VidPly]', message, data);
}

Common Issues

📚 Documentation Files

🔗 Quick Reference

Key Files

Build Output

External Dependencies

Default CDN fallback URLs (override via hlsScriptUrl / dashScriptUrl):

• cdn.jsdelivr.net/npm/hls.js@1.7.3/dist/hls.min.js
• cdn.jsdelivr.net/npm/dashjs@5.2.1/dist/modern/umd/dash.all.min.js

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/my-feature
3. Make changes
4. Test thoroughly
5. Build: npm run build
6. Commit: git commit -m 'Add my feature'
7. Push: git push origin feature/my-feature
8. Open Pull Request

Code Style

• Strict TypeScript (strict: true, noImplicitAny, strictNullChecks)
• BEM CSS naming
• Meaningful variable names
• Comment non-obvious intent (not what the code does)
• Include ARIA attributes on every interactive element
• Run npm run typecheck and npm run test before committing

Version: 1.1.7 | License: GPL-2.0-or-later