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.<\/p>\n\n\n\n
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.<\/p>\n\n\n\n
Here’s how to reduce the size of your Ruby demo videos while keeping the code readable.<\/p>\n\n\n\n
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 \u2014 including your desktop wallpaper and other windows \u2014 has no business being part of your demo video.<\/p>\n\n\n\n
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 \u2014 even after exporting the video.<\/p>\n\n\n\n
Prepare the commands you\u2019ll execute during the demo. If you\u2019re going to demonstrate a failing RSpec example, there\u2019s 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\u2019s reaction, and finally capture the unintended outcome. Removing these moments of failure from your recorded demos eliminates their purpose.<\/p>\n\n\n\n
At some point you’ll likely decide to trim a video recording. Getting the framing correct upfront saves extra editing work.<\/p>\n\n\n\n
\u201cExport at 720p\u201d seems straightforward until your backtrace is rendered as gray confetti.<\/p>\n\n\n\n
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.<\/p>\n\n\n\n
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?<\/p>\n\n\n\n
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\u2019re documenting.<\/p>\n\n\n\n
While conserving disk space is important, losing key information is even more significant.<\/p>\n\n\n\n
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).<\/p>\n\n\n\n
For example, a two-minute recording averaging 2 megabits per second contains about 30 megabytes of media data, before container overhead.<\/p>\n\n\n\n
However, such calculations say absolutely nothing regarding whether the code in your demo remains readable.<\/p>\n\n\n\n
Scrolling terminal output can be harder to compress cleanly than a static method definition. If the bitrate used is too low, characters may \u201csmear\u201d at exactly the moment when someone needs to study them.<\/p>\n\n\n\n
When trying different compression settings, export again from the original recording. Repeated lossy compression of an already compressed copy can degrade the quality further.<\/p>\n\n\n\n
For background reading, this Wikipedia link currently references its expanded description of data compression:<\/p>\n\n\n\n
https:\/\/en.wikipedia.org\/wiki\/Video_compression<\/a><\/p>\n\n\n\n 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.<\/p>\n\n\n\n MP4 is often referred to as a \u201cdefault,\u201d 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.<\/p>\n\n\n\n Another valid alternative when you know that your target audience and publishing location support it is WebM.<\/p>\n\n\n\n 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\u2019t mean that it will play similarly in others.<\/p>\n\n\n\n You don\u2019t need to create a video-encoding service to detect oversized demo videos.<\/p>\n\n\n\n Assuming that you store demo videos locally under a path called Save this script as Ruby’s 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\u2019t modify any of the files referenced.<\/p>\n\n\n\n Checking whether the RSpec output is readable still falls on you. This tool simply helps ensure that oversized exported video clips aren\u2019t accidentally published due to a missing optimization setting.<\/p>\n\n\n\n If you create multiple Ruby tutorials weekly, maintaining export settings in scripts may be beneficial. Using On the other hand, if you only occasionally produce pull request videos \u2014 perhaps clicking through a few interfaces \u2014 you may find manually clicking through several steps preferable.<\/p>\n\n\n\nExport a format that plays well where you plan to share it<\/h2>\n\n\n\n
Let Ruby warn you when oversized demo clips are created<\/h2>\n\n\n\n
docs\/demos<\/code> before publishing them, here\u2019s a simple Ruby script that detects them relative to an example budget size:<\/p>\n\n\n\nlimit = 25 * 1024 * 1024 # Example budget: 25 MiB per file\n\noversized = Dir.glob(\"docs\/demos\/**\/*.{mp4,webm,mov}\").select do |path|\n File.file?(path) && File.size(path) > limit\nend\n\noversized.each do |path|\n size = File.size(path) \/ (1024.0 * 1024)\n warn format(\"%s: %.1f MiB\", path, size)\nend\n\nabort \"Review these demos before publishing.\" unless oversized.empty?<\/code><\/pre>\n\n\n\nscript\/check_demo_sizes.rb<\/code>. Then run ruby script\/check_demo_sizes.rb<\/code> from the project root.<\/p>\n\n\n\nDir.glob<\/code> finds matching paths, and File.size<\/code> returns each file’s size in bytes. The script prints any detected oversized files and exits with a failure status if any are found.<\/p>\n\n\n\nAutomate compression when it saves you work<\/h2>\n\n\n\n
Open3.capture3<\/code>, Ruby can invoke FFmpeg and gather its output. Additionally, FFmpeg\u2019s exit status can be examined programmatically. Pass the executable and arguments separately so you aren’t generating an interpolated shell command string.<\/p>\n\n\n\n