Recordings, aka HTML/CSS to Video

By Jeffrey Needles

Product
Recordings

We've added recordings to HTML/CSS to Image. You can send a URL or HTML/CSS, along with numerous parameters to create high-quality videos (MP4 or WebM) or animated GIFs.

The words HTML/CSS to Image type out, a red marker strikes through Image, and Video is written above it by hand. Below it, Introducing Recordings appears, followed by htmlcsstovideo.com.

That GIF is plain HTML and CSS, recorded by the API in a single request. Every animation on the page lands on the frame it's supposed to.

Recording a live website is just as simple. Here's PlanetScale's homepage and the whole request that made it. Our free scrolling screenshot tool sends the same thing:

The response comes back right away with a recording_url and a status_url, and the video renders in the background.

If you already use our screenshot API, most of that request looks familiar. Viewport size, device scale, custom headers, proxies, consent banner blocking and storage destinations all work the way they do for images. What's new is actions, a list of things the browser does while the recording happens.

Why we built it

Recording websites isn't a new idea. Plenty of screenshot APIs offer some version of it, and it was the most obvious gap with ours. We didn't want a version that only works on simple pages, so most of our time went into the hard parts: steady frame timing, lazy-loaded images and sites that fight back. There's more on that below. We also wanted to support more unique, scripted creations.

What changed our thinking was AI agents. They're already good at writing HTML and CSS, and more and more of what people ask them for is visual: a launch graphic, a product teaser, a short clip for social. Asking an agent to produce a video file directly rarely goes well. Asking it to write a page and a short list of actions works surprisingly well. The structure gives it something concrete to work with: a timeline it can read, timing that comes out the same on every render, and a result it can look at and adjust. We think a lot of marketing videos and product assets are going to get made this way, and we want to be the tool that renders them.

The GIF at the top of this post was made that way. An agent wrote the HTML and CSS, rendered it through our MCP server, checked the frames, and fixed a stray red dot before I even gave any feedback. Recordings are available to agents through the same create_htmlcss_recording and create_url_recording tools.

What you can build

A few ideas we're excited about:

  • Outreach people actually watch. Put a short video of a prospect's own website in the first email. It feels personal because it is, and nobody has to sit in front of a screen recorder for each lead.
  • Release notes (kept current). Record a new feature as a GIF for the changelog or the docs. When the UI changes next month, send the same request again instead of recording it all over by hand.
  • Animated HTML from your data. A chart that draws itself, a counter that climbs to this quarter's number, a year-in-review built for each customer. If you can make it with HTML, CSS and JavaScript, you can turn it into a video, and you can make thousands of them.
  • Testing evidence. Script a user flow, fail the recording when something is missing, and keep a video of what happened.
  • Launch graphics and social clips. Design a title card, a feature announcement or a product teaser in HTML and CSS, then export it as a GIF for the blog, an MP4 for social, or both from the same markup.
  • Website previews that move. Directories, theme marketplaces and agency portfolios can show a site the way a visitor sees it, with a few seconds of scrolling instead of a cropped hero. Make one for every listing, and make them again whenever the sites change.

The GIF at the top of this post is one of those. It's about 45 lines of CSS and a single execute_javascript action that starts it on the first frame. Here's everything that went into it:

<main>
  <div class='rec'><i></i>REC <b></b></div>
  <div class='stage'>
    <h1>
      <span class='t' style='--i:0'>H</span><span class='t' style='--i:1'>T</span><span class='t' style='--i:2'>M</span><span class='t' style='--i:3'>L</span><span class='t' style='--i:4'>/</span><span class='t' style='--i:5'>C</span><span class='t' style='--i:6'>S</span><span class='t' style='--i:7'>S</span>
      <span class='t' style='--i:8'>t</span><span class='t' style='--i:9'>o</span>
      <span class='old'>
        <span class='t' style='--i:10'>I</span><span class='t' style='--i:11'>m</span><span class='t' style='--i:12'>a</span><span class='t' style='--i:13'>g</span><span class='t' style='--i:14'>e</span>
        <svg class='strike' viewBox='0 0 300 40' preserveAspectRatio='none'>
          <path pathLength='1' d='M6 26 C 60 14, 120 30, 180 18 S 270 12, 294 20'/>
        </svg>
        <em class='new'>Video</em>
      </span>
    </h1>
    <p class='intro'>Introducing <b>Recordings</b></p>
    <ul class='chips'>
      <li style='--d:2.6s'>MP4 · WebM · GIF</li>
      <li style='--d:2.72s'>Scripted scrolling and clicks</li>
      <li style='--d:2.84s'>Up to 4K at 30 fps</li>
    </ul>
  </div>
  <div class='url'><span class='play'></span><span class='host'>htmlcsstovideo.com</span></div>
