mono/packages/ui/docs/QUICKSTART_MUX.md

# Mux Video Quick Start Guide

## 🎯 What You Have Now

You now have a complete Mux video integration with:

1. **VideoCard Component** - Display videos with Vidstack player
2. **Mux Uploader Integration** - Upload videos directly to Mux
3. **Video Player Playground** - Test at `/playground/video-player`
4. **Supabase Edge Function** - Secure Mux API proxy

## ⚡ Quick Setup (5 minutes)

### Step 1: Get Mux Credentials

1. Go to https://dashboard.mux.com/signup
2. After signing up, go to **Settings** → **Access Tokens**
3. Click **Generate new token**
4. Name it "pm-pics" and enable **Mux Video** permissions
5. Copy the **Token ID** and **Token Secret**

### Step 2: Configure Supabase Secrets

You need to add your Mux credentials as secrets to your Supabase project:

```bash
# Using Supabase CLI
supabase secrets set MUX_TOKEN_ID=your_token_id_here
supabase secrets set MUX_TOKEN_SECRET=your_token_secret_here
```

Or via Supabase Dashboard:
1. Go to your Supabase project dashboard
2. Navigate to **Project Settings** → **Edge Functions** → **Secrets**
3. Add `MUX_TOKEN_ID` and `MUX_TOKEN_SECRET`

### Step 3: Deploy the Edge Function

```bash
supabase functions deploy mux-proxy
```

### Step 4: Test It Out

1. Start your dev server: `npm run dev`
2. Navigate to http://localhost:5173/playground/video-player
3. Sign in (required for uploads)
4. Go to the "Upload Video" tab
5. Drag & drop a video or click to select one
6. Watch it upload, process, and play!

## 📝 How It Works

### The Upload Flow

```
User Selects Video
       ↓
Frontend calls /functions/v1/mux-proxy (create-upload)
       ↓
Edge Function calls Mux API
       ↓
Returns signed upload URL
       ↓
MuxUploader uploads video directly to Mux
       ↓
Video processes on Mux servers
       ↓
Poll for asset creation
       ↓
Get playback ID
       ↓
Play video using Vidstack player
```

### Key Concepts

- **Upload ID**: Temporary ID for tracking the upload
- **Asset ID**: Permanent ID for managing the video in Mux
- **Playback ID**: Public ID used to stream the video

### URLs You Get

After uploading, you get these URLs:

**HLS Stream (for playback):**
```
https://stream.mux.com/{PLAYBACK_ID}.m3u8
```

**Thumbnail:**
```
https://image.mux.com/{PLAYBACK_ID}/thumbnail.jpg
```

**MP4 Download (if enabled):**
```
https://stream.mux.com/{PLAYBACK_ID}/high.mp4
```

## 💾 Save to Database

The playground has a "Save to Database" button that stores:

```typescript
{
  user_id: current_user.id,
  title: "Video Title",
  description: "Description",
  video_url: "https://stream.mux.com/{playback_id}.m3u8",
  thumbnail_url: "https://image.mux.com/{playback_id}/thumbnail.jpg",
  meta: {
    mux_asset_id: "asset_abc123",
    mux_playback_id: "playback_xyz789"
  }
}
```

## 🎨 Using in Your App

### Upload Component

```tsx
import MuxUploader from "@mux/mux-uploader-react";
import { supabase } from "@/integrations/supabase/client";

function MyUploader() {
  const fetchUploadUrl = async () => {
    const response = await fetch(
      `${supabase.supabaseUrl}/functions/v1/mux-proxy`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${session.access_token}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ action: 'create-upload' }),
      }
    );
    
    const { data } = await response.json();
    return data.url;
  };

  return (
    <MuxUploader
      endpoint={fetchUploadUrl}
      onSuccess={(e) => console.log('Done!', e.detail)}
    />
  );
}
```

### Video Player

```tsx
import VideoCard from "@/components/VideoCard";

function MyVideo({ video }) {
  return (
    <VideoCard
      videoId={video.id}
      videoUrl={video.video_url}
      thumbnailUrl={video.thumbnail_url}
      title={video.title}
      author={video.author_name}
      authorId={video.user_id}
      likes={video.likes_count || 0}
      comments={video.comments_count || 0}
      description={video.description}
    />
  );
}
```

## 🆓 Pricing

Mux offers **$20/month in free credits**, which includes:
- ~40 minutes of video encoding
- ~100 hours of video streaming

Perfect for testing and small projects!

## 🔧 Troubleshooting

**Upload button doesn't appear**
- Make sure you're signed in
- Check that edge function is deployed

**Upload fails**
- Verify Mux credentials are set as Supabase secrets
- Check browser console for errors
- Make sure edge function has correct environment variables

**Video stuck processing**
- Large videos take time (can be 5-10 minutes for HD)
- Check Mux dashboard: https://dashboard.mux.com
- Look for the asset in the "Assets" section

**Video won't play**
- Verify the HLS URL format: `https://stream.mux.com/{playback_id}.m3u8`
- Check that playback policy is "public"
- Try the URL directly in your browser

## 📚 More Info

See `docs/mux-integration.md` for detailed documentation including:
- Complete API reference
- Webhook setup
- Advanced configuration
- Production best practices

## 🎉 You're Done!

You now have:
- ✅ VideoCard component for displaying videos
- ✅ Mux upload integration
- ✅ Secure API proxy via Edge Functions
- ✅ Video player playground
- ✅ Database storage ready

Go to `/playground/video-player` and start uploading! 🎬