agent-screenplay 0.1.0 → 0.1.2

package/schema/scenario.schema.json

@@ -26,7 +26,7 @@
       "type": "boolean"
     },
     "viewport": {
-      "description": "Web: browser size in CSS pixels (default 1440x900).",
+      "description": "Web: browser size in CSS pixels (default: the video's shape with a longer side of 1440, such as 1440x810 for 16:9, so the page fills the frame when padding is 0).",
       "type": "object",
       "properties": {
         "width": {
@@ -90,7 +90,7 @@
       "type": "object",
       "properties": {
         "background": {
-          "description": "A preset (sunset, ocean, lavender, forest, midnight, mono, paper), a color like #0f172a, an image path (relative to the file that sets it), or a gradient { \"gradient\": [\"#0ea5e9\", \"#6366f1\"], \"angle\": 135 }.",
+          "description": "A preset (dawn, iris, citrus, apricot, coral, blaze, cloud, glacier, tide, meadow; default dawn), a color like #0f172a, an image path (relative to the file that sets it), or a gradient { \"gradient\": [\"#0ea5e9\", \"#6366f1\"], \"angle\": 135 }.",
           "anyOf": [
             {
               "type": "string"
@@ -178,6 +178,10 @@
             "none",
             "browser"
           ]
+        },
+        "cards": {
+          "description": "Show the title and end cards (default false: `title` and `end` steps are left out of the video). Turn on when the person wants an intro and an outro.",
+          "type": "boolean"
         }
       },
       "additionalProperties": false
@@ -186,15 +190,23 @@
       "type": "object",
       "properties": {
         "enabled": {
-          "description": "Speak each step's `say` text (default false). Needs CARTESIA_API_KEY.",
+          "description": "Speak each step's `say` text (default false). Needs CARTESIA_API_KEY or ELEVENLABS_API_KEY, unless every spoken step has its own `audio` file.",
           "type": "boolean"
         },
+        "provider": {
+          "description": "Who speaks (default: Cartesia when CARTESIA_API_KEY is set, else ElevenLabs when ELEVENLABS_API_KEY is).",
+          "type": "string",
+          "enum": [
+            "cartesia",
+            "elevenlabs"
+          ]
+        },
         "language": {
           "description": "Language code, e.g. en, fr, de (default en).",
           "type": "string"
         },
         "id": {
-          "description": "Cartesia voice id (default: a narration voice for the language).",
+          "description": "The provider's voice id (default: a narration voice).",
           "type": "string"
         },
         "speed": {
@@ -203,7 +215,7 @@
           "maximum": 1.5
         },
         "model": {
-          "description": "Cartesia model (default sonic-3.6).",
+          "description": "The provider's model (default sonic-3.6 for Cartesia, eleven_multilingual_v2 for ElevenLabs).",
           "type": "string"
         }
       },
@@ -289,6 +301,10 @@
                   }
                 ]
               },
+              "audio": {
+                "description": "An audio file (MP3, WAV, M4A…) with this step's narration, relative to the scenario: used instead of generating `say`, with no voice key. The step lasts at least as long as the file.",
+                "type": "string"
+              },
               "hold": {
                 "description": "Extra seconds to stay on the result of this step before the next one.",
                 "type": "number",
@@ -341,6 +357,10 @@
                   }
                 ]
               },
+              "audio": {
+                "description": "An audio file (MP3, WAV, M4A…) with this step's narration, relative to the scenario: used instead of generating `say`, with no voice key. The step lasts at least as long as the file.",
+                "type": "string"
+              },
               "hold": {
                 "description": "Extra seconds to stay on the result of this step before the next one.",
                 "type": "number",
@@ -404,6 +424,10 @@
                   }
                 ]
               },
+              "audio": {
+                "description": "An audio file (MP3, WAV, M4A…) with this step's narration, relative to the scenario: used instead of generating `say`, with no voice key. The step lasts at least as long as the file.",
+                "type": "string"
+              },
               "hold": {
                 "description": "Extra seconds to stay on the result of this step before the next one.",
                 "type": "number",
@@ -473,6 +497,10 @@
                   }
                 ]
               },
+              "audio": {
+                "description": "An audio file (MP3, WAV, M4A…) with this step's narration, relative to the scenario: used instead of generating `say`, with no voice key. The step lasts at least as long as the file.",
+                "type": "string"
+              },
               "hold": {
                 "description": "Extra seconds to stay on the result of this step before the next one.",
                 "type": "number",
@@ -525,6 +553,10 @@
                   }
                 ]
               },
