# Closed Caption Creator IFrame Embed — LLM Integration Reference

> Self-contained reference for AI coding assistants integrating the Closed Caption Creator caption/subtitle editor into a web application via `<iframe>` + PenPal. Every remote method that exists is listed in the API Reference section. Do not call or invent methods that are not listed here.

Human docs: https://www.closedcaptioncreator.com/docs/integrations/iframe-embed
Index for agents: https://www.closedcaptioncreator.com/docs/llms.txt

## Rules for code generation

1. The parent page talks to the editor with **PenPal v7** (`penpal` on npm). Do not use raw `window.postMessage`.
2. Create the PenPal connection **inside the iframe's `load` event**, then `await connection.promise` to get `remote`.
3. **Every** `remote.*` call is async and returns a Promise. Always `await` it.
4. Call order on startup: theme (optional) → project settings (`setProjectName`, `setProjectFrameRate`, `setProjectDropFrame`, …) → `importMedia` → `importSubtitle`.
5. Many methods return `{ success: boolean, message: string, ... }`. Check `success` instead of relying on exceptions. Others return raw data (`string`, `array`, `object`) or `void` — see each method's **Returns**.
6. Use the exact iframe origin in `allowedOrigins` in production. `'*'` is for local development only.
7. The `<iframe>` must have `allow="clipboard-write; clipboard-read; encrypted-media"` (plus `autoplay` recommended).
8. Event Group = one caption/subtitle track (e.g. "English CC", "French Subtitles"). Methods take either an Event Group **ID** (`eventGroupId: string`) or an Event Group **index** (`evgIndex: number`) — read the signature carefully; they are not interchangeable.
9. Subtitle formats are identified by **profile** strings (`"subRip"`, `"webVtt"`, …). See "Subtitle format profiles" below.

## Install

CDN (exposes a global `Penpal`):

```html
<script src="https://unpkg.com/penpal@^7/dist/penpal.min.js"></script>
```

npm (ES modules):

```bash
npm install penpal@^7
```

```js
import { WindowMessenger, connect } from 'penpal';
```

## Embed the iframe

```html
<iframe
  id="editor"
  src="https://iframe-demo.closedcaptioncreator.com/"
  style="width: 100%; height: 90vh; border: 0;"
  allow="accelerometer; autoplay; clipboard-write; clipboard-read; encrypted-media"
  allowfullscreen>
</iframe>
```

`https://iframe-demo.closedcaptioncreator.com` is the public demo origin. Customers with a dedicated build get their own origin — substitute it in `src` and `allowedOrigins`. Dedicated builds may also restrict which parent origins can embed them (CSP `frame-ancestors`); contact Closed Caption Creator to add your domain.

## Connect (canonical pattern)

```js
import { WindowMessenger, connect } from 'penpal';

const EDITOR_ORIGIN = 'https://iframe-demo.closedcaptioncreator.com';
const iframe = document.getElementById('editor');

iframe.addEventListener('load', async () => {
  const messenger = new WindowMessenger({
    remoteWindow: iframe.contentWindow,
    allowedOrigins: [EDITOR_ORIGIN],
  });

  const connection = connect({
    messenger,
    // Methods the PARENT exposes to the editor (optional, see "Parent-side methods").
    methods: {},
  });

  const remote = await connection.promise;

  console.log('Editor version:', await remote.getVersion());

  await remote.setProjectName('My Project');
  await remote.setProjectFrameRate(29.97);
  await remote.setProjectDropFrame(true);

  const media = await remote.importMedia('https://example.com/video.mp4');
  if (!media.success) throw new Error(media.message);

  const sub = await remote.importSubtitle('https://example.com/captions.srt', 'subRip');
  if (!sub.success) throw new Error(sub.message);
});
```

With the CDN build, use `Penpal.WindowMessenger` and `Penpal.connect`. Call `connection.destroy()` when unmounting (e.g. in a React `useEffect` cleanup).

## Parent-side methods

The editor can call back into the parent. Expose these on the `methods` object passed to `connect()`. All are optional; only implement the ones you enable.

| Parent method | Called when | Expected return |
|---|---|---|
| `exportSubtitle()` | User clicks the toolbar **Save** button (enable with `remote.setParentToolbarActions({ exportSubtitle: true })`) | anything; the parent decides what Save does |
| `cancel()` | User clicks the toolbar **Close** button (enable with `remote.setParentToolbarActions({ cancel: true })`) | anything |
| `getVoices()` | Audio Description mode (`remote.setAdLicense(true)`) needs the voice list | `{ success: boolean, message?: string, voices?: { id: string, name: string, language: string \| null, gender?: string }[], defaultVoice?: string }` |
| `renderAudio(request)` | Audio Description mode renders a cue to speech. `request = { text: string (≤ 5000 chars), voice?: string, speed?: number (0.25–4.0), format?: "mp3" \| "wav", eventId?: string }` | `{ success: boolean, message?: string, url?: string, format?: string, contentType?: string, cached?: boolean, eventId?: string \| null }` — `url` must be playable by the browser |

**Naming clash:** the parent-side `exportSubtitle()` (no arguments, toolbar Save callback) is unrelated to the editor-side `remote.exportSubtitle(profile, encodeOptions, saveAsFile, ...)` which encodes captions. A typical Save handler calls the latter from inside the former:

```js
let remote;
const connection = connect({
  messenger,
  methods: {
    async exportSubtitle() {
      const res = await remote.exportSubtitle('webVtt', {}, false);
      if (!res.success) return remote.alertUser({ title: 'Export failed', text: res.message });
      await fetch('/api/captions', { method: 'PUT', headers: { 'Content-Type': 'text/vtt' }, body: res.data });
      await remote.alertUser({ title: 'Saved', text: 'Captions saved.' });
    },
    cancel() {
      window.location.href = '/library';
    },
  },
});
remote = await connection.promise;
await remote.setParentToolbarActions({ exportSubtitle: true, cancel: true });
```

## Core workflows

### Export edited captions as a string and upload

```js
const res = await remote.exportSubtitle('subRip', {}, false); // saveAsFile=false → returns data
if (res.success) {
  await fetch('/api/captions', { method: 'POST', body: res.data });
}
```

`saveAsFile: true` triggers a browser download instead of returning `data`. Optional later arguments: `forcedOption` (`"include"` | `"exclude"` | `"only"`), `eventGroupId` (defaults to the selected group), `exportTracks` (e.g. `["B"]`).

### Import into an existing Event Group / track

`importSubtitle` creates a new Event Group by default. Pass the 7th argument `target` to merge or replace instead:

```js
const { id: groupId } = await remote.getSelectedEventGroupId();
await remote.importSubtitle(secondLanguageUrl, 'subRip', null, {}, {}, false, {
  eventGroupId: groupId,
  importOption: 'merge', // or 'replace' (default)
  track: 'B',            // 'A' | 'B' | 'C' | 'D'
});
```

Set Event Group metadata on a new group via the 4th argument, e.g. `{ name: 'French Subtitles', type: 'subtitle', language: 'fr-FR' }`.

### Quality-control gate before publishing

```js
const guide = await remote.loadStyleGuide({
  id: 'my-platform-guide', // stable ID → re-loading updates it in place
  name: 'My Platform Guide',
  enabled: true,
  maxLines: 2,
  maxChars: 42,
  maxCps: 17,
  minDuration: 1,
  maxDuration: 7,
  minEventGap: 0.083,
  overlap: true,
  illegalChars: true,
  leadingTrailingSpace: true,
});

const { id: groupId } = await remote.getSelectedEventGroupId();
const qc = await remote.qcEventGroup(groupId, guide.id);
if (qc.errorCount > 0) {
  await remote.alertUser({ title: 'Fix QC errors', text: `${qc.errorCount} issues found.` });
  return; // block publish
}
```

Style guide fields (all optional): `id, name, enabled, totalMaxChars, minLines, maxLines, maxChars, maxDuration, minDuration, minCps, maxCps, minWpm, maxWpm, minWordsPerLine, maxWordsPerLine, minEventGap, maxEventGap, minEventGapTolerance, maxEventGapTolerance` (numbers; durations/gaps in seconds) and boolean checks `overlap, illegalChars, hyphenSpace, hasUnderscore, periods, missingSpeaker, useEllipses, spellNumbers, spellNumbersAtStart, netflixGlyphs, partialItalics, fullItalics, partialBold, fullBold, partialUnderline, fullUnderline, repeatWords, fitSubtitles, leadingTrailingSpace, whitespace, blankLines, positionTopLeft, positionTopCenter, positionTopRight, positionCenterLeft, positionCenter, positionCenterRight, positionBottomLeft, positionBottomCenter, positionBottomRight, positionYOffset, positionXOffset, approvalPassed, approvalFailed, approvalNotSet, notes, tags, forced`.

### Save / restore full project state

```js
const ccprj = await remote.getProjectData();      // full project JSON
await saveToBackend(ccprj);
// later
await remote.loadProjectData(ccprj);               // resets undo stack, sets clean baseline
```

### Warn about unsaved changes

```js
// beforeunload handlers cannot await, so poll and cache the dirty flag.
let dirty = false;
setInterval(async () => { dirty = await remote.hasUnsavedChanges(); }, 2000);
window.addEventListener('beforeunload', (e) => {
  if (dirty) e.preventDefault();
});
```

### Progress modal while the parent prepares content

```js
await remote.toggleStatusModal(true);
await remote.updateModalTitle('Preparing media');
await remote.updateModalStatus({ progress: 30, msg: 'Fetching captions…' });
// ... do work ...
await remote.completeImport();          // or: await remote.failImport('Could not fetch media');
```

### Theming (call right after connecting, before importMedia)

```js
await remote.setTheme({
  primary: '#408fe0',
  bodyBg: '#181c24',
  bodyColor: 'rgba(255, 255, 255, 0.9)',
  borderColor: 'rgba(255, 255, 255, 0.1)',
  fontFamily: 'Inter, system-ui, sans-serif',
});
```

Tokens: `primary, primaryRgb, bodyBg, bodyBgRgb, bodyColor, bodyColorRgb, secondaryColor, borderColor, fontFamily, linkColor, linkHoverColor, light, danger, warning, success, info`, or raw `--bs-*` CSS variable names. Theming affects UI chrome only — not the timeline canvas, caption preview font (`setPreviewFontFamily`), or QC rules (`loadStyleGuide`). Use `loadCustomStyles(cssText)` for advanced CSS and `clearTheme()` to reset.

### Watermark the player (overlay only; never burned into exports)

```js
await remote.setWatermark({
  enabled: true,
  showDateTime: true,
  dateTime: '2026-09-14 07:22:43', // host supplies the value; static until called again
  email: 'user@example.com',
  ipAddress: null,
  customText: 'CONFIDENTIAL',
  alignment: 'bottom',
  textOpacity: 100,
  shadowOpacity: 100,
});
```

