obs-r2-uploader/ADMIN.md

# Admin Panel - Video Visibility Management

The admin panel allows you to control who can access your videos with three visibility levels:

## Visibility Levels

### 🔒 Private
- **Access**: Only you (admin) can view
- **Use case**: Unreleased content, drafts, personal recordings
- **Sharing**: Not shareable via any link

### 🔗 Shareable
- **Access**: Anyone with the link can view the full video
- **Use case**: Public content, presentations, tutorials
- **Sharing**: Full video URL works for anyone

### ✂️ Clip Shareable
- **Access**: Full video requires admin auth, but time-based clips can be shared
- **Use case**: Long recordings where you only want to share specific segments
- **Sharing**: Generate clip links with start/end times

## Setup

### 1. Create KV Namespace

```bash
cd worker
wrangler kv:namespace create VIDEO_METADATA
```

This creates a Cloudflare KV storage for video metadata.

### 2. Configure Wrangler

Copy the enhanced configuration:

```bash
cp wrangler-enhanced.toml wrangler.toml
```

Update the KV namespace ID in `wrangler.toml`:

```toml
[[kv_namespaces]]
binding = "VIDEO_METADATA"
id = "YOUR_KV_NAMESPACE_ID"  # From step 1
```

### 3. Set Admin Password

```bash
wrangler secret put ADMIN_PASSWORD
```

Enter a secure password when prompted. This will be your login password.

### 4. Build and Deploy

```bash
# Build the worker with embedded admin interface
python3 scripts/build-worker.py

# Deploy
cd worker
wrangler deploy
```

## Usage

### Accessing the Admin Panel

1. Navigate to `https://videos.jeffemmett.com/admin`
2. Enter your admin password
3. You'll see all your videos with management controls

### Managing Video Visibility

For each video, you can:

1. **Change Visibility**
   - Click the dropdown to select: Private, Shareable, or Clip Shareable
   - Changes are saved immediately

2. **Copy Share Link**
   - Click "Copy Link" to get the direct video URL
   - For shareable videos, anyone with this link can watch

3. **Create Video Clips**
   - Click "Create Clip" to expand the clip generator
   - Enter start time (e.g., `0:30` or `1:30`)
   - Enter end time (e.g., `2:00`)
   - Click "Generate Clip Link"
   - Share the clip URL with others

4. **Delete Videos**
   - Click "Delete" to permanently remove a video
   - Confirms before deletion
   - Cannot be undone

### Dashboard Statistics

The admin panel shows:
- **Total Videos**: All videos in your R2 bucket
- **Private**: Videos only you can access
- **Shareable**: Videos accessible by anyone
- **Clip Shareable**: Videos where only clips are shareable

### Search and Filter

Use the search bar to quickly find videos by name.

## Clip Generation

### How Clips Work

When you generate a clip link, it creates a URL like:

```
https://videos.jeffemmett.com/clip/video.mp4?start=0:30&end=2:00
```

This creates a shareable link that:
- Starts playback at the specified time
- Shows only the requested segment
- Works even for "Clip Shareable" videos

### Time Format

Times can be specified as:
- Seconds: `30`, `90`
- Minutes:Seconds: `1:30`, `2:45`
- Hours:Minutes:Seconds: `1:30:00`

### Use Cases for Clips

- **Highlights**: Share best moments from long streams
- **Excerpts**: Pull specific segments from meetings
- **Teasers**: Create preview clips from full content
- **Context**: Share relevant portions without exposing full video

## API Endpoints

For automation, you can use these endpoints (requires authentication):

### List All Videos
```bash
GET /admin/api/videos
```

Returns JSON with all videos and their metadata.

### Update Video Visibility
```bash
POST /admin/api/videos/visibility
Content-Type: application/json

{
  "filename": "video.mp4",
  "visibility": "private" | "shareable" | "clip_shareable"
}
```

### Delete Video
```bash
DELETE /admin/api/videos/{filename}
```

### Authentication

API requests require the `admin_auth` cookie. You can obtain this by logging in through the web interface.

For programmatic access:

