Repository navigation
v0.5.0 - one-click start, pairing token, and everything from 0.4
The biggest update since the first release. 0.4.0 was never published on its own, so this release carries all of it — a listening report, razor-free editing, Premiere Speech-to-Text, effects from the CLI, one action contract — plus 0.5: double-click start-up without clicking Load, a pairing token and an audit log, fixes from three real editing jobs, and a probe of what Premiere's UXP API really does.
Upgrading from 0.3.2 is a breaking change: run the CLI, broker and panel from the same 0.5.0 folder (the broker refuses older CLIs), and read "Changes visible to scripts" below if you call the bridge from your own code.
New in 0.5
Start it with a double-click
setup_bridge.bat (once) opens a setup window of its own (Edge app mode: no address bar or tabs, no console left open) that walks through the machine step by step, in English or Chinese: Python, the Python packages, Premiere (at least the panel's minimum, 26.3), UXP Developer Tool, developer mode, the optional ffmpeg / Pillow / faster-whisper, then a desktop shortcut, starting with Windows and starting the bridge. Each fix is a button; the window checks again whenever you come back to it. Without Python it opens a page that explains how to install it. setup_bridge.bat --console is the same check as text (python -m ppro_bridge.doctor), and python -m ppro_bridge.setup_ui --demo shows the window on made-up data. Its animated icons are Material Line Icons and SVG Spinners (both MIT, see THIRD_PARTY_NOTICES.md).
start_bridge.bat (every day) runs the broker with --load-panel: it starts UXP Developer Tool minimized when it is not running and loads the panel into Premiere whenever Premiere connects to UXP Developer Tool. No more clicking Load.
UXP Developer Tool still has to run: Premiere only connects to a developer service that UXP Developer Tool announces through Adobe's own IPC, so the bridge drives UXP Developer Tool's command-line service instead of replacing it (ppro_bridge/devloader.py; python -m ppro_bridge.devloader loads once). Loading by hand (UXP Developer Tool → Add Plugin → Load) still works.
Pairing token and audit log
On its first start the broker writes a random token to %USERPROFILE%.ppro-agent-bridge\token; the CLI and any script using ppro_bridge send it on every connection. (Not in %LOCALAPPDATA%: Windows gives packaged apps such as the Claude desktop app a private copy of it, so a CLI run from one would read a different token than a broker started by double-click.) A client without it — including a CLI older than 0.5 — is refused with AUTH_FAILED and nothing reaches Premiere. PPRO_BRIDGE_TOKEN / PPRO_BRIDGE_TOKEN_FILE override it for both sides. The browser Origin check stays.
Every request, refusal and panel (dis)connection is logged as one JSON line in %USERPROFILE%.ppro-agent-bridge\audit\audit-YYYY-MM-DD.jsonl: action, read/write, shortened params, guard, outcome, queue and run time. 30 days are kept; PPRO_AUDIT_DIR moves it, PPRO_AUDIT_DIR=off turns it off. The token is never logged.
Fixes from real jobs
Clip swaps (replace_clip, from a language-version swap): transitions are attributed by owner and side, so a neighbour's outgoing fade is no longer taken as the clip's own (and is put back exactly when the removal takes it); off-centre or handle-less shared transitions, and effects the new clip cannot get (such as Premiere 27's colour-tool container), are refused before anything is written (--skip-effect leaves one behind); an explicit --in/--out snaps to the nearest source frame. set_params gained a dry run.
Transitions: add_transition refuses an edit point that already has one (TRANSITION_EXISTS; Premiere would keep the old one) and verifies the result from OTIO.
Breathing room (extend_cut, from a re-cut): lists keyframed Level/Opacity on the clips it lengthens (heldKeyframes) and refuses an extension that a fade would hold silent or invisible (KEYFRAMED; --allow-silent to go ahead).
Listening report: the shadow mix refuses clips without a media file (NO_MEDIA) — Enhance Speech results and other generated items used to mix as silence; use --render there.
Frame export: all-black PNGs are flagged (black, with a warning), the reply reports the PNG size and how long the export took, and the file is polled every 50 ms instead of 500 ms.
Dry runs of remove_items, set_scale and set_volume honour --expect-seq.
What does this Premiere build's UXP API really do?
Groundwork for porting a much larger catalogue of editing tools to UXP: - probe_api (panel action and CLI) lists every class, method and instance member of the running build's UXP API and checks a watch list of the calls a port needs; --diff old.json shows what changed after a Premiere update. - tests/live/api_smoke.py runs the panel's api_smoke cases in a PAB_TEST* project, on scratch clips after the end of the sequence, undoing each case and listing anything it could not undo. - Result on Premiere 27.1.0 (build 21): almost every documented call tried works — removing markers, transitions, effects and keyframes, hold keyframes, adding Lumetri and audio effects (by display name), cloning, activating and deleting sequences, subclips, bins, relinking, custom properties, FCP XML and video export, saving. Two did not: changing a sequence's frame size through createSetSettingsAction had no effect, and AAF export waits on a modal log dialog (opt-in: --aaf). The only missing call on the watch list is a native razor.
Also in this release (0.4.0, never published separately)
Hear the cut
UXP can't play or meter audio, so the bridge listens offline. review_cuts rebuilds the dialogue track from the source files (or has Premiere render its own mix with --render, about a second per minute, plus integrated loudness and true peak) and measures every cut: too little breathing room before or after the words, a word cut off, room tone jumping, a click. The same report lints the timeline for slivers, near-miss V/A cuts, gaps and edges off the frame grid. lint_timeline and export_audio are available on their own.
Cut without a razor, keep the editor's work
Premiere 27.1 exposes no razor to UXP, and re-placing source ranges loses clip volume, scaling and effects. These commands build every piece from the clip itself: - split_clip --track V1 --at s — clone, trim, move; both halves keep every attribute. - cut_range --from a --to b — remove a range from every track and close the gap on all of them in one undo step, so tracks with gaps stay in sync. - extend_cut --at s --out 0.3 --in 0.25 — open a cut up with more of the clips' own source. - conform_captions --track V3 --srt f.srt — trims pieces of a pre-rendered caption movie that would flash the wrong line at a cut. - set_volume --track A1 --at s --db -6 — clip volume in dB as Premiere shows it; set_params and inspect_items work on audio tracks too. - snap_edges puts clip edges that drifted microseconds off the frame grid back on it; every position the bridge writes now lands on an exact frame.
Every step is read back and the whole timeline compared with the plan; dry runs plan the exact steps without writing.
Premiere Speech-to-Text
transcribe_clip --item "name" [--language en-US] [--wait 600] [--output f.json] runs Premiere's built-in transcription (26.5+) and saves the transcript. Local Whisper (transcribe.py) stays the default and writes valid Adobe language codes.
Effects from the CLI, with explicit keyframe time
set_params --track V2 --at s --json params.json writes effect params and keyframes; every keyframe list states its time base (media, clip or sequence), the whole request is validated before anything is written, and occurrence addresses repeated effects. add_transition --track V2 --at s --match-name "…" --duration 0.5 --edge start|end.
Transcripts that verify themselves
import_transcript checks the file, imports it, reads it back and compares word counts (TRANSCRIPT_NOT_IMPORTED for some 26.x builds' empty-import bug), and needs --replace to overwrite. export_transcript takes bin paths and refuses ambiguous names.
Safer protocol
ping reports protocol, per-build capabilities (--probe), a code hash (a warning when the loaded panel is stale) and a host denylist.
One action spec (ppro_bridge/actions.json, 27 panel actions) that the panel, the fake panel and the CLI are tested against: unknown or mistyped params are refused before Premiere is touched, every error has a code, outcomes are not_committed, committed, partial or unknown.
Requests can be pinned to a project/sequence (name, prefix or guid); the panel checks the pin on the very object it edits. --expect-seq on writes.
Commands that need the new panel refuse an old one (PANEL_OUTDATED).
From 0.3.3: source in/out points no longer lose a frame to float rounding, the broker sends one request at a time, the panel runs requests in order with a watchdog, apply_plan verifies the audio leg too.
Under the hood
The CLI is the ppro_bridge package (python -m ppro_bridge …, one function per command in ppro_bridge.ops); cli/ppro.py and the other scripts keep working. The panel is split into modules. One VERSION file; docs and skill copies are generated (scripts/sync_version.py). A fake panel answers every action, panel code is tested on Node, and live tests write only into projects named PAB_TEST*.
Changes visible to scripts
0.5: controllers must send the pairing token (ppro_bridge.transport does it for you); a 0.3/0.4 CLI cannot talk to a 0.5 broker.
0.4: unknown or mistyped params are refused (BAD_PARAMS); keyframes need a timeBase; export_transcript refuses empty placeholder transcripts and ambiguous names; import_transcript needs --replace to overwrite; CLI output no longer carries id/broker, error messages start with :, import_media lists missing files under data.missing; failed reads report not_committed; output is UTF-8; the transcript digest attaches punctuation tokens (sentence counts can change). cli/ppro.py keeps its 0.3.3 names.
Upgrading from 0.3.2
Stop the old broker. Replace the folder with this release and run pip install -r requirements.txt (websockets>=14).
Double-click setup_bridge.bat once, then start_bridge.bat (keep its window open). Or by hand: python broker/broker.py, then UXP Developer Tool → Load plugin/manifest.json.
python cli/ppro.py ping should say "compatible": true.
Windows only; Premiere Pro 26.3+, tested on 27.1.
Tests: python -m unittest discover -s tests — 441 tests on synthetic data (a broker and the fake panel on free ports; nothing touches Premiere). The release zip also passed a headless end-to-end run (every CLI command against the fake panel, wrong-token refusal, audit log, origin checks). Live on Premiere 27.1.0 (build 21): the api_smoke run above, and the start script loading the panel with no clicks.