Guide: Marker Exporter for Premiere Pro

User documentation ships in English and French only, while the panel itself is localized in six languages. A full translation pass is planned once the feature set settles. The French guide (HOW_TO_FR.md) is currently the more detailed of the two, notably on AI setup.

Complete user guide for the UXP version. It describes the current panel workflows, confirmations, folder permissions, AI correction and marker exchange.

1. Quick start

1. Open Premiere Pro.
2. Open the project and the sequence you want to export.
3. Open Marker Exporter for Premiere Pro.
4. Check the Premiere Project area: sequence name, marker count, frame rate and frame size.
5. Click Choose or change and select the output folder.
6. Enable the options you need.
7. Click Export HTML.
8. Read the confirmation, then validate.

The panel refreshes automatically when the active sequence changes. The Refresh button forces a full reread if needed.

Language follows Premiere Pro. If a translation or built-in help section is missing, Marker Exporter for Premiere Pro falls back to English (en). AI prompt files follow the selected marker language first, then the interface language, then _EN if no localized prompt exists. The manual UI language selector exists only in the hidden debug/test area.

2. Understanding the panel

Header

The header shows the extension name, its version and the Help icon. Help is displayed as an overlay so it does not resize the panel.

Premiere Project

This section shows:

• the active sequence;
• the marker count;
• the frame rate with three decimals;
• the frame size;
• the authorized output folder.

Main actions

• Refresh: rereads Premiere and the active sequence, and queries the online AI services (Gemini, OpenRouter) again, which automatic updates do not.
• AI correction: prepares marker-text corrections with an available provider.
• Export HTML: generates the interactive HTML report.

Configuration

Available options:

• Clip markers: includes internal clip markers.
• Color labels: displays only colors used in the active sequence.
• Include thumbnails: exports PNG images referenced by the HTML report.
• AI correction: enables model selection, marker-language hinting, optional write-back and external API-key management.
• Export log file: writes a log next to the HTML report.
• Controls and reports: hidden in the stable release; it can be re-enabled only in a support/debug configuration.

Interoperability

This section groups third-party exports and imports:

• Final Cut Pro;
• Avid;
• Resolve;
• marker import.

3. Exporting an HTML report

Quick text-only export

1. Choose a folder.
2. Disable Include thumbnails.
3. Click Export HTML.
4. Confirm.

Result: a standalone HTML file without an image folder.

Illustrated export with thumbnails

1. Choose a folder.
2. Enable Include thumbnails.
3. Click Export HTML.
4. Confirm.
5. Wait while Premiere exports the images.

Result: one HTML file and an adjacent thumbnail folder. Keep both together when sending or archiving the report.

Generating a PDF

1. Open the HTML file in a browser.
2. Adjust filters and the number of thumbnails per page.
3. Click Print / Save as PDF in the report.
4. Choose Save as PDF in your browser's print dialog.

The extension does not write the PDF itself: your browser does, using its own margins and paper size. The report ships a print stylesheet tuned for A4 landscape, so leave the orientation on landscape for the intended layout.

Timecode and drop-frame

The panel, the HTML report and every exported interchange file show the same timecode as Premiere.

On 29.97 and 59.94 sequences the extension reads the sequence's own time display setting instead of deducing it from the frame rate, so a 29.97 sequence set to non-drop reads as non-drop everywhere. Drop-frame timecodes use a semicolon before the frame number (00:01:00;02); non-drop use a colon (00:01:00:00).

4. Using color labels

1. Enable Color labels.
2. Fill only the labels you need.
3. Run the HTML export.

Only colors actually present in the active sequence are shown. When you switch sequence, the list is recalculated.

Examples:

• Green: Client approved;
• Red: Needs fix;
• Blue: Editing question;
• Yellow: To check.

5. Including clip markers

1. Enable Clip markers.
2. Click Refresh if the count has not updated yet.
3. Export HTML or run AI correction.

Clip markers complement sequence markers. In the HTML report, useless columns are hidden when only one marker type is present.

6. AI correction

Important concept

No AI model is bundled inside the extension. To use AI correction, you must provide one of these services:

• a local MLX server;
• a local Ollama server;
• an external provider key such as Gemini or OpenRouter.

The correction button appears only when a usable model is detected.

Preparing a local AI

MLX (recommended on Apple Silicon):

1. Install MLX-LM if needed:

   python3 -m pip install mlx-lm
   

2. Start the MLX server, which is OpenAI-endpoint compatible:

   python3 -m mlx_lm.server --model mlx-community/Qwen2.5-7B-Instruct-4bit --port 8080
   