</main>

The actions array

If you've ever read a script for a play, the actions array will feel familiar. It's stage direction for the browser: what happens on the page, in what order, and for how long. The recording keeps rolling the whole time and captures whatever the page does.

This one is for a product page:

"actions": [
  { "type": "stall", "duration_ms": 1000 },
  {
    "type": "scroll",
    "steps": [
      {
        "to": { "type": "selector", "selector": "#pricing", "offset_y": -80 },
        "duration_ms": 1800,
        "easing": "ease_in_out_cubic"
      }
    ]
  },
  { "type": "click", "selector": "[data-billing='annual']", "timeout_ms": 2000 },
  { "type": "stall", "duration_ms": 1500 },
  {
    "type": "scroll",
    "steps": [
      { "to": { "type": "position", "position": "bottom" }, "duration_ms": 5000, "easing": "ease_in_out_sine" },
      { "to": { "type": "position", "position": "top" }, "duration_ms": 1200, "easing": "ease_out_expo" }
    ]
  }
]

Read it top to bottom and you can picture the video. It holds on the hero for a second, then takes 1.8 seconds to move down to pricing, stopping 80 pixels short so a sticky header doesn't cover the heading. It clicks the annual toggle and waits while the prices change. Then it makes a slow, five-second pass to the footer and a quick trip back to the top. If the pacing feels off, change a number and record it again.

These are the actions you can use:

  • scroll runs one or more movements. Each one can head for an edge of the page, exact coordinates, or an element by CSS selector with offsets. Set container_selector to scroll inside an element, like a chat window or a sidebar, instead of the page.
  • simple_scroll scrolls down in steps until it reaches the bottom or runs out of time, pausing after each move. Every setting has a default, and the defaults made the videos in this post.
  • click finds an element, scrolls it into view if needed, and clicks it. You can choose the mouse button, the click count and how long the button is held down.
  • stall waits.
  • execute_javascript runs async code in the page, so you can open a menu, fill in a demo value or start an animation.
  • locate_selector checks for an element, then runs one branch of actions if it's there and another if it isn't.
  • error fails the recording. It goes at the end of a branch.

Branches are where it gets interesting. Say you're making previews for a directory of SaaS products. Every site is built differently, but one request can handle all of them:

"actions": [
  {
    "type": "locate_selector",
    "selector": "[role='dialog'] button[aria-label='Close']",
    "timeout_ms": 1500,
    "if_found": [
      { "type": "click", "selector": "[role='dialog'] button[aria-label='Close']" }
    ]
  },
  { "type": "stall", "duration_ms": 800 },
  {
    "type": "locate_selector",
    "selector": "#pricing",
    "if_found": [
      {
        "type": "scroll",
        "steps": [
          {
            "to": { "type": "selector", "selector": "#pricing", "offset_y": -80 },
            "duration_ms": 2000,
            "easing": "ease_in_out_cubic"
          }
        ]
      },
      {
        "type": "click",
        "selector": "[data-billing='annual']",
        "if_not_found": [{ "type": "stall", "duration_ms": 1000 }]
      },
      { "type": "stall", "duration_ms": 2000 }
    ],
    "if_not_found": [
      { "type": "simple_scroll", "stall_at_end_ms": 1000 }
    ]
  }
]