```bash
# Login
curl -X POST https://videos.jeffemmett.com/admin/login \
  -H "Content-Type: application/json" \
  -d '{"password": "your_password"}' \
  -c cookies.txt

# Use the cookie for subsequent requests
curl https://videos.jeffemmett.com/admin/api/videos \
  -b cookies.txt
```

## Security Considerations

### Admin Password

- Store your admin password securely
- Use a strong, unique password
- Rotate periodically using `wrangler secret put ADMIN_PASSWORD`

### Session Management

- Sessions expire after 24 hours
- HttpOnly cookies prevent JavaScript access
- Secure flag ensures HTTPS-only transmission

### Video URLs

- **Private videos**: URLs return 403 Forbidden without auth
- **Shareable videos**: Anyone with the URL can access (by design)
- **Clip shareable**: Full video protected, clips are public

### Best Practices

1. **Don't share admin credentials**
2. **Use Private for sensitive content**
3. **Review permissions regularly**
4. **Consider signed URLs** for temporary access (future feature)
5. **Monitor your R2 usage** in Cloudflare dashboard

## Public vs Admin Gallery

### Public Gallery
- URL: `https://videos.jeffemmett.com/gallery`
- Shows only "Shareable" videos
- No authentication required
- Great for sharing your portfolio

### Admin Panel
- URL: `https://videos.jeffemmett.com/admin`
- Shows ALL videos regardless of visibility
- Requires authentication
- Full management controls

## Troubleshooting

### Can't login

- Verify password: `wrangler secret put ADMIN_PASSWORD`
- Check browser cookies are enabled
- Try incognito mode to clear old sessions

### Video not accessible after changing visibility

- Changes are immediate, but CDN may cache
- Wait a few minutes for cache invalidation
- Use `?cache_bust=timestamp` in URL to bypass cache

### Clips not working

- Ensure video format supports seeking (MP4 recommended)
- Check that start/end times are valid
- Verify "Clip Shareable" is set correctly

### KV namespace errors

- Verify KV namespace ID in `wrangler.toml`
- Check KV namespace exists: `wrangler kv:namespace list`
- Ensure worker has KV binding configured

## Advanced Usage

### Bulk Operations

You can script bulk visibility changes:

```bash
# Set all videos to private
for video in $(curl -s https://videos.jeffemmett.com/admin/api/videos -b cookies.txt | jq -r '.videos[].name'); do
  curl -X POST https://videos.jeffemmett.com/admin/api/videos/visibility \
    -b cookies.txt \
    -H "Content-Type: application/json" \
    -d "{\"filename\": \"$video\", \"visibility\": \"private\"}"
done
```

### Backup Metadata

Export your visibility settings:

```bash
curl https://videos.jeffemmett.com/admin/api/videos -b cookies.txt > backup.json
```

### Custom Domain for Admin

You can set up a separate subdomain for admin:

```toml
[env.production]
routes = [
  { pattern = "videos.jeffemmett.com/*", custom_domain = true },
  { pattern = "admin.jeffemmett.com/*", custom_domain = true }
]
```

Then route `/admin/*` paths to the admin subdomain.

## Future Enhancements

Potential features for future versions:

- [ ] **Signed URLs**: Time-limited access for private videos
- [ ] **User roles**: Multiple admin levels
- [ ] **View analytics**: Track video views and downloads
- [ ] **Automatic transcoding**: Generate optimized clips server-side
- [ ] **Thumbnail management**: Custom thumbnails for each video
- [ ] **Batch uploads**: Upload multiple videos at once
- [ ] **Video editing**: Trim, merge, or modify videos in the admin panel
- [ ] **Access logs**: See who accessed which videos
- [ ] **Expiring links**: Set expiration dates for shareable links
- [ ] **Password-protected videos**: Per-video password protection

## Support

For issues or questions:
- Check the main [README.md](README.md)
- Review [SETUP.md](SETUP.md) for configuration help
- Check Cloudflare Worker logs: `wrangler tail`

---

**Admin Panel Version:** 1.0
**Last Updated:** 2024-11-22