Add new consent template and optional choice for exp-lookit-images-audio

This release adds new options; no changes are required to existing studies to update:

• exp-lookit-video-consent now offers a new template consent_005, which has substantially clarified text

• exp-lookit-images-audio now has a choiceAllowed parameter to separate allowing and requiring a choice of an image

Also includes minor updates to docs.

Remove deprecated frames

This release forms a foundation for further development by removing frames that have known issues and that should be replaced by other more robust components. To take advantage of future updates users will need to replace any uses of the frames below.

Removed frames

This release removes the following deprecated frames:

• exp-lookit-composite-video-trial
• exp-lookit-preferential-looking
• exp-video-preview
• exp-video-preview-explanation
• exp-lookit-story-page
• exp-lookit-dialogue-page
• exp-lookit-geometry-alternation
• exp-lookit-geometry-alternation-open
• exp-exit-survey (used only by physics study - NOT exp-lookit-exit-survey)
• exp-video-consent (used only by physics study - NOT exp-lookit-video-consent)
• pref-phys randomizer

For details on how to replace the exp-composite-video-trial, exp-lookit-preferential-looking, exp-lookit-geometry-alternation*, exp-lookit-story-page, and exp-lookit-dialogue-page frame types, please see the documentation. For details on how to replace the exp-video-preview and exp-video-preview-explanation frames, please see this walkthrough in the docs.

Minor updates

• Introduces the parameter requireWatchOrRead for the exp-lookit-instructions-video frame, allowing the user to make watching the video optional to use for e.g. debriefing

Sphinx docs

This release moves all documentation for the experiment runner over to this repository rather than the docs subrepo. It does NOT affect how the frames work if you are a researcher using the experiment runner!

Documentation can now be found at https://lookit.readthedocs.io/projects/frameplayer/. Docs for versions <1.3.1 are still available here.

Bugfixes

Added frames for basic implementation of infant-controlled trials:

• exp-lookit-images-audio-infant-control
• exp-lookit-video-infant-control

Deprecate frames:

• exp-lookit-composite-video-trial
• exp-lookit-preferential-looking

This frame is still available, but it has known issues with respect to video timing and will not be available past release 2.x. Users are encouraged to switch to using exp-lookit-video and exp-lookit-calibration instead.

Minor fixes/updates:

• bump lodash from 4.17.13 -> 4.17.19 (security update)
• throw error during parsing if frame ID is invalid (e.g. has underscores in it), which would lead to missing video files
• exp-lookit-stimuli-preview: make video recording optional
• exp-lookit-video-assent: fix display on small screens & make playing audio upon load more reliable
• pref-phys randomizer: fix to use exp-lookit-composite-video-trial frame
• exp-lookit-exit-survey: scroll to top of debriefing when leaving exit survey
• exp-lookit-video: fix for correct application of backgroundColor & adjust text color accordingly. Fixes "white bars" when video should be maximized with dark background. Allow unpausing from exp-lookit-video even if no pauseKey is selected in case participant paused by leaving fullscreen mode
• exp-lookit-start-recording, exp-lookit-stop-recording: fix for correct application of backgroundColor & adjust text color accordingly. If neither image nor video given for start/stop recording frame, just don't display
• exp-lookit-images-audio: store which audio file was played

Add support for protocol generator Javascript function

This release adds support for defining a "protocol generator" function on Lookit (soon to be released) rather than providing a JSON protocol specification.

If you define a protocol generator on Lookit, you will need to update the experiment runner version to at least this version for it to be used. If you are NOT using a protocol generator on Lookit, there is no harm in updating to this version, but it won't change anything.

Bugfix: exp-lookit-preferential-looking

Fixes audio not playing in Firefox in exp-lookit-preferential-looking test segment

Bugfix

• Fixes bug in exp-lookit-video frame where video and audio were counted as being complete upon starting (sorry!)
• Bump websocket version due to security advisory

v1.2.0: Wug

Experiment runner version (change on Lookit to use this release)

2aa08ee6132cd6351eed58abc2253368c14ad184

Changes in this release

• Frame documentation is now at https://lookit.github.io/lookit-frameplayer-docs/modules/frames.html . Links have been updated in the docs and wiki, but if you have this bookmarked you'll want to update it.

• Introduces several new frames:

  • exp-lookit-video - new more general frame replacing the old exp-lookit-video, which
    can still be used but is called exp-lookit-composite-video-trial
  • exp-lookit-calibration - for getting video of a child looking to several locations on
    the screen to calibrate for looking measures
  • exp-lookit-change-detection - for alternation paradigms, where two streams of images
    are displayed
  • exp-lookit-images-audio - general frame for showing images and playing audio, including
    for forced-choice trials
  • exp-lookit-start-recording - utility frame to start session recording
  • exp-lookit-stop-recording - utility frame to stop session recording
  • exp-looking-webcam-display - utility frame to display the participant's webcam (e.g.
    to give a break and let them re-check setup)

• Configuration frame exp-video-config now asks participants to try reloading the webcam,
  to avoid some recent problems in Firefox with permissions not being saved

• Consent frame now has participants review their video to ensure everything worked (they
  can re-record if not). An additional_segments parameter can be passed to add additional
  sections if required by your IRB and approved by Lookit. You have the option to add a
  section prompting all adults present to consent, in case your IRB is concerned about
  use of video with non-consented family members in the background. A new template consent_003
  has a combined "Benefits, risks, and payment" section instead of separating these.

• Session recording overrides individual-frame recording: if there is an active session
  recording in progress, no additional individual frame recording will be created. This avoids
  issues caused by accidentally creating overlapping session and individual-frame recordings.

• frameDuration is recorded on all frames as a convenience for checking how long the frame was
  without calculating it from event data.

• videoId and pipeId are recorded on events only when starting recording, not on every
  single event thereafter, to reduce file size of data downloads

• Other bugfixes and housekeeping:

  • MANY dependency updates for security and functionality improvements
  • Do a better job detecting when participant leaves fullscreen mode and making the
    "return to fullscreen" button visible
  • Leave fullscreen mode upon ctrl-X/F1

• The following frames are deprecated and will not be included in release 2.x.
  These are all bespoke frames for specific studies - if you use them, you can continue to
  use them, but won't be able to update past release 2.x without replacing them:

  exp-exit-survey
exp-lookit-dialogue-page
exp-lookit-geometry-alternation
exp-lookit-geometry-alternation-open
exp-lookit-preview-explanation
exp-lookit-story-page
exp-video-consent
exp-video-preview

Update guide

1. If you currently use an exp-lookit-video frame, change the kind of that frame in your
   study protocol to exp-lookit-composite-video-trial and it will continue to work as expected.

2. IF you currently use the videoId or pipeId fields in the event data you download, adapt
   your analysis workflow as follows:

• If using videoId: look for this field in the most recent setupVideoRecorder event
• If using pipeId: look for this field in the most recent startRecording event
• If using sessionVideoId: look for this field in the most recent setupSessionVideoRecorder event
• If using sessionPipeId: look for this field in the most recent startSessionRecording event