@bigbinary/neeto-media-recorder

Overview

@bigbinary/neeto-media-recorder is a React package that simplifies the media capturing process. It records the device's screen and audio and uploads the recording to AWS S3 storage using multipart uploads. Recordings are capped at 15 minutes, and the package works across plain web apps, Electron, and browser extensions.

It ships four sets of exports:

• Components — a MediaRecorder React component with built-in UI controls to start, pause/resume, discard, and restart a recording.
• Core — a singleton screenRecorder class that handles screen and audio capture, a getMultipartS3Uploader method, and a useMultipartS3UploadStatus React hook for tracking upload progress.
• Utilities — helpers such as generatePublicUrl to build a shareable link for a recording.
• Constants — recorder status, event, and error enums plus browser/extension detection helpers.

Used by

This package powers the screen recording experience across the neeto-record suite:

• neeto-record-web — the web app.
• neeto-record-electron — the desktop (Electron) app.
• neeto-record-chrome-extension — the browser extension.

Installation

yarn add @bigbinary/neeto-media-recorder

Usage

This package exports four different sets of functions and components.

1. Components
2. Utilities
3. Constants
4. Core

Components

• MediaRecorder

  The MediaRecorder react component capture's device screen and upload it to the AWS S3 storage. It contains UI controls to start, pause/resume, discard and restart a recording.

  You can import the components from @bigbinary/neeto-media-recorder.

  import { MediaRecorder } from "@bigbinary/neeto-media-recorder";
  

  MediaRecorder accepts three props:

  • onUploadComplete: This callback will get triggered once the uploading of the screen recording is completed.
  • onRecordingCreated: This callback will get triggered with the recording once it is created on the server, before any of it is uploaded.
  • onDiscard: This callback will get triggered whenever the user discard's the screen recording.
  • appName: This prop is used to set the application name which will be used in the permission denied messages. By default it will be set to globalProps.appName
  • mimeType: This prop is used to set the mime type of the recording. By default it will be set to video/webm;codecs=h264.

Utilities

You can import utilities from @bigbinary/neeto-media-recorder/utils.

import { generatePublicUrl } from "@bigbinary/neeto-media-recorder/utils";

• generatePublicUrl(recordingId, baseURL = window.location.origin)

  Can be used to generate the public URL for a screen recording by providing the recordingId and baseURL as arguments.

Constants

You can import constants from @bigbinary/neeto-media-recorder/constants.

import { UPLOAD_EVENT, UPLOAD_STATUS,... } from "@bigbinary/neeto-media-recorder/constants"

The available constants are:

const UPLOAD_EVENT = { onComplete: "onComplete" };

const UPLOAD_STATUS = {
  uploading: "uploading",
  completed: "completed",
  aborting: "aborting",
};

const SCREEN_RECORDER_STATUS = {
  media_aborted: "media_aborted",
  permission_denied: "permission_denied",
  no_specified_media_found: "no_specified_media_found",
  media_in_use: "media_in_use",
  invalid_media_constraints: "invalid_media_constraints",
  no_chrome_flags_set: "no_chrome_flags_set",
  recorder_error: "recorder_error",
  idle: "idle",
  acquiring_media: "acquiring_media",
  media_acquired: "media_acquired",
  restarting: "restarting",
  recording: "recording",
  stopping: "stopping",
  stopped: "stopped",
  paused: "paused",
};

const SCREEN_RECORDER_ERROR = {
  AbortError: "media_aborted",
  NotAllowedError: "permission_denied",
  NotFoundError: "no_specified_media_found",
  NotReadableError: "media_in_use",
  OverconstrainedError: "invalid_media_constraints",
  TypeError: "no_chrome_flags_set",
  None: "",
  NoRecorder: "recorder_error",
  UnSupportedBrowser: "unsupported_browser",
};

const SCREEN_RECORDER_EVENT = {
  onStart: "onStart",
  onStop: "onStop",
  onDiscard: "onDiscard",
  onDataAvailable: "onDataAvailable",
  onDiscardDuringCountdown: "onDiscardDuringCountdown",
  onRestart: "onRestart",
  onReUpload: "onReUpload",
  onReUploadFromDisk: "onReUploadFromDisk",
  onPause: "onPause",
  onResume: "onResume",
};

const HAS_CHROME_NAMESPACE = typeof chrome === "object";

const IS_EXTENSION = HAS_CHROME_NAMESPACE && isNotNil(chrome.extension);

const IS_SAFARI = platform.name === "Safari";

const IS_SAFARI_EXTENSION = IS_SAFARI && IS_EXTENSION;

Core

The @bigbinary/neeto-media-recorder/core contains a singleton class screenRecorder and getMultipartS3Uploader method and a react hook useMultipartS3UploadStatus.

import {
  screenRecorder,
  getMultipartS3Uploader,
  useMultipartS3UploadStatus,
} from "@bigbinary/neeto-media-recorder/core";

