Skip to content

Feat: add initialize-media-recording #3576

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Feat: add initialize-media-recording #3576

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 85 additions & 0 deletions docs/plugins/plugin-initialize-media-recording.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# plugin-initialize-media-recording

## Overview

The `plugin-initialize-media-recording` plugin integrates the functionality of both the `initialize-microphone` and `initialize-camera` jsPsych plugins into a single, unified trial. This makes it easier to manage media permissions when both microphone and camera are required, and provides a consistent interface for participants to select their preferred devices.

When either a microphone or camera (or both) are requested, the plugin:

- Prompts the participant to grant permission to access the corresponding device(s).
- Allows device selection if multiple input options are available.
- Provides customizable instructional messages and button labels.
- Offers support for configuring resolution constraints (min/max height/width).
- Supports choosing whether to include camera audio when initializing the camera.

Once initialized, the selected devices can be accessed later in the experiment using the appropriate plugins, such as:

- [`html-video-response`](https://www.jspsych.org/v8/plugins/html-video-response/)
- [`html-audio-response`](https://www.jspsych.org/v8/plugins/html-audio-response/)

## Loading (Note: these CDN resources don't currently exist... but maybe will eventually?)

Using the CDN-hosted JavaScript file:

```js
<script src="https://unpkg.com/@jspsych/plugin-initialize-media-recording@VERSION_HERE"></script>
```

Using the JavaScript file downloaded from a GitHub release dist archive:

```js
<script src="jspsych/plugin-initialize-media-recording.js"></script>
```

Using NPM:

```
npm install @jspsych/plugin-initialize-media-recording
```

```js
import jsPsychPluginInitializeMediaRecording from "@jspsych/plugin-initialize-media-recording";
```

## Compatibility

`plugin-initialize-media-recording` requires jsPsych v8.0.0 or later.

## Parameters

| Name | Type | Default | Description |
| --------------------------- | ----------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `initialize_microphone` | boolean | `false` | Whether to initialize the microphone. |
| `microphone_select_message` | HTML string | `<p>Please select the microphone you would like to use.</p>` | Message displayed above the microphone dropdown menu. |
| `microphone_button_label` | string | `"Use this microphone"` | Label for the microphone selection button. |
| `initialize_camera` | boolean | `false` | Whether to initialize the camera. |
| `camera_select_message` | HTML string | `<p>Please select the camera you would like to use.</p>` | Message displayed above the camera dropdown menu. |
| `camera_button_label` | string | `"Use this camera"` | Label for the camera selection button. |
| `include_camera_audio` | boolean | `false` | If true, includes audio when recording video with the camera. |
| `width` | integer | `null` | Requested width of the camera video stream. If `null`, the browser default is used. |
| `height` | integer | `null` | Requested height of the camera video stream. If `null`, the browser default is used. |
| `min_width` | integer | `640` | Minimum width of the video stream. |
| `max_width` | integer | `null` | Maximum width of the video stream. |
| `min_height` | integer | `400` | Minimum height of the video stream. |
| `max_height` | integer | `null` | Maximum height of the video stream. |
| `mime_type` | string | `null` | Preferred MIME type for recorded media (e.g., `"video/webm"` or `"video/x-matroska"`). If `null`, the browser chooses automatically. |
| `permission_reject_message` | string | `null` | Optional message to display if the participant denies camera or microphone access. |

## Data Generated

This plugin records the selected device IDs, which can be useful for diagnostics or ensuring consistent device usage in subsequent trials.

```json
{
"microphone_device_id": "default:12345abcde",
"camera_device_id": "facecamHD:98765zyxwv"
}
```

## Documentation

See [documentation](https://github.com/themusiclab/pose/tree/main/test/plugin-initialize-media-recording/README.md)

## Author / Citation

[Courtney B. Hilton](https://github.com/courtney-bryce-hilton)
55 changes: 55 additions & 0 deletions examples/jspsych-initialize-media-recording.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
<!DOCTYPE html>
<html>
<head>
<title>jsPsychPluginInitializeMediaRecording Example</title>
<script src="https://unpkg.com/jspsych@8"></script>
<!-- Load the published plugin package here, e.g.
<script src="https://unpkg.com/plugin-initialize-media-recording"></script>
<script src="../dist/index.global.js"></script> -->
<script src="../dist/index.browser.js"></script>
<script src="https://unpkg.com/@jspsych/[email protected]"></script>
<script src="https://unpkg.com/@jspsych/[email protected]"></script>
<script src="https://unpkg.com/@jspsych/[email protected]"></script>
<link rel="stylesheet" href="https://unpkg.com/jspsych@8/css/jspsych.css" />
</head>

<body></body>
<script>
const jsPsych = initJsPsych({
on_finish: () => {
jsPsych.data.displayData();
},
});

const recordVideo = {
type: jsPsychHtmlVideoResponse,
stimulus: "jsPsych is now recording video.",
recording_duration: 3500,
allow_playback: true,
};

const recordAudio = {
type: jsPsychHtmlAudioResponse,
stimulus: "<p>Now let's record audio.</p>",
recording_duration: 5000,
allow_playback: true,
};

// **⚠️ Note:** To use this plugin, your experiment must be served over HTTPS.
// Browsers block access to camera and microphone devices when served over HTTP or `file://` protocols due to security restrictions.
// See https://blog.mozilla.org/webrtc/camera-microphone-require-https-in-firefox-68/ for details.
// E.G., IF YOU WANT TO RUN THIS LOCALLY:
// cd /path/to/plugin-directory
// python -m http.server 8000
// in your browser: http://localhost:8000/examples/index.html
const initialiseMedia = {
type: jsPsychPluginInitializeMediaRecording,
initialize_camera: true,
initialize_microphone: true,
permission_reject_message:
"Thank you for participating; we noticed you've declined audio/video access, which is essential to proceed. Please update your settings to allow these permissions and restart the experiment if you wish to continue.",
};

jsPsych.run([initialiseMedia, recordVideo, recordAudio]);
</script>
</html>
41 changes: 41 additions & 0 deletions packages/plugin-initialize-media-recording/CITATION.cff
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
- family-names: "Courtney B. Hilton" # Replace with last name
given-names: "Courtney B. Hilton" # Replace with first name
name-particle: "Courtney B. Hilton" # Replace with name particle(s)
orcid: "https://orcid.org/0000-0000-0000-0000" # Replace with ORCID
# More authors can be listed here in the same format as above
contact: # Contact person for this extension
- family-names: "Courtney B. Hilton"
given-names: "Courtney B. Hilton"
email: "{email}" # Replace with contact person's email
orcid: "https://orcid.org/0000-0000-0000-0000" # Replace with contact person's ORCID
title: "jsPsychPluginInitializeMediaRecording"
version: 0.0.0
doi: 10.5281/zenodo.1234 # Replace with DOI
date-released: 2000-01-01
url: "{softwareUrl}" # Replace with URL to this extension

# If you wish to cite a paper on this extension instead, you can use the following template:
preferred-citation:
authors:
- family-names: "Courtney B. Hilton"
given-names: "Courtney B. Hilton"
name-particle: "Courtney B. Hilton"
orcid: "https://orcid.org/0000-0000-0000-0000"
# More authors can be listed here in the same format as above
date-published: 2023-05-11
doi: 10.21105/joss.12345
issn: 1234-5678
issue: 01
journal: Journal for Open Source Software
publisher:
name: Open Journals
start: 0001
title: "{title}"
type: article # Other options include: book, pamphlet, conference-paper...
url: "{linkToPublicationInJournal}"
volume: 1

# More information on the preffered-citation CFF format can be found at https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files#citing-something-other-than-software
85 changes: 85 additions & 0 deletions packages/plugin-initialize-media-recording/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# plugin-initialize-media-recording

## Overview

The `plugin-initialize-media-recording` plugin integrates the functionality of both the `initialize-microphone` and `initialize-camera` jsPsych plugins into a single, unified trial. This makes it easier to manage media permissions when both microphone and camera are required, and provides a consistent interface for participants to select their preferred devices.

When either a microphone or camera (or both) are requested, the plugin:

- Prompts the participant to grant permission to access the corresponding device(s).
- Allows device selection if multiple input options are available.
- Provides customizable instructional messages and button labels.
- Offers support for configuring resolution constraints (min/max height/width).
- Supports choosing whether to include camera audio when initializing the camera.

Once initialized, the selected devices can be accessed later in the experiment using the appropriate plugins, such as:

- [`html-video-response`](https://www.jspsych.org/v8/plugins/html-video-response/)
- [`html-audio-response`](https://www.jspsych.org/v8/plugins/html-audio-response/)

## Loading (Note: these CDN resources don't currently exist... but maybe will eventually?)

Using the CDN-hosted JavaScript file:

```js
<script src="https://unpkg.com/@jspsych/plugin-initialize-media-recording@VERSION_HERE"></script>
```

Using the JavaScript file downloaded from a GitHub release dist archive:

```js
<script src="jspsych/plugin-initialize-media-recording.js"></script>
```

Using NPM:

```
npm install @jspsych/plugin-initialize-media-recording
```

```js
import jsPsychPluginInitializeMediaRecording from "@jspsych/plugin-initialize-media-recording";
```

## Compatibility

`plugin-initialize-media-recording` requires jsPsych v8.0.0 or later.

## Parameters

| Name | Type | Default | Description |
| --------------------------- | ----------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `initialize_microphone` | boolean | `false` | Whether to initialize the microphone. |
| `microphone_select_message` | HTML string | `<p>Please select the microphone you would like to use.</p>` | Message displayed above the microphone dropdown menu. |
| `microphone_button_label` | string | `"Use this microphone"` | Label for the microphone selection button. |
| `initialize_camera` | boolean | `false` | Whether to initialize the camera. |
| `camera_select_message` | HTML string | `<p>Please select the camera you would like to use.</p>` | Message displayed above the camera dropdown menu. |
| `camera_button_label` | string | `"Use this camera"` | Label for the camera selection button. |
| `include_camera_audio` | boolean | `false` | If true, includes audio when recording video with the camera. |
| `width` | integer | `null` | Requested width of the camera video stream. If `null`, the browser default is used. |
| `height` | integer | `null` | Requested height of the camera video stream. If `null`, the browser default is used. |
| `min_width` | integer | `640` | Minimum width of the video stream. |
| `max_width` | integer | `null` | Maximum width of the video stream. |
| `min_height` | integer | `400` | Minimum height of the video stream. |
| `max_height` | integer | `null` | Maximum height of the video stream. |
| `mime_type` | string | `null` | Preferred MIME type for recorded media (e.g., `"video/webm"` or `"video/x-matroska"`). If `null`, the browser chooses automatically. |
| `permission_reject_message` | string | `null` | Optional message to display if the participant denies camera or microphone access. |

## Data

This plugin records the selected device IDs, which can be useful for diagnostics or ensuring consistent device usage in subsequent trials.

```json
{
"microphone_device_id": "default:12345abcde",
"camera_device_id": "facecamHD:98765zyxwv"
}
```

## Documentation

See [documentation](https://github.com/themusiclab/pose/tree/main/test/plugin-initialize-media-recording/README.md)

## Author / Citation

[Courtney B. Hilton](https://github.com/courtney-bryce-hilton)
Loading