diff --git a/docs/authoring.md b/docs/authoring.md index 55fae4c..6e6caa4 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -13,6 +13,13 @@ If you want to avoid hand-building scene arrays for every launch asset, you can The repo ships with one public example under [../examples/quickstart/README.md](../examples/quickstart/README.md). +Treat authoring choices as framing decisions: + +- scene arrays are good when you want explicit structure and deliberate beats +- freeform demo functions are good when you want custom motion and interaction logic +- more camera follow and zoom create emphasis +- less camera follow and lower zoom preserve more context + ## Demo Runtime API Async demo functions receive: @@ -65,10 +72,10 @@ await cursor.moveToSelector("[data-demo='search']", { Built-in move timing presets: -- `"continuous"` -- `"late-arrival"` -- `"depart-reveal"` -- `"settle"` +- `"continuous"`: follow and zoom through the whole move +- `"late-arrival"`: stay broader early, then tighten near arrival +- `"depart-reveal"`: widen earlier as the cursor departs, then travel broader +- `"settle"`: slower handoff suited to smaller local corrections or hover-heavy beats ## Scene API @@ -145,9 +152,9 @@ Supported scene types: Template helpers generate scene arrays for common flows: -- `createFeatureTour()` -- `createFormFillCapture()` -- `createHeroWalkthrough()` +- `createFeatureTour()`: guided multi-step product tours with travel between selectors +- `createFormFillCapture()`: steadier form-entry and submit flows +- `createHeroWalkthrough()`: a more presentation-led landing-page or hero sequence ### Hero Walkthrough Example @@ -240,16 +247,16 @@ camera: { } ``` -## Recommended Workflow +## Framing Guidance -For strong release-style captures: +Use these as tradeoffs, not defaults: -- use a source viewport around `1440x900` and render at `1920x1080` +- use a source viewport around `1440x900` and render at `1920x1080` when you want a normal desktop capture baseline - use `output.preset` for repeatable delivery targets instead of hand-tuning every config - pause deliberately with `cursor.wait()` or `camera.wait()` so the camera has time to settle -- use `camera.focusSelector()` before important interactions instead of letting every shot be cursor-led -- increase `camera.smoothingMs` if a cursor-led sequence still feels twitchy, or reduce it if the camera feels too lazy -- switch `camera.mode` to `"static"` when you want a composed showcase clip that behaves like a normal screen recording +- use `camera.focusSelector()` when a specific interaction deserves emphasis +- increase `camera.smoothingMs` if cursor-led motion feels too twitchy, or reduce it if it feels too slow +- switch `camera.mode` to `"static"` when the goal is full-page readability rather than cursor-led motion - use `cursor.typeSelector()` for form entries so the footage reads like a real person using the app - export `prores` when the clip is headed into Motion or Final Cut for finishing diff --git a/docs/config-reference.md b/docs/config-reference.md index 4058433..71adc7c 100644 --- a/docs/config-reference.md +++ b/docs/config-reference.md @@ -73,13 +73,25 @@ export default { - `browser.cursor.hideSelectors` lets you hide custom DOM cursor layers when you want Screenstage's cursor but the app also renders its own follower elements. - `setup` lets you put the app into the right pre-record state before capture starts. +## How To Choose Camera Settings + +Camera options control taste and emphasis, not correctness. + +Use them based on what the viewer needs: + +- more context: lower zoom, calmer preset, or `camera.mode: "static"` +- more emphasis: higher zoom and cursor-led follow behavior +- balanced motion: a follow preset with moderate zoom + +The preset names are descriptive, not normative. They are not ranked from best to worst. + ## Presets ### Camera Presets -- `"showcase-follow"`: balanced default for release-style motion with calmer hover behavior -- `"tight-follow"`: more responsive for compact UI and faster travel -- `"lazy-follow"`: slower, calmer tracking for broad navigation or hover-heavy sequences +- `"showcase-follow"`: moderate cursor-led framing for guided demos where you want motion without making every move feel aggressive +- `"tight-follow"`: faster, tighter framing for compact UI, small controls, and interaction-heavy beats +- `"lazy-follow"`: slower, broader tracking for flows where page context should stay visible longer - `"static"`: fixed framing with no follow-cam movement ### Output Presets @@ -113,6 +125,15 @@ export default { - `"minimal"`: quieter shell with less glow and ornament - `"glass"`: brighter, more luminous shell treatment +## Common Intent Mapping + +These are guidance patterns, not hard rules. + +- product walkthrough with lots of page context: `camera.mode: "static"` or a calmer follow preset +- cinematic feature emphasis: follow preset plus a higher zoom +- dashboard or broad navigation: `lazy-follow` or `static` +- form fill or CTA focus: `showcase-follow` or `tight-follow` + ## Examples ### Shell Customization @@ -257,11 +278,7 @@ On machines with `ffmpeg` installed, manual recordings can use one of three path - `balanced`: JPEG frames plus a high-quality intermediate - `rgb-frames`: PNG frames plus a lossless RGB intermediate for maximum fidelity -For real local apps, the current recommendation is: - -- `browser.capture.mode: "video"` -- a larger source viewport like `1728x1080` on desktop -- `output.preset: "motion-edit"` with both `mp4` and `prores` +Choose among those based on fidelity and runtime tradeoffs, not because one is universally correct. Built-in shot markers: diff --git a/skills/screenstage/SKILL.md b/skills/screenstage/SKILL.md index 58d8aab..bc28ba0 100644 --- a/skills/screenstage/SKILL.md +++ b/skills/screenstage/SKILL.md @@ -130,9 +130,20 @@ When a run fails, inspect: For common fixes, read [troubleshooting.md](./references/troubleshooting.md). -## Good Defaults +## Choosing Visual Style -Prefer these defaults unless the task suggests otherwise: +Do not assume the user wants either maximum follow-cam motion or maximum static readability by default. + +Choose based on what the video is for: + +- use more follow-cam motion when the point is to emphasize a specific interaction, field, CTA, or compact workflow beat +- use calmer or wider framing when the point is to preserve page context, layout understanding, or broader navigation +- use `camera.mode: "static"` when the user wants a composed screen recording feel rather than cursor-led reframing +- use camera presets and zoom values as style controls, not as mandatory defaults + +If the user clearly wants one style, follow that direction. If the intent is ambiguous and the framing choice materially affects clarity, ask for clarification or make the smallest reasonable assumption and keep the choice easy to revise. + +Operational defaults that are still safe: - `run` over `record` for repeatable feature demos - `record` when the user explicitly wants to drive the browser live in studio mode @@ -140,5 +151,3 @@ Prefer these defaults unless the task suggests otherwise: - `--output-dir` to keep artifacts isolated from user-owned folders during iteration - `--headless` for automated runs - the manifest over ad hoc file guessing - -When the user asks for a polished clip but does not specify styling, keep the existing Screenstage presets rather than inventing a custom visual treatment. diff --git a/skills/screenstage/references/config-patterns.md b/skills/screenstage/references/config-patterns.md index 52fb83e..84b4a28 100644 --- a/skills/screenstage/references/config-patterns.md +++ b/skills/screenstage/references/config-patterns.md @@ -132,3 +132,30 @@ Good starting points: - `studio-browser` for a polished browser-shell presentation Avoid hand-tuning widths, heights, and camera parameters unless the preset is clearly wrong for the task. + +## 8. Camera Choice Guidance + +Treat camera options as tradeoffs, not quality rankings. + +Use more cursor-led follow behavior when: + +- the user wants a cinematic, guided product demo +- the action happens in small UI regions +- the point is to emphasize specific controls or form fields + +Use calmer or more static framing when: + +- the user needs more page context +- the app layout matters as much as the interaction +- the flow includes broad navigation, dashboards, or large page sections + +Useful controls: + +- `camera.mode: "follow"`: cursor-led reframing +- `camera.mode: "static"`: fixed framing +- lower `camera.zoom`: more context +- higher `camera.zoom`: more emphasis +- calmer presets like `lazy-follow`: slower reframing +- tighter presets like `tight-follow`: more aggressive reframing + +If the user did not specify taste and the choice will materially change how understandable the video is, ask or make the smallest reasonable assumption instead of treating a preset name as a universal best practice.