# VidPly Getting Started with VidPly Welcome! This guide will help you get VidPly up and running in 5 minutes. ## Prerequisites - Node.js 18+ installed - A text editor - A modern web browser ## Quick Installation ### 1. Get the Code ```bash git clone https://github.com/MatthiasPeltzer/vidply.git cd vidply ``` ### 2. Install Dependencies ```bash npm install ``` This installs: - `esbuild` - Fast TypeScript/JavaScript bundler - `typescript` - Strict type-checking and `.d.ts` emission - `clean-css` - CSS minifier - `vitest` + `@playwright/test` - Unit and end-to-end testing ### 3. Build the Player ```bash npm run build ``` This creates production-ready files in `dist/`: - `prod/vidply.esm.min.js` - Minified ES Module (recommended for production) - `legacy/vidply.min.js` - Minified IIFE bundle (global `VidPly`) - `types/index.d.ts` - TypeScript type declarations for IDE / `tsc` consumers - `vidply.min.css` - Minified styles (~12KB) ### 4. View the Demo ```bash npm run dev ``` Open http://localhost:3000/demo/ to see VidPly in action! ## Your First Video Player ### Create `index.html` ```html My Video Player

My Video Player

``` ### Test It ```bash # Start a local server npm run dev # Or use Python python -m http.server 3000 # Or use PHP php -S localhost:3000 ``` Open http://localhost:3000 in your browser. ## 3-Step Quick Start If you just want to use the source files directly without building: ### Step 1: Include the CSS ```html ``` ### Step 2: Add Your Video ```html ``` ### Step 3: Import the Player ```html ``` That's it! ## Basic Examples ### Example 1: Simple Video ```html ``` ### Example 2: Audio Player ```html ``` ### Example 3: YouTube Video ```html ``` ### Example 4: Vimeo Video ```html ``` ### Example 5: SoundCloud Track ```html ``` ### Example 6: HLS Streaming ```html ``` ### Example 7: DASH Streaming ```html ``` ### Example 8: With Download Button ```html ``` ### Example 9: With the Custom Floating Player Enable the in-page floating player ("own PiP"). When the original scrolls out of the viewport, VidPly pops the video into a draggable, resizable floating shell in the chosen corner; when it scrolls back in, the player docks again. The PiP button in the control bar manually pins/unpins the floating shell. Native browser PiP is suppressed automatically while floating is enabled. ```html ``` > Audio players ignore `floating`. The feature is hidden below `floatingMinViewportWidth` (default `768px`) and the floating PiP button never appears in the overflow menu. ### Example 10: With Options ```html ``` ### Example 11: Manual Initialization ```html ``` > Working with TypeScript? Import directly from the source tree (`import Player from 'vidply'`) — VidPly ships its own `.d.ts` declarations, so you'll get full type-safety on `PlayerOptions`, events and renderer APIs. ## Configuration ### Via Data Attribute ```html ``` ### Via JavaScript ```javascript const player = new Player('#my-video', { controls: true, autoplay: false, loop: false, volume: 0.8, playbackSpeed: 1.0, captions: true, captionsDefault: true, keyboard: true, language: 'en', responsive: true }); ``` ## Common Options ```javascript { // Playback autoplay: false, // Auto-start playback loop: false, // Loop video muted: false, // Start muted volume: 0.8, // Volume (0-1) playbackSpeed: 1.0, // Speed (0.25-2.0) // Display responsive: true, // Responsive sizing controls: true, // Show controls // Captions captions: true, // Enable captions captionsDefault: false, // Show captions by default // Accessibility keyboard: true, // Keyboard shortcuts // Language language: 'en' // UI language (en, es, fr, de, ja) } ``` ## Multi-Language Captions ```html ``` **How it works:** - Click the CC button to open the caption menu - Select your preferred language - Or press C to open the menu (if multiple tracks available) - The active track is marked with a checkmark ## Creating Captions (WebVTT) Create a file called `captions.vtt`: ``` WEBVTT 00:00:00.000 --> 00:00:05.000 Welcome to my video! 00:00:05.000 --> 00:00:10.000 This is how captions work. 00:00:10.000 --> 00:00:15.000 Pretty easy, right? ``` ## Controlling the Player ```javascript const player = new Player('#video'); // Playback player.play(); player.pause(); player.stop(); player.seek(60); // Jump to 1 minute // Volume player.setVolume(0.5); // 50% volume player.mute(); player.unmute(); // Speed player.setPlaybackSpeed(1.5); // 1.5x speed // Fullscreen player.enterFullscreen(); player.exitFullscreen(); // Captions player.enableCaptions(); player.disableCaptions(); // Events player.on('play', () => console.log('Playing!')); player.on('pause', () => console.log('Paused')); player.on('ended', () => console.log('Finished')); player.on('timeupdate', (time) => { console.log('Current time:', time); }); ``` ## Keyboard Shortcuts Once the player is focused: - Space / P / K - Play/Pause - F - Fullscreen - M - Mute/Unmute - ↑ / ↓ - Volume Up/Down - ← / → - Seek -10s / +10s - C - Toggle Captions - A - Open Caption Style Menu - < / > - Decrease/Increase Speed - S - Open Speed Menu - Q - Open Quality Menu - J - Open Chapters Menu - T - Toggle Transcript - D - Toggle Drag Mode (Transcript/Sign Language) - R - Toggle Resize Mode (Transcript/Sign Language) - Home - Reset Position (Transcript/Sign Language) - Escape - Exit Mode or Close Menu ## Customizing Styles ### Override CSS Variables ```css .vidply-player { --vidply-primary-color: #ff0000; --vidply-background: rgba(0, 0, 0, 0.9); } ``` ### Custom Progress Bar ```css .vidply-progress-played { background: linear-gradient(90deg, #ff0000, #ff00ff); } ``` ### Custom Button Hover ```css .vidply-button:hover { background: rgba(255, 0, 0, 0.2); } ``` ## Change Language ### Built-in Languages VidPly includes translations for 5 languages: - `en` - English - `es` - Spanish (Español) - `fr` - French (Français) - `de` - German (Deutsch) - `ja` - Japanese (日本語) ```javascript const player = new Player('#video', { language: 'de' // German UI }); ``` ### Custom Translations You can add your own translations by loading language files from URLs. The player supports JSON and YAML formats. #### Using Data Attributes Load multiple language files: ```html ``` Load a single language file: ```html ``` Or use separate attributes: ```html ``` #### Using JavaScript Options ```javascript const player = new Player('#video', { language: 'pt', // Set language after loading languageFiles: { 'pt': 'languages/pt.json', 'it': 'languages/it.json' } }); ``` #### Language File Format (JSON) Create a file `languages/pt.json`: ```json { "player": { "play": "Reproduzir", "pause": "Pausar", "mute": "Silenciar", "unmute": "Ativar som", "fullscreen": "Tela cheia", "exitFullscreen": "Sair da tela cheia", "captions": "Legendas", "settings": "Configurações" }, "time": { "currentTime": "Tempo atual", "duration": "Duração" } } ``` #### Auto-detection from HTML The player automatically detects the language from the HTML `lang` attribute if a matching translation is available: ```html ``` #### Programmatic Translation Loading ```javascript import { i18n } from './src/i18n/i18n.js'; // Load a language file await i18n.loadLanguageFromUrl('pt', 'languages/pt.json'); // Or load multiple languages await i18n.loadLanguagesFromUrls({ 'pt': 'languages/pt.json', 'it': 'languages/it.json' }); // Set the language i18n.setLanguage('pt'); ``` ## Development Mode Enable debug logging: ```javascript const player = new Player('#video', { debug: true }); ``` Check the browser console for detailed logs. ## Deployment Options ### Option 1: ES Module (Modern Browsers) ```html ``` ### Option 2: Traditional Script Tag (IIFE) ```html ``` ### Option 3: CDN (Future) ```html ``` ## Mobile Optimization VidPly is mobile-friendly by default with a mobile breakpoint at 768px. For best results: ```html ``` And use responsive mode: ```javascript const player = new Player('#video', { responsive: true }); ``` **Mobile-specific behavior (< 768px breakpoint):** - Transcript window appears below the video (not draggable/resizable) - Sign language video is not draggable/resizable - Optimized control bar with overflow menu for many buttons - Touch-friendly interface with 44px minimum touch targets - Transcript window minimum width: 300px ## Accessibility VidPly is WCAG 2.2 AA compliant out of the box: - Full keyboard navigation - Screen reader support - High contrast mode - Focus indicators - ARIA labels No extra configuration needed! ## Troubleshooting ### Video Won't Play 1. Check console for errors (press F12) 2. Verify video URL is correct 3. Check CORS headers if loading from different domain 4. Enable debug mode: `{ debug: true }` ### Captions Not Showing 1. Verify VTT file format is correct 2. Check file path 3. Enable captions: click the CC button 4. Or enable by default: `{ captionsDefault: true }` ### Build Failed ```bash # Clean and rebuild npm run clean rm -rf node_modules npm install npm run build ``` ### Autoplay Not Working Browsers block autoplay with audio. Solution: ```javascript const player = new Player('#video', { autoplay: true, muted: true // Required for autoplay }); ``` ## Available Build Scripts ```bash npm run build # Build everything npm run build:js # Build JS only npm run build:css # Build CSS only npm run watch # Watch mode for development npm run clean # Clean dist/ npm run dev # Start dev server (port 3000) npm start # Alias for npm run dev ``` ## File Structure After building, you'll have: ``` vidply/ ├── dist/ │ ├── dev/ │ │ └── vidply.esm.js # ES Module (dev) │ ├── prod/ │ │ └── vidply.esm.min.js # ES Module (prod) │ ├── legacy/ │ │ ├── vidply.js # IIFE (dev) │ │ └── vidply.min.js # IIFE (prod) │ ├── types/ │ │ └── index.d.ts # TypeScript declarations │ ├── vidply.css # Styles (dev) │ └── vidply.min.css # Styles (prod) └── ... ``` Only include in production: - `dist/prod/vidply.esm.min.js` (or `dist/legacy/vidply.min.js`) - `dist/vidply.min.css` Total: ~62KB uncompressed, ~18KB gzipped ## Streaming (HLS & DASH) VidPly auto-detects streaming formats by file extension: - **HLS** (`.m3u8`) - Uses **hls.js 1.6.16** on Chrome / Firefox / Edge / desktop Safari (CDN fallback when not preloaded). On iOS / iPadOS the native `