3. Check that it answers on http://127.0.0.1:8080.

4. Reload the panel, or run detection again.

Ollama:

1. Install Ollama from https://ollama.com/download if needed.

2. Pull a compatible text model, for example:

   ollama pull qwen2.5
   

3. Start Ollama.

4. Check that a compatible model is installed:

   ollama list
   

5. If needed, test the model quickly:

   ollama run qwen2.5 "Answer OK only."
   

6. Check the http://localhost:11434 endpoint.

Preparing an external AI

Create the key first, if you do not have one. Both providers issue keys from a free account page:

• Gemini: https://aistudio.google.com/apikey
• OpenRouter: https://openrouter.ai/keys

Then, in the panel:

1. Open AI correction.
2. Enable Add an external API key?.
3. Choose the external provider from the list.
4. Paste its API key.
5. Click Save.
6. Wait for model detection to run again.

Save stores the key in UXP secureStorage. It does not modify resources/ai/ai_config.json.

The api_key field of resources/ai/ai_config.json is a manual fallback. Detection and AI correction read it only if you enable Show manual JSON fallbacks in the panel. That choice is remembered. Even when it is off, the AI JSON still defines the available providers, models, endpoints, priorities, prompts and generation settings; only the reading of api_key values is blocked.

One active key is kept per provider. Pasting a new key for the selected provider replaces that provider's previous secure entry. The panel does not create duplicates and does not rotate automatically between several keys.

secureStorage is the UXP encrypted vault belonging to this extension. Keys persist across panel openings, Premiere sessions and machine restarts, as long as the user profile and the extension are not reset. You can write and delete keys from the panel, but the interface never displays them again. Direct access is possible only from UXP code in the same plugin, through require("uxp").storage.secureStorage.

After saving, the extension checks the key by detecting models again (for OpenRouter, whose model list is public, with a call that requires the key). If the provider rejects it — 401/403, or for Gemini a 400 API_KEY_INVALID —, it is invalid, expired or revoked: paste a new key or delete the local entry, then check the Google AI Studio or OpenRouter dashboard. The check can be cancelled; the key stays saved.

If secureStorage is unavailable, or if you deliberately want a local plaintext fallback, tick Show manual JSON fallbacks: the panel then shows the path and the fields to edit. That action does not write the key into the JSON for you.

External providers without an active key are not shown in the list.

To replace a key cleanly:

1. create a new key at the provider;
2. paste it into the panel;
3. click Save;
4. check that models appear again;
5. revoke the old key in Google AI Studio or OpenRouter.

The Delete button removes only the local secureStorage copy. It does not revoke the provider-side key.

The model list is filtered automatically for text correction: image, audio, embedding/rerank, moderation and known legacy models are hidden. The remaining models are grouped by provider (MLX local, Ollama local, Gemini, OpenRouter), and the first recommended model is selected automatically if your previous choice is no longer available.

Marker language

Specify marker language for the AI prompt tells the model which source language to correct. It does not translate marker text.

Running a correction

1. Enable AI correction.
2. Choose an available model.
3. Choose the language to state in the AI prompt.
4. Click AI correction.
5. Read the confirmation.
6. Confirm.

The correction prepares texts for the HTML report. It does not write into the timeline.

What interrupts a running correction

Correcting a hundred markers takes several minutes. Throughout, the extension works on a snapshot of the markers taken when the run started. If the sequence changes underneath it, the result would no longer match anything, so the correction is cancelled.

These cancel a running correction:

• closing the project;
• loading another sequence;
• closing the current sequence;
• opening another project;
• changing the project's content.

These do not:

• switching from one Premiere window to another;
• giving focus to the panel or to the timeline.

You can go back and look at your timeline while a correction runs without losing it.

When a correction is cancelled, no marker is modified and the activity log states the reason.

Exporting with corrections

After a successful correction:

1. Leave the AI option enabled.
2. Click HTML export.
3. Confirm.

The report contains the corrected texts and keeps the original information needed for review.

Applying corrections to markers

Apply corrections to markers is ticked when the panel opens for the first time. Unticked, a correction still runs and its corrected text appears in the HTML report; the sequence markers keep their own text.

1. Keep Apply corrections to markers ticked before starting the correction, or before loading a corrections JSON.

2. Start the AI correction, or load the corrections.

3. When valid corrections arrive, a confirmation dialog appears. It states how many markers will change and the split between titles and comments.