### Customize the secondary toolbar

```js
await remote.configureSecondaryToolbar({
  left: ['undo', 'redo', 'shortcuts'],
  center: ['addEvent', 'removeEvent', 'split', 'merge'],
  right: ['alignLeft', 'alignCenter', 'alignRight', 'copy', 'cut', 'paste'],
});
// remote.configureSecondaryToolbar(null) restores the default layout
```

## API Reference (editor-side `remote` methods)

These are all 77 methods on the `remote` object returned by `await connection.promise`. Call them as `await remote.methodName(...)`. No other methods exist.

- Modal Control: `getVersion`, `updateModalStatus`, `toggleStatusModal`, `updateModalTitle`, `completeImport`, `failImport`, `alertUser`
- Project Settings: `setProjectId`, `setProjectName`, `setProjectDescription`, `setProjectFrameRate`, `setProjectDropFrame`, `setProjectIncode`, `setProjectState`, `setAdLicense`, `setParentToolbarActions`, `configureSecondaryToolbar`
- Display Settings: `setDisplaySettings`, `enableSubtitleMode`, `enableCaptionMode`, `setPreviewFontSize`, `setPreviewFontFamily`, `setWatermark`
- App Theme / Branding: `setTheme`, `loadCustomStyles`, `clearTheme`
- Keyboard Shortcuts: `getKeyboardShortcuts`, `setKeyboardShortcuts`
- Media & Timeline: `setMediaPeaksPath`, `setMediaPeaksData`, `useFallbackTimeline`, `useDefaultTimeline`, `toggleTimeline`, `setPoster`, `importMedia`
- Quick Tools: `setQuickToolsSettings`, `selectQuickToolsPanel`
- Transcript Sync: `setTranscript`, `checkSync`, `resyncEventGroup`, `loadTranscript`
- Subtitle Import & Export: `importSubtitle`, `exportSubtitle`
- Markers: `getMarkers`, `setMarkers`, `createMarkerList`, `insertMarker`
- Style Guide & QC: `loadStyleGuide`, `getStyleGuides`, `qcEventGroup`
- Event Groups: `getSelectedEventGroupId`, `getEventGroupInfo`, `addEventGroup`, `removeEventGroup`, `mergeEventGroups`
- Speakers: `addSpeaker`, `getSpeakers`
- Project Data: `loadProjectData`, `getHistory`, `hasUnsavedChanges`, `getProjectData`
- Event Selection & Navigation: `getSelectedEvents`, `selectEventById`, `selectEventByIndex`, `scrollToEventById`, `scrollToEventByIndex`
- Lock State: `enableVideoLock`, `disableVideoLock`, `enableCaptionLock`, `disableCaptionLock`, `enablePreviewLock`, `disablePreviewLock`
- Auto Formatting & Correction: `autoFormat`, `autoCorrectReadingSpeed`, `fixEventOverlap`, `setProjectFrameGap`, `insertBlankFrames`

### Modal Control

#### `getVersion()`

- **Arguments:** none
- **Returns:** `Promise<string>`

Returns the current application version.

#### `updateModalStatus(statusInfo)`

- **Arguments:**
  - statusInfo: { progress: number, msg: string }
- **Returns:** `Promise<boolean>`

Updates the progress bar and status message in the IFrame remote modal.

#### `toggleStatusModal(show)`

- **Arguments:**
  - show: boolean
- **Returns:** `Promise<void>`

Controls the IFrame remote status modal. If `show` is true, displays the modal. If falsy: hides the modal when it is already open, otherwise shows it.

#### `updateModalTitle(title)`

- **Arguments:**
  - title: string
- **Returns:** `Promise<boolean>`

Updates the title text displayed in the IFrame remote modal header.

#### `completeImport()`

- **Arguments:** none
- **Returns:** `Promise<void>`

Displays a success alert and closes the modal after a successful import operation.

#### `failImport(msg)`

- **Arguments:**
  - msg: string
- **Returns:** `Promise<void>`

Displays an error alert with the provided message and closes the modal after a failed import.

#### `alertUser(alertObj)`

- **Arguments:**
  - alertObj: { title?: string, text?: string }
- **Returns:** `Promise<void>`

Displays a SweetAlert2 modal with a custom title and message to alert the user.

### Project Settings

#### `setProjectId(id)`

- **Arguments:**
  - id: string
- **Returns:** `Promise<void>`

Sets the unique identifier for the current project.

#### `setProjectName(name)`

- **Arguments:**
  - name: string
- **Returns:** `Promise<void>`

Sets the display name of the current project.

#### `setProjectDescription(description)`

- **Arguments:**
  - description: string
- **Returns:** `Promise<void>`

Sets the description for the current project.

#### `setProjectFrameRate(frameRate)`

- **Arguments:**
  - frameRate: number (e.g., 23.976, 25, 29.97, 30)
- **Returns:** `Promise<void>`

Sets the project's video frame rate.

#### `setProjectDropFrame(dropFrame)`

- **Arguments:**
  - dropFrame: boolean
- **Returns:** `Promise<void>`

Sets whether the project uses drop-frame timecode.

#### `setProjectIncode(incode)`

- **Arguments:**
  - incode: string (timecode string, e.g., "00:00:00:00")
- **Returns:** `Promise<void>`

Sets the project's incode (start timecode).

#### `setProjectState(state)`