If a popup shows up in the first second and a half, close it. Hold on the hero. If the site has a pricing section, glide down to it, flip to annual billing if there's a toggle, and let the viewer read the prices. If there's no pricing section, scroll the whole page instead. Every branch is an ordinary list of actions, so branches can hold more branches, up to 16 levels deep.

Every scroll movement has its own duration and easing curve, and there are 31 curves to choose from. Most videos look best with ease_in_out_cubic or one of the sine curves. We also included bounce and elastic curves. Use them sparingly.

You also decide when recording starts and how long it runs. By default, the first frame is captured once the page is ready. You can wait for an element to become visible instead, or have your page call window.RecordingReady() when it's set up.

For length, duration_ms goes up to 30 seconds, and duration_mode decides how strictly it's applied. The default, at_most, ends when your actions finish. fixed pads or trims to the exact length. target records the whole sequence, up to 90 seconds, then changes the playback speed to fit the length you asked for. A 40-second walkthrough can come back as a 12-second video without you retiming every step.

What should we add next?

These seven actions are a starting point, and we'd like your help picking the next ones. A few we've been thinking about:

  • Typing into a form field, one character at a time.
  • Hovering to show menus and tooltips.
  • A visible cursor that moves between clicks.
  • Zooming in on part of the page.

If one of those would help you, or you're trying to record something the current actions can't handle, tell us what you're making, or have your agent pass along feedback. The strangest requests are often the most useful.

What goes into a smooth recording

We wanted every recording to come out smooth, whether it's a scroll down a busy homepage, a click through a pricing page or an animation you wrote yourself. That has to hold on any site, on a server that's busy with other work.

The simple way to record a browser is to capture the screen while things happen. That works on a quiet machine with a simple page. On real websites you get skipped frames, animations that run too fast or too slow, blank images and the occasional page that fights you. Here's what we do about each.

Every frame is rendered on schedule

Browser recordings are usually made with Chrome's screencast, or more recently with Puppeteer's built-in screen recorder. Both capture frames in real time, as the page happens to draw them. If the page or the machine is busy for a moment, the frames from that moment arrive late or not at all, and the video skips. We tried both and weren't happy with either, so we went a level lower and took control of timing ourselves. Each frame is rendered when we ask for it, and as far as the page can tell, time moves at exactly the right speed. A busy server makes a recording take longer to render, but the video comes out the same.

That took most of our time on recordings. A few of the problems we had to solve:

  • Holding the page still between frames is easy. Running your actions at the same time is not. A script that waits on a timer will wait forever if time never moves forward, so actions and frames have to take turns without either one blocking the other.
  • Pages put infinite loops in timers more often than you'd expect. When one starts mid-frame, we have to stop it, report it against the action that triggered it, and pick up again on the next frame.
  • Chrome quietly drops a frame whose timestamp doesn't move forward, and rounding between milliseconds and microseconds can land two frames on the same tick. That bug shows up as a single missing frame every few seconds, which is exactly the kind of stutter we were trying to get rid of.
  • Pages need frames to load, lay out and fetch lazy images before recording starts, and none of those frames can end up in the video.
  • Ads add and remove iframes while a frame is being drawn.

Smooth motion depends on every frame landing exactly one frame apart, with the scroll position calculated for that exact moment. Be off by a few milliseconds and the eye reads it as a stutter, even when it can't say what's wrong. Our scroll position comes from the easing curve at each frame's exact time, which is why the movement in our videos is so even. Your own CSS and JavaScript animations get the same treatment, which is how the GIF at the top of this post hits every beat.

A few things still keep their own time: network requests, web workers, <video> elements and animated GIFs on the page. In practice, a GIF on the page may play at a slightly different speed than it would in your browser.

Images load before the first frame

Most sites don't load an image until you scroll near it. If you start recording right away, the video shows empty boxes filling in as they come into view.

When your actions include scrolling, we scroll through the page first, quickly and before recording starts. That's up to 12 steps or about three seconds, with a short wait at the bottom to see whether the page keeps growing. Then we go back to the top, give the page a moment to repaint, and capture the first frame. If you want the video to show the page loading in, set skip_scroll_preload to true.

