@codingfactory/mediables-vue 2.0.1

package/docs/video-subsystem/api-reference.md

@@ -0,0 +1,747 @@
+# Video Subsystem API Reference
+
+**Version**: 1.0.0  
+**Base URL**: `/api/v1/video`  
+**Authentication**: Bearer token required for all endpoints
+
+## Table of Contents
+
+1. [Upload API](#upload-api)
+2. [Playback API](#playback-api)
+3. [Export API](#export-api)
+4. [Live Streaming API](#live-streaming-api)
+5. [Webhook API](#webhook-api)
+6. [Error Responses](#error-responses)
+
+## Upload API
+
+### Create Upload URL
+
+Request a signed upload URL for direct-to-provider video upload.
+
+**Endpoint**: `POST /api/v1/video/upload`
+
+**Request Body**:
+```json
+{
+  "filename": "my-video.mp4",
+  "size": 52428800,
+  "mime_type": "video/mp4",
+  "collection": "user-videos"
+}
+```
+
+**Parameters**:
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| filename | string | Yes | Original filename |
+| size | integer | Yes | File size in bytes (max 5GB) |
+| mime_type | string | Yes | MIME type (video/mp4, video/quicktime, video/webm) |
+| collection | string | No | Media collection name (default: "videos") |
+
+**Success Response** (201 Created):
+```json
+{
+  "upload_url": "https://video.bunnycdn.com/library/your-library-id/videos/video-guid-abc123",
+  "upload_id": "upload_abc123",
+  "media_uuid": "550e8400-e29b-41d4-a716-446655440000",
+  "expires_at": "2025-01-30T12:00:00Z"
+}
+```
+
+**Error Responses**:
+- `400 Bad Request`: Invalid parameters
+- `401 Unauthorized`: Missing or invalid token
+- `413 Payload Too Large`: File exceeds size limit
+- `415 Unsupported Media Type`: Invalid video format
+
+**Example cURL**:
+```bash
+curl -X POST https://api.example.com/api/v1/video/upload \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "filename": "demo.mp4",
+    "size": 10485760,
+    "mime_type": "video/mp4"
+  }'
+```
+
+### Complete Upload
+
+Notify the server that client-side upload is complete.
+
+**Endpoint**: `POST /api/v1/video/upload/{uuid}/complete`
+
+**URL Parameters**:
+| Field | Type | Description |
+|-------|------|-------------|
+| uuid | string | Media UUID from upload creation |
+
+**Success Response** (200 OK):
+```json
+{
+  "message": "Upload completed, processing started",
+  "media": {
+    "uuid": "550e8400-e29b-41d4-a716-446655440000",
+    "status": "processing",
+    "processing_status": "pending"
+  }
+}
+```
+
+### Check Upload Status
+
+Get the current status of a video upload.
+
+**Endpoint**: `GET /api/v1/video/upload/{uuid}/status`
+
+**Success Response** (200 OK):
+```json
+{
+  "uuid": "550e8400-e29b-41d4-a716-446655440000",
+  "status": "processing",
+  "processing_status": "encoding",
+  "processing_progress": 45,
+  "duration": null,
+  "playback_available": false
+}
+```
+
+**Status Values**:
+- `pending`: Upload created, waiting for file
+- `uploading`: File upload in progress
+- `processing`: Server processing video
+- `ready`: Video ready for playback
+- `failed`: Processing failed
+
+## Playback API
+
+### Get Playback URL
+
+Get a signed playback URL for video streaming.
+
+**Endpoint**: `GET /api/v1/video/{uuid}/playback`
+
+**URL Parameters**:
+| Field | Type | Description |
+|-------|------|-------------|
+| uuid | string | Media UUID |
+
+**Query Parameters**:
+| Field | Type | Description |
+|-------|------|-------------|
+| quality | string | Preferred quality (auto, 1080p, 720p, 480p) |
+| thumbnail | boolean | Include thumbnail URL |
+
+**Success Response** (200 OK):
+```json
+{
+  "playback_url": "https://your-cdn.b-cdn.net/your-library-id/play_video-guid-abc123/playlist.m3u8",
+  "thumbnail_url": "https://your-cdn.b-cdn.net/your-library-id/video-guid-abc123/thumbnail.jpg",
+  "token_expires_at": "2025-01-30T13:00:00Z",
+  "duration": 120.5,
+  "width": 1920,
+  "height": 1080,
+  "has_audio": true
+}
+```
+
+**Error Responses**:
+- `404 Not Found`: Media not found
+- `403 Forbidden`: No access to media
+- `503 Service Unavailable`: Video still processing
+
+### Get Video Metadata
+
+Retrieve detailed metadata about a video.
+
+**Endpoint**: `GET /api/v1/video/{uuid}/metadata`
+
+**Success Response** (200 OK):
+```json
+{
+  "uuid": "550e8400-e29b-41d4-a716-446655440000",
+  "filename": "my-video.mp4",
+  "duration": 120.5,
+  "aspect_ratio": "16:9",
+  "width": 1920,
+  "height": 1080,
+  "frame_rate": 29.97,
+  "bitrate": 4000000,
+  "has_audio": true,
+  "has_captions": false,
+  "codec": "h264",
+  "container": "mp4",
+  "size": 52428800,
+  "created_at": "2025-01-30T10:00:00Z",
+  "processing_status": "ready"
+}
+```
+
+### Generate Thumbnail
+
+Generate a thumbnail at a specific timestamp.
+
+**Endpoint**: `POST /api/v1/video/{uuid}/thumbnail`
+
+**Request Body**:
+```json
+{
+  "time": 5.0,
+  "width": 640,
+  "height": 360
+}
+```
+
+**Parameters**:
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| time | float | No | Timestamp in seconds (default: 0) |
+| width | integer | No | Thumbnail width (default: 640) |
+| height | integer | No | Thumbnail height (default: 360) |
+
+**Success Response** (200 OK):
+```json
+{
+  "thumbnail_url": "https://cdn.example.com/thumbnails/abc123_5s.jpg",
+  "width": 640,
+  "height": 360,
+  "time": 5.0
+}
+```
+
+## Export API
+
+### Create Export Job
+
+Start a video export job with edits and filters.
+
+**Endpoint**: `POST /api/v1/video/{uuid}/export`
+
+**Request Body**:
+```json
+{
+  "recipe": {
+    "version": "1.0",
+    "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
+      }
+    ],
+    "audio": {
+      "volume": 1.0,
+      "fade_in": 0,
+      "fade_out": 2
+    },
+    "output": {
+      "format": "mp4",
+      "quality": "1080p",
+      "fps": 30
+    }
+  }
+}
+```
+
+**Recipe Schema**:
+| Field | Type | Description |
+|-------|------|-------------|
+| version | string | Recipe format version |
+| timeline | array | Array of timeline clips |
+| filters | array | Array of filters to apply |
+| audio | object | Audio settings |
+| output | object | Output format settings |
+
+**Success Response** (202 Accepted):
+```json
+{
+  "job_id": "job_xyz789",
+  "status": "queued",
+  "estimated_time": 180,
+  "created_at": "2025-01-30T11:00:00Z"
+}
+```
+
+### Check Export Status
+
+Get the status of an export job.
+
+**Endpoint**: `GET /api/v1/video/exports/{job_id}`
+
+**Success Response** (200 OK):
+```json
+{
+  "job_id": "job_xyz789",
+  "status": "processing",
+  "progress": 65,
+  "started_at": "2025-01-30T11:00:00Z",
+  "estimated_completion": "2025-01-30T11:03:00Z",
+  "output_media_uuid": null
+}
+```
+
+**Status Values**:
+- `queued`: Job in queue
+- `processing`: Export in progress
+- `completed`: Export successful
+- `failed`: Export failed
+
+### Get Export Result
+
+Retrieve the completed export result.
+
+**Endpoint**: `GET /api/v1/video/exports/{job_id}/result`
+
+**Success Response** (200 OK):
+```json
+{
+  "job_id": "job_xyz789",
+  "status": "completed",
+  "output_media_uuid": "650e8400-e29b-41d4-a716-446655440001",
+  "playback_url": "https://your-cdn.b-cdn.net/your-library-id/play_video-guid-def456/playlist.m3u8",
+  "duration": 30,
+  "size": 15728640,
+  "completed_at": "2025-01-30T11:03:00Z"
+}
+```
+
+### Cancel Export
+
+Cancel a running export job.
+
+**Endpoint**: `DELETE /api/v1/video/exports/{job_id}`
+
+**Success Response** (204 No Content)
+
+## Live Streaming API
+
+### Create Live Stream
+
+Create a new live stream session.
+
+**Endpoint**: `POST /api/v1/video/live`
+
+**Request Body**:
+```json
+{
+  "title": "My Live Stream",
+  "description": "Stream description",
+  "low_latency": true,
+  "auto_record": true,
+  "max_duration": 3600
+}
+```
+
+**Parameters**:
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| title | string | No | Stream title |
+| description | string | No | Stream description |
+| low_latency | boolean | No | Enable low latency mode (5-7s delay) |
+| auto_record | boolean | No | Auto-record for VOD (default: true) |
+| max_duration | integer | No | Max duration in seconds |
+
+**Success Response** (201 Created):
+```json
+{
+  "stream_id": "stream_abc123",
+  "media_uuid": "750e8400-e29b-41d4-a716-446655440002",
+  "stream_key": "live_xyz789",
+  "rtmp_url": "rtmp://ingest.bunny.live/live_xyz789",
+  "playback_url": "https://your-cdn.b-cdn.net/your-library-id/play_live123/playlist.m3u8",
+  "status": "idle",
+  "created_at": "2025-01-30T12:00:00Z"
+}
+```
+
+### Get Stream Status
+
+Get current status of a live stream.
+
+**Endpoint**: `GET /api/v1/video/live/{stream_id}`
+
+**Success Response** (200 OK):
+```json
+{
+  "stream_id": "stream_abc123",
+  "status": "live",
+  "started_at": "2025-01-30T12:05:00Z",
+  "duration": 300,
+  "viewer_count": 42,
+  "peak_viewers": 75,
+  "health": {
+    "bitrate": 4500000,
+    "framerate": 30,
+    "keyframe_interval": 2
+  }
+}
+```
+
+**Status Values**:
+- `idle`: Stream created, waiting for connection
+- `connecting`: Encoder connecting
+- `live`: Stream is live
+- `disconnected`: Stream ended
+
+### End Live Stream
+
+Manually end a live stream session.
+
+**Endpoint**: `POST /api/v1/video/live/{stream_id}/end`
+
+**Success Response** (200 OK):
+```json
+{
+  "stream_id": "stream_abc123",
+  "status": "ended",
+  "duration": 1800,
+  "vod_media_uuid": "850e8400-e29b-41d4-a716-446655440003",
+  "ended_at": "2025-01-30T12:30:00Z"
+}
+```
+
+### Get Stream Metrics
+
+Retrieve detailed metrics for a live stream.
+
+**Endpoint**: `GET /api/v1/video/live/{stream_id}/metrics`
+
+**Query Parameters**:
+| Field | Type | Description |
+|-------|------|-------------|
+| interval | string | Metric interval (1m, 5m, 1h) |
+| start | string | Start time (ISO 8601) |
+| end | string | End time (ISO 8601) |
+
+**Success Response** (200 OK):
+```json
+{
+  "stream_id": "stream_abc123",
+  "metrics": [
+    {
+      "timestamp": "2025-01-30T12:10:00Z",
+      "viewers": 45,
+      "bitrate": 4500000,
+      "framerate": 29.97,
+      "dropped_frames": 0,
+      "rebuffer_percentage": 0.1
+    }
+  ],
+  "summary": {
+    "total_viewers": 250,
+    "peak_viewers": 75,
+    "average_viewers": 42,
+    "total_watch_time": 10800,
+    "engagement_score": 0.85
+  }
+}
+```
+
+## Webhook API
+
+### Bunny Webhooks
+
+Handle webhooks from the Bunny video provider.
+
+**Endpoint**: `POST /api/v1/video/webhooks/bunny`
+
+**Headers**:
+```
+X-Webhook-Signature: webhook_signature_here
+Content-Type: application/json
+```
+
+**Security**:
+- Preferred: shared secret query parameter: `POST /api/v1/video/webhooks/bunny?secret=...`
+- Optional: `X-Webhook-Signature` header (deployment-specific)
+
+**Request Body** (Status Update):
+```json
+{
+  "VideoLibraryId": 12345,
+  "VideoGuid": "video-guid-abc123",
+  "Status": 3
+}
+```
+
+**Notes**:
+- `VideoGuid` is used to locate the `Media` record (`provider_asset_id`)
+- `Status` indicates processing state (e.g. `3` = finished/ready)
+
+**Success Response** (204 No Content)
+
+**Error Response** (401 Unauthorized):
+```json
+{
+  "error": "Invalid signature"
+}
+```
+
+## Error Responses
+
+All API endpoints follow a consistent error response format.
+
+### Error Response Format
+
+```json
+{
+  "error": {
+    "code": "VIDEO_NOT_FOUND",
+    "message": "The requested video could not be found",
+    "details": {
+      "uuid": "550e8400-e29b-41d4-a716-446655440000"
+    }
+  },
+  "timestamp": "2025-01-30T12:00:00Z",
+  "path": "/api/v1/video/550e8400-e29b-41d4-a716-446655440000/playback"
+}
+```
+
+### Common Error Codes
+
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| INVALID_REQUEST | 400 | Request validation failed |
+| UNAUTHORIZED | 401 | Missing or invalid authentication |
+| FORBIDDEN | 403 | Insufficient permissions |
+| VIDEO_NOT_FOUND | 404 | Video not found |
+| UPLOAD_TOO_LARGE | 413 | File exceeds size limit |
+| UNSUPPORTED_FORMAT | 415 | Video format not supported |
+| RATE_LIMITED | 429 | Too many requests |
+| PROCESSING_ERROR | 500 | Server processing error |
+| PROVIDER_ERROR | 502 | Video provider error |
+| SERVICE_UNAVAILABLE | 503 | Service temporarily unavailable |
+
+### Rate Limiting
+
+API endpoints are rate limited to prevent abuse.
+
+**Rate Limits**:
+- Upload creation: 10 per minute
+- Playback URLs: 60 per minute
+- Export jobs: 5 per hour
+- Live streams: 2 concurrent
+- Webhooks: 1000 per minute
+
+**Rate Limit Headers**:
+```
+X-RateLimit-Limit: 60
+X-RateLimit-Remaining: 45
+X-RateLimit-Reset: 1706621400
+```
+
+**Rate Limited Response** (429 Too Many Requests):
+```json
+{
+  "error": {
+    "code": "RATE_LIMITED",
+    "message": "Rate limit exceeded",
+    "details": {
+      "limit": 60,
+      "remaining": 0,
+      "reset_at": "2025-01-30T12:10:00Z"
+    }
+  }
+}
+```
+
+## Authentication
+
+All API endpoints require authentication using Bearer tokens.
+
+### Request Headers
+
+```
+Authorization: Bearer YOUR_ACCESS_TOKEN
+Content-Type: application/json
+Accept: application/json
+```
+
+### Token Generation
+
+```php
+// Generate API token in Laravel
+$token = $user->createToken('api-token', ['video:read', 'video:write'])->plainTextToken;
+```
+
+### Token Scopes
+
+| Scope | Description |
+|-------|-------------|
+| video:read | View videos and metadata |
+| video:write | Upload and edit videos |
+| video:delete | Delete videos |
+| video:export | Create export jobs |
+| live:create | Create live streams |
+| live:manage | Manage live streams |
+
+## SDK Examples
+
+### JavaScript/TypeScript
+
+```typescript
+import { MediablesVideo } from '@mediables/sdk'
+
+const client = new MediablesVideo({
+  apiKey: 'YOUR_API_KEY',
+  baseUrl: 'https://api.example.com'
+})
+
+// Upload video
+const upload = await client.uploads.create({
+  filename: 'video.mp4',
+  size: 10485760,
+  mimeType: 'video/mp4'
+})
+
+// Upload file to provider
+await client.uploads.uploadFile(upload.uploadUrl, file)
+
+// Get playback URL
+const playback = await client.videos.getPlaybackUrl(upload.mediaUuid)
+console.log('Watch at:', playback.playbackUrl)
+```
+
+### PHP
+
+```php
+use Mediables\VideoClient;
+
+$client = new VideoClient([
+    'api_key' => 'YOUR_API_KEY',
+    'base_url' => 'https://api.example.com'
+]);
+
+// Request upload URL
+$upload = $client->uploads->create([
+    'filename' => 'video.mp4',
+    'size' => 10485760,
+    'mime_type' => 'video/mp4'
+]);
+
+// Get playback URL
+$playback = $client->videos->getPlaybackUrl($upload['media_uuid']);
+echo "Watch at: " . $playback['playback_url'];
+```
+
+### Python
+
+```python
+from mediables import VideoClient
+
+client = VideoClient(
+    api_key='YOUR_API_KEY',
+    base_url='https://api.example.com'
+)
+
+# Upload video
+upload = client.uploads.create(
+    filename='video.mp4',
+    size=10485760,
+    mime_type='video/mp4'
+)
+
+# Get playback URL
+playback = client.videos.get_playback_url(upload['media_uuid'])
+print(f"Watch at: {playback['playback_url']}")
+```
+
+## Postman Collection
+
+Download our Postman collection for easy API testing:
+
+[Download Postman Collection](https://www.getpostman.com/collections/mediables-video-api)
+
+## OpenAPI Specification
+
+The complete OpenAPI 3.0 specification is available at:
+
+```yaml
+openapi: 3.0.0
+info:
+  title: Mediables Video API
+  version: 1.0.0
+  description: Video management API for Mediables package
+servers:
+  - url: https://api.example.com/api/v1
+    description: Production server
+  - url: http://localhost:8000/api/v1
+    description: Development server
+paths:
+  /video/upload:
+    post:
+      summary: Create upload URL
+      tags: [Upload]
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [filename, size, mime_type]
+              properties:
+                filename:
+                  type: string
+                  example: video.mp4
+                size:
+                  type: integer
+                  example: 10485760
+                mime_type:
+                  type: string
+                  enum: [video/mp4, video/quicktime, video/webm]
+                collection:
+                  type: string
+                  example: user-videos
+      responses:
+        '201':
+          description: Upload URL created
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  upload_url:
+                    type: string
+                  upload_id:
+                    type: string
+                  media_uuid:
+                    type: string
+                  expires_at:
+                    type: string
+                    format: date-time
+# ... Additional endpoints
+```
+
+## Changelog
+
+### Version 1.0.0 (2025-01-30)
+- Initial release
+- Video upload with direct-to-provider support
+- Playback with signed URLs
+- Video export with FFmpeg processing
+- Live streaming support
+- Webhook handling for Bunny provider
+
+## Support
+
+For API support and questions:
+
+- **Documentation**: https://mediables.dev/docs/api
+- **GitHub Issues**: https://github.com/mediables/mediables/issues
+- **API Status**: https://status.mediables.dev
+- **Email**: api-support@mediables.dev