Open audio in Auditius from your app

How it works

Two windows talk with postMessage. Every message has a type and v: 1, and each side only listens to the window it opened or was opened by, on the origin it expects.

1. Inside a click, your app opens https://auditius.com/?editor&handoff=1 in a new window.
2. Auditius tells your window it is ready, and your app sends the file with its name and, if you want the result back, a save URL on your own site.
3. The file opens in a new session in Auditius, which shows your site as its source and keeps it after a reload.
4. When the person is done, the File menu offers to save to your app: Auditius opens your save URL and sends the edited file there.

Open a file in Auditius

On your page, open the editor and send the file once it is ready. The save URL must use https and be on the same origin as the page that sends it; formats lists the types you accept, preferred first (Auditius writes MP3, WAV, FLAC and Ogg Vorbis, and sends MP3 if you give none).

// Inside your click handler: popup blockers allow windows opened by a click.
const AUDITIUS = 'https://auditius.com';
const editor = window.open(AUDITIUS + '/?editor&handoff=1');

window.addEventListener('message', function onReady(e) {
  if (e.source !== editor || e.origin !== AUDITIUS) return;
  if (e.data?.type !== 'handoff:ready' || e.data.v !== 1) return;
  window.removeEventListener('message', onReady);
  editor.postMessage({
    type: 'handoff:open', v: 1,
    file: audioBlob,                      // a Blob or File
    name: 'Interview.m4a',
    app: { name: 'My App' },              // shown as a label
    save: { url: 'https://myapp.example/handoff/save/123', formats: ['audio/mpeg'] },
  }, AUDITIUS);
});

Receive the edited file

The save URL is a page on your site. It tells Auditius it is ready, takes the file and answers with progress, then saved, cancelled or an error with one of these codes: too_large, unsupported, quota, unauthorized or unexpected.

// On https://myapp.example/handoff/save/123, the page Auditius opens to save.
const AUDITIUS = 'https://auditius.com';

window.addEventListener('message', async (e) => {
  if (e.source !== window.opener || e.origin !== AUDITIUS) return;
  if (e.data?.type !== 'handoff:save' || e.data.v !== 1) return;
  const reply = (msg) => e.source.postMessage({ ...msg, v: 1 }, e.origin);
  try {
    // e.data.file, e.data.name and e.data.meta (title, transcript as WebVTT, chapters…)
    const id = await upload(e.data.file, (ratio) => reply({ type: 'handoff:progress', ratio }));
    reply({ type: 'handoff:saved', id });
  } catch {
    reply({ type: 'handoff:error', code: 'unexpected' });
  }
});

window.opener.postMessage({ type: 'handoff:save-ready', v: 1 }, '*');

What Auditius checks

Auditius takes one file, from the window that opened it, and only when the address asked for a handoff.

• The file must be audio or video the browser can decode.
• A save URL on another origin, or without https, is refused.
• Your app name is shown as plain text, at most 40 characters; the source is always shown as your real site address.
• Nothing is uploaded: the file stays in the browser of the person editing it.