# Wild Dragon MAM - Premiere Pro CEP Panel

A professional media asset management (MAM) plugin for Adobe Premiere Pro that allows users to browse, search, and import proxy files directly from the Wild Dragon MAM system into their Premiere projects.

## Features

- **Server Connection**: Configure and connect to the Wild Dragon MAM server
- **Asset Browser**: Browse and search media assets in a grid view
- **Project Filter**: Filter assets by project
- **Lazy-Loaded Thumbnails**: Efficient thumbnail loading with signed URLs from S3
- **Asset Details**: View comprehensive metadata (codec, resolution, FPS, duration, file size, tags)
- **Proxy Import**: Download and import proxy files into Premiere Pro projects
- **Batch Import**: Import multiple assets at once
- **Progress Tracking**: Real-time download and import progress indicators
- **Wild Dragon Design System**: Professional OKLCH-based dark theme matching web-ui branding
- **FCP XML Export & Conform**: Export timeline as FCP XML, conform server-side via FFmpeg, and import as new MAM asset (see [Advanced Features Guide](docs/ADVANCED_FEATURES.md))
- **Hi-Res Auto-Relink**: Detect proxy clips, render trimmed hi-res segments server-side, and auto-relink in the timeline (see [Advanced Features Guide](docs/ADVANCED_FEATURES.md))

## Installation