4. One page per marker, in timeline order. The ‹ and › arrows browse the changed markers; the counter shows the current page and the page count. A marker whose title and comment were corrected shows both on the same page: it is the whole marker you accept or refuse.

   Each field reads on four levels: the marker and its timecode, the field concerned (title or comment), then Before and After, each above its own text. The original text is set back and quieter, the correction stands out.

   The fragments that changed are in bold, on both sides: red on the original text, green on the correction. The words themselves are marked, not the stretch of sentence between them — a correction made in five places gives five marks. The weight carries the information; the colour only says which side of the comparison you are looking at.

   What a correction removed is written under the heading: Re-read: 1 word removed · 2 line breaks removed. A one-word heading deleted, two lines run together, the end of a long comment cut; the confirmation message says how many markers are concerned. A word joined to its neighbour, an added hyphen, a moved word or one blank line fewer do not count. A word accidentally repeated and removed does: the line asks you to check, it does not judge the correction.

   The removed words appear in your own text, in the amber of that line, where they were. A word removed too far from the 2000-character cut is counted without being shown.

   Texts are shown in full. Past 2000 characters the review cuts, around the place that changed and never at the start of the text; the value is review.max_text_length in ai_config.json.

5. Every page carries its two decisions.

   Go to this marker moves Premiere's playhead onto it, without closing the dialog or changing your decision. It does not appear if your Premiere version does not expose that command — the extension works without it.

   Reject this correction leaves that marker exactly as it is — both its title and its comment, since a marker is refused as a whole — and becomes Restore this correction if you change your mind. Nothing is rejected unless you say so: by default every correction is applied. A field the model filled from its neighbour is not offered to you. Sometimes a model does not correct a field but copies the marker's other field into it — a meaningless title replaced by the comment's content. The extension puts that field back as you wrote it, before the review, and the activity log says how many were put back; <report>_ai_correction_log.txt carries a Fields put back line. Those markers are worth a look: the model had nothing to say about them.

6. Answer Continue to write into the sequence markers, or Cancel to drop the plan without changing anything. No HTML export is required.

   The activity log then says what was written and, when you rejected something, how many corrections were left untouched.

   A rejection does not disappear with the dialog. The HTML report shows the marker's row with the text it kept and the refused correction, marked Rejected; <report>_ai_correction_log.txt gives the count. Nothing is erased — that is what lets you re-read afterwards what the model had proposed.

7. Check the timeline. If needed, use Edit > Undo immediately.

Use this workflow on a testable copy of the project until you have validated the result on your own sequence.

The extension may write an empty comment when AI correction determines that a comment should be cleared. Empty marker names are ignored to avoid deleting a title accidentally.

7. Importing markers

1. Open the target sequence.
2. Click Import markers.
3. Choose an Avid, Resolve or FCPXML file.
4. Read the confirmation:
   • detected format;
   • marker count;
   • planned creations;
   • skipped entries;
   • readable titles, comments and colors.
5. Confirm to write into Premiere.

Supported imports:

• Resolve marker EDL;
• Avid marker TXT/XML;
• Final Cut Pro XML when marker data is available.

Imports are analyzed first, then checked against the active sequence. If every candidate marker already exists at the same timecode, nothing is written and the activity log explains why.

After importing, check the timeline. An import is written in two steps — the markers, then their colours, since Premiere's creation action carries no colour — so undoing it takes Edit > Undo twice.

8. Exporting to Final Cut Pro, Avid or Resolve

1. Choose an output folder.
2. Check the active sequence.
3. Click the target format.
4. Wait for the write to finish.

Supported exports:

• Final Cut Pro XML;
• Avid TXT/XML;
• DaVinci Resolve EDL.

The panel shows a short summary. Details of the files written are available in the log if you enabled it.

What each format keeps of your markers

None of these formats carries everything a Premiere marker holds. The panel writes what it can, and says so in the log after every export.

• Colours do not travel to Final Cut Pro. An FCPXML marker holds a name, a note and a time, no colour: the colour is written in an attribute of the panel's own, which Final Cut ignores — it shows every marker in its standard colour. The panel reads it back when the file returns. Avid and Resolve do carry the colour.
• Text is flattened as the format requires. Final Cut accepts no line break in a title; Avid accepts none in a title or a comment; an EDL replaces | with ¦, because it separates its columns. After each export the log names what was changed and what was not.
• An empty title stays empty. None of these files receives a manufactured title: a marker with no title comes back with no title.

9. Logs and reports

The activity log stays visible and shows important success, warning and error messages. Detailed diagnostic data belongs in export logs or support reports.

Activity log

The visible log must stay short. It shows:

• operations started and finished;
• important successes;
• warnings;
• errors.

Export log file

Enable Export log file when you want to keep a log next to the HTML report. Choose, under Log file level:

• Warnings and errors for a light log;
• Detailed log to investigate a regression.

That choice also governs the activity log during an AI correction. With Warnings and errors, the panel tells the story of the run: batch sent, answer received, quota waits, result. With Detailed log, every attempt joins it with its failure code, endpoint and duration — what a support report needs, more than everyday use wants.

The log does not include marker text unless an explicit report format needs it.

Support report

In the stable release the activity log stays visible, but the Checks and reports block is hidden by default. Use, in this order:

1. the error message shown in the panel;
2. the activity log;
3. the export log file if the error concerns an export.

In a support configuration where advanced checks are explicitly re-enabled:

1. open Checks and reports;
2. run the necessary checks;
3. click Save report;
4. attach the report to your feedback.

The report is designed not to expose marker text, native paths, private identifiers or API keys.

The controls in that block, once opened:

• Copy to clipboard copies the activity log as shown, and Clear empties it — neither touches the log files;
• Log level sets what the visible log shows, up to Detailed log, which also shows the debug channel. Not to be confused with Log file level, which sets the file written next to the report and, with it, the AI debug lines of the activity log;
• Include logs in report adds the log to the saved report;
• Check business state runs the read-only checks again;
• Test language changes the interface language without touching Premiere.

Advanced transactional validation

The Transactional validation tool is for support diagnostics only. It is hidden in the stable channel and must not be used as a normal way to modify markers.

Real user writes go through:

• direct marker import with confirmation;
• applying AI corrections to markers with confirmation.

When importing FCPXML, Avid or Resolve files, an imported marker whose start frame already matches a marker in the sequence is skipped. Import never updates the title, comment or color of an existing marker; this rule avoids duplicates and unexpected rewrites.

FCPXML import: a marker carrying the completed="1" attribute, or a <chapter-marker> tag, is always recolored green on import — whatever its original color in Final Cut Pro. This is a deliberate choice (neither notion has a direct Premiere equivalent), worth keeping in mind if you import an FCPX project whose "completed" markers or chapters use another color.

After a confirmed write, check the timeline immediately and use Edit > Undo in Premiere if you need to restore the previous state.

10. Troubleshooting

The panel shows no sequence

1. Open a Premiere project.
2. Open a sequence in the timeline.
3. Click Refresh.
4. If the issue persists, check the activity log.

The output folder is not accepted

UXP requires explicit folder authorization. Click Choose or change again and select the folder from the system picker.

AI models are not listed

Check that MLX/Ollama is running, or that a valid external key is saved. Then refresh the panel. If the provider still does not appear, open Help and review the AI setup section.

A provider can also be unreachable for a reason outside the extension: a network blocker or a corporate firewall. The log tells this case (ai_network_unreachable) apart from a missing key (ai_provider_missing_secret) or a rejected one.

HTML export fails

Check the selected folder permissions, available disk space and whether a file with the same name is locked by another application. Enable the export log and try again.

11. Editing the AI configuration

Main file:

resources/ai/ai_config.json

Prompts:

resources/ai/prompt_system_short_EN.txt
resources/ai/prompt_user_template_EN.txt
resources/ai/prompt_system_short_FR.txt
resources/ai/prompt_user_template_FR.txt
resources/ai/prompt_system_short_DE.txt
resources/ai/prompt_user_template_DE.txt
resources/ai/prompt_system_short_IT.txt
resources/ai/prompt_user_template_IT.txt
resources/ai/prompt_system_short_ES.txt
resources/ai/prompt_user_template_ES.txt
resources/ai/prompt_system_short_PT.txt
resources/ai/prompt_user_template_PT.txt

The distributed prompts are available as _EN, _FR, _DE, _IT, _ES and _PT variants. The extension selects the variant from the marker language chosen for the AI prompt, then the interface language, and finally _EN when no localized prompt exists.

Recommendations:

• keep a copy of the file before editing it;
• do not change the answer format the model is asked for: one numbered line per marker, N: title {SEP} comment, with {NL} for line breaks;
• avoid prompts that are too long for small local models;
• never commit an API key into a shared version.

External API keys in UXP

For a UXP release, use the panel:

1. open AI correction;
2. enable Add an external API key?;
3. choose the provider;
4. paste the key;
5. click Save.

The key is stored in secureStorage for this plugin and this user profile. It persists across panel reloads, Premiere sessions and restarts, unless the profile or the extension's storage is reset.

resources/ai/ai_config.json always remains the configuration source for providers, models, endpoints, priorities, prompts, timeouts and batch sizes. Its api_key field, however, is ignored unless Show manual JSON fallbacks is enabled.