- **Arguments:**
  - state: object (Partial project state object)
- **Returns:** `Promise<void>`

Updates multiple project state properties at once.

#### `setAdLicense(enabled)`

- **Arguments:**
  - enabled: boolean
- **Returns:** `Promise<boolean> (resulting adLicense value)`

Enables or disables Audio Description license mode. When true, voice listing and text-to-speech rendering are routed through the parent host instead of the Firebase cloud TTS path. The parent must expose `getVoices()` and `renderAudio(request)` on its Penpal methods for AD features to work.

#### `setParentToolbarActions(actions)`

- **Arguments:**
  - actions: { exportSubtitle?: boolean, cancel?: boolean } (Optional; omitted keys are left unchanged)
- **Returns:** `Promise<{ exportSubtitle: boolean, cancel: boolean }> (resulting visibility flags)`

Shows or hides the iframe toolbar Close and Save buttons. Defaults come from envStore (`parentCancel` / `parentExportSubtitle`, both false). When Save is shown, clicks call the parent's `exportSubtitle()`; when Close is shown, clicks call the parent's `cancel()`. This is separate from the child `exportSubtitle` encode/retrieve API.

#### `configureSecondaryToolbar(settings)`

- **Arguments:**
  - settings: { left?: string[], center?: string[], right?: string[] } or `null` / omitted to restore defaults.
  - Customizable IDs: exportFile, importFile, undo, redo, shortcuts, addEvent, removeEvent, alignLeft, alignCenter, alignRight, writingMode, position, positionLineUp, positionLineDown, copy, cut, paste, shiftWordBack, shiftWordForward, shiftLineBack, shiftLineForward, split, merge, expand, compress, autoFormat, snapToStart, snapToEnd.
  - Exempt (ignored): open, save, mediaImport, transcription, translation, settings.
- **Returns:** `Promise<{ success: boolean, message?: string, layout?: { left: string[], center: string[], right: string[] }, ignored?: { id: string, reason: string }[] }>`

Replaces the iframe secondary-toolbar layout. Only listed customizable icons appear, in array order, in the given slot. Omitted slot keys become empty arrays. `null` / no argument restores the default iframe layout (undo/redo/shortcuts on the left, caption tools on the right). Unknown, duplicate, and exempt IDs are skipped and returned in `ignored`. Session-only; does not persist across reloads. Keyboard shortcuts remain available when an icon is hidden.

### Display Settings

#### `setDisplaySettings(settings)`

- **Arguments:**
  - settings: { displayWidth?: number (1-100), displayHeight?: number (1-50), xPadding?: number (0-50), yPadding?: number (0-50), lineSpacing?: number (0-50) }
- **Returns:** `Promise<{ success: boolean, message: string, settings?: object }>`

Updates caption display settings including width, height, padding, and line spacing. Settings are validated and saved to localStorage.

#### `enableSubtitleMode()`

- **Arguments:** none
- **Returns:** `Promise<void>`

Enables subtitle preview mode (sets non-CC mode for rendering).

#### `enableCaptionMode()`

- **Arguments:** none
- **Returns:** `Promise<void>`

Enables caption preview mode (sets CC mode for rendering).

#### `setPreviewFontSize(size)`

- **Arguments:**
  - size: number
- **Returns:** `Promise<void>`

Sets the preview font size.

#### `setPreviewFontFamily(family)`

- **Arguments:**
  - family: string
- **Returns:** `Promise<void>`

Sets the preview font family.

#### `setWatermark(settings)`

- **Arguments:**
  - settings: { enabled: boolean, showDateTime: boolean, dateTime: string | null ("YYYY-MM-DD HH:mm:ss", local), email: string | null, ipAddress: string | null, customText: string | null, alignment: "top" | "center" | "bottom", textOpacity: number (0-100), shadowOpacity: number (0-100) }
- **Returns:** `Promise<{ success: boolean, message: string, settings?: object }>`

Draws a visual watermark over the media player, beneath the caption/subtitle preview. The host resolves the display values, so `dateTime`, `email`, `ipAddress`, and `customText` are passed as strings (or `null` when that field is off). The date/time is static: push a new call to refresh it. Host settings take precedence over any team watermark configured in Options for the rest of the session. The watermark is an overlay only and is never burned into exported media.

### App Theme / Branding

#### `setTheme(tokens)`

- **Arguments:**
  - tokens: object (aliases such as primary, primaryRgb, bodyBg, bodyBgRgb, bodyColor, bodyColorRgb, secondaryColor, borderColor, fontFamily, linkColor, linkHoverColor, light, danger, warning, success, info — or raw --bs-* CSS variable names)
- **Returns:** `Promise<{ success: boolean, message: string }>`

Applies structured UI chrome theme overrides as CSS variables on the document root. Hex `primary` auto-derives `primaryRgb` when omitted. Call after the PenPal connection resolves and before media import when possible. Does not recolor the Konva timeline. Separate from caption QC `loadStyleGuide`.

#### `loadCustomStyles(cssText)`

- **Arguments:**
  - cssText: string (CSS stylesheet text)
- **Returns:** `Promise<{ success: boolean, message: string }>`

Injects or replaces a runtime <style> block for advanced host chrome theming. Prefer `setTheme` for simple color/font overrides. Does not remove the build-time system theme file.

#### `clearTheme()`

- **Arguments:** none
- **Returns:** `Promise<{ success: boolean, message: string }>`

