SCHEMAXIS · Declared work. Results you can check.Documentation ↗ · Contact
schemaxis/Agent’s Hands

Documentation / premiere.md
Core 11629ae · View or edit Markdown on GitHub ↗

Adobe Premiere Pro sequence contracts

This is an experimental integration, with no installed Premiere native acceptance recorded. The bundled UXP panel implements a bounded read-only sequenceContract using public Adobe APIs. Linux runs fail explicitly with NATIVE_ENVIRONMENT_UNAVAILABLE; host planning, schema inspection and verification of retained responses work without Adobe imports. Node tests execute the actual companion with contract doubles and are host-only evidence.

Declare the exact absolute saved project path, active sequence name, width/height, integer fps and ordered source ranges. See examples/schemaxis/premiere-sequence.json. Windows drive paths and macOS absolute paths are accepted as native identities; the host does not read the source files. Each clip uses zero-based startFrame and positive frameCount; the native out point is expected to be exclusive. Ranges accumulate from timeline zero. Rates 24/25/30/50/60 use 254016000000 ticks per second, serialized as exact decimal strings. No JavaScript floating-point tick arithmetic or BigInt is required. At most 128 clips and 600 timeline frames are accepted.

The native sequence must have exactly one unmuted video track, no captions or transitions, and at most 8 empty audio tracks. Disabled, adjustment, reversed, offline, nested, merged, multicam or proxy clips are rejected. Source identity, native in/out/duration/start/end ticks, sequence dimensions/timebase/end and runtime identity must match. This checks structure; it does not inspect source bytes, effects, intermediate time remapping, colour, pixel fidelity, audio output or rendered media. Equal endpoint durations do not prove unchanged playback inside a clip.

The companion reads the complete bounded observation twice and rechecks active project/sequence GUIDs around each read. Matching observations detect observed changes; they are not an atomic snapshot. Keep Premiere idle during inspection. The panel never selects, edits, saves, imports, renders or exports a project.

Native setup and execution#

  1. Use Windows or macOS with Premiere 26.5.0 or later and Adobe UXP Developer Tool 2.2 or later. Enable developer mode. Load src/schemaxis/adaptors/premiere/uxp/manifest.json using UDT. Its manifest 5 host is premierepro, with only localFileSystem: request permission. There is no network, external-process, arbitrary-JavaScript or unrestricted filesystem permission.
  2. Open the saved native project and activate the declared sequence. Create a private local bridge directory. Replace project/source identities in your authored JSON with exact native paths.
  3. Run schemaxis run your-contract.json --output-directory /absolute/new-attempt --premiere-bridge /absolute/private-jobs --timeout 300. The dedicated CLI option configures transport; configure premiere configures executables and is not a bridge configuration command. A private config may instead set locations.premiereBridge to the existing absolute directory.
  4. While the host waits, inspect /absolute/new-attempt/bridge-job.json. Open the Schemaxis Sequence Contract panel, click its button and select that exact fresh jobDirectory using the native folder picker. The panel reads request.json, observes the active sequence and writes the response. Select the job subdirectory, rather than its parent bridge directory.
  5. Run schemaxis verify /absolute/new-attempt to repeat offline checks. Read observation.json, verification.json, the retained request/response and failed result if applicable. Artifact 0 is a JSON sequenceObservation; no project or video artifact is produced.

Each attempt creates an unpredictable per-attempt directory (mode 0700 where supported, otherwise inheriting the private bridge folder access controls) and fresh 128-bit nonce. Request bytes, response filename and returned requestSHA256 must agree; stale previous responses cannot satisfy a new attempt. The panel checks bounded expiry and re-reads the request before writing and publishing. It writes a pending file fully, then publishes with documented UXP Entry.moveTo, so the host reads the completed response name. The host rejects symlink/nonregular/oversized response files before parsing, bounds JSON to 1 MiB, and checks the shared elapsed deadline/cancellation before success. No native application subprocess is owned or killed. Cancellation ends the host wait; expired/cancelled responses cannot become accepted output. Failed bridge jobs are retained for diagnosis; use a fresh attempt rather than overwriting them.

Ordinary retained-byte or authored-plan changes fail verification. A request hash and native identity fields do not provide remote attestation or defend against someone fabricating all local evidence. Trust the supplied panel and local filesystem. Host-side expressions, document references and finite analytic planning use the shared runtime; every native visit still needs a fresh human-selected UXP job. No workflow scheduling, automatic reuse or shared native-inspection workspace hook is advertised for this human-mediated transport.

Qualification recipe#

On a native machine, independently prepare and inspect a silent six-frame colours.mp4 source (H.264 AVC, 25 fps; red, green, blue, yellow, cyan, magenta in order) and two 32x24/25 fps sequences in a saved project. Schemaxis Colours contains source frames 3..5 followed by 0..1. Schemaxis Repeat contains frames 1..2 twice. Use one video track and empty audio tracks, without transitions/effects/retiming. Verify this manually in Premiere before running the tool.

Run python tools/qualify_premiere.py --bridge /absolute/private-jobs --project-path /absolute/colours.prproj --source-path /absolute/colours.mp4 --output-directory /absolute/new-acceptance. For each printed case, activate its sequence and select the fresh printed job folder in the panel. The tool checks literal expected ticks/ranges and rejected mutations independently. It retains actual responses and a report. This recipe is currently unexecuted on installed Premiere; absorbedVersion remains null and no native qualification receipt is registered. The ordinary conformance kit also contains baseline and held-out cases; its unattended timeout/cancel expectations are not yet native-qualified for a human-mediated panel.

