add guides for updating from deprecated frame types

app/components/exp-lookit-calibration/doc.rst

@@ -177,4 +177,146 @@ The events recorded specifically by this frame are:
 :startCalibration: Beginning of each calibration segment
 
     :location: [String]
-        The location of calibration image/video, relative to child: 'left', 'right', or 'center'
+        The location of calibration image/video, relative to child: 'left', 'right', or 'center'
+
+
+Updating from deprecated frames
+---------------------------------
+
+.. _update_composite_to_calibration:
+
+Updating an exp-lookit-composite-video-trial (or the old exp-lookit-video) frame
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Your ``exp-lookit-composite-video-trial`` frame may have included a calibration phase. If so (``calibrationLength`` set to >0),
+then you can replace that phase with an ``exp-lookit-calibration`` frame.
+
+Consider the following ``exp-lookit-composite-video-trial`` frame which includes calibration:
+
+.. code:: javascript
+
+    "sample-physics-trial-2": {
+        "kind": "exp-lookit-composite-video-trial",
+        "baseDir": "https://www.mit.edu/~kimscott/placeholderstimuli/",
+        "audioTypes": [
+            "ogg",
+            "mp3"
+        ],
+        "videoTypes": [
+            "webm",
+            "mp4"
+        ],
+
+        "attnSources": "attentiongrabber",
+        "announceLength": 2,
+        "audioSources": "video_02",
+
+        "calibrationLength": 3000,
+        "calibrationAudioSources": "chimes",
+        "calibrationVideoSources": "attentiongrabber"
+
+        "introSources": "cropped_block",
+
+        "sources": "example_pairing",
+        "altSources": "example_pairing",
+        "testCount": 2,
+        "musicSources": "music_02",
+
+        "pauseAudio": "pause",
+        "unpauseAudio": "return_after_pause",
+
+    }
+
+To create the corresponding ``exp-lookit-calibration`` frame, you will change the ``kind`` to ``exp-lookit-calibration``,
+rename ``calibrationAudioSources`` and ``calibrationVideoSources``, and remove the irrelevant fields, like this:
+
+.. code:: javascript
+
+    "sample-physics-calibration": {
+        "kind": "exp-lookit-calibration", <-- change the "kind"
+        "baseDir": "https://www.mit.edu/~kimscott/placeholderstimuli/", <-- leave this the same
+        "audioTypes": [ <-- leave this the same
+            "ogg",
+            "mp3"
+        ],
+        "videoTypes": [ <-- leave this the same
+            "webm",
+            "mp4"
+        ],
+
+        "calibrationLength": 3000,  <-- leave this the same
+        "calibrationAudio": "chimes",  <-- just rename from "calibrationAudioSources"
+        "calibrationVideo": "attentiongrabber"  <-- just rename from "calibrationVideoSources"
+    }
+
+If your old frame defined ``calibrationPositions``, you can leave that the same too. Otherwise this will continue to
+use the default of ``['center', 'left', 'right', 'center']``.
+
+The one difference is that you will not yet be able to pause the study during the calibration phase.
+
+.. _update_preferential_to_calibration:
+
+Updating an exp-lookit-preferential-looking frame
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Your ``exp-lookit-preferential-looking`` frame may have included a calibration phase. If so (``calibrationLength`` set to >0),
+then you can replace that phase with an ``exp-lookit-calibration`` frame.
+
+Consider the following ``exp-lookit-preferential-looking`` frame which includes calibration:
+
+.. code:: javascript
+
+    "sample-trial": {
+        "kind": "exp-lookit-preferential-looking",
+        "baseDir": "https://s3.amazonaws.com/lookitcontents/labelsconcepts/",
+        "audioTypes": [
+            "ogg",
+            "mp3"
+        ],
+        "videoTypes": [
+            "webm",
+            "mp4"
+        ],
+
+        "announcementVideo": "attentiongrabber",
+        "announcementAudio": "video_02",
+        "announcementLength": 2,
+
+        "introVideo": "cropped_book",
+
+        "calibrationLength": 0,
+        "calibrationAudio": "chimes",
+        "calibrationVideo": "attentiongrabber",
+
+        "pauseAudio": "pause",
+        "unpauseAudio": "return_after_pause",
+
+        "testAudio": "400Hz_tones",
+        "loopTestAudio": false,
+        "leftImage": "stapler_test_02.jpg",
+        "rightImage": "novel_02.jpg",
+        "testLength": 8,
+    }
+
+You can change it to an ``exp-lookit-calibration`` frame just by changing the ``kind`` and removing the irrelevant parameters:
+
+.. code:: javascript
+
+    "sample-trial": {
+        "kind": "exp-lookit-calibration", <-- change the "kind"
+        "baseDir": "https://s3.amazonaws.com/lookitcontents/labelsconcepts/", <-- leave this the same
+        "audioTypes": [ <-- leave this the same
+            "ogg",
+            "mp3"
+        ],
+        "videoTypes": [ <-- leave this the same
+            "webm",
+            "mp4"
+        ],
+
+        "calibrationLength": 0, <-- leave this the same
+        "calibrationAudio": "chimes", <-- leave this the same
+        "calibrationVideo": "attentiongrabber" <-- leave this the same
+    }
+
+The one difference is that you will not yet be able to pause the study during the calibration phase.