Removes runtime theme CSS and token overrides applied via `setTheme` / `loadCustomStyles`. The build-time `assets/css/themes/{system}.css` stylesheet (if present) remains loaded.

### Keyboard Shortcuts

#### `getKeyboardShortcuts()`

- **Arguments:** none
- **Returns:** `Promise<{ success: boolean, data: array, count: number, message: string }>`

Retrieves the current keyboard shortcuts. Returns saved shortcuts if available, otherwise returns platform defaults.

#### `setKeyboardShortcuts(shortcuts)`

- **Arguments:**
  - shortcuts: array|string (Array of shortcut groups, or JSON string, with { name: string, shortcuts: [{ name: string, keyCmd: string, description?: string, shortName?: string }] })
- **Returns:** `Promise<{ success: boolean, message: string, updatedCount: number, ignoredCount: number, shortcuts?: array }>`

Updates matching keyboard shortcuts by shortcut name and saves them to localStorage. Partial shortcut payloads are merged with current shortcuts; unknown shortcut names are ignored.

### Media & Timeline

#### `setMediaPeaksPath(path)`

- **Arguments:**
  - path: string (URL to audio peaks JSON)
- **Returns:** `Promise<void>`

Sets the URL for the audio waveform peaks data to be displayed in the timeline.

#### `setMediaPeaksData(data)`

- **Arguments:**
  - data: object (Audio peaks data object)
- **Returns:** `Promise<void>`

Directly sets the audio waveform peaks data as an object, bypassing a URL fetch.

#### `useFallbackTimeline()`

- **Arguments:** none
- **Returns:** `Promise<void>`

Deprecated. Sets `projectState.media.useFallback` to true. The legacy fallback timeline no longer exists in the Konva-based timeline; kept as a no-op so external iframe consumers do not crash.

#### `useDefaultTimeline()`

- **Arguments:** none
- **Returns:** `Promise<void>`

Deprecated companion to `useFallbackTimeline()`. Sets `projectState.media.useFallback` to false.

#### `toggleTimeline(enable)`

- **Arguments:**
  - enable: boolean
- **Returns:** `Promise<void>`

Controls timeline visibility. If `enable` is true, shows the timeline. If false, flips the current visibility (does **not** mean “hide”).

#### `setPoster(thumbnailUrl)`

- **Arguments:**
  - thumbnailUrl: string
- **Returns:** `Promise<void>`

Sets the poster image (thumbnail) for the video player.

#### `importMedia(mediaUrl, thumbnailUrl, mediaType, storageType)`

- **Arguments:**
  - mediaUrl: string
  - thumbnailUrl: string (Optional)
  - mediaType: string (e.g., "video/mp4", default "video/mp4")
  - storageType: string (e.g., "Cloud Storage", "Vimeo", "YouTube", "HLS Manifest", default "Cloud Storage")
- **Returns:** `Promise<{ success: boolean, message: string }>`

Loads a video or audio file into the editor from a specified URL. If `mediaUrl` is a Framelight X / Grass Valley FLX URL, the iframe auto-switches to the Framelight player (no extra `storageType` needed).

### Quick Tools

#### `setQuickToolsSettings(settings)`

- **Arguments:**
  - settings: { selected?: string, styles?: boolean, summary?: boolean, search?: boolean, spellCheck?: boolean, timing?: boolean, liveCaptioning?: boolean, qc?: boolean, errorNav?: boolean, templates?: boolean, voices?: boolean, speakers?: boolean, tags?: boolean, notes?: boolean, markers?: boolean, videoFilters?: boolean, manualQc?: boolean, media?: boolean }
- **Returns:** `Promise<{ success: boolean, message?: string, quickTools?: object }>`

Toggles Quick Tools panel visibility flags and optionally selects the active panel. Valid `selected` panel IDs: summary, styles, findAndReplace, spellCheck, timingAndSync, liveCaptioning, qcAndReview, manualQc, errors, speakers, tags, markers, notes, videoFilters, eventTemplates, voices, media. If the requested panel is disabled, falls back to the first visible panel.

#### `selectQuickToolsPanel(panelName)`

- **Arguments:**
  - panelName: string (case-insensitive panel ID; see `setQuickToolsSettings` for valid IDs)
- **Returns:** `Promise<{ success: boolean, message?: string, selected?: string }>`

Selects an enabled Quick Tools panel and switches editor mode (timing for Timing & Sync, edit otherwise).

### Transcript Sync

#### `setTranscript(transcript, profile)`

- **Arguments:**
  - transcript: object (Transcription data object)
  - profile: string (Source profile, e.g., "deepgram", default "deepgram")
- **Returns:** `Promise<void>`

Sets the raw transcript data to be processed by the editor.

#### `checkSync()`

- **Arguments:** none
- **Returns:** `Promise<{ success: boolean, message: string, drift: number|null, driftAnalysis: object|null, missingDialogueCount: number }>`

Runs transcript-to-caption alignment against the currently selected event group using transcript data previously set via `setTranscript`. Does not apply timing changes; use for drift analysis only. Requires a selected event group with timed events and a loaded transcript.

#### `resyncEventGroup()`

- **Arguments:** none
- **Returns:** `Promise<{ success: boolean, message: string, drift: number|null, driftAnalysis: object|null, missingDialogueCount: number }>`

Same prerequisites as `checkSync()`, but applies aligned start/end times to the selected event group and records an undo history entry.

#### `loadTranscript()`

- **Arguments:** none
- **Returns:** `Promise<{ success: boolean, message: string }>`

