@mohanscodex/spectra-code 0.4.9 → 0.5.0

package/skills/cloudflare-deploy/references/stream/api-live.md

@@ -0,0 +1,195 @@
+# Stream Live Streaming API
+
+Live input creation, status checking, simulcast, and WebRTC streaming.
+
+## Create Live Input
+
+### Using Cloudflare SDK
+
+```typescript
+import Cloudflare from 'cloudflare';
+
+const client = new Cloudflare({ apiToken: env.CF_API_TOKEN });
+
+const liveInput = await client.stream.liveInputs.create({
+  account_id: env.CF_ACCOUNT_ID,
+  recording: { mode: 'automatic', timeoutSeconds: 30 },
+  deleteRecordingAfterDays: 30
+});
+
+// Returns: { uid, rtmps, srt, webRTC }
+```
+
+### Raw fetch API
+
+```typescript
+async function createLiveInput(accountId: string, apiToken: string) {
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/live_inputs`,
+    {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        recording: { mode: 'automatic', timeoutSeconds: 30 },
+        deleteRecordingAfterDays: 30
+      })
+    }
+  );
+  const { result } = await response.json();
+  return {
+    uid: result.uid,
+    rtmps: { url: result.rtmps.url, streamKey: result.rtmps.streamKey },
+    srt: { url: result.srt.url, streamId: result.srt.streamId, passphrase: result.srt.passphrase },
+    webRTC: result.webRTC
+  };
+}
+```
+
+## Check Live Status
+
+```typescript
+async function getLiveStatus(accountId: string, liveInputId: string, apiToken: string) {
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/live_inputs/${liveInputId}`,
+    { headers: { 'Authorization': `Bearer ${apiToken}` } }
+  );
+  const { result } = await response.json();
+  return {
+    isLive: result.status?.current?.state === 'connected',
+    recording: result.recording,
+    status: result.status
+  };
+}
+```
+
+## Simulcast (Live Outputs)
+
+### Create Output
+
+```typescript
+async function createLiveOutput(
+  accountId: string, liveInputId: string, apiToken: string,
+  outputUrl: string, streamKey: string
+) {
+  return fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/live_inputs/${liveInputId}/outputs`,
+    {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        url: `${outputUrl}/${streamKey}`,
+        enabled: true,
+        streamKey // For platforms like YouTube, Twitch
+      })
+    }
+  ).then(r => r.json());
+}
+```
+
+### Example: Simulcast to YouTube + Twitch
+
+```typescript
+const liveInput = await createLiveInput(accountId, apiToken);
+
+// Add YouTube output
+await createLiveOutput(
+  accountId, liveInput.uid, apiToken,
+  'rtmp://a.rtmp.youtube.com/live2',
+  'your-youtube-stream-key'
+);
+
+// Add Twitch output
+await createLiveOutput(
+  accountId, liveInput.uid, apiToken,
+  'rtmp://live.twitch.tv/app',
+  'your-twitch-stream-key'
+);
+```
+
+## WebRTC Streaming (WHIP/WHEP)
+
+### Browser to Stream (WHIP)
+
+```typescript
+async function startWebRTCBroadcast(liveInputId: string) {
+  const pc = new RTCPeerConnection();
+  
+  // Add local media tracks
+  const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
+  stream.getTracks().forEach(track => pc.addTrack(track, stream));
+  
+  // Create offer
+  const offer = await pc.createOffer();
+  await pc.setLocalDescription(offer);
+  
+  // Send to Stream via WHIP
+  const response = await fetch(
+    `https://customer-<CODE>.cloudflarestream.com/${liveInputId}/webRTC/publish`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/sdp' },
+      body: offer.sdp
+    }
+  );
+  
+  const answer = await response.text();
+  await pc.setRemoteDescription({ type: 'answer', sdp: answer });
+}
+```
+
+### Stream to Browser (WHEP)
+
+```typescript
+async function playWebRTCStream(videoId: string) {
+  const pc = new RTCPeerConnection();
+  
+  pc.addTransceiver('video', { direction: 'recvonly' });
+  pc.addTransceiver('audio', { direction: 'recvonly' });
+  
+  const offer = await pc.createOffer();
+  await pc.setLocalDescription(offer);
+  
+  const response = await fetch(
+    `https://customer-<CODE>.cloudflarestream.com/${videoId}/webRTC/play`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/sdp' },
+      body: offer.sdp
+    }
+  );
+  
+  const answer = await response.text();
+  await pc.setRemoteDescription({ type: 'answer', sdp: answer });
+  
+  return pc;
+}
+```
+
+## Recording Settings
+
+| Mode | Behavior |
+|------|----------|
+| `automatic` | Record all live streams |
+| `off` | No recording |
+| `timeoutSeconds` | Stop recording after N seconds of inactivity |
+
+```typescript
+const recordingConfig = {
+  mode: 'automatic',
+  timeoutSeconds: 30, // Auto-stop 30s after stream ends
+  requireSignedURLs: true, // Require token for VOD playback
+  allowedOrigins: ['https://yourdomain.com']
+};
+```
+
+## In This Reference
+
+- [README.md](./README.md) - Overview and quick start
+- [api.md](./api.md) - On-demand video APIs
+- [configuration.md](./configuration.md) - Setup and config
+- [patterns.md](./patterns.md) - Full-stack flows, best practices
+- [gotchas.md](./gotchas.md) - Error codes, troubleshooting
+
+## See Also
+
+- [workers](../workers/) - Deploy live APIs in Workers

package/skills/cloudflare-deploy/references/stream/api.md

@@ -0,0 +1,199 @@
+# Stream API Reference
+
+Upload, playback, live streaming, and management APIs.
+
+## Upload APIs
+
+### Direct Creator Upload (Recommended)
+
+**Backend: Create upload URL (SDK)**
+```typescript
+import Cloudflare from 'cloudflare';
+
+const client = new Cloudflare({ apiToken: env.CF_API_TOKEN });
+
+const uploadData = await client.stream.directUpload.create({
+  account_id: env.CF_ACCOUNT_ID,
+  maxDurationSeconds: 3600,
+  requireSignedURLs: true,
+  meta: { creator: 'user-123' }
+});
+// Returns: { uploadURL: string, uid: string }
+```
+
+**Frontend: Upload file**
+```typescript
+async function uploadVideo(file: File, uploadURL: string) {
+  const formData = new FormData();
+  formData.append('file', file);
+  return fetch(uploadURL, { method: 'POST', body: formData }).then(r => r.json());
+}
+```
+
+### Upload from URL
+
+```typescript
+const video = await client.stream.copy.create({
+  account_id: env.CF_ACCOUNT_ID,
+  url: 'https://example.com/video.mp4',
+  meta: { name: 'My Video' },
+  requireSignedURLs: false
+});
+```
+
+## Playback APIs
+
+### Embed Player (iframe)
+
+```html
+<iframe
+  src="https://customer-<CODE>.cloudflarestream.com/<VIDEO_ID>/iframe?autoplay=true&muted=true"
+  style="border: none;" height="720" width="1280"
+  allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
+  allowfullscreen="true"
+></iframe>
+```
+
+### HLS/DASH Manifest URLs
+
+```typescript
+// HLS
+const hlsUrl = `https://customer-<CODE>.cloudflarestream.com/${videoId}/manifest/video.m3u8`;
+
+// DASH
+const dashUrl = `https://customer-<CODE>.cloudflarestream.com/${videoId}/manifest/video.mpd`;
+```
+
+### Thumbnails
+
+```typescript
+// At specific time (seconds)
+const thumb = `https://customer-<CODE>.cloudflarestream.com/${videoId}/thumbnails/thumbnail.jpg?time=10s`;
+
+// By percentage
+const thumbPct = `https://customer-<CODE>.cloudflarestream.com/${videoId}/thumbnails/thumbnail.jpg?time=50%`;
+
+// Animated GIF
+const gif = `https://customer-<CODE>.cloudflarestream.com/${videoId}/thumbnails/thumbnail.gif`;
+```
+
+## Signed URLs
+
+```typescript
+// Low volume (<1k/day): Use API
+async function getSignedToken(accountId: string, videoId: string, apiToken: string) {
+  const response = await fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/${videoId}/token`,
+    {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        exp: Math.floor(Date.now() / 1000) + 3600,
+        accessRules: [{ type: 'ip.geoip.country', action: 'allow', country: ['US'] }]
+      })
+    }
+  );
+  return (await response.json()).result.token;
+}
+
+// High volume: Self-sign with RS256 JWT (see "Self-Sign JWT" in patterns.md)
+```
+
+## Captions & Clips
+
+### Upload Captions
+
+```typescript
+async function uploadCaption(
+  accountId: string, videoId: string, apiToken: string,
+  language: string, captionFile: File
+) {
+  const formData = new FormData();
+  formData.append('file', captionFile);
+  return fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/${videoId}/captions/${language}`,
+    {
+      method: 'PUT',
+      headers: { 'Authorization': `Bearer ${apiToken}` },
+      body: formData
+    }
+  ).then(r => r.json());
+}
+```
+
+### Generate AI Captions
+
+```typescript
+// TODO: Requires Workers AI integration - see workers-ai reference
+async function generateAICaptions(accountId: string, videoId: string, apiToken: string) {
+  return fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/${videoId}/captions/generate`,
+    {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ language: 'en' })
+    }
+  ).then(r => r.json());
+}
+```
+
+### Clip Video
+
+```typescript
+async function clipVideo(
+  accountId: string, videoId: string, apiToken: string,
+  startTime: number, endTime: number
+) {
+  return fetch(
+    `https://api.cloudflare.com/client/v4/accounts/${accountId}/stream/clip`,
+    {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        clippedFromVideoUID: videoId,
+        startTimeSeconds: startTime,
+        endTimeSeconds: endTime
+      })
+    }
+  ).then(r => r.json());
+}
+```
+
+## Video Management
+
+```typescript
+// List videos
+const videos = await client.stream.videos.list({
+  account_id: env.CF_ACCOUNT_ID,
+  search: 'keyword' // optional
+});
+
+// Get video details
+const video = await client.stream.videos.get(videoId, {
+  account_id: env.CF_ACCOUNT_ID
+});
+
+// Update video
+await client.stream.videos.update(videoId, {
+  account_id: env.CF_ACCOUNT_ID,
+  meta: { title: 'New Title' },
+  requireSignedURLs: true
+});
+
+// Delete video
+await client.stream.videos.delete(videoId, {
+  account_id: env.CF_ACCOUNT_ID
+});
+```
+
+## In This Reference
+
+- [README.md](./README.md) - Overview and quick start
+- [configuration.md](./configuration.md) - Setup and config
+- [api-live.md](./api-live.md) - Live streaming APIs (RTMPS/SRT/WebRTC)
+- [patterns.md](./patterns.md) - Full-stack flows, best practices
+- [gotchas.md](./gotchas.md) - Error codes, troubleshooting
+
+## See Also
+
+- [workers](../workers/) - Deploy Stream APIs in Workers

package/skills/cloudflare-deploy/references/stream/configuration.md

@@ -0,0 +1,141 @@
+# Stream Configuration
+
+Setup, environment variables, and wrangler configuration.
+
+## Installation
+
+```bash
+# Official Cloudflare SDK (Node.js, Workers, Pages)
+npm install cloudflare
+
+# React component library
+npm install @cloudflare/stream-react
+
+# TUS resumable uploads (large files)
+npm install tus-js-client
+```
+
+## Environment Variables
+
+```bash
+# Required
+CF_ACCOUNT_ID=your-account-id
+CF_API_TOKEN=your-api-token
+
+# For signed URLs (high volume)
+STREAM_KEY_ID=your-key-id
+STREAM_JWK=base64-encoded-jwk
+
+# For webhooks
+WEBHOOK_SECRET=your-webhook-secret
+
+# Customer subdomain (from dashboard)
+STREAM_CUSTOMER_CODE=your-customer-code
+```
+
+## Wrangler Configuration
+
+```jsonc
+{
+  "name": "stream-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2025-01-01", // Use current date for new projects
+  "vars": {
+    "CF_ACCOUNT_ID": "your-account-id"
+  }
+  // Store secrets: wrangler secret put CF_API_TOKEN
+  // wrangler secret put STREAM_KEY_ID
+  // wrangler secret put STREAM_JWK
+  // wrangler secret put WEBHOOK_SECRET
+}
+```
+
+## Signing Keys (High Volume)
+
+Create once for self-signing tokens (thousands of daily users).
+
+**Create key**
+```bash
+curl -X POST \
+  "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/keys" \
+  -H "Authorization: Bearer <API_TOKEN>"
+
+# Save `id` and `jwk` (base64) from response
+```
+
+**Store in secrets**
+```bash
+wrangler secret put STREAM_KEY_ID
+wrangler secret put STREAM_JWK
+```
+
+## Webhooks
+
+**Setup webhook URL**
+```bash
+curl -X PUT \
+  "https://api.cloudflare.com/client/v4/accounts/{account_id}/stream/webhook" \
+  -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Content-Type: application/json" \
+  -d '{"notificationUrl": "https://your-worker.workers.dev/webhook"}'
+
+# Save the returned `secret` for signature verification
+```
+
+**Store secret**
+```bash
+wrangler secret put WEBHOOK_SECRET
+```
+
+## Direct Upload / Live / Watermark Config
+
+```typescript
+// Direct upload
+const uploadConfig = {
+  maxDurationSeconds: 3600,
+  expiry: new Date(Date.now() + 3600000).toISOString(),
+  requireSignedURLs: true,
+  allowedOrigins: ['https://yourdomain.com'],
+  meta: { creator: 'user-123' }
+};
+
+// Live input
+const liveConfig = {
+  recording: { mode: 'automatic', timeoutSeconds: 30 },
+  deleteRecordingAfterDays: 30
+};
+
+// Watermark
+const watermark = {
+  name: 'Logo', opacity: 0.7, padding: 20,
+  position: 'lowerRight', scale: 0.15
+};
+```
+
+## Access Rules & Player Config
+
+```typescript
+// Access rules: allow US/CA, block CN/RU, or IP allowlist
+const geoRestrict = [
+  { type: 'ip.geoip.country', action: 'allow', country: ['US', 'CA'] },
+  { type: 'any', action: 'block' }
+];
+
+// Player params for iframe
+const playerParams = new URLSearchParams({
+  autoplay: 'true', muted: 'true', preload: 'auto', defaultTextTrack: 'en'
+});
+```
+
+## In This Reference
+
+- [README.md](./README.md) - Overview and quick start
+- [api.md](./api.md) - On-demand video APIs
+- [api-live.md](./api-live.md) - Live streaming APIs
+- [patterns.md](./patterns.md) - Full-stack flows, best practices
+- [gotchas.md](./gotchas.md) - Error codes, troubleshooting
+
+## See Also
+
+- [wrangler](../wrangler/) - Wrangler CLI and configuration
+- [workers](../workers/) - Deploy Stream APIs in Workers

package/skills/cloudflare-deploy/references/stream/gotchas.md

@@ -0,0 +1,130 @@
+# Stream Gotchas
+
+## Common Errors
+
+### "ERR_NON_VIDEO"
+
+**Cause:** Uploaded file is not a valid video format
+**Solution:** Ensure file is in supported format (MP4, MKV, MOV, AVI, FLV, MPEG-2 TS/PS, MXF, LXF, GXF, 3GP, WebM, MPG, QuickTime)
+
+### "ERR_DURATION_EXCEED_CONSTRAINT"
+
+**Cause:** Video duration exceeds `maxDurationSeconds` constraint
+**Solution:** Increase `maxDurationSeconds` in direct upload config or trim video before upload
+
+### "ERR_FETCH_ORIGIN_ERROR"
+
+**Cause:** Failed to download video from URL (upload from URL)
+**Solution:** Ensure URL is publicly accessible, uses HTTPS, and video file is available
+
+### "ERR_MALFORMED_VIDEO"
+
+**Cause:** Video file is corrupted or improperly encoded
+**Solution:** Re-encode video using FFmpeg or check source file integrity
+
+### "ERR_DURATION_TOO_SHORT"
+
+**Cause:** Video must be at least 0.1 seconds long
+**Solution:** Ensure video has valid duration (not a single frame)
+
+## Troubleshooting
+
+### Video stuck in "inprogress" state
+- **Cause**: Processing large/complex video
+- **Solution**: Wait up to 5 minutes for processing; use webhooks instead of polling
+
+### Signed URL returns 403
+- **Cause**: Token expired or invalid signature
+- **Solution**: Check expiration timestamp, verify JWK is correct, ensure clock sync
+
+### Live stream not connecting
+- **Cause**: Invalid RTMPS URL or stream key
+- **Solution**: Use exact URL/key from API, ensure firewall allows outbound 443
+
+### Webhook signature verification fails
+- **Cause**: Incorrect secret or timestamp window
+- **Solution**: Use exact secret from webhook setup, allow 5-minute timestamp drift
+
+### Video uploads but isn't visible
+- **Cause**: `requireSignedURLs` enabled without providing token
+- **Solution**: Generate signed token or set `requireSignedURLs: false` for public videos
+
+### Player shows infinite loading
+- **Cause**: CORS issue with allowedOrigins
+- **Solution**: Add your domain to `allowedOrigins` array
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Max file size | 30 GB |
+| Max frame rate | 60 fps (recommended) |
+| Max duration per direct upload | Configurable via `maxDurationSeconds` |
+| Token generation (API endpoint) | 1,000/day recommended (use signing keys for higher) |
+| Live input outputs (simulcast) | 5 per live input |
+| Webhook retry attempts | 5 (exponential backoff) |
+| Webhook timeout | 30 seconds |
+| Caption file size | 5 MB |
+| Watermark image size | 2 MB |
+| Metadata keys per video | Unlimited |
+| Search results per page | Max 1,000 |
+
+## Performance Issues
+
+### Upload is slow
+- **Cause**: Large file size or network constraints
+- **Solution**: Use TUS resumable upload, compress video before upload, check bandwidth
+
+### Playback buffering
+- **Cause**: Network congestion or low bandwidth
+- **Solution**: Use ABR (adaptive bitrate) with HLS/DASH, reduce max bitrate
+
+### High processing time
+- **Cause**: Complex video codec, high resolution
+- **Solution**: Pre-encode with H.264 (most efficient), reduce resolution
+
+## Type Safety
+
+```typescript
+// Error response type
+interface StreamError {
+  success: false;
+  errors: Array<{
+    code: number;
+    message: string;
+  }>;
+}
+
+// Handle errors
+async function uploadWithErrorHandling(url: string, file: File) {
+  const formData = new FormData();
+  formData.append('file', file);
+  const response = await fetch(url, { method: 'POST', body: formData });
+  const result = await response.json();
+  
+  if (!result.success) {
+    throw new Error(result.errors[0]?.message || 'Upload failed');
+  }
+  return result;
+}
+```
+
+## Security Gotchas
+
+1. **Never expose API token in frontend** - Use direct creator uploads
+2. **Always verify webhook signatures** - Prevent spoofed notifications
+3. **Set appropriate token expiration** - Short-lived for security
+4. **Use requireSignedURLs for private content** - Prevent unauthorized access
+5. **Whitelist allowedOrigins** - Prevent hotlinking/embedding on unauthorized sites
+
+## In This Reference
+
+- [README.md](./README.md) - Overview and quick start
+- [configuration.md](./configuration.md) - Setup and config
+- [api.md](./api.md) - On-demand video APIs
+- [api-live.md](./api-live.md) - Live streaming APIs
+- [patterns.md](./patterns.md) - Full-stack flows, best practices
+
+## See Also
+
+- [workers](../workers/) - Deploy Stream APIs securely