EasyField

Releases · Release process

EasyField is a compact AI creation panel for DaVinci Resolve. It combines live EasyField Cloud generation with a local Resolve bridge that can grab timeline media and place generated image, video, and audio results back on the current timeline.

Current status

The catalog contains 20 tools across 5 categories. Every card now opens a complete, auto-saved workspace with recipes, source selection, validated-model browsing, cost preflight and a review state. 17 of the 20 carry a live execution path in the direct-cloud development/operator path; the remaining three (culling, review, prompt in src/data/toolDefinitions.ts) are execution: 'review-only' and end at a review screen with no implementation behind them. Counted from that file rather than maintained by hand — an earlier revision of this paragraph named eight tools and had been understating the catalog for some time.

The established generation adapters are available to the verified direct-cloud development/operator path. Regular-customer paid forwarding remains deliberately fail-closed until the server-side generation and billing gateway is deployed and verified. Newer workflows stop at an honest preflight when their cloud or Resolve execution adapter is not installed; they never simulate a successful paid run. SuperBrain can call a real cloud chat model in the direct path and validates its typed plan, but applying a multi-tool plan remains blocked until every step exposes cost, privacy, provider, placement and rollback contracts.

The Resolve-hosted main process uses SQLite for settings, drafts, job ledgers and artifact metadata. Accepted provider task IDs recover after restart, and remote generation results are materialized into the local artifact store as soon as the host can download them.

Requirements

• macOS 15+ and DaVinci Resolve Studio 21.0.2+ installed directly from Blackmagic Design. EasyField loads WorkflowIntegration.node from Resolve's official SDK SamplePlugin installation; the Blackmagic binary is neither tracked by this repository nor redistributed in EasyField releases.
• Node.js 22.18+ and npm.
• For local development only, ffmpeg and ffprobe on PATH provide timeline grabs, media conversion and animation export. With Homebrew: brew install ffmpeg. Public builds instead require the signed, checksum-pinned runtime catalog described below.
• For local development only, Python 3 with the project-managed librosa environment provides Beat Detection. See plugin/python/README.md; packages are not installed globally.
• A verified EasyField account with an active plan and sufficient credits for customer generation. Administrator and lifetime Partner accounts may instead connect their own direct cloud credential.

Development

npm ci
npm run dev

Open http://localhost:5173. This is enough for UI and EasyField Cloud development; the Resolve badge remains offline unless the plugin bridge is also running.

Browser development exercises the UI and local development proxies. To exercise the main/preload boundary without Resolve, leave Vite running and start the development-only Electron harness in a second terminal:

npm run plugin:dev

Resolve supplies the production Electron host. The npm Electron dependency is used only by this local harness and is not copied into the plugin, update archive, or installer.

Useful checks:

npm test              # all contract and bridge tests
npm run build         # typecheck + standalone UI build
npm run plugin:build  # typecheck + plugin UI build
npm run verify:source # plugin UI first, then all source/contract tests
npm run verify        # clean-checkout tests + both builds + release-tree checks

The standalone dist/ build contains only the UI. Live EasyField Cloud and Resolve calls must be served through the Vite development proxies or the plugin's embedded server.

Developer install in DaVinci Resolve

npm ci
npm run plugin:install

Do not copy WorkflowIntegration.node into this repository. The install preflight verifies the regular, signed, universal module installed by Blackmagic at its official SamplePlugin path before staging EasyField.

The install script builds a checksummed local release, publishes it under ~/Library/Application Support/EasyField/Updates, and atomically swaps the manifest-listed integration files into:

/Library/Application Support/Blackmagic Design/DaVinci Resolve/Workflow Integration Plugins/com.easyfield.panel

macOS will request administrator permission. Restart Resolve, open a project and timeline, then choose Workspace → Workflow Integrations → EasyField.

The managed librosa runtime is versioned separately under ~/Library/Application Support/EasyField/runtime/python; the 300+ MB virtual environment is not duplicated inside Resolve's root-owned plugin directory by developer installs. It is not valid evidence for a public release.