Processes the transcript data previously set via `setTranscript` and imports it into the editor as a new event group.

### Subtitle Import & Export

#### `importSubtitle(subtitleUrl, profile, decodeOptions, evgOptions, autoFormatOptions, forced, target)`

- **Arguments:**
  - subtitleUrl: string (URL to subtitle file)
  - profile: string (Subtitle format profile, e.g., "subRip", "webVtt")
  - decodeOptions: object (Optional, format-specific decoding options)
  - evgOptions: object (Optional, event group options like type, name, language; ignored when target.eventGroupId is set)
  - autoFormatOptions: { enable?: boolean, maxLines?: number, maxChars?: number, minDuration?: number, allowOrphanWords?: boolean, selective?: boolean } (Optional; on merge, only the newly imported events are formatted)
  - forced: boolean (Optional, default false; when true, marks all imported events as forced)
  - target: { eventGroupId?: string, importOption?: "merge"|"replace", track?: "A"|"B"|"C"|"D" } (Optional; import into an existing Event Group instead of creating a new one. importOption defaults to "replace". track is applied to imported events on merge into a non-multiview group)
- **Returns:** `Promise<{ success: boolean, message: string, id?: string, index?: number, importedCount?: number }>`

Loads a subtitle file from a URL into the editor, converting it to the internal project format. Creates a new event group by default, or merges/replaces into an existing group when target.eventGroupId is provided. Optionally applies auto-formatting and a track assignment.

#### `exportSubtitle(profile, encodeOptions, saveAsFile, forcedOption, eventGroupId, exportTracks)`

- **Arguments:**
  - profile: string (Target subtitle format profile)
  - encodeOptions: object (Optional, format-specific encoding options)
  - saveAsFile: boolean (If true, triggers a file download; otherwise, returns data)
  - forcedOption: string (Optional, default "include"; values: "include", "exclude", "only")
  - eventGroupId: string (Optional; ID of the Event Group to export. When omitted, uses the currently selected Event Group)
  - exportTracks: string[] (Optional, default ["none", "A", "B", "C", "D"]; only events on the listed tracks are exported. "none" matches events without a track assignment. An empty array or all values selected exports everything)
- **Returns:** `Promise<{ success: boolean, message: string, data?: string, fileName?: string }>`

Exports captions from a specified Event Group (or the selected Event Group by default) into a specified format, optionally filtered by track. Can return the data or trigger a file download.

### Markers

#### `getMarkers()`

- **Arguments:** none
- **Returns:** `Promise<object> (Copy of marker state)`

Retrieves the current marker data from the editor, including all marker lists and their markers.

#### `setMarkers(markers)`

- **Arguments:**
  - markers: object (Marker state object with lists and selected properties)
- **Returns:** `Promise<void>`

Sets the entire marker state for the editor, allowing you to load custom markers and lists.

#### `createMarkerList(markerList)`

- **Arguments:**
  - markerList: { name: string, color?: string }
- **Returns:** `Promise<void>`

Creates a new named marker list within the editor.

#### `insertMarker(marker, markerList)`

- **Arguments:**
  - marker: object (_Marker object, e.g., { time: number, comment: string })
  - markerList: number (Optional, 0-based index of the target marker list, default 0)
- **Returns:** `Promise<void>`

Inserts a new marker into a specified marker list by list index (not list ID).

### Style Guide & QC

#### `loadStyleGuide(styleGuideData)`

- **Arguments:**
  - styleGuideData: object (Style guide configuration object)
- **Returns:** `Promise<{ success: boolean, message: string, id?: string }>`

Loads or updates a style guide in the editor's local storage. If a guide with the same ID exists, it will be updated.

#### `getStyleGuides()`

- **Arguments:** none
- **Returns:** `Promise<{ success: boolean, data: array, count: number, message: string }>`

Retrieves all style guides currently stored in local storage.

#### `qcEventGroup(eventGroupId, styleGuideId)`

- **Arguments:**
  - eventGroupId: string (ID of event group to validate)
  - styleGuideId: string (ID of style guide to use for validation)
- **Returns:** `Promise<{ success: boolean, errors: array, errorCount: number, message: string, eventGroupId?: string, eventGroupName?: string, styleGuideId?: string, styleGuideName?: string }>`

Runs quality control validation on a specified event group using a specified style guide. Returns all validation errors found.

### Event Groups

#### `getSelectedEventGroupId()`

- **Arguments:** none
- **Returns:** `Promise<{ success: boolean, id: string|null, index: number|null, name?: string, type?: string, eventCount?: number, language?: string, tracks?: string[], message: string }>`

Retrieves the ID and details of the currently selected event group in the editor, including which letter tracks (A–D) are in use.

#### `getEventGroupInfo()`

- **Arguments:** none
- **Returns:** `Promise<array> (Array of { id, name, type, eventCount, language, tracks })`

Returns summary details for all event groups currently loaded in the editor, including which letter tracks (A–D) are in use per group.

#### `addEventGroup(eventGroupOptions)`

- **Arguments:**
  - eventGroupOptions: object (Optional, Event Group options like { name?: string, type?: string, language?: string, linkedGroup?: string|false, allowOriginalEdit?: boolean, rtl?: boolean, events?: array })
- **Returns:** `Promise<{ success: boolean, message: string, id?: string, index?: number, eventCount?: number, eventGroup?: object }>`

Creates a new event group in the project, selects it, and records the change in history.

#### `removeEventGroup(eventGroupId)`

