@snap/camera-kit 0.7.0

package/docs/md/classes/CameraKitSession.md

@@ -0,0 +1,359 @@
+[CameraKit Web SDK - v0.7.0-alpha.1](../README.md) / [Exports](../modules.md) / CameraKitSession
+
+# Class: CameraKitSession
+
+A CameraKitSession represents a single rendering pipeline connecting an input media source to output `<canvas>`
+elements. When a Lens is applied to the session, CameraKit uses the Lens to transform the input media into rendered
+output.
+
+CameraKitSession is the primary object that applications interact with when integrating the CameraKit SDK.
+
+A CameraKitSession instance is obtained by calling [createSession](CameraKit.md#createsession).
+
+**`Example`**
+
+```ts
+const cameraKit = await bootstrapCameraKit(config)
+const session = await cameraKit.createSession()
+```
+
+## Table of contents
+
+### Properties
+
+- [output](CameraKitSession.md#output)
+- [playing](CameraKitSession.md#playing)
+- [events](CameraKitSession.md#events)
+- [metrics](CameraKitSession.md#metrics)
+- [keyboard](CameraKitSession.md#keyboard)
+
+### Methods
+
+- [applyLens](CameraKitSession.md#applylens)
+- [removeLens](CameraKitSession.md#removelens)
+- [play](CameraKitSession.md#play)
+- [pause](CameraKitSession.md#pause)
+- [mute](CameraKitSession.md#mute)
+- [unmute](CameraKitSession.md#unmute)
+- [setSource](CameraKitSession.md#setsource)
+- [setFPSLimit](CameraKitSession.md#setfpslimit)
+- [destroy](CameraKitSession.md#destroy)
+
+## Properties
+
+### output
+
+• `Readonly` **output**: `Object`
+
+CameraKitSession renders video output to a `<canvas>` element. In fact, each session contains two canvas outputs
+corresponding to the RenderTargets used by Lens creators, when using LensStudio to create a Lens.
+
+The `live` output renders content suitable for the Lens user (e.g. it may contain additional UI elements
+applicable only to the person applying the lens). The `capture` output renders content suitable for sharing with
+other users (e.g. sent to the other members of a video call, or saved to disk for sharing later).
+
+For many lenses, these outputs are identical – but each lens is free to render differently, based on its own
+use-case.
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `live` | `HTMLCanvasElement` |
+| `capture` | `HTMLCanvasElement` |
+
+___
+
+### playing
+
+• **playing**: ``false`` \| [`RenderTarget`](../modules.md#rendertarget)
+
+Indicates whether or not the session is currently rendering. If `false`, rendering is stopped. Otherwise the
+value indicates which output is being rendered.
+
+___
+
+### events
+
+• `Readonly` **events**: [`TypedEventTarget`](TypedEventTarget.md)<[`CameraKitSessionEvents`](../modules.md#camerakitsessionevents)\>
+
+Add event listeners here to handle events which occur during the CameraKitSession.
+
+**Note:** Applications may want to handle the `error` event, and check the contained error type -- if the type
+is [LensExecutionError](../modules.md#lensexecutionerror), this means the current lens was unable to render and CameraKit will automatically
+remove the lens.
+
+**`Example`**
+
+```ts
+cameraKitSession.events.addEventListener('error', ({ detail }) => {
+  if (detail.error.name === 'LensExecutionError') {
+    console.log(`Lens ${detail.lens.name} encountered an error and was removed. Please pick a different lens.`)
+  }
+})
+```
+
+___
+
+### metrics
+
+• `Readonly` **metrics**: [`LensPerformanceMetrics`](LensPerformanceMetrics.md)
+
+Use this to measure current lens performance.
+
+___
+
+### keyboard
+
+• `Readonly` **keyboard**: [`Keyboard`](../modules.md#keyboard)
+
+Use this to interact with lenses which require text input.
+
+## Methods
+
+### applyLens
+
+▸ **applyLens**(`lens`, `launchParams?`): `Promise`<`boolean`\>
+
+Apply a Lens to this session.
+
+This method will download (and cache) the Lens executable, and then use that Lens for rendering. If the session
+is currently playing, this will immediately update the rendered output. Otherwise, the new Lens will be used
+when session playback in resumed.
+
+Calling `applyLens` replaces any prior Lens – only one Lens is allowed at a time (per session).
+
+**NOTE**: Errors may occur after the Lens is applied. If the Lens encounters errors while rendering,
+Camera Kit will automatically remove the Lens from the session and emit a [LensExecutionError](../modules.md#lensexecutionerror) event.
+Applications may want to listen for this error and, for example,
+prevent the Lens from being selected again by the user.
+
+```ts
+session.events.addEventListener("error", ({ detail }) => {
+  if (detail.error.name === "LensExecutionError") {
+    preventFutureLensSelection(detail.lens);
+    showMessage("We're sorry, but the Lens you selected encountered an error. Please choose a different Lens.");
+  }
+});
+```
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `lens` | [`Lens`](../interfaces/Lens.md) | The Lens to apply to this session. |
+| `launchParams?` | [`LensLaunchParams`](../modules.md#lenslaunchparams) | - |
+
+#### Returns
+
+`Promise`<`boolean`\>
+
+A promise which can have the following results:
+1. Resolved with `true`: the lens has been applied.
+2. Resolved with `false`: the lens has not been applied, but no error occurred – this can happen if a
+subsequent call to `applyLens` interrupted the lens application.
+3. Rejected: the lens has not been applied because an error occurred. This can happen if:
+  - The lens ID cannot be found in the LensRepository (use LensRepository to load the lens before calling this
+    method)
+  - Lens content download fails, or the download of any required lens assets fails.
+  - An internal failure occurs in the Lens rendering engine when attempting to apply the lens.
+
+___
+
+### removeLens
+
+▸ **removeLens**(): `Promise`<`boolean`\>
+
+Remove a Lens from this session.
+
+When a Lens is removed, rendering continues if the session is playing. It will just render the session input
+directly to the outputs without any image processing.
+
+#### Returns
+
+`Promise`<`boolean`\>
+
+A promise which can have the following results:
+1. Resolved with `true`: the session's rendered output has no lens applied.
+2. Resolved with `false`: the current lens has been removed, but a subsequent call to `applyLens` means that the
+session's rendered output will still have a (new) lens applied.
+3. Rejected: the lens has failed to be removed. This can happen if an internal failure occurs in the Lens
+rendering engine when attempting to remove the lens.
+
+___
+
+### play
+
+▸ **play**(`target?`): `Promise`<`void`\>
+
+Start/resume session playback – LensCore will begin rendering frames to the output.
+
+If no source has been set for the session, calling `play()` will update the playing state, but no actual image
+processing will occur until `setSource()` is called.
+
+**`Example`**
+
+```ts
+const cameraKitSession = await cameraKit.createSession()
+await cameraKitSession.setSource(mySource)
+await cameraKitSession.play()
+
+// If you call `play` before `setSource`, the call to `play` will resolve but playback will only begin once a
+// media source has been set.
+```
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `target` | [`RenderTarget`](../modules.md#rendertarget) | `"live"` | Specify the [RenderTarget](../modules.md#rendertarget) to render. Defaults to the `live` RenderTarget. |
+
+#### Returns
+
+`Promise`<`void`\>
+
+Promise resolves when playback state has been updated. If no source has been set, this means `play` will
+resolve before any frames are processed -- but once a source is set, frames will immediately begin processing.
+
+___
+
+### pause
+
+▸ **pause**(`target?`): `Promise`<`void`\>
+
+Pause session playback – LensCore will stop rendering frames to the output.
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `target` | [`RenderTarget`](../modules.md#rendertarget) | `"live"` | Specify the RenderTarget to pause playback. May be either `'live'` or `'capture'`. Default is `'live'`. |
+
+#### Returns
+
+`Promise`<`void`\>
+
+Promise resolves when playback has stopped.
+
+___
+
+### mute
+
+▸ **mute**(`fade?`): `void`
+
+Mute all sounds (default SDK state is unmuted).
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `fade` | `boolean` | `false` | Do we want audio to fade out? |
+
+#### Returns
+
+`void`
+
+___
+
+### unmute
+
+▸ **unmute**(`fade?`): `void`
+
+Unmute all sounds.
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `fade` | `boolean` | `false` | Do we want audio to fade in? |
+
+#### Returns
+
+`void`
+
+___
+
+### setSource
+
+▸ **setSource**(`source`): `Promise`<[`CameraKitSource`](CameraKitSource.md)\>
+
+Set the media source for this session.
+
+Sessions may only have one source at a time - if `setSource` is called multiple times, subsequent calls replace
+the prior source. Setting the source does not trigger rendering (that’s done by `session.play()`). If the session
+is already playing, setting the source will immediately begin rendering the new source.
+
+The CameraKit SDK provides implementations for various common sources, which applications can create using the
+following functions:
+- [createUserMediaSource](../modules.md#createusermediasource)
+- [createMediaStreamSource](../modules.md#createmediastreamsource)
+- [createVideoSource](../modules.md#createvideosource)
+- [createImageSource](../modules.md#createimagesource)
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `source` | [`CameraKitSource`](CameraKitSource.md) | A CameraKitSource object representing input media (e.g. a webcam stream, video, or some other source of image data), which CameraKit will supply to Lenses in order for them to render effects on top of that source. |
+
+#### Returns
+
+`Promise`<[`CameraKitSource`](CameraKitSource.md)\>
+
+Promise is resolved when the source has successfully be set. If the session was already in the playing
+state, the Promise resolves when the first frame from the new source has been rendered. The resolved value is
+the [CameraKitSource](CameraKitSource.md) object attached to the session.
+
+▸ **setSource**(`source`, `options?`): `Promise`<[`CameraKitSource`](CameraKitSource.md)\>
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `source` | `HTMLVideoElement` \| `MediaStream` |
+| `options?` | `Partial`<[`CameraKitDeviceInfo`](../modules.md#camerakitdeviceinfo)\> |
+
+#### Returns
+
+`Promise`<[`CameraKitSource`](CameraKitSource.md)\>
+
+___
+
+### setFPSLimit
+
+▸ **setFPSLimit**(`fpsLimit`): `Promise`<`void`\>
+
+Set an FPS limit.
+
+This may be useful to reduce CPU/GPU resource usage by CameraKit if, for example, the input
+media source has a low FPS – CameraKit would then not try to render more frequently than the source produces
+new frames.
+
+This may also be useful to gracefully degrade performance in situations where lowering FPS is preferable over
+alternatives.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `fpsLimit` | `number` | A maximum FPS, rendering will not exceed this limit |
+
+#### Returns
+
+`Promise`<`void`\>
+
+Promise is resolved when the limit is successfully set.
+
+___
+
+### destroy
+
+▸ **destroy**(): `Promise`<`void`\>
+
+Destroy the session.
+
+The session will become inoperable. Frame processing stops, and any session-scoped graphical resources are freed.
+
+#### Returns
+
+`Promise`<`void`\>

package/docs/md/classes/CameraKitSource.md

@@ -0,0 +1,110 @@
+[CameraKit Web SDK - v0.7.0-alpha.1](../README.md) / [Exports](../modules.md) / CameraKitSource
+
+# Class: CameraKitSource
+
+This general-purpose class represents a source of media for a [CameraKitSession](CameraKitSession.md).
+
+When an instance is passed to [CameraKitSession.setSource](CameraKitSession.md#setsource), it will be "attached"
+to the session. Later it may be "detached" from the session.
+
+Passing a [CameraKitSourceSubscriber](../interfaces/CameraKitSourceSubscriber.md) to the constructor allows callers to specify behavior
+that will occur when the source is attached and detached. This can be used to e.g. update the render size.
+
+## Table of contents
+
+### Constructors
+
+- [constructor](CameraKitSource.md#constructor)
+
+### Methods
+
+- [copy](CameraKitSource.md#copy)
+- [setRenderSize](CameraKitSource.md#setrendersize)
+- [setTransform](CameraKitSource.md#settransform)
+
+## Constructors
+
+### constructor
+
+• **new CameraKitSource**(`sourceInfo`, `subscriber?`, `deviceInfo?`)
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `sourceInfo` | [`CameraKitSourceInfo`](../modules.md#camerakitsourceinfo) |
+| `subscriber` | [`CameraKitSourceSubscriber`](../interfaces/CameraKitSourceSubscriber.md) |
+| `deviceInfo` | `Partial`<[`CameraKitDeviceInfo`](../modules.md#camerakitdeviceinfo)\> |
+
+## Methods
+
+### copy
+
+▸ **copy**(`deviceInfo?`): [`CameraKitSource`](CameraKitSource.md)
+
+Make a copy of the source, sharing the same [CameraKitSourceSubscriber](../interfaces/CameraKitSourceSubscriber.md).
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `deviceInfo` | `Partial`<[`CameraKitDeviceInfo`](../modules.md#camerakitdeviceinfo)\> | Optionally provide new device info for the copy (e.g. to change the camera type). |
+
+#### Returns
+
+[`CameraKitSource`](CameraKitSource.md)
+
+The new [CameraKitSource](CameraKitSource.md)
+
+___
+
+### setRenderSize
+
+▸ **setRenderSize**(`width`, `height`): `Promise`<`void`\>
+
+Set the resolution used to render this source.
+
+It’s important to distinguish render size from display size. The size at which the output canvases are displayed
+on a web page is determined by the CSS of the page. It is distinct from the size at which LensCore renders
+Lenses. Performance is dominated by render size, while any display scaling can most often be thought of as free.
+
+If greater performance is required, a smaller render size may boost frame-rate. It does come at a cost, including
+loss of accuracy in various tracking and computer-vision algorithms (since they'll be operating on fewer pixels).
+
+The size of the Live and Capture [RenderTarget](../modules.md#rendertarget) is always the same.
+
+**`Todo`**
+
+Currently it's only valid to call `setRenderSize` after `CameraKitSession.play` has been called. This
+constraint should be removed, so callers don't have to understand the underlying LensCore state machine.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `width` | `number` | pixels |
+| `height` | `number` | pixels |
+
+#### Returns
+
+`Promise`<`void`\>
+
+Promise resolves when the render size has been successfully updated.
+
+___
+
+### setTransform
+
+▸ **setTransform**(`transform`): `Promise`<`void`\>
+
+Apply a 2D transformation to the source (e.g. translation, rotation, scale).
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `transform` | [`Transform2D`](Transform2D.md) | Specifies the 3x3 matrix describing the transformation. |
+
+#### Returns
+
+`Promise`<`void`\>

package/docs/md/classes/LensPerformanceMeasurement.md

@@ -0,0 +1,77 @@
+[CameraKit Web SDK - v0.7.0-alpha.1](../README.md) / [Exports](../modules.md) / LensPerformanceMeasurement
+
+# Class: LensPerformanceMeasurement
+
+Represents an ongoing measurement of rendering metrics.
+
+An instance of this class is obtained by calling [beginMeasurement](LensPerformanceMetrics.md#beginmeasurement). Then it may be
+used to record rendering performance metrics, reset measurement, or end the measurement.
+
+## Table of contents
+
+### Constructors
+
+- [constructor](LensPerformanceMeasurement.md#constructor)
+
+### Methods
+
+- [measure](LensPerformanceMeasurement.md#measure)
+- [reset](LensPerformanceMeasurement.md#reset)
+- [end](LensPerformanceMeasurement.md#end)
+
+## Constructors
+
+### constructor
+
+• **new LensPerformanceMeasurement**(`instances`)
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `instances` | `Set`<[`LensPerformanceMeasurement`](LensPerformanceMeasurement.md)\> |
+
+## Methods
+
+### measure
+
+▸ **measure**(): [`ComputedFrameMetrics`](../interfaces/ComputedFrameMetrics.md)
+
+Return a [ComputedFrameMetrics](../interfaces/ComputedFrameMetrics.md) object, containing lens performance metrics.
+
+This method may be called multiple times, each time reporting values computed since the time when this instance
+was created.
+
+#### Returns
+
+[`ComputedFrameMetrics`](../interfaces/ComputedFrameMetrics.md)
+
+___
+
+### reset
+
+▸ **reset**(): `void`
+
+Reset the measured perforamance statistics (averages, std deviations). This is equivalent to using
+[beginMeasurement](LensPerformanceMetrics.md#beginmeasurement) to create a new LensPerformanceMeasurement instance, but may be
+more convenient.
+
+#### Returns
+
+`void`
+
+___
+
+### end
+
+▸ **end**(): `void`
+
+Stop measuring performance statistics.
+
+This instance will not be garbage collected until this method is called. Therefore it is important to call this
+method at the appropriate time to avoid leaking memory -- particularly if your application creates many
+LensPerformanceMeasurement instances.
+
+#### Returns
+
+`void`

package/docs/md/classes/LensPerformanceMetrics.md

@@ -0,0 +1,37 @@
+[CameraKit Web SDK - v0.7.0-alpha.1](../README.md) / [Exports](../modules.md) / LensPerformanceMetrics
+
+# Class: LensPerformanceMetrics
+
+Use to measure lens rendering performance.
+
+The [beginMeasurement](LensPerformanceMetrics.md#beginmeasurement) method is used to start measuring rendering performance. After
+a measurement has begun, performance metrics can be read using [LensPerformanceMeasurement](LensPerformanceMeasurement.md).
+
+**`Example`**
+
+```ts
+const measurement = cameraKitSession.metrics.beginMeasurement()
+// some time later
+console.log(measurement.measure())
+```
+
+## Table of contents
+
+### Methods
+
+- [beginMeasurement](LensPerformanceMetrics.md#beginmeasurement)
+
+## Methods
+
+### beginMeasurement
+
+▸ **beginMeasurement**(): [`LensPerformanceMeasurement`](LensPerformanceMeasurement.md)
+
+Begin a measurement window, during which time rendering metrics will be gathered.
+
+#### Returns
+
+[`LensPerformanceMeasurement`](LensPerformanceMeasurement.md)
+
+A [LensPerformanceMeasurement](LensPerformanceMeasurement.md) representing an ongoing measurement of aggregated rendering
+metrics, from which specific metrics can be obtained.