HEAVYLIGHT.TOOLS

Tool Documentation Atlas

Project Documentation

quickPlace

quickPlace is built for fast, predictable Resolume ingest. It routes media into first open clip slots, can run multiple watch folders at once, and optionally converts non-DXV media before placement.

Primary Workflow Watch Folder Automation
Placement Safety First Open Slot on Target Layer
Runtime URL localhost:17320
Conversion Auto DXV (Optional)

What quickPlace Does

quickPlace removes manual clip-slot hunting during show prep and live operation. It watches selected folders, handles conversion as needed, then ingests into the selected Resolume layer safely.

Multi-Watch Layer Routing Auto-Trigger Optional

First-Time Setup (2 Minutes)

  1. Open quickPlace and click the gear icon to open Settings.
  2. Set Resolume API port (usually 8080) and save.
  3. Activate license key if your build requires licensing.
  4. Close Settings and confirm layers populate correctly.
  • Prerequisites: Resolume running, API enabled, Node.js, and ffmpeg/ffprobe.
  • App URL: http://localhost:17320

Recommended Daily Workflow: Watch Folder

  1. Open Watch Folder tab and choose target layer.
  2. Set auto-trigger behavior for that watcher.
  3. Set folder path (paste path or choose folder).
  4. Click Start Watch.
  5. Drop files into watched folder and let quickPlace ingest automatically.

Each watcher can use its own layer, folder, and auto-trigger setting. Stop individual watchers from Active Watch Folders when needed.

Manual Workflow: Quick Place Tab

  1. Choose target layer and select File or Folder mode.
  2. Drag/drop media or use file/folder picker.
  3. Set Convert if not DXV3 and Auto-trigger loaded clip.
  4. Run place action for file or folder ingest.
  • If manual file path is filled, it takes priority over uploaded file.
  • Still images can be converted to a one-frame DXV clip.
  • Converted outputs use incremented suffixes: _converted, _converted_2, etc.

Reliability Behavior

First-Open-Slot Guardrail

Placement always targets first empty clip slot on the selected layer to reduce overwrite risk.

Resolume Offline Recovery

When Resolume is unavailable, watcher ingest pauses and resumes automatically after reconnect.

Multi-Watch Management

Run multiple watch folders simultaneously with independent layer and trigger settings.

Status Visibility

Use Status, Watch Status, and Recent Jobs panels to inspect failures and queue activity quickly.

Troubleshooting Checklist

  • Layers missing: verify Resolume Web Server is enabled and port matches quickPlace settings.
  • Placement fails: check path validity, layer availability, and open clip slots.
  • Conversion fails: confirm ffmpeg and ffprobe are installed and discoverable.
  • Watcher idle: confirm files arrive at exact watched path and extension is supported.
  • Licensing issue: validate key state in Settings if enforcement is enabled for the build.

Developer Stack Map

  • Desktop shell: Electron (desktop/main.js, desktop/preload.js).
  • Backend runtime: Node server (server.js) for watch/ingest/conversion + API.
  • Frontend: static UI (public/index.html, public/app.js, public/styles.css).
  • Media conversion: bundled FFmpeg/FFprobe with PATH fallback in dev.
  • Resolume integration target: default http://127.0.0.1:8080/api/v1.

Developer Infrastructure

Licensing

License API on Render with local app endpoints at /api/license/*.

Distribution

S3 + CloudFront delivery for beta/stable channels under quickplace/beta and quickplace/stable.

Update Feeds

Stable manifest latest-mac.yml, beta manifest beta-mac.yml.

Domain Layer

Namecheap DNS, Netlify website, license and downloads served on dedicated subdomains.

Developer Release Checklist

  • Version policy: beta x.y.z-beta.N, stable x.y.z.
  • Ensure FFmpeg binaries + notices are complete for mac/win distribution.
  • Run preflight: npm run release:check (or unsigned variant).
  • Run channel-specific build/publish and verify packaged metadata + update feeds.
  • Validate QA gates: tray behavior, watcher reliability, conversion, updater channel, licensing payloads.

Developer Commands and Env

Most used commands:

  • npm run dev
  • npm run build:mac:test:unsigned
  • npm run release:check / npm run release:check:unsigned
  • npm run verify:feed:stable / npm run verify:feed:beta

Key release environment variables:

  • QUICKPLACE_BETA_PUBLISH_URL, QUICKPLACE_STABLE_PUBLISH_URL
  • QUICKPLACE_LICENSE_API_BASE_URL, LICENSE_TOKEN_SECRET, LICENSE_ADMIN_API_KEY
  • APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID
  • CSC_LINK, CSC_KEY_PASSWORD