+              "audio": {
+                "description": "An audio file (MP3, WAV, M4A…) with this step's narration, relative to the scenario: used instead of generating `say`, with no voice key. The step lasts at least as long as the file.",
+                "type": "string"
+              },
               "hold": {
                 "description": "Extra seconds to stay on the result of this step before the next one.",
                 "type": "number",
@@ -578,6 +610,10 @@
                   }
                 ]
               },
+              "audio": {
+                "description": "An audio file (MP3, WAV, M4A…) with this step's narration, relative to the scenario: used instead of generating `say`, with no voice key. The step lasts at least as long as the file.",
+                "type": "string"
+              },
               "hold": {
                 "description": "Extra seconds to stay on the result of this step before the next one.",
                 "type": "number",
@@ -645,6 +681,10 @@
                   }
                 ]
               },
+              "audio": {
+                "description": "An audio file (MP3, WAV, M4A…) with this step's narration, relative to the scenario: used instead of generating `say`, with no voice key. The step lasts at least as long as the file.",
+                "type": "string"
+              },
               "hold": {
                 "description": "Extra seconds to stay on the result of this step before the next one.",
                 "type": "number",
@@ -701,6 +741,10 @@
                   }
                 ]
               },
+              "audio": {
+                "description": "An audio file (MP3, WAV, M4A…) with this step's narration, relative to the scenario: used instead of generating `say`, with no voice key. The step lasts at least as long as the file.",
+                "type": "string"
+              },
               "hold": {
                 "description": "Extra seconds to stay on the result of this step before the next one.",
                 "type": "number",
@@ -771,6 +815,10 @@
                   }
                 ]
               },
+              "audio": {
+                "description": "An audio file (MP3, WAV, M4A…) with this step's narration, relative to the scenario: used instead of generating `say`, with no voice key. The step lasts at least as long as the file.",
+                "type": "string"
+              },
               "hold": {
                 "description": "Extra seconds to stay on the result of this step before the next one.",
                 "type": "number",
@@ -825,6 +873,10 @@
                   }
                 ]
               },
+              "audio": {
+                "description": "An audio file (MP3, WAV, M4A…) with this step's narration, relative to the scenario: used instead of generating `say`, with no voice key. The step lasts at least as long as the file.",
+                "type": "string"
+              },
               "hold": {
                 "description": "Extra seconds to stay on the result of this step before the next one.",
                 "type": "number",
@@ -871,6 +923,10 @@
               "say": {
                 "description": "Narration for this step: shown as a caption, and spoken when voice is enabled. The step lasts at least as long as the sentence.",
                 "type": "string"
+              },
+              "audio": {
+                "description": "An audio file (MP3, WAV, M4A…) with this step's narration, relative to the scenario: used instead of generating `say`, with no voice key. The step lasts at least as long as the file.",
+                "type": "string"
               }
             },
             "required": [
@@ -896,6 +952,10 @@
               "say": {
                 "description": "Narration for this step: shown as a caption, and spoken when voice is enabled. The step lasts at least as long as the sentence.",
                 "type": "string"
+              },
+              "audio": {
+                "description": "An audio file (MP3, WAV, M4A…) with this step's narration, relative to the scenario: used instead of generating `say`, with no voice key. The step lasts at least as long as the file.",
+                "type": "string"
               }
             },
             "required": [
@@ -937,6 +997,10 @@
                   }
                 ]
               },
+              "audio": {
+                "description": "An audio file (MP3, WAV, M4A…) with this step's narration, relative to the scenario: used instead of generating `say`, with no voice key. The step lasts at least as long as the file.",
+                "type": "string"
+              },
               "hold": {
                 "description": "Extra seconds to stay on the result of this step before the next one.",
                 "type": "number",
@@ -999,6 +1063,10 @@
                   }
                 ]
               },
+              "audio": {
+                "description": "An audio file (MP3, WAV, M4A…) with this step's narration, relative to the scenario: used instead of generating `say`, with no voice key. The step lasts at least as long as the file.",
+                "type": "string"
+              },
               "hold": {
                 "description": "Extra seconds to stay on the result of this step before the next one.",
                 "type": "number",
@@ -1057,6 +1125,10 @@
                   }
                 ]
               },
+              "audio": {
+                "description": "An audio file (MP3, WAV, M4A…) with this step's narration, relative to the scenario: used instead of generating `say`, with no voice key. The step lasts at least as long as the file.",
+                "type": "string"
+              },
               "hold": {
                 "description": "Extra seconds to stay on the result of this step before the next one.",
                 "type": "number",
@@ -1093,6 +1165,6 @@
     "steps"
   ],
   "additionalProperties": false,
