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

```
# macOS
rsync -a services/premiere-plugin/ ~/Library/Application\ Support/Adobe/CEP/extensions/com.wilddragon.mam.panel/

# Windows
robocopy services\premiere-plugin %APPDATA%\Adobe\CEP\extensions\com.wilddragon.mam.panel /MIR
```

Enable CEP debug:

```
# 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.