• screenRecorder

  It handles the screen and audio capturing process. The recordings are limited to 15 minutes. The various methods provided by screenRecorder are:

  • startRecording()

    Used to start screen recording.

  • stopRecording()

    Used to stop the current screen recording.

  • pauseRecording()

    Used to pause the current screen recording.

  • resumeRecording()

    Used to resume the screen recording.

  • discardRecording()

    Used to discard the current screen recording.

  • restartRecording()

    Used to discard the current screen recording and start a new one.

  • addCallback(event, callback)

    Used to add callback function for a specific screen recording event. The constant SCREEN_RECORDER_EVENT contains all the possible screen recording events.

    screenRecorder.addCallback(
      SCREEN_RECORDER_EVENT.onStart,
      handleStartRecording
    );
    

  • removeCallback(event, callback)

    Used to remove an already added callback by providing the event and callback to be removed.

    screenRecorder.removeCallback(
      SCREEN_RECORDER_EVENT.onStart,
      handleStartRecording
    );
    

  • removeAllCallbacksByEvent(event)

    Used to remove all callbacks associated with a particular event.

    screenRecorder.removeCallback(SCREEN_RECORDER_EVENT.onStart);
    

  • resetState()

    Used to reset the internal states of the screenRecorder to initial state.

  • revokePermissions()

    Used to revoke the browser permission to access the MediaRecorder api.

  • useRecorderStore()

    A zustand store which can be used know the screenRecorder status and error if any occurred inside a react component

  • setAudioConfiguration({ deviceId, ...}) Used to set the configuration for the audio device. Ref: https://w3c.github.io/mediacapture-main/#dom-mediatracksupportedconstraints

  • videoStream A write-only property which can be set by the client to set a video stream, once set the screenRecorder will not acquire a new video stream or request for permission to share the screen.

• getMultipartS3Uploader

  It returns an instance of MultipartS3Uploader which handles the upload of recorded screen data to AWS S3 storage.

  getMultipartS3Uploader optionally accepts an object with the following properties:

  • initialize

    When set to true, it will automatically initialize a new instance of MultipartS3Uploader and returns it. This is useful when you want to clean up the existing multipart uploader instance and create a new one.

  The MultipartS3Uploader instance returned by getMultipartS3Uploader provides the ability to upload the recording to S3 in multiple chunks. The methods provided by MultipartS3Uploader instance are:

  • setRecording(recordingId, uploadId)

    Used to initialize the multipartS3Uploader by providing the recordingId and uploadId. recordingId and uploadId can be obtained by creating a new recording in neeto-record-web.

  • push(data)

    Used to upload the recorded chunk to S3.

  • completeUpload()

    Once the recording is completed this method should be called to mark the recording as completed.

  • abortUpload()

    Used to discard the partially uploaded recording.

  • resetState()

    Used to reset the internal state of multipartS3Uploader to initial state.

  • addCallback(event, callback)

    Used to add callback function to a specific upload event. The constant UPLOAD_EVENT contains all the possible upload events.

  • removeCallback(event, callback)

    Used to remove an already added callback by providing the event and callback to be removed.

  • status

    A property which returns the current status of the MultipartS3Uploader instance.

  • mimeType

    A property which returns the mime type of the recording.

  • setMimeType(mimeType)

    Used to set the mime type of the recording.

• useMultipartS3UploadStatus

  A react hook which can be used to know the current status of the MultipartUploader instance. It rerenders the component whenever the status changes.

  const { status, isStatus } = useMultipartS3UploadStatus();
  // `status` can be one of the following:
  // UPLOAD_STATUS.uploading, UPLOAD_STATUS.completed, UPLOAD_STATUS.aborting, UPLOAD_STATUS.error, UPLOAD_STATUS.insufficient_data
  // `isStatus` is a function which can be used to check if the current status is one of the given statuses.
  isStatus(UPLOAD_STATUS.uploading); // will return true if the current status is UPLOAD_STATUS.uploading
  isStatus(UPLOAD_STATUS.uploading, UPLOAD_STATUS.completed); // will return true if the current status is either UPLOAD_STATUS.uploading or UPLOAD_STATUS.completed
  

Development

Install all the dependencies by executing the following command

yarn install

Using host application

1. Clone this repository.
2. Run yarn install to download the dependencies and setup the development environment.
3. Have a host application ready.
4. Run yarn watch to automatically transpile code as you save the file. You can run yarn build if you want to run the build only once.
5. In a different terminal, run yalc publish to publish the neeto-media-recorder to the local yalc store.
6. Run yalc add @bigbinary/neeto-media-recorder to install the neeto-media-recorder to the host application.
7. After making necessary changes to neeto-media-recorder, run yarn release to push the changes to the host application (assuming that you are in watch mode and the changes are bundled automatically). Restart webpack-dev-server in host if changes are not applied.
8. Video explanation on how to use yalc: https://www.youtube.com/watch?v=QBiYGP0Rhe0

Building and releasing.

The @bigbinary/neeto-neeto-media-recorder package gets published to NPM when we merge a PR with patch, minor or major label to the main branch. The patch label is used for bug fixes, minor label is used for new features and major label is used for breaking changes. You can checkout the Create and publish releases workflow in GitHub Actions to get a live update.

In case if you missed to add the label, you can manually publish the package. For that first you need to create a PR to update the version number in the package.json file and merge it to the main branch. After merging the PR, you need to create a new github release from main branch. Whenever a new release is created with a new version number, the github actions will automatically publish the built package to npm. You can checkout the Publish to npm workflow in GitHub Actions to get a live update.

Please note that before publishing the package, you need to verify the functionality in some of the neeto web-apps locally using yalc package manager.

Project integrations