# Qawlak in your editor (P9-01)

Every path below uses a **plugin key** (Qawlak → Plugins → Create plugin key). The key is free; it spends your
workspace's processing minutes, and every new account starts with ten free minutes. Free, Editor and Creator
workspaces have one plugin key; Studio gives each member their own. Below Studio an ordinary API key is refused by
the plugins' handshake (403).

A plugin key may only call these routes (`accounts.PLUGIN_ROUTES`); every other route answers 403:
`GET /api/plugin/ping`, `GET /api/health`, the resumable uploads (`/api/uploads…`), `POST /api/projects`,
`GET /api/projects[/{id}]`, `POST …/transcribe`, `POST …/render`, `POST …/process/alpha`, `POST …/process/align`,
`GET …/export/…`, `GET /api/jobs`, `POST /api/jobs/{id}/cancel`, `GET /api/templates`, `GET /api/presets`, and (K30)
`GET /api/plugin/jobs` and `GET /api/dialects`.
The request and answer shapes are in `premiere-panel/README.md` (Backend contract).

K30 additions (contract: `research/plans/K30-plugin-api.md`; all cost 0 minutes):
- Caption file options on `GET …/export/srt|vtt`: `max_words` (1–20), `max_lines` (1–5), `max_chars` (8–120, tashkeel not
  counted, breaks only at spaces), `delay_ms` (±600000); on srt/vtt/txt: `no_punct`, `no_tashkeel`,
  `digits=western|arabic-indic|perso-arabic|devanagari`. `lane=arabizi` on an Arabic project is written on the fly.
- `GET /api/plugin/jobs?limit=20`: the key holder's recent projects with status, language, dialect, duration and `exports`.
- `GET /api/plugin/ping` adds `min_duration`, an exact `max_duration` (Free cap included), `max_duration_render`,
  `max_upload_bytes`, `chunk_size`; refuse before upload when `ceil(seconds) > seconds_left`.
- `GET /api/dialects`: every dialect preset with the transcribe `language` to send and its script lanes.
- Audio-only files (wav, m4a, mp3) take the same resumable upload + transcribe path as video.

| Editor | What ships here | Version | Status |
|---|---|---|---|
| Premiere Pro 25.6+ | `premiere-panel/` UXP panel (`manifest.json`, `uxp.html`, `uxp.js`): pick clips on the active sequence → upload → transcribe → SRT placed at the clip's sequence time, optional ProRes 4444 alpha into the project. Load the UXP panel with `python scripts/premiere_ccx.py --install` (builds the .ccx and runs Adobe's UPIA installer; no UXP Developer Tool needed), then Window → UXP Plugins → Qawlak — قولك. | 0.3.0 | mocked-host test only; needs Premiere |
| Premiere Pro ≤ 25.x | same folder, CEP panel (`CSXS/manifest.xml`, `index.html`, `panel.js`, `host/qawlak.jsx`): export In/Out → SRT on a native caption track via `Sequence.createCaptionTrack`, and while it is open it places the UXP panel's captions too. Install it signed (no PlayerDebugMode) with `python scripts/premiere_zxp.py --install`. | 0.2.0 | needs Premiere |
| DaVinci Resolve (free) | `resolve-menu/Qawlak Import.lua` (newest export ZIP → timeline + subtitle track) and `resolve-menu/Qawlak Round-trip.lua` (timeline audio → Qawlak → SRT on a subtitle track), with `resolve-helper/` running outside Resolve (P15-46). Resolve 21.1 free lists only Lua menu scripts and runs no Python | 0.3.0 | live in free Resolve 21.1 (R29, 16 Sep): round trip on five bench clips, Import, refusals; pytest on Resolve's lua5.1.dll |
| Final Cut Pro 10.6.6+ | `GET /api/projects/{id}/export/fcpxml` (editable Basic Titles) or `?captions=true` (native SRT captions) | — | validates against the FCPXML 1.11 DTD |
| CapCut desktop/web | `capcut-import-guide.md` (SRT import, Arabic RTL caveats) | — | guide |

## Install the Resolve menu scripts and the Qawlak helper (free edition)

Why a helper: a free-Resolve **Workspace → Scripts** menu script cannot reach the network or read a file. It has no
`ffi`, `io`, `os.execute` or `require`, its `print` shows nowhere, and bmd's file calls stop it (measured live in 21.1,
15 Sep 2026); only the Console (F6) has `ffi`, and Workflow Integration panels need Studio. It can render and import.
So the menu script renders the timeline audio into a queue folder, and the helper, a small Python program outside
Resolve, uploads it with your plugin key, transcribes it and writes the captions back for the script to place.

1. Download the Resolve package (`resolve-helper/qawlak-resolve.zip`, linked on the Plugins page), unzip it, and double-click `resolve-helper\install.cmd` (Python 3.10+): it copies both Lua scripts, asks for the plugin key, server, language and Arabic dialect, and starts the helper hidden now and at every sign-in; `uninstall.cmd` removes it.
   The helper watches `%APPDATA%\Qawlak\resolve-queue`, logs to `%APPDATA%\Qawlak\resolve-helper.log` (never the key), and
   shows low-balance, credit-wall and refusal messages as Windows notifications in the key file's language.
2. Restart Resolve, open a project, then **Workspace → Scripts → Qawlak Round-trip** (captions the current timeline; with In/Out
   marked, only that range is rendered and charged; **Qawlak Round-trip (Gulf)**, **(English)** … pick the language for that run,
   **Qawlak Cancel** stops the running job and refunds it) or
   **Qawlak Import** (the newest Qawlak export ZIP in Downloads, which the helper unpacks into `resolve-queue\import\`).
   Progress shows as a marker at the timeline start. Free Resolve puts subtitle clips after the end of a timeline that
   already has content, so Qawlak Import builds its new timeline captions-first (they start at 00:00), and the round trip
   makes a new timeline `<cut> (Qawlak)` with the captions first and your cut nested at the start (live R29, 16 Sep). Status messages are Arabic; set
   `M.LANGUAGE = 'en'` near the menu path in `Qawlak Import.lua` for English.

From the Console (F6) the Lua scripts still work without the helper (they have `ffi` there).

Every export ZIP also carries `EDITOR-HANDOFF.md` (generated by `handoff.py`) with the plain
file-based Premiere/Resolve steps.

Checks: `node --test tests/js/premiere-panel.test.mjs tests/js/premiere-uxp.test.mjs`,
`pytest tests/test_plugin_scripts.py tests/test_resolve_lua.py tests/test_resolve_helper.py tests/test_fcpxml.py`.