@codingfactory/mediables-vue 2.0.1

package/docs/video-subsystem/README.md

@@ -0,0 +1,490 @@
+# Mediables Video Subsystem
+
+**Version**: 2.0.0  
+**Status**: Production Ready  
+**Last Updated**: January 2025
+
+## Overview
+
+The Mediables Video Subsystem provides comprehensive video management capabilities for Laravel applications, treating video as a first-class media type alongside images. Built with a provider-agnostic architecture, it supports both Video on Demand (VOD) and live streaming through providers like Bunny, while maintaining the familiar patterns of the mediables package.
+
+## Key Features
+
+### 🎬 Video Management
+- **Upload**: Direct-to-provider uploads with resumable support
+- **Processing**: Automatic encoding with adaptive bitrate streaming
+- **Playback**: Secure, token-based playback with automatic refresh
+- **Storage**: Provider-based storage with CDN distribution
+
+### ✂️ Video Editor
+- **Timeline Editing**: Trim, split, and rearrange clips
+- **Filters**: 15 deterministic filters that work identically in preview and export
+- **Export**: Server-side processing with FFmpeg
+- **Real-time Preview**: PIXI.js-based frame filtering
+
+### 📡 Live Streaming
+- **Low Latency**: 5-7 second delay option
+- **Auto-Recording**: Automatic VOD archive creation
+- **RTMP Support**: Standard streaming protocol support
+- **Real-time Metrics**: Viewer count and stream health
+
+### 🔐 Security & Privacy
+- **Signed URLs**: Time-limited, secure playback URLs
+- **Token Refresh**: Automatic token renewal without interruption
+- **Webhook Validation**: Cryptographic signature verification
+- **Access Control**: Integration with application permissions
+
+## Architecture
+
+### Provider Abstraction
+
+The video subsystem uses a provider-agnostic architecture that allows swapping video providers without changing application code:
+
+```
+Application Code
+       ↓
+VideoProviderInterface
+       ↓
+Provider Implementation (Bunny, custom, etc.)
+```
+
+### Database Schema
+
+Two main tables handle video data:
+
+**Media Table Extensions**: Adds video-specific fields to existing media table
+- `duration`, `aspect_ratio`, `width`, `height`
+- `frame_rate`, `bitrate`, `has_audio`
+- `provider`, `provider_asset_id`, `playback_id`
+- `processing_status`, `processing_progress`
+
+**Live Streams Table**: Dedicated table for streaming data
+- Stream credentials (`stream_key`, `rtmp_url`)
+- Stream state (`status`, `started_at`, `ended_at`)
+- Metrics (`viewer_count`, `peak_viewers`)
+- Configuration (`auto_record`, `low_latency`)
+
+## Technology Stack
+
+### Backend (Laravel)
+- **Laravel 11/12**: Framework foundation
+- **FFmpeg**: Server-side video processing
+- **Bunny.net Video API**: Default provider integration
+- **Queue Workers**: Background job processing
+- **PostgreSQL**: Database with UUID primary keys
+
+### Frontend (Vue 3)
+- **Vue 3**: Composition API with TypeScript
+- **PIXI.js**: GPU-accelerated preview rendering
+- **Ionic Framework**: Mobile-optimized UI components
+- **Pinia**: State management
+- **Vite**: Build tooling with HMR
+
+## Quick Start
+
+### Installation
+
+1. **Install the package**:
+```bash
+composer require mediables/mediables:^2.0
+npm install @mediables/vue@^2.0
+```
+
+2. **Run migrations**:
+```bash
+php artisan migrate
+```
+
+3. **Configure provider** (`.env`):
+```env
+VIDEO_PROVIDER=bunny
+BUNNY_VIDEO_API_KEY=your-api-key
+BUNNY_VIDEO_LIBRARY_ID=your-library-id
+BUNNY_VIDEO_CDN_HOSTNAME=your-cdn.b-cdn.net
+BUNNY_VIDEO_WEBHOOK_SECRET=your-secret
+```
+
+### Basic Usage
+
+#### Upload a Video
+```vue
+<template>
+  <VideoUploader
+    :collection="'videos'"
+    @uploaded="handleUploaded"
+    @error="handleError"
+  />
+</template>
+
+<script setup>
+import { VideoUploader } from '@mediables/vue'
+
+function handleUploaded(media) {
+  console.log('Video uploaded:', media.uuid)
+}
+</script>
+```
+
+#### Play a Video
+```vue
+<template>
+  <VideoPlayer
+    :media="videoMedia"
+    :controls="true"
+    :autoplay="false"
+  />
+</template>
+
+<script setup>
+import { VideoPlayer } from '@mediables/vue'
+import { ref } from 'vue'
+
+const videoMedia = ref({
+  uuid: 'video-uuid-here',
+  playback_url: 'https://...'
+})
+</script>
+```
+
+#### Edit a Video
+```vue
+<template>
+  <VideoEditor
+    :media-uuid="videoUuid"
+    @export="handleExport"
+  />
+</template>
+
+<script setup>
+import { VideoEditor } from '@mediables/vue'
+
+const videoUuid = 'your-video-uuid'
+
+async function handleExport(recipe) {
+  // Recipe contains timeline edits and filters
+  const response = await api.post(`/video/${videoUuid}/export`, { recipe })
+  console.log('Export job started:', response.job_id)
+}
+</script>
+```
+
+## Component Reference
+
+### VideoUploader
+Handles direct-to-provider video uploads with progress tracking.
+
+**Props**:
+- `collection` (string): Media collection name
+- `multiple` (boolean): Allow multiple file selection
+- `maxSize` (number): Maximum file size in bytes
+- `acceptedFormats` (array): Allowed video formats
+
+**Events**:
+- `@uploaded`: Fired when upload completes
+- `@progress`: Upload progress updates
+- `@error`: Upload errors
+
+### VideoPlayer
+Provider-agnostic video player with automatic token refresh.
+
+**Props**:
+- `media` (object): Media object with playback URL
+- `playbackUrl` (string): Direct playback URL
+- `controls` (boolean): Show player controls
+- `autoplay` (boolean): Start playing automatically
+- `muted` (boolean): Start muted
+- `isLive` (boolean): Live stream mode
+
+**Events**:
+- `@play`: Playback started
+- `@pause`: Playback paused
+- `@ended`: Playback completed
+- `@error`: Playback error
+
+### VideoEditor
+Full-featured video editor with timeline and filters.
+
+**Props**:
+- `mediaUuid` (string): UUID of video to edit
+- `initialRecipe` (object): Pre-load edit recipe
+
+**Events**:
+- `@export`: Export requested with recipe
+- `@save-draft`: Draft save requested
+- `@change`: Edit state changed
+
+### LiveStreamManager
+Manages live streaming setup and monitoring.
+
+**Props**:
+- `mediaUuid` (string): Media UUID for stream
+
+**Events**:
+- `@stream-created`: Stream credentials ready
+- `@stream-started`: Stream went live
+- `@stream-ended`: Stream stopped
+
+## Filter Reference
+
+The video subsystem includes 15 deterministic filters that produce identical results in both preview (PIXI.js) and export (FFmpeg):
+
+### Color Adjustments
+- `brightness`: Adjust brightness (-1 to 1)
+- `contrast`: Adjust contrast (0 to 2)
+- `saturation`: Adjust color saturation (0 to 2)
+- `hue`: Rotate hue angle (-180 to 180)
+
+### Blur Effects
+- `gaussian-blur`: Gaussian blur (sigma: 0 to 10)
+- `motion-blur`: Motion blur effect
+
+### Stylize Filters
+- `vintage`: Vintage film look
+- `sepia`: Sepia tone effect
+- `grayscale`: Convert to grayscale
+
+### Effects
+- `vignette`: Add vignette overlay
+- `sharpen`: Sharpen details
+- `denoise`: Reduce noise
+
+### Transform
+- `flip-horizontal`: Mirror horizontally
+- `flip-vertical`: Mirror vertically
+- `rotate`: Rotate by degrees
+
+## Recipe Format
+
+The video editor generates a JSON recipe that describes all edits:
+
+```json
+{
+  "version": "1.0",
+  "source": {
+    "media_uuid": "uuid-here",
+    "duration": 120.5
+  },
+  "timeline": [
+    {
+      "type": "clip",
+      "id": "clip-1",
+      "start": 0,
+      "end": 30,
+      "source_in": 10,
+      "source_out": 40,
+      "speed": 1.0
+    }
+  ],
+  "filters": [
+    {
+      "id": "vintage",
+      "params": {},
+      "intensity": 0.8,
+      "ffmpeg": "curves=preset=vintage"
+    }
+  ],
+  "audio": {
+    "volume": 1.0,
+    "fade_in": 0,
+    "fade_out": 0
+  },
+  "output": {
+    "format": "mp4",
+    "codec": "h264",
+    "quality": "1080p",
+    "fps": 30
+  }
+}
+```
+
+## Performance Considerations
+
+### Upload Performance
+- **Resumable Uploads**: Automatic retry on network failure
+- **Direct Upload**: Bypass application server for large files
+- **Background Processing**: Non-blocking asset processing
+
+### Playback Performance
+- **Adaptive Bitrate**: Automatic quality adjustment
+- **CDN Delivery**: Global edge caching
+- **Token Caching**: Minimize API calls
+
+### Editor Performance
+- **Frame Sampling**: Process every 3rd frame on mobile
+- **GPU Acceleration**: PIXI.js WebGL rendering
+- **Lazy Loading**: Load components on demand
+
+### Mobile Optimization
+- **Touch Gestures**: Native gesture support
+- **Reduced Quality**: Lower preview quality on mobile
+- **Battery Awareness**: Throttle processing on low battery
+
+## Security Best Practices
+
+### API Security
+- Always validate webhook signatures
+- Use time-limited signed URLs
+- Implement rate limiting on endpoints
+- Validate file types and sizes
+
+### Token Management
+- Tokens expire after 60 minutes
+- Automatic refresh at 50-minute mark
+- Secure token storage in memory
+- No token persistence to disk
+
+### Access Control
+```php
+// Example policy integration
+class VideoPolicy
+{
+    public function view(User $user, Media $media): bool
+    {
+        return $media->user_id === $user->id || 
+               $media->visibility === 'public';
+    }
+    
+    public function edit(User $user, Media $media): bool
+    {
+        return $media->user_id === $user->id;
+    }
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Upload fails immediately**
+- Check CORS configuration on provider
+- Verify API credentials
+- Check file size limits
+
+**Playback shows black screen**
+- Video still processing
+- Token expired (check console)
+- Unsupported codec
+
+**Export never completes**
+- Check queue worker is running
+- Verify FFmpeg installation
+- Check disk space
+
+**Live stream won't connect**
+- Verify RTMP URL format
+- Check firewall settings
+- Confirm stream key
+
+### Debug Mode
+
+Enable debug logging:
+```php
+// config/mediables.php
+'video' => [
+    'debug' => env('MEDIABLES_VIDEO_DEBUG', false),
+    'log_webhooks' => env('MEDIABLES_LOG_WEBHOOKS', false),
+]
+```
+
+### Health Checks
+
+```php
+// Check provider connectivity
+app(VideoProviderInterface::class)->healthCheck();
+
+// Verify FFmpeg
+app(VideoProcessor::class)->verifyFFmpeg();
+
+// Test webhook signature
+app(WebhookValidator::class)->testSignature($payload, $signature);
+```
+
+## Migration Guide
+
+### From v1.x to v2.0
+
+1. **Database Migration**:
+```bash
+php artisan migrate
+```
+
+2. **Update Imports**:
+```javascript
+// Old
+import { ImageEditor } from '@mediables/vue'
+
+// New
+import { ImageEditor, VideoEditor, VideoPlayer } from '@mediables/vue'
+```
+
+3. **Configuration Changes**:
+```env
+VIDEO_PROVIDER=bunny
+BUNNY_VIDEO_API_KEY=your-api-key
+BUNNY_VIDEO_LIBRARY_ID=your-library-id
+BUNNY_VIDEO_CDN_HOSTNAME=your-cdn.b-cdn.net
+BUNNY_VIDEO_WEBHOOK_SECRET=your-secret
+```
+
+## Browser Compatibility
+
+### Supported Browsers
+- Chrome 90+ (recommended)
+- Safari 14+ (iOS 14+)
+- Firefox 88+
+- Edge 90+
+
+### Required Features
+- WebGL 2.0 (for editor)
+- Media Source Extensions
+- Web Workers
+- IndexedDB
+
+### Progressive Enhancement
+The video subsystem gracefully degrades:
+- No WebGL: Disable preview filters
+- No MSE: Fallback to progressive download
+- No Workers: Process on main thread
+- Mobile: Reduced quality settings
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](../CONTRIBUTING.md) for details.
+
+### Development Setup
+```bash
+# Clone repository
+git clone https://github.com/mediables/mediables.git
+
+# Install dependencies
+composer install
+npm install
+
+# Run tests
+composer test
+npm run test
+
+# Build assets
+npm run build
+```
+
+## License
+
+The Mediables package is open-sourced software licensed under the [MIT license](../../LICENSE.md).
+
+## Support
+
+- **Documentation**: [Full Documentation](https://mediables.dev/docs)
+- **Issues**: [GitHub Issues](https://github.com/mediables/mediables/issues)
+- **Discord**: [Community Discord](https://discord.gg/mediables)
+- **Email**: support@mediables.dev
+
+## Credits
+
+Created and maintained by the Mediables Team.
+
+Special thanks to:
+- Laravel team for the framework
+- Bunny.net for video infrastructure
+- PIXI.js team for rendering engine
+- FFmpeg project for video processing