Your story.
In motion.

From ZIP to story in a minute

The download is a complete, small website: the runtime, editor, this guide, and the eleven-scene demo.

1. Unzip scrollstory-0.7.1-beta.zip.
2. Open a terminal in the extracted folder.
3. Start either a PHP server or a simple static server:

# PHP: editing, server-side Save and media uploads
php -S 127.0.0.1:8000

# Or static: editing works; Save downloads JSON
python3 -m http.server 8000

Open http://127.0.0.1:8000/. The homepage is the demo. Use the pencil to edit it.

For PHP Save/Upload: copy api/secret.sample.php to api/secret.php and replace the sample token with your own random token. Run php -r "echo bin2hex(random_bytes(16));" to generate one. Make content/ and media/ writable by PHP. Never publish or commit your real secret.php.

The page is the canvas

Open the pencil, or press Ctrl/⌘ + E. Select a block, then use the Content, Motion and Layout inspector tabs. The scene rail jumps, renames, duplicates and reorders scenes.

Useful keys: Ctrl/⌘ + S saves; Ctrl/⌘ + Z undoes; add Shift to redo; arrow keys step scenes; Esc clears the selection. Use Done to leave editing.

The editor is desktop-first in this Beta. Use a wide browser window for the full toolbar and inspector. Reading and responsive preview work on small screens; the complete editing UI is not yet a mobile interface.

One scene, one snap stop

A story is one JSON document. Its scenes array holds the cards; each scene owns background media and positioned content blocks. The browser keeps native wheel, touch and keyboard scrolling—ScrollStory does not intercept the wheel.

{
  "version": 5,
  "title": "My story",
  "theme": {"bg": "#101014", "ink": "#f6f3ee", "accent": "#79bfff"},
  "settings": {"xfade": 650, "hud": "bar"},
  "scenes": [{
    "id": "opening",
    "media": {"type": "image", "src": "media/demo/eclipse.webp", "dim": 0.3},
    "blocks": [{
      "id": "headline", "type": "title", "html": "Begin here.",
      "x": 50, "y": 45, "w": 80, "align": "center",
      "anim": {"name": "rise-words", "in": 0.08, "out": 1, "dist": 4}
    }]
  }]
}

Block positions x, y and width w are percentages. Optional mx, my and mw override them at narrow widths. A scene with "media": {"carry": true} keeps the previous scene’s background while its words change.

Word Rise is plain text. It rebuilds a block into word spans, so inner HTML classes and <br> are not preserved. Use ordinary rise for rich HTML or deliberate line breaks.

Choreograph the crossing

Entrances and exits follow the scene’s crossing: entering, docked, then covered. Choose fade, rise, reveal, word rise, zoom, count-up and more. Track mode exposes IN, ON and OUT poses for position, opacity, scale, rotation and blur.

Kinema blocks add a self-contained, timed stage inside a scene. The included “Motion with meaning” scene is a working example with three text poses and a moving playhead. Loop it or play it once; reduced-motion readers receive the static ON composition. Set the project’s stage.bg to "transparent" and the stage is see-through — the story’s own background shows behind the objects, no backdrop of its own.

Hold the image. Frame every screen.

Backgrounds accept images, video or color. Use dim for legibility, x/y for the focal point, and fx for a restrained effect such as Ken Burns. Scroll-scrubbed effects travel across a whole carried group: scan-y walks a tall image top to bottom (desktop), scan-x walks a wide image left to right (narrow screens), and zoom-in / zoom-out magnify toward or away from the focal point as the reader scrolls.

For a full wide-image reveal on a phone, leave portrait unset on that scan-x scene; a portrait substitute would supply a different aspect ratio and a different crop to reveal. Reduced-motion readers receive the effect’s first frame without travel.

"media": {
  "type": "image",
  "src": "media/demo/lovelace.webp",
  "srcset": [
    {"w": 768, "url": "media/demo/lovelace-768.webp"},
    {"w": 1920, "url": "media/demo/lovelace.webp"}
  ],
  "sizes": "100vw",
  "portrait": {"src": "media/demo/lovelace-portrait.webp", "x": 0.55, "y": 0.35},
  "dim": 0.3
}

