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