- **Arguments:**
  - eventGroupId: string (ID of event group to remove)
- **Returns:** `Promise<void | { success: false, message: string }>`

Removes an event group by ID and resets selection to the first remaining group when available. Returns `{ success: false, message }` when the group is locked; otherwise returns nothing after the group is removed.

#### `mergeEventGroups(sourceGroups, eventGroupOptions, orderByStart, groupTracks)`

- **Arguments:**
  - sourceGroups: string[] (Array of source event group IDs)
  - eventGroupOptions: object (Optional, properties for the merged event group)
  - orderByStart: boolean (Optional, default true; sorts merged events by start time)
  - groupTracks: object (Optional; map of source event group ID to a track letter "A"|"B"|"C"|"D". Events copied from that group are assigned the track in the merged result. Groups omitted from the map keep their existing track values)
- **Returns:** `Promise<{ success: boolean, message: string, id?: string, index?: number, eventCount?: number, sourceCount?: number }>`

Merges events from multiple source event groups into a new event group and selects the merged result. Optionally assigns a letter track per source group.

### Speakers

#### `addSpeaker(speaker)`

- **Arguments:**
  - speaker: string | { id?: string, name: string, colour?: string, color?: string }
- **Returns:** `Promise<{ success: boolean, message: string, speaker?: object }>`

Adds a speaker to the current project. String input is used as the speaker name; object input may include an id and colour (`colour` or `color` both accepted).

#### `getSpeakers()`

- **Arguments:** none
- **Returns:** `Promise<array> (Array of speaker objects)`

Retrieves all speakers currently defined in the project.

### Project Data

#### `loadProjectData(ccprj)`

- **Arguments:**
  - ccprj: object or string (Closed Caption Project JSON data)
- **Returns:** `Promise<{ success: boolean, message: string }>`

Loads a complete Closed Caption Creator project (in .ccprj format) into the editor. Resets the undo stack and marks the loaded state as the saved baseline for `hasUnsavedChanges`.

#### `getHistory()`

- **Arguments:** none
- **Returns:** `Promise<{ position: number, actions: array }> (Each action is { name: string, eventGroup: number })`

Returns a lightweight summary of the undo stack (action names and event-group indices only; not full snapshots). Use to inspect undo position without fetching the entire project.

#### `hasUnsavedChanges()`

- **Arguments:** none
- **Returns:** `Promise<boolean>`

Returns true when the undo-stack position differs from the last saved baseline. `loadProjectData` establishes that baseline. Undoing back to the baseline clears the dirty flag.

#### `getProjectData()`

- **Arguments:** none
- **Returns:** `Promise<object> (Complete project JSON)`

Retrieves the entire current project data from the editor in .ccprj JSON format.

### Event Selection & Navigation

#### `getSelectedEvents()`

- **Arguments:** none
- **Returns:** `Promise<array> (Array of selected event objects)`

Retrieves all currently selected events from the active event group.

#### `selectEventById(id)`

- **Arguments:**
  - id: string (Event ID)
- **Returns:** `Promise<void>`

Selects a specific event in the current event group by its unique ID.

#### `selectEventByIndex(index)`

- **Arguments:**
  - index: number | array (Event index or array of indices)
- **Returns:** `Promise<void>`

Selects one or more events in the current event group by their index position(s). Accepts a single index or an array of indices for multiple selection.

#### `scrollToEventById(id)`

- **Arguments:**
  - id: string (Event ID)
- **Returns:** `Promise<void>`

Scrolls the event list to make the event with the specified ID visible in the editor.

#### `scrollToEventByIndex(index)`

- **Arguments:**
  - index: number (Event index)
- **Returns:** `Promise<void>`

Scrolls the event list to make the event at the specified index visible in the editor.

### Lock State

#### `enableVideoLock()`

- **Arguments:** none
- **Returns:** `Promise<void>`

Enables the video lock (video follows captions).

#### `disableVideoLock()`

- **Arguments:** none
- **Returns:** `Promise<void>`

Disables the video lock (video follows captions).

#### `enableCaptionLock()`

- **Arguments:** none
- **Returns:** `Promise<void>`

Enables the caption lock (captions follow video).

#### `disableCaptionLock()`

- **Arguments:** none
- **Returns:** `Promise<void>`

Disables the caption lock (captions follow video).

#### `enablePreviewLock()`

- **Arguments:** none
- **Returns:** `Promise<void>`

Shows the on-screen caption/subtitle preview overlay on the video player.

#### `disablePreviewLock()`

- **Arguments:** none
- **Returns:** `Promise<void>`

Hides the on-screen caption/subtitle preview overlay on the video player.

### Auto Formatting & Correction

#### `autoFormat(evgIndex, maxLines, maxChars, minDuration, allowOrphanWords, selective)`

- **Arguments:**
  - evgIndex: number (Event group index)
  - maxLines: number (Maximum lines per event)
  - maxChars: number (Maximum characters per line)
  - minDuration: number (Minimum event duration in seconds)
  - allowOrphanWords: boolean (Whether to allow single words on a line)
  - selective: boolean (Optional, default false; when true, only formats events that fail line/char checks)
- **Returns:** `Promise<void | { success: false, message: string }>`

Automatically formats the specified event group by splitting/merging events based on line and character limits. Returns `{ success: false, message }` when the group is locked; otherwise returns nothing after formatting.

#### `autoCorrectReadingSpeed(maxCps, minDuration, maxDuration, minFrameGap, allowMerge)`