Grab the installer for your platform from the
[latest release](https://forge.wilddragon.net/zgaetano/dragonflight/releases):

| File | Platform | How to install |
|------|----------|----------------|
| `dragonflight-premiere-panel-<version>-windows-setup.exe` | Windows | Double-click, Next → Finish. Copies the bundle, sets `PlayerDebugMode`, and removes any legacy `com.wilddragon.mam.panel` install. |
| `dragonflight-premiere-panel-<version>.zxp` | macOS + Windows | Install with [Anastasiy's ZXP Installer](https://install.anastasiy.com/) (free GUI). |

### macOS ZXP — one extra step

The `.zxp` is self-signed, so macOS editors must enable CEP debug mode once
before the panel will load:

```
defaults write com.adobe.CSXS.11 PlayerDebugMode 1
```

Restart Premiere Pro afterward. The Windows `.exe` installer does this
automatically for every CEP version Premiere might use (CSXS 8 through 13).

### Building from source

If you do not want to install the release artifact, you can run the panel
straight from the source tree. See [`build/README.md`](build/README.md) for
the build pipeline, or copy the directory yourself:

```
# Windows (PowerShell, as the same user that runs Premiere)
robocopy . "$env:APPDATA\Adobe\CEP\extensions\net.wilddragon.dragonflight.panel" /MIR /XD build

# macOS
rsync -a --exclude=build/ ./ ~/Library/Application\ Support/Adobe/CEP/extensions/net.wilddragon.dragonflight.panel/
```

Then enable `PlayerDebugMode` as above.

### Access the Panel

1. Open Premiere Pro
2. Go to **Window** > **Extensions** > **Wild Dragon MAM**
3. The panel will open as a floating window on the right side

### Upgrading from `com.wilddragon.mam.panel`

The bundle ID changed to `net.wilddragon.dragonflight.panel` as part of the
wild-dragon → dragonflight rename. The Windows installer offers to remove
the old folder for you (checkbox on the install wizard, default on). For ZXP
installs or manual copies, delete the legacy folder yourself or you will see
two panels in **Window → Extensions**:

```
# Windows
Remove-Item -Recurse -Force "$env:APPDATA\Adobe\CEP\extensions\com.wilddragon.mam.panel"

# macOS
rm -rf ~/Library/Application\ Support/Adobe/CEP/extensions/com.wilddragon.mam.panel
```

## Usage

### Connect to MAM Server

1. In the panel, enter the MAM server URL (default: `http://localhost:7434`)
2. Click the **Connect** button
3. The status indicator will turn green when connected

### Browse Assets

- Once connected, assets will load in the grid
- Scroll through the asset grid to see thumbnails
- Click an asset to view detailed information in the right panel

### Search Assets

- Enter a search term in the search bar to filter assets by filename
- Press Enter or wait 300ms for results to update automatically

### Filter by Project

- Use the project dropdown to filter assets by project
- Select "All Projects" to see all assets

### Import Assets

**Import Single Asset:**
1. Click an asset to select it
2. Click the **Import** button
3. The plugin will download the proxy file and import it into your project

**Import Multiple Assets:**
1. Click **Import All** to import all visible assets
2. Assets will be imported sequentially

### Monitor Progress

- A progress bar appears at the bottom during downloads and imports
- Progress updates in real-time
- Once complete, a success message is displayed

## Configuration

### Server Settings

The panel saves your server URL to browser local storage, so it persists between sessions.

To change the server URL:
1. Edit the URL in the input field
2. Click **Connect** to test the connection
3. The URL is saved automatically

## File Structure

```
net.wilddragon.dragonflight.panel/   # installed bundle
├── CSXS/
│   └── manifest.xml          # CEP extension manifest
├── css/
│   └── styles.css            # Panel styling with dark theme
├── js/
│   ├── CSInterface.js        # Adobe CEP interface shim
│   └── main.js               # Main panel logic
├── jsx/
│   └── premiere.jsx          # Premiere Pro ExtendScript
├── index.html                # Main panel UI
├── .debug                    # CEP debug configuration
└── README.md                 # This file

build/                        # not shipped — installer/.zxp build pipeline
├── README.md                 # how to build .zxp + .exe locally
├── build-all.ps1             # build both artifacts
├── build-zxp.mjs             # ZXP signer
├── installer.iss             # Inno Setup script
└── ...
```

## API Integration

The plugin connects to the Wild Dragon MAM API with the following endpoints:

- `GET /api/health` - Health check
- `GET /api/projects` - List projects
- `GET /api/assets` - List assets (with pagination and search)
- `GET /api/assets/{id}` - Get asset details
- `POST /api/assets/{id}/download` - Get signed download URL
- `POST /api/assets/{id}/proxies/{proxy_id}/download` - Get signed proxy URL

## Premiere Pro Integration

The plugin uses ExtendScript to interact with Premiere Pro:

- `importFileToProject(filePath)` - Import a file into the project
- `getActiveSequence()` - Get the active sequence
- `insertClipToSequence(filePath, trackIndex)` - Insert clip into timeline
- `getProjectPath()` - Get current project path
- `getSequenceTracks()` - Get available video tracks
- `getPlayheadPosition()` - Get playhead timecode
- `getProjectInfo()` - Get project metadata
- `exportSequence(path, preset)` - Export current sequence

## Troubleshooting

### Panel doesn't appear in Extensions menu

- Ensure the extension folder is in the correct CEP extensions directory
- On Windows, verify `PlayerDebugMode` is set to `1` in the registry
- On macOS, verify `PlayerDebugMode` is set to `1` in defaults
- Restart Premiere Pro after making changes

### Cannot connect to server

- Verify the server URL is correct
- Check that the MAM server is running and accessible
- Ensure no firewall is blocking the connection
- Check browser console (F12) for detailed error messages

### Assets not loading

- Verify connection is established (green indicator)
- Check that assets exist on the server
- Try refreshing by clicking Connect again

### Import fails

- Verify the proxy files exist on the MAM server
- Check that S3 credentials are configured on the server
- Ensure disk space is available for temporary downloads
- Check Premiere Pro error messages in the Event Monitor

## Performance Notes

- Thumbnails are lazy-loaded for better performance
- Asset grid is paginated (50 items per page)
- Search and filter operations are debounced (300ms)
- Large proxy downloads show real-time progress

## Security

- Server connections should use HTTPS in production
- Signed URLs expire after a configurable period (default: 1 hour)
- The plugin does not store any credentials; URLs are obtained on-demand
- All file downloads happen to temporary directories

## Requirements

- Adobe Premiere Pro 22.0 or later
- CEP 11.0 compatible version of Premiere Pro
- Wild Dragon MAM server 1.0 or later
- Internet connection to MAM server

## Support

For issues, feature requests, or questions:
- Check the troubleshooting section above
- Review Premiere Pro's Event Monitor for detailed errors
- Check browser console (F12) for JavaScript errors
- Contact the Wild Dragon team

## License

Copyright 2026 Wild Dragon. All rights reserved.

---

**Version:** 1.0.0  
**Last Updated:** April 2026