app/components/exp-lookit-composite-video-trial/component.js

@@ -80,7 +80,6 @@ let {
 ```json
         "sample-intermodal-trial-2": {
             "kind": "exp-lookit-composite-video-trial",
-            "isLast": false,
             "baseDir": "https://s3.amazonaws.com/lookitcontents/intermodal/",
             "sources": "sbs_ramp_down_up_apple_c1_b1_NN",
             "testCount": 2,

app/components/exp-lookit-composite-video-trial/doc.rst

@@ -4,8 +4,19 @@ exp-lookit-composite-video-trial
 This frame is deprecated and will not be included in release 2.x.
 Please see `the old docs <https://lookit.github.io/lookit-frameplayer-docs/releases/v1.3.1/classes/Exp-lookit-composite-video-trial.html>`__.
 
+
+
 Consider instead
 ------------------
 
-- :ref:`exp-lookit-video` to play a video and optional audio, with more configurability & better timing precision for the recording
-- :ref:`exp-lookit-calibration` to show a calibration stimulus at specific locations, again with more configurability and better timing precision
+- :ref:`exp-lookit-video` to play a video and optional audio, with more configurability & better timing precision for the recording. (:ref:`Update guide <update_composite_to_video>`)
+- :ref:`exp-lookit-calibration` to show a calibration stimulus at specific locations, again with more configurability and better timing precision (:ref:`Update guide <update_composite_to_calibration>`)
+
+There are up to four phases in the exp-lookit-composite-video-trial frame, each of which will become a new frame:
+
+- An "announcement" with audio and a small attention-getter video. If using, turn this into a separate exp-lookit-video frame.
+- Calibration where a video is shown at various locations. If using, turn this into an exp-lookit-calibration frame.
+- An "intro" video which is played once through.  If using, turn this into a separate exp-lookit-video frame.
+- A test video which can be played N times or for N seconds, along with optional audio. If using, turn this into a separate exp-lookit-video frame.
+
+

app/components/exp-lookit-dialogue-page/doc.rst

@@ -7,4 +7,4 @@ Please see `the old docs <https://lookit.github.io/lookit-frameplayer-docs/relea
 Consider instead
 ------------------
 
-- :ref:`exp-lookit-images-audio`, which should be able to do everything this frame can, but more reliably and with more options!
+- :ref:`exp-lookit-images-audio`, which should be able to do everything this frame can, but more reliably and with more options! (:ref:`Update guide <update_dialogue_to_images>`)