@onirix/screen-capture

v1.3.0

Published

3 months ago

Onirix helper for take screen captures in experiences.

Downloads

0High
0Medium
0Low

frangaren

vifergo

onirix_development

Augmented reality WebAR Scree capture

Onirix Screen Capture

Onirix Screen Capture makes it easy to take screenshots and video recordings in AR experiences.

You should keep in mind that using this library ONLY with WebXR may generate a loss of performance and a white strip will also appear at the top of the navigation bar with your phone. Both issues are generated by Google and cannot be hidden or improved in any way.

If you need help take a look at our documentation.

Install

npm install @onirix/screen-capture

Include the dependency within the HTML head tag:

<head>
    <script src="https://unpkg.com/@onirix/[email protected]/dist/ox-screencapture-lib.umd.js"/>
</head>

As ESM modules:

import OxScreenCapturedLib from "https://unpkg.com/@onirix/[email protected]/dist/ox-screencapture-lib.esm.js";

Usage

To use this library, first, the Onirix Embed SDK must be initialize and pass it to the constructor. Onirix Screen Capture requires Onirix Embed SDK v.1.11.2 or higher.

import OnirixEmbedSDK from "https://unpkg.com/@onirix/[email protected]/dist/ox-embed-sdk.esm.js";
import OxScreenCaptureLib from "https://unpkg.com/@onirix/[email protected]/dist/ox-screencapture-lib.esm.js";


const embedSDK = new OnirixEmbedSDK();
embedSDK.connect();

const oxScreenCapture = new OxScreenCaptureLib(embedSDK);

Onirix Screen Capture can be configured by adding a second parameter to the constructor, the texts of the html elements.

Onirix Screen Capture provides a default user interface that displays a button for the user to capture. It also provides a component to preview the capture and methods to add images to the capture (watermarks, borders, emojis...).

If you need a more specific behaviour, you can not show the UI and use directly the methods described in OxScreenCaptureLib Class.

UI

The Onirix Screen Capture module provides you with a default UI to make you have to write as little code as possible.

Just call the addUI method and it will automatically add a control to trigger the screenshot. This screenshot will be displayed in a preview component where the user will be able to share it (if the browser is supported) or download it.

oxScreenCapture.addUI();

This method supports three parameters: video, preview and uIText:

video: If you want to add a button to record video, you must pass the video parameter as true. By default it is false.
preview: If you want to show a preview component after screenshot, you must pass the preview parameter as true. By default it is true. Preview component is only available for screenshots, not for video.
uIText: If you want to customize the texts of the buttons, you must pass a JSON object with the texts you want to change. By default it is null. Take a look at the section on how to particularize the default ui.

Let's see some examples:

// Default config: take screenshot and show preview component.
oxScreenCapture.addUI();

// Take screenshot and NOT show preview component.
oxScreenCapture.addUI(false, false);

// Record video and customize texts
oxScreenCapture.addUI(true, false, {
    label_video: 'Record video',
    recording_video: 'Stop recording',
});

Customize default UI

Customizing texts

When you use the default UI these are the texts that will be shown to the user:

| Text | Description | |------|-------------| | label_video | Text of the button to record video | | recording_video | Text of the button to stop recording video | | label_photo | Text of the button to take photo | | video_prefix | Prefix for the video file name | | photo_prefix | Prefix for the photo file name |

If you want to change any of these texts, you must pass a JSON object with the texts you want to change.

const CUSTOM_UI_TEXTS = {
    label_video: 'Start recording',
    recording_video: 'Stop recording',
    label_photo: 'Take a picture',
    video_prefix: 'recording_',
    photo_prefix: 'picture_',
};

oxScreenCapture.addUI(false, false, CUSTOM_UI_TEXTS);

This are the default texts:

const DEFAULT_UI_TEXTS = {
    label_video: 'Start video',
    recording_video: 'Press to stop',
    label_photo: 'Take photo',
    video_prefix: 'video_',
    photo_prefix: 'photo_',
}

Customizing CSS

The body has a css class called ox-screen-capture. And during screen capture or video recording the class ox-screen-capture--in--progress is added.

Default UI has ox-screen-capture__ui and the preview has a class called ox-screen-capture__preview. By employing these selectors, you will be able to customize the style of individual elements under them in the DOM.

To modify the look and feel of the UI controls and preview component you can add all the CSS you need to your experience through Onirix Studio's online code editor.

Let's change de preview's component background color:

.ox-screen-capture__preview > div {
    background-color: #FABADA;
}

Another small example of how to change text style:

.ox-screen-capture__text {
    color: #000;
    font-weight: bold;
    font-size: 18px;
}

You can make infinite changes to the interface by adding the appropriate CSS selectors. Through your browser's development tools you can explore the names of the css classes used by the library and add your own custom selectors and rules.

Overlays (watermarks)

Adding an image over the capture is very easy. You can use any image asset from your asset's library.

const OVERLAY_ASSET_OID = '<your_asset_oid>';

const embedSDK = new OnirixEmbedSDK();
embedSDK.connect();
const oxScreenCapture = new OxScreenCaptureLib(embedSDK);

embedSDK.subscribe(OnirixEmbedSDK.Events.SCENE_LOAD_END, async (params) => {
    await oxScreenCapture.setOverlay(OVERLAY_ASSET_OID, { bottom: 0, right: 0, top: 0, left: 0 }); 
});

oxScreenCapture.addUI();

The setOverlay method needs two parameters:

The oid of the asset you want to use as an overlay.
An object with the desired position and size settings. For more information see the detailed description of the method.

OxScreenCaptureLib Class

These are the methods offered by Onirix Screen Capture. With them you can create your own UI and take screenshots and record video in response to any action or need in your experience.

Constructor

constructor(embedSdk);

Take screenshot method

capturePhoto();

This method takes a screenshot of the experience and download a file with the image.

Take screenshot method with preview

capturePhotoPreview();

This method takes a screenshot of the experience and displays it in a preview popup with save and share options.

Start video recording method

captureVideoStart();

This method starts the screen recording.

Stop video recording method

captureVideoEnd(preview = true)

This method finish the screen recording and download the video. If preview is true the video will be loaded into preview component.

Add default UI

Show the default UI ready to take screenshots or record video.

addUI(video = false, preview = true, uiTexts = DEFAULT_UI_TEXTS)

Supports three parameters:

video: True if you want to record video, false if you want to take a screenshot.
preview: True if you want to show a preview component after screenshot.
uIText: A JSON object with the texts you want to change. Take a look at the section on how to particularize the default ui.

Remove default UI

Remove the default UI from document.

removeUI()

Remove preview component

Remove the preview component if exists.

removePreview()

Set overlay image

setOverlay(overlay, params?)

overlay can be any type of object supported by createImageBitmap, including img, canvas elements or Blob instances. It can also be the OID of a Studio asset that is of type image.
params is optional. If provided it must be an object with zero or more of the following attributes: top, bottom, left, right, height and width. All of them accept numeric values that will be considered pixels and will work similar to their CSS analogues. If top, bottom and height are present at the same time it will give an error. If left, right and width are present at the same time it will give an error.

Clear overlay image

clearOverlay()

Clears the current overlay. Captures made after calling this method will not show any overlay until an overlay is redefined.

Not enough?