-  "$id": "https://raw.githubusercontent.com/gmpetrov/screenplay/main/schema/scenario.schema.json",
+  "$id": "https://raw.githubusercontent.com/gmpetrov/agent-screenplay/main/schema/scenario.schema.json",
   "title": "Screenplay scenario"
 }

package/skills/screenplay/SKILL.md

@@ -12,31 +12,29 @@ Tools: the MCP tools `screenplay_check`, `screenplay_record`, `screenplay_render
 ## The loop
 
 1. **Understand what to show.** One video shows one idea: a feature, a flow, a fix. 15 to 60 seconds. Decide the story first: the starting point, the 3 to 8 actions that matter, the result.
+   **Ask about the voice-over before writing**, in one question, unless the request already says: no voice (captions only, the default), or a voice-over, in which language. If they want one, see *Voice-over* below for how to get the voice.
 2. **Explore the app** (with your browser tools, or by reading its code) to find the real path: which page, which buttons, what text they carry, what data is on screen. Prefer a demo account with realistic data: an empty dashboard or "test123" ruins the video.
 3. **Write the scenario** next to where the video should go (for example `demos/handoff.json`).
 4. **Run `check`.** It plays the scenario fast, without filming, and tells you which step fails and which targets are visible instead. Fix and check again until it plays to the end.
 5. **Run `record`.** It films and edits, and writes `<name>.mp4` and `<name>.storyboard.png`.
 6. **Look at the storyboard** (one image per step). Check: is each zoom framed on the right element, is a bubble hiding something, does a step show an error, is the data credible? Fix the scenario. If you only changed text, narration, style or zoom, run `render` (no new filming); if you changed actions, `record` again.
-7. Hand over the MP4 path (and the GIF if asked).
+7. Hand over the MP4 path (and the GIF if asked), then **offer to adjust the look**: the person can set the background, padding, corners, shadow and the intro/outro cards by eye with `npx agent-screenplay style <scenario.json>`, which opens an editor in their browser and re-renders without filming. If they accept and the computer has a screen, run it for them in the background (it keeps running until stopped) and say a browser tab opened; otherwise give them the command.
 
 ## Scenario
 
 ```json
 {
-  "$schema": "https://raw.githubusercontent.com/gmpetrov/screenplay/main/schema/scenario.schema.json",
+  "$schema": "https://raw.githubusercontent.com/gmpetrov/agent-screenplay/main/schema/scenario.schema.json",
   "url": "https://app.example.com/inbox",
-  "viewport": { "width": 1440, "height": 900 },
   "auth": { "storageState": ".screenplay/auth.json" },
-  "style": { "background": "ocean" },
+  "style": { "background": "dawn" },
   "steps": [
-    { "title": "Human handoff, in one click", "subtitle": "New in 2.4" },
     { "click": "text=Camille Laurent", "say": "When the AI agent gets stuck, the conversation lands in your inbox." },
     { "callout": "role=button[name='Take over']", "text": "Take over from the AI agent" },
     { "click": "role=button[name='Take over']" },
     { "type": "Hi Camille, I'm on it.", "into": "placeholder=Write a reply…" },
     { "click": "role=button[name='Send']" },
-    { "highlight": "text=Assigned to you", "text": "Your teammates see it's yours" },
-    { "end": "Available today on every plan" }
+    { "highlight": "text=Assigned to you", "text": "Your teammates see it's yours" }
   ]
 }
 ```
@@ -96,31 +94,41 @@ On any step: `say` (narration: a caption, and speech when voice is on), `zoom` (
 ### Style, voice, output
 
 ```json
-"style": { "background": "ocean", "padding": 72, "radius": 14, "cursor": "macos", "maxZoom": 1.9, "frame": "browser", "accent": "#3b82f6", "captions": true },
+"style": { "background": "dawn", "padding": 72, "radius": 14, "cursor": "macos", "maxZoom": 1.9, "frame": "browser", "accent": "#3b82f6", "captions": true },
 "voice": { "enabled": true, "language": "fr" },
 "output": { "width": 1920, "height": 1080, "fps": 30, "gif": false }
 ```
 
-Backgrounds: `sunset`, `ocean`, `lavender`, `forest`, `midnight`, `mono`, `paper`, a color (`#0f172a`), an image path, or a gradient `{ "gradient": ["#0ea5e9", "#6366f1"], "angle": 135 }`. `frame: "browser"` adds a minimal browser bar with the URL.
+Backgrounds: `dawn` (default), `iris`, `citrus`, `apricot`, `coral`, `blaze`, `cloud`, `glacier`, `tide`, `meadow`, a color (`#0f172a`), an image path, or a gradient `{ "gradient": ["#0ea5e9", "#6366f1"], "angle": 135 }`. `frame: "browser"` adds a minimal browser bar with the URL.
 
 A `screenplay.config.json` in the scenario's folder or a parent sets the style of every video below it (`{ "style": { … } }`); a scenario's own `style` wins, setting by setting. Keep a project's look there rather than repeating it in each scenario, and leave it alone unless asked. When a person wants to choose the look themselves, tell them to run `npx agent-screenplay style <scenario.json>`: it opens a visual editor in their browser (it needs a screen, so do not run it yourself in a headless environment).
 
