HoshinoKoji/jsPsych
1
0
Fork 0
mirror of https://github.com/jspsych/jsPsych.git synced 2025-05-10 19:20:55 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

documentation for the initialize-camera plugin

Browse Source
This commit is contained in:
Josh de Leeuw 2022-07-12 11:10:55 -04:00
parent 1381f575f5
commit fd90e0e422
3 changed files with 138 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
docs/demos/jspsych-initialize-camera-demo1.html Normal file
View File

@ -0,0 +1,53 @@
<!DOCTYPE html>
<html>
<head>
<script src="https://unpkg.com/jspsych@7.2.3"></script>
<script src="https://unpkg.com/@jspsych/plugin-html-button-response@1.1.1"></script>
<script src="https://unpkg.com/@jspsych/plugin-initialize-camera@0.0.1"></script>
<link rel="stylesheet" href="https://unpkg.com/jspsych@7.2.3/css/jspsych.css">
<style>
.jspsych-btn {margin-bottom: 10px;}
</style>
</head>
<body></body>
<script>
var jsPsych = initJsPsych();
var start = {
type: jsPsychHtmlButtonResponse,
stimulus: '',
choices: ['Run demo']
};
var show_data = {
type: jsPsychHtmlButtonResponse,
stimulus: function() {
var trial_data = jsPsych.data.get().last(1).values();
var trial_json = JSON.stringify(trial_data, null, 2);
return `<p style="margin-bottom:0px;"><strong>Trial data:</strong></p>
<pre style="margin-top:0px;text-align:left;">${trial_json}</pre>`;
},
choices: ['Repeat demo']
};
var init_mic = {
type: jsPsychInitializeCamera
}
var trial_loop = {
timeline: [init_mic, show_data],
loop_function: function() {
return true;
}
};
if (typeof jsPsych !== "undefined") {
jsPsych.run([start, trial_loop]);
} else {
document.body.innerHTML = '<div style="text-align:center; margin-top:50%; transform:translate(0,-50%);">You must be online to view the plugin demo.</div>';
}
</script>
</html>

78
docs/plugins/initialize-camera.md Normal file
View File