The portrait source is used at narrow aspect ratios without JavaScript selection. With the PHP media API and GD, uploads can receive width derivatives automatically. Only publish media you own or are licensed to share, and keep its credits with the story.

A score drawn in moving notes

A musicbox block synthesizes notes with Web Audio; there are no audio files to upload. Notes move through a playhead and sound as they cross. Playback begins after user interaction and stops when its scene or end condition ends.

{
  "id": "theme", "type": "musicbox", "x": 50, "y": 60,
  "music": {
    "title": "My theme", "mode": "horizontal", "play": "loop",
    "span": 3200, "volume": 0.5, "endAfter": 1,
    "w": 72, "h": 23,
    "notes": [
      {"note": "C4", "y": 0},
      {"note": "E4", "y": 400},
      {"note": "G4", "y": 800}
    ]
  }
}

y is the note’s time in milliseconds; span is the full loop. Use horizontal or vertical, loop or once, and endAfter or endScene to control its life. The editor’s ♪ Music panel also assigns single transition notes to scenes.

The Beta includes Son de la Luz and Lollipop Circuit, two original, synthesized miniatures created for this demo. They do not contain samples or reproduce the referenced commercial songs. Use only music you have permission to publish.

Your story stays portable

With PHP and your token configured, Save writes content/<page-id>.json and keeps dated snapshots under content/history/. Load restores pages and revisions.

Without the API, Save downloads the complete JSON instead, and selected media can be embedded as data URLs for the session. This is how the public scrollstory.org demo works: no visitor can write to the server.

To make an edited homepage permanent without the API, replace content/home.json with your downloaded JSON. Keep a backup first. To add another page, copy index.html and boot.js, point window.STORY_URL in the new bootstrap at its JSON, and give it a unique id query value.

Upload files, not infrastructure

Serve the folder from any ordinary web host. Reading, editing and JSON download need only static files. Add PHP when you want server-side Save and Upload.

• Upload index.html, boot.js, story.js, liveeditor.js, site.css, assets/, vendor/, content/ and your cleared media/.
• For the public demo, omit api/ entirely. For a private editable deployment, include it and configure api/secret.php.
• Do not deploy content/history/, local credentials, deployment configuration, or private test media.
• When you change story JSON or JavaScript, update its ?v= query in index.html so returning readers receive the new version.

What Beta means here

• The reading engine uses native scroll-snap, CSS crossfades and reduced-motion cuts. Keyboard arrows, Page Up/Down, Home and End are supported.
• The editor is desktop-first. Narrow-screen story overrides are available in JSON, but the full per-block mobile editing UI is still on the roadmap.
• Standalone HTML export is not yet included. A story currently ships as the small runtime plus its JSON and media.
• Audio needs a user gesture. Browsers may keep sound suspended until the visitor interacts.
• The public homepage has no write API. Your edits are yours until you download the JSON; refreshing discards unsaved changes.

Keep the Beta label on production experiments, test your own media on phone and desktop, and save a JSON backup before upgrading the engine.

From the Magazine archive

The demo crops and converts these works to WebP; original authors and licenses remain attached to their scenes and to media/demo/credits.json.

• Total solar eclipse, 12 August 2026 · Luc Viatour · CC BY-SA 4.0.
• Ada Lovelace · Alfred Edward Chalon · public domain. Quotation: Ada Lovelace, Note A, 1843.
• Indtoget i Myklegaard · Gerhard Munthe · public-domain artwork; owner-provided museum scan via ScrollStory Magazine.
• Discomedusae · Ernst Haeckel · public domain.
• Cuban soldiers, 1898 · Harper & Brothers · public domain.
• Charon, Inferno plate IX · Gustave Doré · public domain.

Engine and editor: ScrollStory v7.1. Embedded motion: Kinema. Color picker: Coloris. Demo compositions: Son de la Luz and Lollipop Circuit, original works made for this Beta.