dragonflight/services/premiere-plugin/docs/ADVANCED_FEATURES.md

# Premiere Plugin: Advanced Features Guide

## Overview

The Wild Dragon MAM Premiere Pro CEP Panel includes two advanced production features: **FCP XML Export & Conform** and **Hi-Res Auto-Relink**. These features streamline the post-production workflow by enabling timeline-level round-tripping between proxy editing and conformed delivery.

---

## 1. FCP XML Export & Conform

Export your Premiere Pro timeline as a Final Cut Pro XML, conform it server-side via FFmpeg, and return it as a new MAM asset.

### Use Cases

- **Proxy-to-Hi-Res Conform**: Edit with low-res proxies, then produce a full-resolution master
- **Broadcast Delivery**: Export with broadcast-quality codec presets (ProRes, DNxHR-equivalent H.264)
- **Multi-Format Output**: Generate web, archive, and broadcast versions from a single timeline
- **Remote Conform**: Upload the timeline XML to the server; the server handles the heavy FFmpeg rendering

### Step-by-Step Workflow

1. Ensure you are connected to a MAM server and have an active sequence in Premiere Pro
2. Click **Advanced > Export & Conform Timeline**
3. In the slide panel that opens, configure export settings:
   - **Preset**: Choose one of the four presets (Broadcast, Web, Archive, Custom)
   - **Codec**: H.264, H.265/HEVC, or ProRes
   - **Quality**: Low, High, or Broadcast-grade
   - **Resolution**: Match sequence, 4K, 1080p, or 720p
   - **Audio**: Include or exclude
4. Click **Start Conform**
5. The plugin reads the timeline, generates FCP XML, and uploads it to the server
6. A progress bar shows the conform job status (parsing, processing, encoding, uploading)
7. When complete, the conformed asset appears in the MAM asset grid with a name like "Conformed: [Sequence Name]"
8. The new asset can be imported like any other MAM asset

### Preset Descriptions

| Preset | Codec | Quality | Resolution | Audio | Use Case |
|--------|-------|---------|------------|-------|----------|
| **Broadcast Quality** | ProRes | Broadcast | Match | Stereo | TV/Cinema delivery |
| **Web Delivery** | H.264 | High | 1080p | AAC | YouTube/Vimeo |
| **Archive** | H.265 | Broadcast | 4K | AAC | Long-term storage |
| **Custom** | User-set | User-set | User-set | Optional | Flexible output |

### Troubleshooting

| Issue | Likely Cause | Solution |
|-------|-------------|----------|
| "No active sequence" | No timeline is open in Premiere | Open a sequence and retry |
| Conform job stuck at 0% | Server worker not running | Check that the worker service is running (`services/worker`) |
| "Asset not found for reel" | Source media not in MAM | Import the hi-res originals into MAM first |
| Conform fails with ffmpeg error | Incompatible codec/format | Try a different codec preset |

### Performance Considerations

- Conform speed depends on timeline length and server GPU/CPU resources
- A 30-minute timeline typically completes in 5-15 minutes with hardware encoding
- Conform jobs run sequentially (concurrency: 1) to avoid overloading the server
- Large timelines may trigger the 50MB request body limit; if needed, increase `express.json({ limit })` in the API

---

## 2. Hi-Res Auto-Relink

Detect proxy clip usage in your timeline, render frame-accurate trimmed hi-res segments on the server, and automatically relink every clip.

### Use Cases

- **Proxy-to-Hi-Res Upgrade**: Replace every proxy clip in a sequence with the matching hi-res original
- **Multi-Clip Batch Relink**: Relink 5, 10, or 50+ clips in a single operation
- **Frame-Accurate Segments**: Each clip is trimmed to exactly its timeline in/out points (no handles)
- **Selective Relink**: Deselect specific clips you want to keep as proxies

### Step-by-Step Workflow

1. Ensure you are connected to a MAM server and have an active sequence in Premiere Pro
2. Click **Advanced > Fetch & Relink All**
3. The plugin analyzes the timeline and shows a clip list with checkboxes:

   ```
   [x] clip_001.mov  Track V1  00:00:00:00 - 00:00:05:12
   [x] clip_002.mov  Track V1  00:00:05:13 - 00:00:12:06
   [x] clip_003.mov  Track V2  00:00:00:00 - 00:00:08:00
   ```

