How Pieces Of Cake Actually Works
Pieces of Cake is an open-source web performance visualization toolkit built on top of WebPageTest. It takes the raw data from a test run and turns it into a video frame-by-frame representation of how a page loads. The typical use case is getting a visual sense of what's actually happening during page render rather than looking at another waterfall chart. I started using it about three years ago when our team was trying to explain layout shift issues to stakeholders who didn't care about Core Web Vitals scores. A video showing the page building itself in real time was infinitely more effective than any LCP number we could throw at them.
Installing Pieces Of Cake
First you need Python 3.8 or later installed. Clone the repository from github.com/WPO-Foundation/pieces-of-cake and create a virtual environment. Then run pip install -e . in the directory. You also need ffmpeg installed on your system because POC uses it to encode the final video output. The dependency chain is straightforward but I ran into issues on Ubuntu when ffmpeg wasn't compiled with libx264 support. The error message is unhelpful and just crashes during encoding. Installing ffmpeg from the default repos on newer Ubuntu versions usually fixes this since they include the right codecs by default.
Running Your First Test
The basic workflow involves three steps: running a WebPageTest test, downloading the results, and feeding them into Pieces of Cake to generate the visualization video. You can run tests through the WebPageTest web interface at webpagetest.org or through their API. The API approach is faster for automated workflows. Here's what a typical command looks like: wptLocation=default&key=YOUR_API_KEY&url=https://yoursite.com&runs=3
Get the Full Details
This returns a JSON response with a test ID and URL to the results page. Download the full results archive from that URL, extract it, and then point Pieces of Cake at the video and screenshot files inside. The command to generate the video is relatively simple once you have the data. poc input/video_file.mp4 screenshots/screenshot_directory/ output/output_video.mp4 Default settings give you a reasonable visualization but you'll want to tweak a few parameters depending on what you're trying to show. The --speed option controls playback speed multiplier and --sync can align the video with the filmstrip view if you need frame-level accuracy.
Common Pitfalls and Edge Cases
One issue that caught me off guard involves mobile versus desktop tests. Pieces of Cake handles desktop test data cleanly because WebPageTest provides a full video stream. Mobile tests often only provide screenshot sequences without synchronized video. In that scenario POC falls back to stitching screenshots together and the result looks choppy at best. I ended up writing a small wrapper script that interpolates between screenshots to smooth things out, which made the output usable for presentations. Another thing to watch for is test duration. Long-running page tests with many elements can produce visualization videos that are impractically large. A single test of a media-heavy page can generate a 4K video file over a gigabyte in size. I started capping my tests at around 30 seconds of real load time and then using the --trim option to focus on the critical rendering path rather than including lazy-loaded content that appears well after initial paint. Sometimes the screenshot timing from WebPageTest doesn't align perfectly with the actual DOM rendering. This creates a desync between what the filmstrip shows and what the video displays. The workaround is to manually adjust timestamps using the --offset parameter. You need to eyeball the difference by comparing the POC output against the original WebPageTest filmstrip and note where frames start drifting apart.
Advanced Usage
For teams running performance comparisons across multiple configurations, Pieces of Cake supports batch processing through a configuration file. You can define test scenarios, target URLs, device profiles, and output directories in a YAML file and let POC iterate through them automatically. The comparison mode is particularly useful. Running poc compare results_baseline/ results_modified/ produces side-by-side video output that makes it obvious when a change improves or degrades rendering behavior. I've used this extensively during CSS optimization work where the DOM mutation patterns changed significantly between versions. If you're integrating this into a CI pipeline, note that the video generation step can take anywhere from two to ten minutes depending on test complexity and output resolution. Factor that into your pipeline timeout settings or you'll get intermittent failures that are painful to debug.
Pieces Of Cake has real limitations. It doesn't handle service worker cache tests well because those alter the load sequence in ways that don't map cleanly to frame-by-frame visualization. It also struggles with Single Page Applications where the initial HTML response is nearly empty and most content arrives via JavaScript. The video will show a blank screen for several seconds and then everything appearing at once, which is technically accurate but not useful for diagnosing what's causing the delay. For those cases Chrome DevTools Performance panel or the Lighthouse studio video capture tend to be more appropriate tools. POC excels at traditional multi-page websites with standard server-rendered content. That's the sweet spot and staying within it will save you frustration.
