@ccp-eva/media-recorder

v2.1.1

Published

2 years ago

Utility functions for WebRTC to recrod (and upload) a webcam stream.

Downloads

0High
0Medium
0Low

kalaschnik

WebRTC Camera Webcam Audio Upload PHP

Media Recorder · `mRec` ·

An unobtrusive and DOM-independent JavaScript/npm package (UMD) providing utility functions to record a webcam stream using WebRTC.
🚀 CodePen Demo (under construction)

Support / Limitations

This package relies on the MediaRecorder API. Although it is widley supported (see https://caniuse.com/?search=mediarecorder), Apple’s Safari still disables that feature by default (see https://stackoverflow.com/questions/54344342/video-recording-for-safari-browser). That means, this package only works in non-iOS environments and for non-Safari browsers.

| | Firefox | Chromium(Chrome, Edge, etc) | Safari | |---|---|---|---| | Linux | 👍 | 👍 | 🚫 | | macOS | 👍 | 👍 | 👎 | | Windows | 👍 | 👍 | 👎 | | Android | 👍 | 👍 | 🚫 | | iOS | 👎 | 👎 | 👎 |

Installation

As of version 2, this package uses webpack to simplify development (see development section) and streamline the bundle output. That entails that this package now follows the UMD pattern, which allows it to be used within the following module systems: CJS, AMD, and ESM (check this article if you want to learn more about these systems).

The following snippets demonstrate how you can integrate this package into your project.

CDN (quick and easy)

Step 1 — Setup

Put the following line in the head section of your HTML file:

<!-- index.html -->
<script src="https://unpkg.com/@ccp-eva/media-recorder" async></script>

Notes

You can safely use the async attribute here, as the required DOM components are included in the js file. You can also put that line at the very end of your body if you feel like it
This line automatically resolves to the latest version (try it in your browser: https://unpkg.com/@ccp-eva/media-recorder and observe the URL). Yet, if you need a specific version, you can browse available versions on npm. Knowing a valid version tag, you can specify an explicit version as such: https://unpkg.com/@ccp-eva/[email protected] (legacy version)
You can also download the JavaScript file and run it without needing an internet connection

Step 2 — Usage

Inserting the script under step 1 will add a global(!) property named: mrec to your window object. Thus, you can access the utility functions/components by prepending them with mrec (see what functions are available here).

Examples

HTML

<!-- index.html -->
<button id="toggle-btn" onclick="mrec.toggleModal()"></button>
<!-- OR -->
<button id="toggle-btn" onclick="window.mrec.toggleModal()"></button>

Similarily you may also use JavaScript to attach event listeners:

JavaScript

// index.js
const toggleButton = document.getElementById('toggle-btn');
toggleButton.addEventListener('click', mrec.toggleModal);

npm

Step 1 — Setup

npm install @ccp-eva/media-recorder

Step 2 — Usage

In order to use npm packages in your browser you need a bundler. The following example uses webpack.

npm init -y
npm i -D webpack webpack webpack-cli

Assuming your index.js is in a src folder, you can use ESM syntax to import components as such:

// src/index.js

// named import for a single or multiple components
// import { toggleModal } from '@ccp-eva/media-recorder'

// import all components
import * as mrec from '@ccp-eva/media-recorder';

// execute toggleModal() function
mrec.toggleModal();

Assuming your index.html is in a dist folder and contains:

<!-- dist/index.html -->
<html lang="en">
  <head>
    <script src="./main.js" async></script>
  </head>
  <body></body>
</html>

Now you should have the following file structure:

my-project
|- /dist
  |- index.html
|- /src
  |- index.js
|- package.json

This file structure uses webpack defaults. Thus, if can run:

npx webpack

webpack will create a main.js within the dist directory. If you now open the index.html you will see the empty modal window.

Functions Overview

Regardless of how you install the package, you can use the following utility functions:

| function | parameter | type | description | | -------- | --------- | ---- | ----------- |

| Utility Function(signature:default value)? = optional ! = required parameter | Description | |---|---| | injectShell() | Injecting HTML & CSS for the modal UI (you may never need to call this function) | | logMediaDevices(showDeviceKind?:true, showDeviceLabel?:true, showDeviceId?:false) | Will console.log device type, label and ID | | modalContent(htmlContent?:'<h1>Hi</h1>', backgroundColor?:'deeppink') | Set the modal content: The first parameter accepts html as a string. The second parameter defines the background color of the modal.Example: modalContent("<h1>Hello</h1>"). You can also pass the predefined strings: #video-preview or #video-playback to load the corresponding video elements.Note: Calling modalContent() always opens the modal afterwards. | | toggleModal() | show/hide the modal UI (use modalContent before to set any content) | | openVideoPreview() | Opens the modal with the video stream by calling implicitly modalContent('#video-preview') | | openVideoPlayback() | Opens the modal off the recorded video by calling implicitly modalContent('#video-playback') | | startStream({constraintObject}?:[1]) | starts a webcam stream w/o recording it | | stopStream() | stops all active webcam streams | | startRecorder({constraintObject}?:[1]) | starts a webcam stream (if not active) and starts recording | | stopRecorder() | stops the recording, creates a video file, stops the webcam stream | | uploadVideo("filename:") | Parameters: string (optional)Uploads the recording using given parameter "filename". If no argument is provided, the filename defaults to a ISO 8601 timestamp. See notes about uploading. |

[1] startStream({obj}) and startRecorder({obj}) allow you tp pass a MediaTrackConstraints Object as an argument, which allows you define what media tracks (e.g., video, audio) should be recorded, and how they should be recorded (e.g., resolution, fps, facing mode). When providing no arguments, both functions default to:

{
  audio: true,
  video: { facingMode: 'user' },
  frameRate: 15,
}

See https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia for examples you can provide to both functions.

Endpoint for Uploading

For local development, I recommend PHP Server for VS Code).

You need to have a server-side endpoint for this function. Right now, this function only works for PHP.

upload_video.php

$target_path = "uploads/" . basename($_FILES["vidfile"]["name"] . ".webm");
move_uploaded_file($_FILES["vidfile"]["tmp_name"], $target_path );

php.ini

Change php’s post_max_size and upload_max_filesize accordingly in your php.ini, if your video is likely to exceed the default 2MB limitation:

post_max_size = 105M
upload_max_filesize = 100M

Development

Local Development

git clone [email protected]:ccp-eva/media-recorder.git
npm install
npm start (opens a dev server on localhost:8080)
You may need to navigate to example.html

Build for Production

git clone [email protected]:ccp-eva/media-recorder.git
npm install
npm run build
Upload the contents of the dist folder to your webserver

Contributions

This project uses the ESLint/AirBnb linter styles (see .eslintrc.yml) and prettier as formatter (see .prettierrc). As there is no CI hook for linting, it would be great if you conform to these styles/linters.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Media Recorder · mRec ·

🚀 CodePen Demo (under construction)

Support / Limitations

Installation

CDN (quick and easy)

Step 1 — Setup

Step 2 — Usage

Examples

HTML

JavaScript

npm

Step 1 — Setup

Step 2 — Usage

Functions Overview

Endpoint for Uploading

Development

Local Development

Build for Production

Contributions

Media Recorder · `mRec` ·