The site's CSS stays out of the way

Some sites set scroll-behavior: smooth or use scroll snapping. Smooth scrolling adds its own animation on top of ours, and snapping pulls the page toward the nearest snap point in the middle of a move. We turn both off for each movement and restore them when it's done.

Pauses give content time to arrive

simple_scroll pauses for 400 ms after each move. That gives new content time to show up, and gives the viewer a moment to see what's on screen. After the pause it measures the page again, and if the page grew, it keeps going. On an infinite feed, it scrolls until time runs out. You can change the length of the pause or set it to zero.

How it compares

Other services record scrolling pages too, so we put ours next to one. We ran the same two sites through a popular screenshot service's free scrolling tool and through ours, with no API tuning on either. All four videos are 1920×1080 and five seconds long. We picked two sites that are hard in different ways.

PlanetScale

PlanetScale's homepage is mostly text, with a tall logo wall. Sharp text and thin logo lines are where a dropped frame or an uneven scroll shows up first, because there's nothing else on screen to distract from them.

Giphy

Giphy is the opposite. The page is a grid of GIFs that load and start playing as they scroll into view, so the recording has to keep up with a lot of images arriving and moving at once.

Ours run at twice the frame rate and glide where theirs stutter. On Giphy, much of their video is colored placeholder boxes for GIFs that never loaded, while ours shows the real GIFs all the way down. Our files are still smaller.

Built for volume

HTML/CSS to Image has no rate limits or concurrency caps on creating or rendering images, and we host every image on our CDN for as long as you have an account. We wanted recordings to work the same way.

Most images render in under a second. A recording can capture 20 seconds of a page and then needs encoding on top of that, so each one keeps a machine busy for far longer. We built dedicated capacity for recordings, and we route each one based on its parameters to keep the output high quality. Larger recordings, up to 4K at 30 frames per second, go to larger machines automatically. A big batch of videos never slows down your image renders. There are no browsers, queues or ffmpeg builds for you to look after.

Recordings also start differently. An image URL renders the first time something requests it. A recording starts rendering as soon as you send the POST, since it takes longer, and you get the URL back right away. You can put the recording_url straight into a <video> tag, or an <img> tag for a GIF, and it will wait for the render to finish. You can also check the status_url or wait for a webhook to know when the video is ready. If you'd rather have the same behavior as images, you can set defer_render and the recording won't start until something requests it. That's handy when you're creating URLs for a lot of pages and only some of them will get watched.

It also fits into whatever you already run:

  • storage_destination_id writes finished videos to your own S3-compatible bucket, the same way Storage Destinations work for images.
  • proxy_id sends the browser through one of your proxies, for sites that need a particular region or IP address.
  • Output can be MP4, WebM or GIF, at 10 to 120 frames per second (GIFs top out at 50). output.scale shrinks the video's dimensions without changing how the page lays out.
  • Coding agents can create recordings through MCP with create_url_recording and create_htmlcss_recording.

Try it

The quickest way to see one is our free scrolling screenshot tool. Paste a URL and watch your own site scroll.

Recordings are available through the API on plans with 10,000 images per month or more. The recordings guide walks through your first request, and the scrolling video guide covers scrolling websites in more depth. Every action and option is in the actions reference.

If you'd rather not write the HTTP calls yourself, we have native clients for Node, .NET, Python, PHP, Ruby and Go, plus an n8n node for building recordings into a workflow without writing code.

We'd love to see what you make with it. And if a site doesn't record the way you'd expect, send us the URL. Plenty of pages scroll in strange ways, and we want to hear about the ones we don't handle well yet.

Loading newsletter signup…

Please wait a moment.

Have a question?

We'd love to hear about what you're building.

Contact us

Get Started

You'll be up and running in 5 minutes.

Grab an API Key

Keep reading

More posts

View all posts
Get Started Now

NO CREDIT CARD NEEDED. 50 FREE IMAGES EVERY MONTH.