The Camera Kit Web SDK allows web developers to build Snap's core AR Lens technology into their applications.
First, familiarize yourself with the Camera Kit docs. This covers access to the Camera Kit Portal, where to find your API Token, how to manage lenses and lens groups, etc.
Most of the content found here can also be found on the Camera Kit docs site.
npm install @snap/camera-kit
The SDK is authored in TypeScript, and distributes type definitions. All the examples here are presented in TypeScript. We encourage the use of TypeScript in projects that consume the SDK – but it's also fully compatible with Javascript projects as well.
Currently, the SDK distributes Javascript modules. We may support other module formats in the future (e.g. CommonJS), but for now you'll need to use import syntax to use the Camera Kit Web SDK.
If you're working in a project that uses a bundler (e.g. Webpack or Rollup), or builds using the TypeScript compiler, this shouldn't be an issue. If you're not using a bundler, many browsers now support import syntax natively – if you don't need support for older browsers (or IE), no bundler is necessary.
With the SDK installed and capable of being imported, the first thing to do is bootstrap the SDK. This tells the SDK to download the LensCore WebAssembly runtime, which will be used to render Lenses. It also allows you to configure the SDK according to your needs.
To call bootstrapCameraKit, you'll need to provide a apiToken. Once you've completed the Getting set up in our portals section of the Getting Started guide, you'll be able to find this in the Snap Kit Portal.
import { boostrapCameraKit } from "@snap/camera-kit";
(async function main() {
const apiToken = "API Token value copied from the Camera Kit Portal";
const cameraKit = await bootstrapCameraKit({ apiToken });
})();
In order to render Lenses, you must first create a CameraKitSession. Each session represents a rendering pipeline - it connects an input media source (e.g. a webcam) to the LensCore AR engine, applies a Lens, and renders the output to a <canvas> element.
There are two ways to create a session. If you already have a <canvas> element on your page that you'd like for the CameraKitSession to render into, you can pass it to Camera Kit when creating the session. Otherwise, the session will create a new <canvas> element which you can add to the DOM.
// Using an existing canvas
const canvas = document.getElementById("my-canvas");
const session = await cameraKit.createSession(canvas);
// Let Camera Kit create a new canvas, then append it to the DOM
const canvasContainer = document.getElementById("canvas-container");
const session = await cameraKit.createSession();
canvasContainer.appendChild(session.output.live);
There are actually two different output canvases: live and capture. These correspond to the two different RenderTargets to which a Lens may render. The live output renders a view suitable for presentation to the current user. Some Lenses may also render to the capture output, which renders content suitable for viewing by other users.
The most common source will be the user's webcam. Camera Kit Web SDK provides helper methods to create a CameraKitSource object from
a MediaStream, or directly from a user's webcam via getUserMedia.
import { createMediaStreamSource } from "@snap/camera-kit";
// ...
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const source = createMediaStreamSource(stream, {
transform: Transform2D.MirrorX,
cameraType: "front",
});
session.setSource(source);
Note that calling getUserMedia will prompt the user to grant the webpage access to the webcam.
In order to apply a lens to our session, we first have to fetch metadata for the lens we wish to apply. We can configure a group of lenses and get all the lenses in that group – this could be useful if we want to allow the user to select a lens from the group. Or if we know the specific lens we want to apply, we can provide its unique ID (along with the ID of a group that contains that lens) and get back just the single lens.
In the Camera Kit Portal, you can find available lenses and add them to lens groups. Once you've chosen a lens or lens group to load, you can use the Lens repository to fetch the lens metadata. Then you can apply the lens to the session.
The Camera Kit docs include info on how to set up Lenses and Lens Groups.
// A single lens
const lens = await cameraKit.lensRepository.loadLens("A lens ID found in the Camera Kit Portal", "A lens group ID");
session.applyLens(lens);
// One or more lens groups – lenses from all groups are returned as a single array of lenses.
const { lenses } = await cameraKit.lensRepository.loadLensGroups([
"A lens group ID",
"These can be found in the Camera Kit Portal",
]);
session.applyLens(lenses[0]);
By default, Camera Kit will render its output at the same resolution as the video input you provided. But you can also tell Camera Kit to render at a different resolution.
Keep in mind that this controls LensCore's render resolution, and not (necessarily) the size at which the output canvas is displayed to the user. The output canvas may be sized using HTML and CSS, and may apply its own scaling to the rendered output.
Most of the time you'll not need to set the render size – but it could be useful if your video source is, say, very high resolution. In that case, you may observe better performance by telling Camera Kit to render at a lower resolution.
session.setRenderSize(width, height);
Note that when calling getUserMedia, best performance can be achieved by requesting the resolution you want to display. This can be done using constraints
The CameraKitSession will only process input video frames and render them to the output when you tell it to do so – this way, you can control when Camera Kit is using a client's resources (e.g. CPU and GPU compute cycles). You can tell the session to play or pause.
session.play();
// ...sometime later
session.pause();
You can also tell the session which output – live or capture - to play / pause. By default, play will start rendering the live output and pause will pause rendering all outputs.
Using the examples above, here's a complete example of the minimal Camera Kit Web SDK integration:
import { boostrapCameraKit, createMediaStreamSource } from "@snap/camera-kit";
(async function main() {
const apiToken = "API Token value copied from the SnapKit developer portal";
const cameraKit = await bootstrapCameraKit({ apiToken });
const canvas = document.getElementById("my-canvas");
const session = await cameraKit.createSession(canvas);
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const source = createMediaStreamSource(stream, {
transform: Transform2D.MirrorX,
cameraType: "front",
});
session.setSource(source);
const lens = await cameraKit.lensRepository.loadLens("A lens ID found in the Camera Kit Portal", "A lens group ID");
await session.applyLens(lens);
await session.play();
console.log("Lens rendering has started!");
})();
Camera Kit Web SDK downloads an executable WebAssembly file containing the Lens rendering engine. This file is served from an optimized CDN. If you have a Content Security Policy in place on your page, you'll likely need to make some changes in order for Camera Kit to work.
connect-srcMust include https://*.snapchat.com, otherwise Camera Kit Web will fail to initialize.
script-srcMust include https://cf-st.sc-cdn.net/ blob: 'wasm-unsafe-eval'.
Note: Some older browser versions may not support the 'wasm-unsafe-eval' source value, and it may be necessary to use 'unsafe-eval' to allow Camera Kit's downloaded WebAssembly to run.
Generated using TypeDoc