Get the edited file

When your visitor presses Done, the editor saves the file in their browser and sends the process event. Nothing is uploaded to Mastershot. What happens to the file next is up to your page.

Take the file from the process event

editor.on("process", ({ src, dest, imageState }) => {
  // src: the file your visitor started with
  // dest: the edited File
  // imageState: the edits, to open them again later
})

dest is a File with a name, so you can upload it as it is:

editor.on("process", async ({ dest }) => {
  const form = new FormData()
  form.append("file", dest, dest.name)
  await fetch("/api/upload", { method: "POST", body: form })
})

Or show it on the page straight away with URL.createObjectURL(dest).

Choose the format, quality and size

The editor's imageWriter decides how the file is written. Make one with createDefaultImageWriter:

import {
  appendDefaultEditor,
  createDefaultImageWriter,
} from "https://cdn.mastershot.app/editor/1.1.0/editor.js"

appendDefaultEditor("#editor", {
  imageWriter: createDefaultImageWriter({
    mimeType: "image/webp",
    quality: 0.85,
    targetSize: { width: 1200, height: 1200, fit: "contain" },
    renameFile: (file) => `avatar-${Date.now()}.webp`,
  }),
})

targetSize applies after your visitor's own edits. fit is "contain" (the default) to fit inside the size, "cover" to fill it and cut what's left over from the middle, or "force" to stretch to it. A result smaller than the size is left as it is unless upscale is true.

Videos use the same imageWriter, and read its targetSize, renameFile and store. They're saved in their own format where the browser can write it, otherwise MP4, at no more than their own quality.

Let the editor upload it

Give store a URL and the editor POSTs the result there as a form, with the file as dest and the edits as imageState (JSON). The process event waits until the upload has finished.

createDefaultImageWriter({
  store: {
    url: "/api/upload",
    credentials: "include",
    headers: { "X-CSRF-Token": token },
    // Optional: your own form fields instead of dest and imageState.
    dataset: ({ dest, imageState }) => [
      ["photo", dest, dest.name],
      ["edits", JSON.stringify(imageState)],
    ],
  },
})

The processprogress event reports the upload's progress. store can also be just the URL, or an async function (output, options, onprogress) => result that uploads it your own way. Whatever the function returns arrives as store in the process event.

Edit without showing the editor

processImage(src, options) applies edits to a file without an interface and resolves with the same output as the process event. Use it to make thumbnails, or to apply edits you saved earlier.

import { processImage } from "https://cdn.mastershot.app/editor/1.1.0/editor.js"

const { dest } = await processImage(file, {
  imageState: savedState,
  imageWriter: {
    mimeType: "image/jpeg",
    targetSize: { width: 400, height: 400, fit: "cover" },
  },
})

Stop or change a save

• willProcessImage(imageState) runs when your visitor presses Done. Return false (or a promise of false) to stop the save, for example to ask them something first.
• preprocessImageState, postprocessImageData and postprocessImageBlob on the image writer let you change the edits before the photo is drawn, its pixels after, or the finished file.
• processerror is sent when a save fails. The editor shows the error to your visitor too.
• editor.abortProcessImage() stops a save that's under way.