\n );\n}\n```\n\n### React (Direct Usage - Full Control)\n\nUse `new MagmaPlayer()` directly when you need:\n\n- Full access to all options (e.g., `waitForCanvas`, `canvasTimeout`)\n- Custom lifecycle management\n- Building custom hooks or components\n\n```jsx\nimport { useRef, useEffect } from \"react\";\nimport { MagmaPlayer } from \"@der-lukas/magma-player\";\n// Or: import { MagmaPlayer } from \"./magma/MagmaPlayer.js\";\n\nfunction VideoPlayer({ colorSrc, maskSrc }) {\n const canvasRef = useRef(null);\n const playerRef = useRef(null);\n\n useEffect(() => {\n if (!canvasRef.current) return;\n\n const player = new MagmaPlayer({\n colorVideoSrc: colorSrc,\n maskVideoSrc: maskSrc,\n canvas: canvasRef.current,\n // Or: canvas: () => canvasRef.current, waitForCanvas: true\n useWebGL: true,\n autoplay: false,\n });\n\n player.on(\"ready\", () => console.log(\"Ready\"));\n player.on(\"error\", (error) => console.error(\"Error:\", error));\n\n playerRef.current = player;\n\n return () => {\n player.destroy();\n };\n }, [colorSrc, maskSrc]);\n\n return ;\n}\n```\n\n### Vue\n\n```vue\n\n \n\n\n\n```\n\n### Angular (Using Component - Recommended)\n\n```typescript\nimport { Component } from \"@angular/core\";\nimport { MagmaPlayerComponent } from \"@der-lukas/magma-player/angular\";\nimport type { MagmaPlayer } from \"@der-lukas/magma-player\";\n// Or: import { MagmaPlayerComponent } from \"./magma/angular/magma-player.component\";\n// Or: import type { MagmaPlayer } from \"./magma/MagmaPlayer.js\";\n\n@Component({\n selector: \"app-video-player\",\n standalone: true,\n imports: [MagmaPlayerComponent],\n template: `\n \n \n \n \n `,\n})\nexport class VideoPlayerComponent {\n playerRef: MagmaPlayerComponent | null = null;\n\n onPlayerReady(player: MagmaPlayer) {\n console.log(\"Player ready:\", player);\n // Access the component instance to control playback\n // Note: You'll need to use @ViewChild to get the component reference\n }\n\n onPlayerError(error: any) {\n console.error(\"Player error:\", error);\n }\n\n onPlay() {\n console.log(\"Playing\");\n }\n\n onPause() {\n console.log(\"Paused\");\n }\n\n onTimeUpdate(time: number) {\n console.log(\"Time:\", time);\n }\n}\n```\n\n**With ViewChild for programmatic control:**\n\n```typescript\nimport { Component, ViewChild } from \"@angular/core\";\nimport { MagmaPlayerComponent } from \"@der-lukas/magma-player/angular\";\n// Or: import { MagmaPlayerComponent } from \"./magma/angular/magma-player.component\";\n\n@Component({\n selector: \"app-video-player\",\n standalone: true,\n imports: [MagmaPlayerComponent],\n template: `\n \n \n \n \n `,\n})\nexport class VideoPlayerComponent {\n @ViewChild(\"player\") player!: MagmaPlayerComponent;\n}\n```\n\n**Reactive signals available on the component:**\n\n```typescript\n// Access reactive state\nplayer.isPlaying(); // Signal\nplayer.isReady(); // Signal\nplayer.currentTime(); // Signal\nplayer.duration(); // Signal\nplayer.videoWidth(); // Signal\nplayer.videoHeight(); // Signal\nplayer.volume(); // Signal\nplayer.playbackRate(); // Signal\n```\n\n### Angular (Direct Usage - Full Control)\n\nUse `new MagmaPlayer()` directly when you need full control over the lifecycle:\n\n```typescript\nimport {\n Component,\n ElementRef,\n OnDestroy,\n OnInit,\n ViewChild,\n} from \"@angular/core\";\nimport { MagmaPlayer } from \"@der-lukas/magma-player\";\n// Or: import { MagmaPlayer } from \"./magma/MagmaPlayer.js\";\n\n@Component({\n selector: \"app-video-player\",\n template: ``,\n})\nexport class VideoPlayerComponent implements OnInit, OnDestroy {\n @ViewChild(\"canvas\", { static: false })\n canvasRef!: ElementRef;\n private player: MagmaPlayer | null = null;\n\n ngOnInit() {\n // Wait for view to initialize\n setTimeout(() => {\n if (this.canvasRef?.nativeElement) {\n this.player = new MagmaPlayer({\n colorVideoSrc: \"color.mp4\",\n maskVideoSrc: \"mask.mp4\",\n canvas: this.canvasRef.nativeElement,\n useWebGL: true,\n autoplay: false,\n });\n\n this.player.on(\"ready\", () => console.log(\"Ready\"));\n this.player.on(\"error\", (error) => console.error(\"Error:\", error));\n }\n });\n }\n\n ngOnDestroy() {\n this.player?.destroy();\n }\n}\n```\n\n## API\n\n### Constructor Options\n\n```typescript\nnew MagmaPlayer({\n colorVideoSrc: string, // URL to color video (MP4)\n maskVideoSrc: string, // URL to alpha mask video (MP4, grayscale)\n canvas: HTMLCanvasElement, // Canvas element to render to\n useWebGL?: boolean, // Use WebGL (default: true)\n autoplay?: boolean, // Autoplay on ready (default: true)\n targetFPS?: number, // Target frame rate (default: 60, use 30/24 for battery saving)\n onReady?: () => void, // Callback when player is ready\n onError?: (error) => void, // Callback for errors (receives MagmaPlayerError)\n strictDuration?: boolean, // Throw error if video durations don't match (default: false)\n pauseWhenHidden?: boolean, // Pause rendering when canvas is not visible (default: true)\n})\n```\n\n### Playback Control Methods\n\n- `play()` - Start playback\n- `pause()` - Pause playback\n- `seek(time)` - Seek to specific time (in seconds)\n- `reset()` - Reset to time 0 and pause\n\n### Volume Control\n\n- `setVolume(volume)` - Set volume (0-1 range)\n- `getVolume()` - Get current volume (0-1)\n\n### Playback Speed Control\n\n- `setPlaybackRate(rate)` - Set playback speed (0.25-4.0 range, default: 1.0)\n- `getPlaybackRate()` - Get current playback rate\n\n### Time & Duration Getters\n\n- `getCurrentTime()` - Get current playback time (in seconds)\n- `getDuration()` - Get video duration (in seconds)\n- `getBuffered()` - Get buffered time ranges (array of `{start, end}` objects)\n\n### Loop Control\n\n- `setLoop(loop)` - Enable/disable infinite looping (boolean, default: true)\n- `getLoop()` - Get current loop setting\n\n### Repeat Control\n\n- `setRepeatCount(count)` - Set total number of times to play (-1 = infinite loop, 0 = don't play, 1 = play once, >1 = play that many times total)\n- `getRepeatCount()` - Get current repeat count\n\n**Semantics (aligned with CSS `animation-iteration-count`):**\n\n- `-1`: Infinite loop (plays forever)\n- `0`: Don't play (0 iterations) - aligns with CSS\n- `1`: Play once and stop (1 iteration)\n- `3`: Play 3 times total (3 iterations)\n\n```javascript\nplayer.setRepeatCount(3); // Play 3 times total\nplayer.setRepeatCount(-1); // Infinite loop\nplayer.setRepeatCount(1); // Play once\nplayer.setRepeatCount(0); // Don't play (0 iterations)\n```\n\n### Utility Methods\n\n- `isPlaying()` - Check if currently playing\n- `isPaused()` - Check if currently paused\n- `getVideoWidth()` - Get video width in pixels\n- `getVideoHeight()` - Get video height in pixels\n- `setSize(width, height)` - Manually set canvas size\n\n### Event System\n\n- `on(event, callback)` - Add event listener\n- `off(event, callback)` - Remove event listener\n\n**Available Events:**\n\n- `ready` - Player is ready and initialized\n- `play` - Playback started\n- `pause` - Playback paused\n- `timeupdate` - Playback time updated (callback receives current time)\n- `ended` - Playback ended (only if loop is disabled)\n- `seeked` - Seek operation completed (callback receives seek time)\n- `error` - Error occurred (callback receives error object)\n\n### Cleanup\n\n- `destroy()` - Clean up and destroy player instance (removes event listeners, stops playback, frees resources)\n\n### Error Handling\n\nMagmaPlayer uses a custom error class `MagmaPlayerError` with error codes for programmatic error handling:\n\n```javascript\nimport { MagmaPlayer, MagmaPlayerError, ERROR_CODES } from './magma/MagmaPlayer.js';\n\ntry {\n const player = new MagmaPlayer({ ... });\n} catch (error) {\n if (error instanceof MagmaPlayerError) {\n switch (error.code) {\n case ERROR_CODES.INVALID_INPUT:\n console.error('Invalid input:', error.message);\n break;\n case ERROR_CODES.VIDEO_LOAD_FAILED:\n console.error('Video failed to load:', error.details);\n break;\n // ... other error codes\n }\n }\n}\n```\n\n**Error Codes:**\n\n- `INVALID_INPUT` - Invalid constructor parameters\n- `VIDEO_LOAD_FAILED` - Video failed to load\n- `VIDEO_LOAD_TIMEOUT` - Video load timeout (30 seconds)\n- `DURATION_MISMATCH` - Video durations don't match (only if `strictDuration: true`)\n- `WEBGL_INIT_FAILED` - WebGL initialization failed (automatically falls back to Canvas2D)\n- `CANVAS_REMOVED` - Canvas was removed from DOM during playback\n\n## How It Works\n\n1. **Shared Clock**: Uses `performance.now()` as a master clock to drive both videos\n2. **Synchronization**: Both videos are synced to the same time using the shared clock\n3. **Compositing**:\n - **WebGL**: Uploads both videos as textures and composites using a fragment shader (WebGL2 when available)\n - **Canvas2D**: Falls back to pixel-by-pixel compositing if WebGL unavailable\n4. **Perfect Sync**: Videos never drift because they're both driven by the same clock\n5. **Performance**: Texture uploads are cached, temp canvases are reused, frame throttling for low-end devices\n\n## Performance Tips\n\n1. **Frame Rate**: Use `targetFPS: 30` or `targetFPS: 24` for battery saving on mobile devices\n2. **Autoplay**: Set `autoplay: false` if you want to control playback manually (e.g., on hover)\n3. **WebGL**: WebGL is automatically used when available for best performance\n4. **Retina Displays**: Pixel ratio scaling is automatic - no configuration needed\n5. **Video Format**: Use H.264 MP4 with yuv420p for best compatibility and performance\n\n## Browser Support\n\n- ✅ Chrome/Edge: Full support (WebGL2 available)\n- ✅ Firefox: Full support (WebGL2 available)\n- ✅ Safari 16.4+: Full support (WebGL2 available)\n- ✅ iOS Safari 16.4+: Full support\n\n**Note**: Older browsers will automatically fall back to Canvas2D rendering if WebGL is unavailable.\n\n## Video Format Requirements\n\n- **Format**: MP4 (H.264, yuv420p)\n- **Color Video**: Standard RGB video\n- **Mask Video**: Grayscale video (white = opaque, black = transparent)\n- **Dimensions**: Both videos must have identical dimensions\n- **FPS**: Both videos must have identical frame rates\n- **Duration**: Both videos must have identical durations (warnings shown if mismatch > 0.1s)\n\n## Troubleshooting\n\n### Videos don't load\n\n- **Check CORS**: Ensure videos are served with proper CORS headers if loading from different domain\n- **Check format**: Videos must be MP4 (H.264). Check browser console for codec errors\n- **Check paths**: Verify video URLs are correct and accessible\n\n### Autoplay doesn't work\n\n- **Browser restrictions**: Many browsers block autoplay. Use `autoplay: false` and call `play()` after user interaction\n- **Mobile devices**: iOS requires user interaction before playback can start\n\n### Videos are out of sync\n\n- **Check dimensions**: Videos must have identical dimensions\n- **Check duration**: Videos should have identical durations (warnings shown if mismatch)\n- **Check frame rate**: Videos should have identical frame rates\n\n### WebGL not working\n\n- **Automatic fallback**: Player automatically falls back to Canvas2D if WebGL unavailable\n- **Context loss**: Player automatically handles WebGL context loss and restoration\n- **Performance**: Canvas2D is slower but works everywhere\n\n### Performance issues\n\n- **Lower frame rate**: Use `targetFPS: 30` or `24` for better battery life\n- **Check video size**: Large videos may cause performance issues\n- **WebGL**: Ensure WebGL is available (check browser console for errors)\n\n## License\n\nMIT\n","readmeFilename":"README.md"}