IFrame Embed
The IFrame Embed integration allows video platforms and web applications to embed the full Closed Caption Creator editor directly within their own interface using a standard HTML <iframe> tag. Instead of building a caption editing tool from scratch, development teams can embed a professional-grade editor with support for over 30 subtitle formats, frame-accurate playback, real-time QC, and multilingual workflows — all accessible without ever leaving the host platform.
Communication between the parent application and the embedded editor is handled by PenPal JS, a lightweight cross-window messaging library. Through this connection, the parent page can programmatically load media, import subtitle files, configure project settings, run quality control checks, and retrieve edited content — making it possible to build tightly integrated captioning workflows tailored to any platform's requirements.
Getting Started
Before embedding the editor, ensure your application includes PenPal JS. The library is available via CDN and should be loaded in the parent page:
<script src="https://unpkg.com/penpal@^7/dist/penpal.min.js"></script>
Next, add an <iframe> element to your page pointing to the Closed Caption Creator IFrame demo URL. The allow attribute must include clipboard-write, clipboard-read, and encrypted-media for the editor to function correctly:
<div class="iframe-container">
<iframe
id="editor"
src="https://iframe-demo.closedcaptioncreator.com/"
style="width: 100%; height: 90vh;"
frameborder="0"
allow="accelerometer; autoplay; clipboard-write; clipboard-read; encrypted-media"
allowfullscreen>
</iframe>
</div>
Once the iframe is in place, use PenPal to establish a connection when the frame loads. The connection.promise resolves to a remote object containing all of the methods exposed by the editor. All calls to these methods are asynchronous and should be awaited:
iframe.addEventListener('load', async () => {
const messenger = new Penpal.WindowMessenger({
remoteWindow: iframe.contentWindow,
allowedOrigins: ['https://iframe-demo.closedcaptioncreator.com']
});
const connection = Penpal.connect({ messenger, methods: {} });
const remote = await connection.promise;
// Configure and load the project
await remote.setProjectName("My Project");
await remote.setProjectFrameRate(29.97);
await remote.setProjectDropFrame(true);
await remote.importMedia(mediaUrl);
await remote.importSubtitle(subtitleUrl, "subRip");
});
Key Functions
The following table describes the primary categories of methods available on the remote object. For a complete function reference including all parameters and return values, visit the IFrame Remote Documentation on the Closed Caption Creator website.
| Category | Representative Methods | Description |
|---|---|---|
| Project configuration | setProjectName, setProjectFrameRate, setProjectDropFrame, setProjectIncode, setProjectDescription | Set project-level metadata before or after loading content. |
| Media | importMedia, setPoster, setMediaPeaksPath, setMediaPeaksData, toggleTimeline | Load a video or audio file, set a thumbnail, and configure the audio waveform display. |
| Subtitle import/export | importSubtitle, exportSubtitle | Load a subtitle file from a URL or retrieve the edited captions in any supported output format. |
| UI control | toggleStatusModal, updateModalStatus, updateModalTitle, alertUser, completeImport, failImport | Control the progress modal and display alerts to the user during loading sequences. |
| Locking & navigation | enableVideoLock, enableCaptionLock, enablePreviewLock, scrollToEventById, selectEventByIndex | Control synchronisation between the video player and the caption list. |
| Quality control | loadStyleGuide, qcEventGroup, getStyleGuides | Load a custom style guide and run validation checks against an Event Group. |
| Data retrieval | getProjectData, loadProjectData, getMarkers, setMarkers, getSelectedEventGroupId, getSelectedEvents | Retrieve or inject full project data, markers, and event selections. |
| Auto tools | autoFormat, autoCorrectReadingSpeed, insertBlankFrames, setProjectFrameGap | Programmatically apply formatting and timing corrections to caption tracks. |
Importing and Exporting Subtitles
The importSubtitle method loads a subtitle file from a URL into the editor. It accepts the file URL, a source profile identifying the format (for example "subRip" for SRT or "webVtt" for VTT), optional decode options specific to the format, and an optional Event Group options object for configuring real-time validation rules such as maxChars, maxLines, maxCps, and overlap. A complete list of supported source profiles is available at https://api.closedcaptionconverter.com/help/profiles/source.
The exportSubtitle method encodes the current captions into a target format. It accepts a target profile, optional encode options, and a saveAsFile boolean. When saveAsFile is false, the method returns the encoded file contents as a string so the parent application can handle delivery — for example, uploading the result to cloud storage or posting it to an API. When saveAsFile is true, a browser file download is triggered instead.
Quality Control Workflows
Custom style guides can be loaded into the editor programmatically using loadStyleGuide, which accepts a style guide configuration object defining rules such as maximum characters per second, maximum duration, minimum event gap, and a range of text formatting checks. Once a style guide is loaded, qcEventGroup runs validation against a specified Event Group and returns all errors found, including error counts and the relevant event data. This enables the parent application to gate the publish action — preventing delivery until caption quality meets the configured standard — and to surface specific errors to the editor using the status modal functions.
Troubleshooting
The most common setup issue is an allowedOrigins mismatch. In production, the allowedOrigins array in the Penpal.WindowMessenger configuration must specify the exact origin of the IFrame — https://iframe-demo.closedcaptioncreator.com — rather than the wildcard '*' used in development. Using '*' in a production environment is a security risk and may also cause connection failures in certain browsers.
If the editor does not respond to method calls after the connection is established, confirm that the allow="clipboard-write; clipboard-read; encrypted-media" attribute is present on the <iframe> tag. Missing permissions prevent certain editor features from functioning and can cause the initialisation sequence to stall.
If the PenPal connection times out before your setup code runs, ensure that connectToIframe is called inside a load event listener on the iframe element rather than immediately after the iframe is added to the DOM. The connection should only be initiated once the iframe's content window is fully loaded.
For developer support and integration assistance, visit the Contact Page to connect with the Closed Caption Creator team.