Written by James Britt
In many cases, all we want to view in a Ruby demo is one simple thing, like finding out which button caused a Rails form to fail. Instead, our demo is two minutes long. And the file size is equal to a director’s cut.
Gem documentation, pull requests and bug reports should never include unnecessary video files. However, reducing file size too aggressively can leave the Ruby code blurry. The developer needs to be able to read the exception message, follow along with the interaction, and then quickly investigate further.
Here’s how to reduce the size of your Ruby demo videos while keeping the code readable.
Don’t capture everything on your screen
For a tutorial on how to use IRB, most of what’s visible on your desktop is irrelevant. Frame just the terminal window. For a Rails validation problem, you should record both the browser and whatever output indicates why the validation failed. Everything else on your screen — including your desktop wallpaper and other windows — has no business being part of your demo video.
Increase the font in your terminal before you start. Also, choose a color scheme that displays clearly defined punctuation and readable syntax highlighting. We expect a Ruby method to display clearly — even after exporting the video.
Prepare the commands you’ll execute during the demo. If you’re going to demonstrate a failing RSpec example, there’s no reason to make the viewer sit through you searching for the directory before executing the command. Display the command, allow it to execute, and pause where the relevant failure occurs. In addition, when demonstrating a Rails UI problem, maintain the interactive flow of events. Capture the click action, followed by the application’s reaction, and finally capture the unintended outcome. Removing these moments of failure from your recorded demos eliminates their purpose.
At some point you’ll likely decide to trim a video recording. Getting the framing correct upfront saves extra editing work.
Test legibility before selecting a lower resolution
“Export at 720p” seems straightforward until your backtrace is rendered as gray confetti.
A terminal with larger text may remain readable at 720p. On the other hand, an editor next to a browser may require more pixels. Always review your exported video at the expected viewing size in your documentation or issue report instead of reviewing it solely in a full-screen editor.
Carefully examine several potential trouble spots: an underscore character, a line number or a punctuation character surrounding a hash. Can another Ruby programmer interpret these characters without having to guess?
Similarly, frame rate should receive the same practical consideration. While thirty frames per second could serve as an acceptable baseline for typical demonstrations, a mostly static console might be sufficient with fewer frames. On the other hand, a flickering drop down menu or a brief Turbo rendering bug in your demonstration requires sufficient frames to adequately represent the behavior that you’re documenting.
While conserving disk space is important, losing key information is even more significant.
Measure the average bitrate and duration
Multiplying an average total bitrate times the length of a recording provides a reasonable estimation of the overall media file-size (prior to adding overhead from the container).
For example, a two-minute recording averaging 2 megabits per second contains about 30 megabytes of media data, before container overhead.
However, such calculations say absolutely nothing regarding whether the code in your demo remains readable.
Scrolling terminal output can be harder to compress cleanly than a static method definition. If the bitrate used is too low, characters may “smear” at exactly the moment when someone needs to study them.
When trying different compression settings, export again from the original recording. Repeated lossy compression of an already compressed copy can degrade the quality further.
For background reading, this Wikipedia link currently references its expanded description of data compression:
https://en.wikipedia.org/wiki/Video_compression
Although you do not need to learn about all possible encoding schemes available to you today, you do need to visually verify that your exported demo clip works as intended.
Export a format that plays well where you plan to share it
MP4 is often referred to as a “default,” however it represents merely a container and not a guarantee of cross-platform compatibility. As such, H.264 encoded video with AAC audio contained within an MP4 container should provide a suitable starting-point for playing in most web-browsers. Actual support still depends on the browser and operating system.
Another valid alternative when you know that your target audience and publishing location support it is WebM.
Once you have completed your video export process, always open the resulting video at least once in the environment where you intend to embed or publish it. Verify that both playback controls and audio are functioning properly. Simply because your video played correctly in your preferred editing software doesn’t mean that it will play similarly in others.
Let Ruby warn you when oversized demo clips are created
You don’t need to create a video-encoding service to detect oversized demo videos.
Assuming that you store demo videos locally under a path called docs/demos before publishing them, here’s a simple Ruby script that detects them relative to an example budget size:
limit = 25 * 1024 * 1024 # Example budget: 25 MiB per file
oversized = Dir.glob("docs/demos/**/*.{mp4,webm,mov}").select do |path|
File.file?(path) && File.size(path) > limit
end
oversized.each do |path|
size = File.size(path) / (1024.0 * 1024)
warn format("%s: %.1f MiB", path, size)
end
abort "Review these demos before publishing." unless oversized.empty?Save this script as script/check_demo_sizes.rb. Then run ruby script/check_demo_sizes.rb from the project root.
Ruby’s Dir.glob finds matching paths, and File.size returns each file’s size in bytes. The script prints any detected oversized files and exits with a failure status if any are found.
The budget size of 25 MiB is simply project specific, not related to any particular upload limits set forth by platforms. Feel free to adjust as necessary for your demo videos. It uses only lowercase extensions and doesn’t modify any of the files referenced.
Checking whether the RSpec output is readable still falls on you. This tool simply helps ensure that oversized exported video clips aren’t accidentally published due to a missing optimization setting.
Automate compression when it saves you work
If you create multiple Ruby tutorials weekly, maintaining export settings in scripts may be beneficial. Using Open3.capture3, Ruby can invoke FFmpeg and gather its output. Additionally, FFmpeg’s exit status can be examined programmatically. Pass the executable and arguments separately so you aren’t generating an interpolated shell command string.
On the other hand, if you only occasionally produce pull request videos — perhaps clicking through a few interfaces — you may find manually clicking through several steps preferable.
Using Clideo’s browser-based video size reducer, you can upload a clip, select a compression preset, preview your new clip size, and download your newly compressed clip. Before downloading, check that the code is readable in Clideo’s preview.
Clideo’s video editor for iPhone also includes trimming and cropping.
These features can help remove idle time from recordings or reframe a demo. Don’t assume the app has the same export options as the browser compressor.
Always check for sensitive information prior to sharing or publishing any Rails recording — including credentials, session cookies, and any customer information that was captured. Recording against dummy development data makes that check easier.
Document the Ruby specifics as text
Regardless of how nicely compressed your video was made — it is an awful place to store your only copy of a stack trace.
Document your Ruby version(s), relevant gem versions, reproduction instructions — as well as any exception messages — inside of the issue itself. A minimal script or failing test gives maintainers something to run without transcribing a command from a paused frame.
Your demo video exists primarily for illustrating what occurred: either the sequence of clicks applied; disappearance of forms; or differences between expected outcomes vs actual outcomes. Your written report supplies the details required to reproduce what the video shows.
Remove all unnecessary pauses. Maintain legibility in your code examples. Review your final video export at least once before sharing it. When people open up your demos — they want to understand Ruby problems — and hopefully get straight to solving them.