postMessage API

Open audiocutter.online/import/ as a popup from your website and hand off an audio file to the editor via window.postMessage. The user lands in the editor with the file already loaded — no upload step, no roundtrip to your server.

This is the lightest integration path. If you also need a pre-filled multi-fragment project, branded UI, or a submit-back callback, use Hosted Sessions instead — see Which method should I use?.

Quick start

// 1. Open the import page as a popup
const popup = window.open('https://audiocutter.online/import/')

// 2. Listen for the ready signal
window.addEventListener('message', (event) => {
  if (event.data?.source === 'audiocutter' && event.data.type === 'ready') {
    // 3. Send the audio file
    popup.postMessage({
      type: 'audio',
      file: file // File object
    }, 'https://audiocutter.online')
  }
})

That's the entire contract. After the file is received, the popup stores it in IndexedDB and navigates to /, where the editor opens with the file loaded.

Message protocol

Popup → opener: ready signal

Once the popup loads, it posts a single ready signal to window.opener with target origin *:

{ source: 'audiocutter', type: 'ready' }

Always check both event.data.source === 'audiocutter' and event.data.type === 'ready' before responding — your listener will see every postMessage the page receives.

Opener → popup: audio file

Send back a single message containing the audio file:

{
  type: 'audio',
  file: File   // a File or File-like Blob from <input type="file"> or drag-and-drop
}

Always specify the target origin as 'https://audiocutter.online' on the postMessage call. Using '*' would leak the file to whatever origin happens to occupy the popup if the user navigates away mid-handshake.

Only one audio file per session. To replace it, send another message — the popup overwrites the IndexedDB entry and redirects again.

Legacy alias

For backwards compatibility, the popup also accepts { type: 'audio', audio: Blob } (the field is audio, the value is a Blob instead of a File). It is wrapped into a File named imported-audio. New integrations should use the file field with a real File object so the filename and MIME type are preserved.

Timeout

The popup waits 30 seconds for the audio message. If nothing arrives in that window, it falls back to showing the integration guide as a static page. Send the file promptly after receiving ready.

Popup blockers

Browsers only allow window.open from a user gesture (click, keypress, etc.). Call it directly inside the event handler — do not wait for an async operation first:

// ❌ Popup blocked — async work runs first
button.addEventListener('click', async () => {
  await fetch('/api/draft')                  // gesture is lost here
  window.open('https://audiocutter.online/import/')
})

// ✅ Open synchronously, then do async work
button.addEventListener('click', () => {
  const popup = window.open('https://audiocutter.online/import/')
  fetchAndSend(popup)
})

Cross-origin headers

audiocutter.online is served with Cross-Origin-Opener-Policy: same-origin + Cross-Origin-Embedder-Policy: require-corp on every route — required for SharedArrayBuffer (FFmpeg).

The /import/ route overrides both to unsafe-none so that window.opener stays accessible across origins. After the file is received, the popup navigates to / — at which point the editor regains SharedArrayBuffer and the opener relationship is intentionally severed.

Your site does not need any special headers to open the popup or call postMessage. Plain HTTPS is enough.

Which method should I use?

When in doubt: if you just have a file to hand off, use the postMessage API. If you have a project to hand off and want the result back, use hosted sessions.

Questions?

Have a question or need help with the integration? Write to us and we’ll get back to you.