-Voice-over is **off by default**. With `voice.enabled`, each `say` is spoken (Cartesia, needs `CARTESIA_API_KEY`) and the video waits for each sentence to finish. Without voice, `say` still shows as a caption.
+Title and end cards are **off by default**: `title` and `end` steps are left out of the video unless `"style": { "cards": true }`. Add them, and turn cards on, only when the person asks for an intro or an outro.
+
+### Voice-over
+
+Off by default. With `"voice": { "enabled": true, "language": "fr" }`, each `say` is spoken and the video waits for each sentence to finish. Without voice, `say` still shows as a caption. Getting the voice:
+
+1. If `CARTESIA_API_KEY` or `ELEVENLABS_API_KEY` is set in the environment, it is used (Cartesia first; `"provider": "elevenlabs"` to choose).
+2. If neither is set, offer the person the choice:
+   - give a key (set `CARTESIA_API_KEY` from https://play.cartesia.ai/keys or `ELEVENLABS_API_KEY` from https://elevenlabs.io/app/settings/api-keys, then restart the agent); or
+   - make the voice themselves: write the narration as a ready-to-paste script, one numbered line per spoken step, with the language and the tone, and ask them to generate it in ElevenLabs' or Cartesia's web app and save one file per line as `voice/01.mp3`, `voice/02.mp3`… next to the scenario. Then give each spoken step its `"audio": "voice/NN.mp3"` and run `render` (no new filming).
+   - or go without voice: captions only.
 
 ## Direction that makes a good video
 
-- **Start on a title card** that names the feature, and **end on a card** with the result or call to action.
 - **One action per step**, and a `say` on the steps that matter, not on every one. Narration: short spoken sentences, present tense, what the viewer gains ("One click, and the conversation is yours"), not what the cursor does ("Now I click the button").
 - **Show before you act** when the control is hard to spot: a `callout` on the button, then the `click`.
 - **End on the proof**: a `highlight` or `hold` on the result (the saved item, the green status, the sent message).
 - **Let zooms work**: they follow clicks and typing automatically. Use `"zoom": false` on a step whose result appears far from the click (a toast, a side panel), or `zoomTo` to frame the result.
 - **Realistic data and typing**: real-looking names and messages, 3 to 10 words typed, not paragraphs.
 - **Keep it short**: under a minute; cut steps that don't move the story.
-- **Logins**: run `screenplay login <url>` once (a person signs in, the session is saved to `.screenplay/auth.json`) and set `auth.storageState`; or log in with steps using `${EMAIL}` / `${PASSWORD}` and `secret: true`.
+- **Logins**: run `npx agent-screenplay login <url>` once (a person signs in in the window that opens, then closes it; the session is saved to `.screenplay/auth.json`) and set `auth.storageState`; or log in with steps using `${EMAIL}` / `${PASSWORD}` and `secret: true`.
 
 ## When something goes wrong
 
-- `check` fails on a target → use one from the listed visible targets, or add a `wait` for it.
+- `check` fails on a target → use one from the listed visible targets, or add a `wait` for it. A listed `css=… (shows "…")` is a button whose text is drawn by CSS (some cookie walls): copy it as is.
+- "shows a bot check that needs a person" (Cloudflare) → run `npx agent-screenplay login <url>` (in the background: it waits), and tell the person: pass the check in the browser window that opened, accept the cookies if asked, then **close the window**. Closing saves the session; do not ask them to press Enter in a terminal. Then set `"auth": { "storageState": ".screenplay/auth.json" }` and check again.
 - "covered by …" → something (a toast, a cookie banner, a modal) sits on the element: close it first with a step.
 - "the typed text did not appear" → the field was not focused: use `into` to click it.
 - A wait is long (page loads, AI answers) → keep it: long waits are sped up in the video automatically.