Production update and PKG builders reject the checked-in, unavailable runtime catalog. A distributable build requires exact arm64 and x64 payload inventories for FFmpeg/ffprobe, librosa/Python and whisper.cpp, valid Mach-O signatures, written redistribution approval and matching SPDX records. No runtime URL, version or checksum is guessed by the build.

End users install a signed and notarized macOS PKG produced by the protected GitHub Release workflow. The PKG validates macOS and Resolve compatibility, requires Resolve to be closed, verifies the complete payload, and can restore the previous installation if its atomic swap fails. See docs/RELEASING.md for repository setup, signing, notarization and the no-publish local dry run. Published installers are available only from the official EasyField releases.

In-app updates

npm run plugin:build also publishes the newest local build to Application Support. The installed panel checks that channel after launch and every five minutes. A newer version or newer build ID opens an Update dialog; the same action is always available in Settings → Resolve → EasyField updates.

Update installation accepts no renderer-supplied path or URL. Main stages only manifest-listed files, and the administrator side rechecks the exact file set and every SHA-256 before swapping directories. A temporary recovery copy is used only during the atomic swap and is removed after successful verification. Restart Resolve after an update so its Electron host loads the new integration.

A tracked pre-push hook republishes that local channel automatically, so a push surfaces an update in a panel that is already open. npm install installs it via the prepare script; run npm run hooks:install to install it by hand. The hook never blocks a push, and it restores plugin/update-manifest.json when only its build timestamp moved, so pushing does not leave a dirty tree.

Local developer installs use the local channel described above. Production PKG installs contain a fixed public GitHub Release feed and an Ed25519 public key. The production updater accepts only that pinned repository, verifies the signed release envelope, archive size and SHA-256, then verifies the exact manifest tree before requesting the same administrator-approved atomic swap. A published version is immutable and an update always requires a higher SemVer.

Account credentials and local security

Regular customers sign in to an EasyField account and never enter or receive a provider credential. Refresh credentials are encrypted with Electron safeStorage (macOS Keychain-backed), while access tokens stay in Main process memory. The renderer receives only a sanitized account snapshot and an opaque internal proxy token.

For a regular customer, checkout opens in the system browser and the signed billing webhook plus database reconciliation update the EasyField account's plan and credits. The desktop stores an encrypted, account-bound checkout request so it can resume after restart or sign-out. It does not infer payment from a local timeout, an expired browser URL, a higher balance, or a changed entitlement; /checkout-status is the authoritative recovery path.

Only a server-verified administrator or active lifetime Partner can see the direct-cloud connection form. Its credential is validated in Main, encrypted, and stored in an account-specific Keychain-backed scope; it is re-authorized against the account service before every direct request. Browser development is not a production credential store and direct access requires an explicit development opt-in.

The Resolve bridge listens only on 127.0.0.1 and protects privileged endpoints with a per-process secret plus origin checks. Keep port 18832 local and do not remove those checks: the bridge can read timeline media and mutate a project.

Billing and credit safety

The Supabase migrations beginning with supabase/migrations/202607140001_subscription_billing.sql and continuing through supabase/migrations/20260715170000_private_billing_rls_hardening.sql form the server-side billing foundation. They are intentionally not a signal that live billing is enabled. Production still requires the real customer generation gateway, deployed merchant and Supabase services, Partner refund/chargeback revocation, production allowlisting and packaged testing of the Main-owned password-recovery callback, tax/document decisions, sandbox verification and operational launch gates. See docs/ACCOUNT_SERVICE_DEPLOYMENT.md for the complete fail-closed deployment checklist.

The database, not the renderer or an external payment adapter, owns the billing state machine:

• billing_private.plan_catalog is the sole authority for plan prices, monthly grants, top-up rates, the $10 minimum and exact model entitlements. Checkout rows and subscription rows receive immutable catalog snapshots in database triggers. Top-up charges use integer arithmetic and round upward to a USD cent, but the $10 minimum is checked against the nominal pre-rounding amount; clients cannot submit a cheaper amount or a larger grant. Catalog rows are append-only. A future price revision must be introduced by an explicit versioned migration and subscription-transition policy, never by mutating the row beneath a paid period.
• A paid-generation quote requires an active, unexpired plan entitlement unless the target account has the server-issued direct-upstream capability. The Starter restriction matches only the exact regular Seedance 2 model ID; similarly named Fast and Mini models are not accidentally blocked. Direct-upstream quotes intentionally skip reserve_credits; the trusted backend goes directly from the approved quote to provider execution so an administrator or active Partner is never accidentally debited from the EasyField ledger.
• Partner is a separate $999 one-time lifetime entitlement with zero included EasyField credits, all verified models and a customer-owned upstream account. It is never represented as a subscription plan or administrator role. Only a reconciled payment event can activate it; regular customers never receive raw upstream prices, balances, purchase links or provider account data.
• Subscription and purchased credits remain separate lots. Reservations consume the soonest-expiring lots first, settlement is append-only and every grant, capture and release retry is bound to a canonical SHA-256 request snapshot. Public account snapshots and column grants exclude provider costs, raw source references, idempotency keys, payment tokens and webhook evidence.
• An annual subscription schedules exactly 12 monthly grant windows. Each lot expires at the next calendar-month boundary, preserving month-end cadence; obsolete schedules are cancelled when the authoritative subscription period changes. A schedule uses the immutable subscription pricing/grant snapshot, so a later catalog version or deactivation cannot cancel credits from an annual period that was already paid.
• Auto-reload is also catalog-derived in a database trigger. Enabling it requires an active matching plan and a private saved payment method belonging to the same customer and supporting the plan currency. The trigger derives the rate, minimum, cent-rounded price and currency; the optional monthly ceiling is a user safety setting, while NULL means that the user chose no ceiling.
• Saved payment method identifiers and renewal evidence live only in billing_private. A due renewal is persisted and claimed before network I/O. Claiming commits permission for exactly one provider call: even a retry with the same claim ID is rejected, so a lost or ambiguous response must be reconciled rather than charged again.
• Webhook ingestion deduplicates both the signed provider event ID and the transport delivery ID, and binds each to the SHA-256 of the exact signed body. Processing uses explicit claim/finish functions, allowing a stale processing lease to be reclaimed without mutating the original evidence.

Only trusted backend workers receive the private function surface. Their direct table privileges are deliberately narrow: balances, lots, reservations, allocations, quotes, webhook evidence, schedules, roles and the ledger are mutated through audited SECURITY DEFINER functions. The first administrator can be bootstrapped once from a trusted database session; every later role change requires a current administrator actor and cannot remove the last admin.

Troubleshooting

• Resolve stays offline: launch EasyField from Resolve rather than a normal browser, confirm a project and timeline are open, and restart Resolve after an install. A native-module error means Resolve's official SamplePlugin module is missing, has an unexpected signature/architecture, or does not match the installed Resolve version; reinstall Resolve from Blackmagic Design.
• Plugin is missing from the menu: rerun npm run plugin:install, confirm the destination above exists, and restart Resolve Studio.
• Frame grab, conversion, or render fails: run ffmpeg -version and ffprobe -version. Install or expose both binaries to Resolve's environment.
• Beat Detection reports that librosa is missing: follow plugin/python/README.md to create plugin/python/.venv. The panel reports the missing pack safely and never modifies the timeline while it is unavailable.
• A recovered job says it needs attention: sign back in to the same EasyField account, then reopen the Activity panel. Accepted provider task IDs are retained in SQLite.
• EasyField Cloud returns an authentication or credit error: refresh the account in Account, confirm its plan and EasyField credit balance, then sign in again if the session expired. Only a verified administrator or lifetime Partner should reconnect a direct-cloud credential. Run the app through Vite or the embedded plugin server; opening dist/index.html directly bypasses the required account proxy.
• Port 18832 is already in use: close stale EasyField/Electron processes and relaunch the panel.

License and third-party software

EasyField is source-visible but not open source. The project is published under an all-rights-reserved proprietary notice; see LICENSE. Runtime dependency and vendor boundaries are recorded in THIRD_PARTY_NOTICES.md, and every release also produces an SPDX SBOM. Report vulnerabilities privately as described in SECURITY.md.