- **Arguments:**
  - maxCps: number (Maximum characters per second)
  - minDuration: number (Minimum event duration in seconds)
  - maxDuration: number (Maximum event duration in seconds)
  - minFrameGap: number (Minimum frame gap between events)
  - allowMerge: boolean (Whether to merge brief neighboring events when they cannot be corrected by extending alone; default true)
- **Returns:** `Promise<void>`

Automatically adjusts event timing to meet reading speed requirements using the shared no-cascade correctReadingSpeed algorithm. Optionally merges brief events; events that cannot be corrected are marked unapproved.

#### `fixEventOverlap(evgIndex)`

- **Arguments:**
  - evgIndex: number (Optional; event group index, defaults to the currently selected event group)
- **Returns:** `Promise<void>`

Resolves overlapping events in the specified event group using the project frame rate and minimum frame gap (same behavior as Format > Fix Event Overlap).

#### `setProjectFrameGap(frameGap)`

- **Arguments:**
  - frameGap: number (Minimum frame gap between events)
- **Returns:** `Promise<void>`

Sets the minimum frame gap for the project editor state.

#### `insertBlankFrames(evIndex, frames, minFrameGap, maxFrameGap, shotChangeAware)`

- **Arguments:**
  - evIndex: number (Event group index, default 0 — not an event index)
  - frames: number (Number of blank frames to insert)
  - minFrameGap: number (Minimum frame gap)
  - maxFrameGap: number (Maximum frame gap)
  - shotChangeAware: boolean (Whether to respect shot changes)
- **Returns:** `Promise<void>`

Inserts blank frames between events in the specified event group, with optional shot change awareness.

## Subtitle format profiles

`importSubtitle(url, profile, ...)` takes a **source** profile and `exportSubtitle(profile, ...)` takes a **target** profile. Common values:

| Format | Profile |
|---|---|
| SubRip (.srt) | `subRip` |
| WebVTT (.vtt) | `webVtt` |
| Scenarist Closed Caption (.scc) | `scenerist` |
| DFXP / TTML (.dfxp, .xml) | `dfxp` |
| SMPTE-TT (.xml) | `smpteTtml` |
| EBU STL (.stl) | `ebuStl` |
| Closed Caption Creator project (.ccprj) | `closedCaptionProject` |

Full lists (profile names are case-sensitive):
- Source profiles: https://api.closedcaptionconverter.com/help/profiles/source
- Target profiles: https://api.closedcaptionconverter.com/help/profiles/target

## Behaviour notes

- **Selection after import:** `importSubtitle` selects the Event Group it created (or the `target` group it merged/replaced into). Its result's `id` is that group's ID, so you can pass it straight to `qcEventGroup` / `exportSubtitle`.
- **QC results:** `qcEventGroup` returns `success: false` only when QC could not run (unknown group or style guide ID, etc.). Issues found are reported as `success: true` with `errorCount > 0` and the details in `errors`.
- **Style guides** are stored in the editor's `localStorage` under the stable `id` you pass; reloading with the same `id` updates it. Load the guide before calling `qcEventGroup`.
- **Unsaved changes:** `hasUnsavedChanges()` compares against the baseline set by `loadProjectData`. If you only use `importMedia` / `importSubtitle`, treat the first edit after loading as dirty and track your own saved state (or save with `getProjectData` and restore with `loadProjectData`).
- **Media and subtitle URLs** are fetched by the editor running in the user's browser on the iframe origin, not by your page. Use publicly reachable or pre-signed URLs (with CORS allowing the iframe origin); cookies for your own domain will not be sent.

## React integration notes

- Use the iframe's `onLoad` prop (or attach the listener before setting `src`) so the `load` event isn't missed.
- Keep `remote` and the connection in `useRef`, not state, so parent-side methods passed to `connect()` always see the current `remote`.
- Call `connection.destroy()` in the `useEffect` cleanup and before reconnecting (StrictMode double-mounts, iframe reloads).
- Parent-side methods may be `async`; guard against repeated Save clicks yourself.

## Common mistakes

- **Connection never resolves:** `connect()` was called before the iframe loaded, or `allowedOrigins` does not exactly match the iframe origin (scheme + host + port, no trailing slash).
- **Using `'*'` in production** for `allowedOrigins` — insecure; use the exact origin.
- **Missing `allow` permissions** on the `<iframe>` (`clipboard-write; clipboard-read; encrypted-media`) — some editor features fail or initialisation stalls.
- **Not awaiting calls** — every remote method returns a Promise.
- **Confusing parent `exportSubtitle()` with `remote.exportSubtitle(...)`** — see "Parent-side methods".
- **Passing an event index where an Event Group index/ID is expected** — e.g. `insertBlankFrames(evIndex, ...)`'s first argument is an Event Group index, not an event index; `qcEventGroup` and `exportSubtitle` take an Event Group **ID** (get it from `getSelectedEventGroupId()` or `getEventGroupInfo()`).
- **`toggleTimeline(false)` / `toggleStatusModal(false)` do not mean "hide"** — a falsy argument flips the current state. Pass `true` to force show.
- **Expecting `setTheme` to recolor the timeline** — it only styles UI chrome.
- **`useFallbackTimeline` / `useDefaultTimeline`** are deprecated no-ops; don't use them in new code.
- **Calling Options/Settings UI** — **Edit → Options** is hidden in iframe mode; configure everything through remote methods.

## Support

Integration help: https://www.closedcaptioncreator.com/contact.html