@ -0,0 +1,78 @@
# initialize-camera
Current version: 0.0.1 [See version history](https://github.com/jspsych/jsPsych/blob/main/packages/plugin-initialize-camera/CHANGELOG.md).
This plugin asks the participant to grant permission to access a camera.
If multiple cameras are connected to the participant's device, then it allows the participant to pick which device to use.
Once access is granted for an experiment you do not need to get permission again.
Once the camera is selected with this plugin it can be accessed with [`jsPsych.pluginAPI.getCameraRecorder()`](../reference/jspsych-pluginAPI.md#getcamerarecorder).
!!! warning
When recording from a camera your experiment will need to be running over `https://` protocol. If you try to run the experiment locally using the `file://` protocol or over `http://` protocol you will not be able to access the microphone because of [potential security problems](https://blog.mozilla.org/webrtc/camera-microphone-require-https-in-firefox-68/).
## Parameters
In addition to the [parameters available in all plugins](../overview/plugins.md#parameters-available-in-all-plugins), this plugin accepts the following parameters. Parameters with a default value of *undefined* must be specified. Other parameters can be left unspecified if the default value is acceptable.
Parameter | Type | Default Value | Description
----------|------|---------------|------------
device_select_message | html string | `<p>Please select the camera you would like to use.</p>` | The message to display when the user is presented with a dropdown list of available devices.
button_label | sting | 'Use this camera.' | The label for the select button.
include_audio | bool | false | Set to `true` to include an audio track in the recordings.
width | int | null | Request a specific width for the recording. This is not a guarantee that this width will be used, as it depends on the capabilities of the participant's device. Learn more about `MediaRecorder` constraints [here](https://developer.mozilla.org/en-US/docs/Web/API/Media_Streams_API/Constraints#requesting_a_specific_value_for_a_setting).
height | int | null | Request a specific height for the recording. This is not a guarantee that this height will be used, as it depends on the capabilities of the participant's device. Learn more about `MediaRecorder` constraints [here](https://developer.mozilla.org/en-US/docs/Web/API/Media_Streams_API/Constraints#requesting_a_specific_value_for_a_setting).
mime_type | string | null | Set this to use a specific [MIME type](https://developer.mozilla.org/en-US/docs/Web/API/MediaRecorder/mimeType) for the recording. Set the entire type, e.g., `'video/mp4; codecs="avc1.424028, mp4a.40.2"'`.
## Data Generated
In addition to the [default data collected by all plugins](../overview/plugins.md#data-collected-by-all-plugins), this plugin collects the following data for each trial.
Name | Type | Value
-----|------|------
device_id | string | The [device ID](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo/deviceId) of the selected camera.
## Simulation Mode
This plugin does not yet support [simulation mode](../overview/simulation.md).
## Install
Using the CDN-hosted JavaScript file:
```js
<script src="https://unpkg.com/@jspsych/plugin-initialize-camera@0.0.1"></script>
```
Using the JavaScript file downloaded from a GitHub release dist archive:
```js
<script src="jspsych/plugin-initialize-camera.js"></script>
```
Using NPM:
```
npm install @jspsych/plugin-initialize-camera
```
```js
import initializeCamera from '@jspsych/plugin-initialize-camera';
```
## Examples
???+ example "Ask for camera permission"
=== "Code"
```javascript
var trial = {
type: jsPsychInitializeCamera
};
```
=== "Demo"
<div style="text-align:center;">
<iframe src="../../demos/jspsych-initialize-camera-demo1.html" width="90%;" height="600px;" frameBorder="0"></iframe>
</div>
<a target="_blank" rel="noopener noreferrer" href="../../demos/jspsych-initialize-camera-demo1.html">Open demo in new tab</a>

9
packages/plugin-initialize-camera/src/index.ts
View File

@ -3,27 +3,32 @@ import { JsPsych, JsPsychPlugin, ParameterType, TrialType } from "jspsych";
const info = <const>{ const info = <const>{
name: "initialize-camera", name: "initialize-camera",
parameters: { parameters: {
/** Message to display with the selection box */
device_select_message: { device_select_message: {
type: ParameterType.HTML_STRING, type: ParameterType.HTML_STRING,
default: `<p>Please select the camera you would like to use.</p>`, default: `<p>Please select the camera you would like to use.</p>`,
}, },
/** */ /** Label to use for the button that confirms selection */
button_label: { button_label: {
type: ParameterType.STRING, type: ParameterType.STRING,
default: "Use this camera", default: "Use this camera",
}, },
/** Set to `true` to include audio in the recording */
include_audio: { include_audio: {
type: ParameterType.BOOL, type: ParameterType.BOOL,
default: false, default: false,
}, },
/** Desired width of the camera stream */
width: { width: {
type: ParameterType.INT, type: ParameterType.INT,
default: null, default: null,
}, },
/** Desired height of the camera stream */
height: { height: {
type: ParameterType.INT, type: ParameterType.INT,
default: null, default: null,
}, },
/** MIME type of the recording. Set as a full string, e.g., 'video/webm; codecs="vp8, vorbis"'. */
mime_type: { mime_type: {
type: ParameterType.STRING, type: ParameterType.STRING,
default: null, default: null,
@ -36,7 +41,7 @@ type Info = typeof info;
/** /**
* **initialize-camera** * **initialize-camera**
* *
* jsPsych plugin for getting permission to initialize a camera * jsPsych plugin for getting permission to initialize a camera and setting properties of the recording.
* *
* @author Josh de Leeuw * @author Josh de Leeuw
* @see {@link https://www.jspsych.org/plugins/jspsych-initialize-camera/ initialize-camera plugin documentation on jspsych.org} * @see {@link https://www.jspsych.org/plugins/jspsych-initialize-camera/ initialize-camera plugin documentation on jspsych.org}