4. Review the clip list; uncheck any clips you do not want relinked
5. Click **Fetch & Relink**
6. A confirmation dialog shows the summary (X clips will be relinked)
7. The server trims each hi-res clip to the exact frame range used on the timeline
8. Each trimmed segment is downloaded and automatically relinked in Premiere
9. A completion summary shows:
   - Success count (relinked successfully)
   - Retry count (relinked after one retry)
   - Failed count (could not relink, with error detail)

### Clip Selection & Filtering

- Each clip instance (including multiple uses of the same source with different in/out points) is listed separately
- Clips are identified by their timeline track and position
- The plugin resolves each clip's file path to a MAM asset ID using the import mapping

### Understanding Temp Segments & TTL

- Each trimmed segment is stored in S3 under `temp-segments/{clipInstanceId}.mov`
- Segments have a 24-hour TTL (time-to-live)
- After 24 hours, expired segments are automatically cleaned up by the server's cleanup task
- The cleanup runs hourly and removes both the S3 objects and the database records
- If a relink job is interrupted, expired segments can be regenerated by running the workflow again

### Troubleshooting Relink Failures

| Issue | Likely Cause | Solution |
|-------|-------------|----------|
| "Asset not found" | Source clip not imported through MAM | Import clips into MAM before editing |
| Segment download fails | Network issue or expired S3 URL | Retry the relink |
| "No matching clip" | Timeline clip position changed | Refresh the clip list and retry |
| Relink partially succeeds | Some clips may be locked | Unlock clips in Premiere and retry failed items |

### Best Practices for Proxy Workflows

1. **Import through MAM first**: Always import proxy or hi-res files through the plugin to create the file-path-to-asset mapping
2. **Use descriptive filenames**: The plugin matches clips by their file path; unique, stable paths improve reliability
3. **Avoid moving media mid-project**: If source files move, the clip list may show "unmatched" clips
4. **Run after final picture lock**: For best results, relink after editing is complete
5. **Server must have hi-res originals**: The trim worker fetches original files from S3; ensure they are uploaded before relinking

---

## 3. Technical Details

### Job Queue & FIFO Processing

- All conform and trim jobs use BullMQ (backed by Redis)
- Conform: FIFO queue, concurrency 1 (one job at a time to avoid resource contention)
- Trim: FIFO queue, concurrency 4 (up to four segments can be rendered simultaneously)
- Job status is tracked in real-time via Server-Sent Events (SSE) from `GET /api/v1/jobs/events`

### Temp Segment Storage & Cleanup

- Database table: `temp_segments`
- S3 prefix: `temp-segments/`
- Default TTL: 24 hours (configurable in database)
- Cleanup interval: 3600 seconds (1 hour)
- S3 lifecycle policy: 1-day expiration on `temp-segments/` prefix (backup to database cleanup)

### Network Requirements

- The plugin communicates with the MAM API over HTTP/HTTPS
- Conform XML upload may be large (up to 50MB); ensure adequate bandwidth
- Trim segments are downloaded from S3 presigned URLs; the server generates these on demand
- For on-premise deployments, latency between the editor workstation and the server should be under 50ms for responsive polling

### Performance Impact

- Timeline reading is fast (< 1 second for 100+ clips)
- Conform jobs use server-side GPU encoding if available (NVIDIA NVENC)
- Trim jobs use stream copy where possible (no re-encode) for speed
- Proxy playback is unaffected during relink operations
- The plugin's UI remains responsive during background operations

---

## Files

| File | Purpose |
|------|---------|
| `services/premiere-plugin/jsx/premiere.jsx` | ExtendScript: timeline reading, FCP XML export, relink |
| `services/premiere-plugin/js/main.js` | Panel JS: UI, API calls, workflow orchestration |
| `services/premiere-plugin/index.html` | Panel UI: layout, advanced section, slide panels |
| `services/premiere-plugin/css/styles.css` | Panel styles: Wild Dragon design system |
| `services/mam-api/src/routes/assets.js` | API: batch-trim, trim-status endpoints |
| `services/mam-api/src/routes/sequences.js` | API: conform endpoint |
| `services/mam-api/src/routes/jobs.js` | API: job listing, trim queue registration |
| `services/mam-api/src/tasks/cleanupTempSegments.js` | Server: temp segment cleanup task |
| `services/worker/src/workers/conform.js` | Worker: FCP XML parsing, FFmpeg conform |
| `services/worker/src/workers/trimWorker.js` | Worker: frame-accurate FFmpeg trimming |
| `services/worker/src/index.js` | Worker: queue registration |