On some UXP/macOS hosts the input field may show the key while you type, or while it holds focus, then mask it again on exit. The panel never redisplays a key that is already saved. Always make sure nobody is watching or recording the screen while you type.

The manifest deliberately keeps network.domains: "all" so that UXP does not block local MLX/Ollama, Gemini or OpenRouter before the application logic runs. The runtime then restricts providers to the shipped families: MLX/Ollama on loopback (localhost, 127.0.0.1) or a private-network address (10.x, 172.16–31.x, 192.168.x), on any port; Gemini and OpenRouter on their own domain only. A refused value — a public domain name, or a name such as studio.local — is replaced by the provider's default endpoint: use the machine's IP address.

Batch size and the token budget

Two settings in ai_config.json decide how many markers go into one AI request.

batch_size, per provider, is a plain marker count. It is the default mechanism and needs no tuning for ordinary use.

max_tokens_per_batch is off by default (0). With Ollama, the num_ctx window then serves as the budget (nine tenths of it): past it, Ollama would cut the start of the prompt, instructions included. Set the key when your local model's context window is the real constraint and you want to fix the budget yourself; a value you set always wins. It is a budget for the whole exchange, and three costs come out of it:

Base the value on the context window of the model you loaded, not the provider: a 4-bit quantised 7B and a 14B do not have the same. Leave a margin. For an 8,192-token window, 7000 is a reasonable starting point.

If you set it below the fixed overhead, no request can fit. The panel says so in the diagnostic log (token_budget_unusable) and falls back to plain count batching, rather than emitting one-marker batches that would look like the budget was being honoured.

chars_per_token converts characters into tokens. The shipped ai_config.json sets 3.5, the ratio measured on French text with MLX and Qwen2.5, which is also the value applied when the key is absent; a morphologically rich language consumes more.

You no longer have to guess. Every provider counts the tokens of its own replies, and since 1.3.5 the AI log prints the configured value beside the measured one, along with the generation rate that explains how long the run took:

Tokens sent                  : 48210
Tokens generated             : 31940
Characters per token         : 3.5 (configured) / 3.5 (measured)
Adaptive ratio               : no — batches split on 3.5
Generation rate              : 69.4 tokens/s

When the measured value changes during a session, the activity log says so at the time, with both numbers — and, depending on the setting, either that the next run will be split on it or that nothing changes and how to allow it. It does not repeat itself when a run measures the same ratio again, which at temperature 0 is the common case.

adaptive_chars_per_token (default false) decides whether that measurement may act on how the next run is split. It stays closed by default: at temperature 0 two runs of one sequence come back identical, and a ratio that re-splits behind your back would remove the only way to compare a before and an after. Open it once the measured value drifts consistently from the configured one on your own sequences.

What happens when the model answers badly

Small local models do not always follow the format. The panel absorbs most of it: reasoning tags, a preamble, Markdown decoration, an omitted separator or markers merged onto one line are all recovered without a retry.

Two things it deliberately refuses rather than guesses: a title appearing on a marker you left untitled, and a field that comes back empty or wildly longer than its source. Those are rejected and the batch is split and re-sent, because writing a wrong correction into your timeline is worse than a slower run.

At temperature 0 — the default — a format failure is never retried on the same batch. The reply would be byte-identical, so the panel goes straight to splitting instead of burning calls.

12. Local release verification

From the project root com.markersexport.panel.uxp/:

npm run check:release
npm test

Then load prototype/manifest.json in UXP Developer Tool.

UXP Developer Tool packages prototype/ as it is — there is no staging folder and no build step. Everything in that folder goes into the .ccx, which is why npm test comes last, immediately before packaging: it is the only check that refuses system files, build artefacts and API keys inside prototype/, and anything created in that folder after it runs goes out undetected. The harness, the reports and the npm metadata live outside that folder for the same reason.

In Premiere:

1. load the panel;
2. open a sequence with several marker colors;
3. check that it refreshes when the sequence changes;
4. export HTML without thumbnails;
5. export HTML with thumbnails;
6. test an Avid, Resolve or FCPXML import on a copy of the project;
7. test an AI correction with the available provider;
8. save a support report only if something needs analysing;
9. leave the advanced controls hidden for a public release validation.

13. Good practices

• Keep the HTML file and thumbnail folder together.
• Test marker imports and AI write-back on a project copy first.
• Use Premiere Edit > Undo right after a write-back — twice after an import — if the result is not what you expected.
• Enable detailed logs only while investigating an issue.
• Never share a bundle or ai_config.json containing a real API key.
• Close other heavy Premiere operations during thumbnail export.