Primary references#

The MP4 example uses an Adobe-listed import format; it is human-prepared and independently inspected. It does not imply that the Shotcut Matroska/FFV1 fixture imports into Premiere. See Adobe supported file formats.

Complete named track layout#

sequenceLayout checks a complete ordered video-track inventory and named editorial coverage decisions. It is useful for finding a missing insert, unintended gap, wrong track/source placement, or an overlay that no longer intersects its background. It uses the same fresh-folder UXP transport as sequenceContract. The existing operation and its contiguous single-track input remain supported.

Start with the layout example or the held-out variant, or use the Premiere named track coverage Studio starter. Replace the project/source paths and prepare the native sequence manually. This operation does not create tracks or apply the declared edits.

  • tracks is the complete list of 1–8 native video tracks in native index order, including empty tracks. Each name is exact, nonblank and unique. Extra tracks, renamed tracks or a changed order fail the contract.
  • Each track's clips lists all its items in timeline order. timelineFrame and startFrame are zero-based inclusive timeline/source starts; frameCount is a positive duration. All are measured at the declared integer sequence timebase. The source out and timeline end are exclusive. Gaps and overlays on different tracks are supported; overlap within one track is rejected. At most 128 clips total and 600 timeline frames are allowed.
  • endFrame is the exclusive sequence end and must equal the latest clip end. Empty trailing padding is not supported. Every track must be unmuted and every clip enabled. Audio tracks must be empty; captions, transitions and the legacy unsupported clip states are rejected. Locked tracks need no change because observation is read-only.
  • Optional requirements contains up to 32 named coverage gates. Select distinct declared track names, an inclusive startFrame, positive frameCount, and minimumActiveTracks (default 1). Every frame in that half-open range must have at least this many selected tracks occupied. Use one for union coverage or two for an overlay intersection. Omission reports gaps but adds no coverage gate.

The baseline has Base items at [0,4) and [6,10), an Overlay at [3,7), and an empty Reserved track. Thus Base has 8 occupied frames and gap [4,6); the Overlay has 4 occupied frames and gaps [0,3), [7,10). Their union covers all 10 frames and both are occupied at frame 3. The variant uses Overlay [4,6) (source [1,3)): union coverage still passes, but there is no two-track intersection. Adjacent clips meeting at an exclusive end produce no gap and never count twice on one track.

The panel returns native identities and exact tick strings, without computing coverage or copying authored expectations into observed values. The host first compares every declared range and identity, then independently builds a bounded frame occupancy grid from the observed ticks. A boundary even one tick away from a frame is rejected, never rounded. The observed duration must equal both the source and timeline interval lengths. This rejects ordinary retiming mismatches; equal endpoints still do not establish unchanged intermediate time remapping. Fractional rates remain explicitly unsupported.

Artifact 1 for this operation is layout.json: per-track occupiedFrames and half-open gaps, plus each requirement's uncoveredFrames and passed decision. schemaxis verify rebuilds this report from retained native observations and the authored input. Missing or changed reports fail verification. On REQUIREMENT_FAILED, the observation and failed report remain for diagnosis; inspect the listed frames, correct the intended requirement or manually repair the native timeline, then start a fresh attempt. INVALID_LAYOUT identifies an inconsistent authored range before native access.

Editorial occupancy is not visible rendered footage. Muted/disabled tracks or clips are rejected rather than silently counted. Effects, opacity, masks, source pixels and renderer visibility are not observed. A clip may occupy an interval while rendering transparent or black pixels. Two matching DOM reads remain a best-effort observation, not an atomic snapshot or remote attestation.

Layout native qualification recipe and status#

On Windows/macOS, use the same independently inspected six-frame silent colour source as the earlier recipe. Prepare two 32×24/25 fps sequences in the saved project, named Schemaxis Layout and Schemaxis Layout Variant. Both have exactly three unmuted video tracks named Base, Overlay, Reserved in that order, empty audio tracks, and no captions/transitions/effects/retiming. Base uses source [0,4) at timeline [0,4) and source [2,6) at [6,10). Baseline Overlay uses source [0,4) at [3,7); variant Overlay uses source [1,3) at [4,6). Reserved is empty. Confirm those intervals independently in Premiere before running:

PYTHONPATH=src python3 tools/qualify_premiere_layout.py \
  --bridge /absolute/private-jobs --project-path /absolute/colours.prproj \
  --source-path /absolute/colours.mp4 --output-directory /absolute/new-layout-acceptance

The tool prompts for each sequence and fresh job folder, checks independently specified literal ticks/gaps/occupancy, probes retained-report tampering, and runs a coverage failure against the unchanged baseline. Its report is scoped evidence, not automatic registration of a native qualification receipt. Native lifecycle qualification still requires the broader documented acceptance review.

This recipe has not run on installed Premiere. The development host is Linux; an actual normal runner attempt returns NATIVE_ENVIRONMENT_UNAVAILABLE. Host schema/planning, fixed DOM doubles and report tampering tests are available, but cannot establish the native API behaviour. On 17 October 2026, Adobe's stable application release notes list 26.5.2, while the UXP changelog lists API baseline 26.5.0. Release tracking now uses the application release notes to detect patch releases. absorbedVersion remains null. The mapping uses public VideoTrack name/index/mute/item queries and the source/timeline methods in VideoClipTrackItem.