dragonflight/docs/GROWING_FILES_QUICKSTART.md

Growing Files + Premiere Panel — Test Plan

A local SMB landing zone for capture so Premiere can edit the master while it is still recording. The promotion worker uploads the finalized file to S3 and the panel relinks Premiere to the hi-res original.

Cluster state (deployed 2026-05-22)

• TrueNAS dataset: NVME/MAM-growing (LZ4, 0777)
• TrueNAS SMB share: mam-growing → /mnt/NVME/MAM-growing
• Host symlink for docker compose: /mnt/NVME/MAM/wild-dragon-growing → the dataset
• mam-api + worker containers mount it at /growing
• Settings (live): growing_enabled=true, growing_smb_url=smb://10.0.0.25/mam-growing

Capture flow (when growing_enabled=true)

1. Recorder starts. mam-api spawns a capture sidecar with GROWING_ENABLED=true and binds /mnt/NVME/MAM/wild-dragon-growing:/growing.
2. FFmpeg writes the hi-res master directly to /growing/<projectId>/<clipName>.<ext> (no S3 stream).
3. The HLS tee continues to publish /live/<assetId>/index.m3u8, so the Recorders + Monitors pages get a real video preview.
4. On stop — or when the file's mtime is idle for growing_promote_after_seconds — the promotion worker:
   • uploads the local file to S3 at projects/<projectId>/masters/<clipName>.<ext>
   • queues a proxy job
   • flips the asset to status=ready
   • deletes the local copy.

Premiere panel install

Grab the latest release artifact and run it — the installer handles the file copy, registry/plist debug-mode flip, and removes any legacy com.wilddragon.mam.panel install:

• Windows: dragonflight-premiere-panel-<version>-windows-setup.exe
• macOS / Win: dragonflight-premiere-panel-<version>.zxp — install via Anastasiy's ZXP Installer (free GUI)

Releases live at https://forge.wilddragon.net/zgaetano/dragonflight/releases.

Building locally (requires Windows for the .exe, any OS for the .zxp):

cd services/premiere-plugin/build
npm install
pwsh -File build-all.ps1     # or: node build-zxp.mjs

The Windows installer takes care of PlayerDebugMode. If you installed the ZXP and the panel does not appear in Window → Extensions, enable debug mode manually:

# macOS
defaults write com.adobe.CSXS.11 PlayerDebugMode 1

# Windows
reg add "HKCU\Software\Adobe\CSXS.11" /v PlayerDebugMode /t REG_SZ /d 1 /f

Mount the SMB share once at OS level: smb://10.0.0.25/mam-growing.

In Premiere: Window → Extensions → Wild Dragon MAM.

Test the live → finalized swap

1. Start a recorder (Ingest → Recorders → Record).
2. The Recorder row's preview becomes a real HLS <video> element.
3. In Premiere, with the growing asset selected (status=live), click Mount Live. The panel calls GET /api/v1/assets/:id/live-path, resolves the SMB UNC path, and app.project.importFiles() it. Premiere imports the still-growing MOV.
4. Stop the recorder. After growing_promote_after_seconds of mtime inactivity, the promotion worker uploads to S3 and flips status.
5. The panel polls every 5 s. When it sees status=ready it surfaces Relink to Hi-Res — clicking that downloads the finalized hi-res and calls ProjectItem.changeMediaPath() to relink in place. Timeline cuts are preserved.

Knobs (Settings → Growing files (SMB))

• growing_enabled — master switch
• growing_path — container mount path (default /growing)
• growing_smb_url — what the Premiere panel hands to the editor
• growing_promote_after_seconds — idle threshold for promotion

What's NOT yet here

• Auth on the SMB share — currently passwordless. Add Samba auth via midclt call sharing.smb.update and put creds in the editor's keychain before exposing this beyond the LAN.
• Concurrent S3 backup of the growing file. Today's MVP writes to SMB only; S3 happens at promotion. If you need belt-and-suspenders, add -f tee in capture-manager to fan out to both destinations.
• Cleanup for stranded files (e.g. recorder crashes mid-capture). The idle threshold will eventually promote them, but a stale-file sweeper would be more graceful.