From b1abafd1de9482059298f0fca2e35247d275f660 Mon Sep 17 00:00:00 2001 From: zgaetano Date: Tue, 31 Mar 2026 15:35:26 -0400 Subject: [PATCH] Update README.md with documentation --- README.md | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 132 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d685ac0..947da45 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,133 @@ -# ame-job-manager +# AME Remote Job Manager -Grassvalley AMPP job management application \ No newline at end of file +A web-based job submission and monitoring tool for Adobe Media Encoder (AME) in a Grassvalley AMPP environment. Editors upload `.prproj` files through the browser, the server remaps `.gves` proxy paths to high-resolution UNC paths, then delivers the remapped project to AME's watch folder for automated rendering. + +## How It Works + +1. Editor uploads a Premiere Pro `.prproj` file via the web UI +2. The server parses and remaps any `.gves` proxy media paths to their high-res UNC equivalents +3. The remapped project file is written to AME's watch folder +4. AME picks up the file, renders it, and writes output to the output folder +5. The job manager polls both folders and updates job status automatically: `queued → encoding → complete` + +## Features + +- `.prproj` path remapping — replaces `.gves` proxy references with full-resolution UNC paths +- Dry-run analysis mode — inspect what paths would be remapped before submitting +- Real-time job status tracking via watch folder and output folder polling +- AME log parsing — reads `AMEEncodingLog.txt` and error logs for encoding stats +- SMB/UNC path configuration via the settings UI +- Session-based authentication +- Docker-ready with volume-backed persistent storage + +## Prerequisites + +- Docker and Docker Compose +- Adobe Media Encoder running on a Windows machine with a configured watch folder +- The watch folder and output folder accessible as Docker volume mounts (e.g. via SMB) +- `.prproj` files that reference `.gves` proxy media on the AMPP platform + +## Quick Start + +1. Clone the repo and copy the example env file: + +```bash +cp .env.example .env +``` + +2. Edit `.env`: + +```env +PORT=3100 +AUTH_USER=admin +AUTH_PASS=changeme + +# Docker volume mount paths +WATCH_FOLDER=/watch +OUTPUT_FOLDER=/output +AME_LOG_DIR=/ame-logs + +# Polling interval (ms) +POLL_INTERVAL_MS=5000 + +# Job timeout — mark as error if AME hasn't produced output after this long (ms) +JOB_TIMEOUT_MS=3600000 +``` + +3. Mount your watch folder and AME log directory in `docker-compose.yml`, then start: + +```bash +docker compose up -d +``` + +4. Open `http://localhost:3100` in your browser and log in. + +## Docker Compose Example + +```yaml +services: + ame-job-manager: + build: . + ports: + - "3100:3100" + volumes: + - /mnt/ame-watch:/watch # AME watch folder (SMB mount or local) + - /mnt/ame-output:/output # AME output folder + - /mnt/ame-logs:/ame-logs # AME log directory (contains AMEEncodingLog.txt) + - job-data:/data + env_file: .env + restart: unless-stopped + +volumes: + job-data: +``` + +## Job Lifecycle + +| Status | Meaning | +|--------|---------| +| `queued` | File written to watch folder, waiting for AME to pick it up | +| `encoding` | File disappeared from watch folder — AME is actively rendering | +| `complete` | Output file detected in the output folder | +| `error` | Job timed out or AME log reported an error | + +The server polls both folders every `POLL_INTERVAL_MS` milliseconds to detect status transitions. + +## Path Remapping + +The core function of this tool is to make `.prproj` files renderable on a high-res render machine. Premiere projects created on AMPP workstations often reference `.gves` proxy files. This server rewrites those references to the corresponding UNC/high-res paths before handing the project to AME. + +The remapping logic lives in `prproj-remapper.js`. You can test a remap without submitting a job using the analyze endpoint or the dry-run button in the UI. + +## API Reference + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/api/login` | Authenticate and get a session ID | +| POST | `/api/logout` | End session | +| POST | `/api/jobs` | Submit a `.prproj` file and create a job | +| POST | `/api/jobs/analyze` | Dry-run analysis of a `.prproj` (no submission) | +| GET | `/api/jobs` | List all jobs | +| GET | `/api/jobs/:id` | Get a single job by ID | +| DELETE | `/api/jobs/:id` | Delete a job record | +| GET | `/api/status` | System status — folder health, job counts, AME log stats | +| GET | `/api/ame/logs` | Full AME log data with recent entries | +| GET | `/api/settings` | Get current settings | +| POST | `/api/settings` | Update settings (watch folder, SMB config, etc.) | + +All endpoints except `/api/login` require an `x-session-id` header from a valid login. + +## Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `PORT` | `3100` | HTTP port | +| `AUTH_USER` | `admin` | Login username | +| `AUTH_PASS` | `password` | Login password | +| `WATCH_FOLDER` | `/watch` | Path AME watches for new projects | +| `OUTPUT_FOLDER` | `/output` | Path AME writes rendered output to | +| `DATA_DIR` | `/data` | Persistent storage for job records and sessions | +| `UPLOAD_TEMP` | `/tmp/uploads` | Temp dir for incoming file uploads | +| `POLL_INTERVAL_MS` | `5000` | How often to poll watch/output folders (ms) | +| `JOB_TIMEOUT_MS` | `3600000` | Time before a stuck job is marked as error (ms) | +| `AME_LOG_DIR` | `/ame-logs` | Directory containing `AMEEncodingLog.txt` |