recordMyDesktop(1)

💖 recordMyDesktop 💖

okay bestie, so this is the manual for recordMyDesktop — and yeah, it lives in the General Commands Manual section, so it's <pink>recordMyDesktop(1)</pink> if you're being formal about it. 🎀

---

✨ NAME ✨

recordMyDesktop — record desktop sessions to an Ogg Theora video file with Vorbis audio 🦋

---

✨ SYNOPSIS ✨

recordmydesktop

recordmydesktop output-filename

recordmydesktop --rescue path-to-data

recordmydesktop {image-options|sound-options|encoding-options|miscellaneous-options| ... }

recordmydesktop {-h|--help}

recordmydesktop --version

recordmydesktop --print-config

---

✨ DESCRIPTION ✨

So recordMyDesktop makes a file — <pink>out.ogv</pink> by default, no cap — that holds a video AND audio recording of your X Window System session. literally both. 💅

For a typical scenario, recording your session is as simple as:

$ recordmydesktop

which will produce a full-screen recording named <pink>out.ogv</pink> in the current working directory, while the command

$ recordmydesktop ../foo

will save the recording in <pink>foo.ogv</pink> in the parent of the current working directory. cute, right? 🫶

---

To end a recording, press Control+C. (This action sends a <purple>SIGINT</purple> to recordMyDesktop.) 👑

---

To designate a region of the screen for recording you can type this:

$ recordmydesktop -x x-pos -y y-pos --width w --height h -o foo.ogv

where x-pos and y-pos specify the offset in pixels from the upper-left corner of your screen and w and h the size of the region to be recorded, again in pixels. If the area extends beyond your current resolution, you will be notified appropriately and nothing will happen. 💀

Note: if any options are used, and you wish to use an output filename other than the default, you must specify it with the <pink>-o</pink> option. no skipping this one bestie, it's giving mandatory 😭

---

Since version 0.3 of recordMyDesktop, encoding is done immediately after recording finishes. While this behavior saves a lot of CPU, you can revert to the old one by specifying the <pink>--on-the-fly-encoding</pink> option. 🌸

The default behavior of recording is to mark areas that have changed (as determined by the X Damage extension) and update the frame. This behavior can be changed through the option <pink>--full-shots</pink> to produce a more accurate result or capture windows that do not generate X events on change, such as windows with accelerated 3D context, but this will notably increase the workload. ⚠️

---

recordMyDesktop doesn't have a user interface in the conventional sense. After startup, it can be controlled only through the following signals:

• <purple>SIGUSR1</purple> — causes the program to pause if it's currently recording, and vice-versa. ⏸️
• <purple>SIGTERM</purple> <purple>SIGINT</purple> — cause normal termination of the recording. 🛑
• <purple>SIGABRT</purple> — terminates the program and removes the output file. 😱

These signals can also be delivered to the application through the configuration of keyboard shortcuts. See <pink>--pause-shortcut</pink> and <pink>--stop-shortcut</pink> in the Miscellaneous subsection of the Options section below. ⌨️✨

For further manipulation of the end result, consult the Options and Notes sections below. 🧚

✨ OPTIONS ✨

okay so real talk, bestie: if and only if you pass zero options, recordMyDesktop will take a single operand and read it as your output filename. That's it. That's the deal.

But it also accepts so many command-line options, like a whole wardrobe, and we're gonna sort them into families so it doesn't feel like a jumbled pile on your floor. 💅

---

🎀 General 🎀

• -h, --help — prints a little summary of usage and dips. bye! 👋
• --version — prints the program version and exits.
• --print-config — prints the deets about which options got selected when the program was compiled, then exits. Right now it tells you whether Jack capture is enabled and whether ALSA or OSS is in use; it may spill more info in the future. ✨

🖼️ Image 🖼️

• --windowid wid — records the region of the screen that corresponds to the X window wid at the time recordMyDesktop starts. Okay important: recording a window does not track the window itself, it tracks the region it covers. If the window gets moved, recordMyDesktop does not follow it. And if something else is sitting on top of it, the contents of that obscuring window inside the recording region are what gets captured. You can grab an X client's window ID with the xwininfo(1) program; peep the Notes section below. 👀
• --display x-display — connect to the X Window System display at x-display. If you don't say anything, the value of the DISPLAY environment variable is used to figure out the display.
• -x x-offset — restrict the recording region so it starts x-offset pixels in from the left edge of the screen, or from the X window ID you picked with --windowid. Default is 0.
• -y y-offset — restrict the recording region so it starts y-offset pixels down from the top edge of the screen, or from the X window ID you picked with --windowid. Default is 0.
• --width w — restrict the recording region to w pixels wide. Default is the full width of the screen, or of the X window ID you picked with --windowid.
• --height h — restrict the recording region to h pixels tall. Default is the full height of the screen, or of the X window ID you picked with --windowid.
• --dummy-cursor color — draw a dummy cursor instead of the normal one. The color has to be a string, and it's either "black" or "white" — those are literally the only two options, no custom hex, sorry babe. 🖤🤍
• --no-cursor — disables drawing of the cursor entirely. ghost mode.
• --no-shared — don't use the MIT shared memory extension (MIT-SHM). Using this option is not recommended, like at all.
• --full-shots — takes a full screenshot at every single frame. Using this option is not recommended. (do you hear me. not recommended. 🫠)
• --follow-mouse — when this is on, the capture area follows your mouse cursor around. This only actually means anything when the selected area is a subset of the full screen. Heads up: this option implies --full-shots.
• --quick-subsampling — sub-samples chroma planes by throwing away extra pixels. ✂️
• --fps n — tries to capture n frames per second, where n is positive and can be an integer or a floating-point number. Realistically the frame rate you can actually get is limited by your system's hardware and workload, so don't come for me if it's lower. Default is 15.

🔊 Sound 🔊

• --channels n — records up to n channels, where n is a positive integer. Default is 2 (stereo, as the icon intended 🎧).
• --freq n — records at a sample rate of n hertz, where n is a positive integer. Default is 22050 (that's 22.05 kHz).
• --buffer-size n — buffers n bytes of sound data when you're using the ALSA or OSS sound systems, where n is a positive integer. Default is 4096 (4 kiB).
• --ring-buffer-size n — sets the size of the JACK ring buffer in seconds, where n is a positive floating-point number. Default is 3.0.

The total size of the buffer in bytes can be expressed as a C language expression:

ring_buffer_size * sample_rate * number_of_ports
        * sizeof(jack_default_audio_sample_t),

where sizeof(jack_default_audio_sample_t) is normally 4.

• --device sound-device — captures audio from sound-device. The default is default or /dev/dsp, depending on whether ALSA or OSS is being used, respectively.
• --use-jack port ... — records audio from the specified list of space-separated JACK ports. When you use this option, all other audio-related options are ignored — except --no-sound, that one still counts. 👑
• --no-sound — do not record sound. silence, but make it cinematic. 🤫

🎬 Encoding 🎬

• --on-the-fly-encoding — encodes the audio/video data while recording. The default behaviour is to hold off on encoding until recording is fully done.
• --v_quality n — sets the desired video quality to n, an integer between 0 and 63 inclusive; higher is better. Default is 63. Check the Notes section below for the tea.
• --v_bitrate n — sets the desired bit rate of the encoded video to n bits per second. The accepted range of n is between 0 and 200,000,000 inclusive; the default is 0. (The thousands separator is shown here just so it's readable — do not use it in the actual option argument. fr.)
• --s_quality n — sets the desired audio quality to n, an integer between -1 and 10 inclusive; higher is better. Default is 10.

🧚 Miscellaneous 🧚

• --rescue path-to-data — encodes cache data from a previous session into an Ogg Theora file. The filename will be the one that was chosen initially. Any other option you specify alongside this one gets implicitly ignored, and recordMyDesktop will exit once the encoding finishes. This option was added in recordMyDesktop 0.3.7, and it will not work with cache files produced from earlier versions. When you're using this option, keep in mind that recordMyDesktop's cache is not safe with respect to data type sizes and endianness. Wanna find the cached data? See the --workdir option below.

⚠️ big one: that cache is not portable across data type sizes or endianness. don't get cute with it.

• --no-wm-check — when a 3D compositing window manager is detected, the program acts as if --full-shots had been specified. This option disables that check.
• --no-frame — normally a frame gets drawn around the recording region to help you see what is and isn't getting captured. When --follow-mouse is given, that frame follows the pointer around too. However, the frame might cause problems for drag-and-drop operations. If you don't want the frame to show up, use this option.
• --pause-shortcut mod+key — designates a key combination to toggle the pause state of the recording. mod can be any combination of these modifier keys: Control, Shift, and Mod1 to Mod5. The modifiers can be separated by any character (except a space) or by nothing at all. key can be any key defined in /usr/include/X11/keysymdef.h. Leave off the XK_ prefixes from the key names you find in that file. The list of modifiers has to be separated from the key with a plus sign +. The default is Control+Mod1+p. (Mod1 usually corresponds to the left Alt key.)
• --stop-shortcut mod+key — designates a key combination to stop the recording. For all the details, see --pause-shortcut above. The default is Control+Mod1+s.
• --compress-cache — image data gets cached with a light compression. 🗜️
• --workdir dir — recordMyDesktop creates a temporary directory inside dir to cache intermediate files. The default is read from the environment variable TMPDIR if it's set, otherwise /tmp is used.
• --delay n[H|h|M|m] — waits n units of time (seconds, if you don't specify a unit) before starting the recording, where n is a non-negative integral or floating-point value. An optional suffix of H or h, or M or m, indicates time units of hours or minutes, respectively. The default is no delay.
• --overwrite — if the output filename already exists, delete it. The default is to refuse to overwrite, and instead interpolate a numeric discriminator into the filename (see the Files section below).
• -o filename — writes the encoded video to filename. The default is out.ogv.

---

🚦 EXIT STATUS 🚦

An exit status of 0 means success, per the usual Unix conventions. ✨

A non-zero exit status means an error happened; these come with diagnostic messages on standard error. And bestie, several exceptional conditions get their own special exit status, like they're getting an award:

• 1 — Argument parsing failed, or the argument input was nonsensical.
• 2 — Encoder initialization failed (Vorbis or Theora).
• 3 — Could not open or configure the sound device.
• 4 — XDamage extension is not present.
• 5 — MIT-SHM extension is not present.
• 6 — XFixes extension is not present.
• 7 — XInitThreads(3) failed.
• 8 — The DISPLAY environment variable is not set and no --display option was specified.
• 9 — Could not connect to the X server.
• 10 — The color depth of the root window is not 32, 24, or 16 bits per pixel.
• 11 — The recording window specification was invalid.
• 12 — Could not attach shared memory to process.
• 13 — Could not open file for writing.

🌍 ENVIRONMENT 🌍

• DISPLAY — specifies the X server to connect to. For typical use cases this variable is already set correctly in the environment and corresponds to the X display the user is already interacting with (in other words, recordMyDesktop "does the right thing" 💅). See section Display Names in X(7) for more information.

📁 FILES 📁

recordMyDesktop adds the suffix .ogv to any output filename that doesn't already have one (in any letter case). 🎀

If you try to save to a filename that already exists, a numeric discriminator of the form -n gets interpolated into the filename before the .ogv suffix. The number n starts at 1 and keeps incrementing if the filename with that discriminator already exists too.

For example, when you're not specifying a name: if out.ogv exists, the new file will be out-1.ogv, and if that one exists too, out-2.ogv is used, and so on ad infinitum (not really — more like ad unsigned short 😭).

💖 NOTES 💖

🪟 Recoding using an X window ID 🪟

Okay bestie, if you're gonna use the --windowid option, please read its description in the Options section up there, like, carefully — and the same goes for the -x, -y, --width, and --height options too. They're all in this together, iykyk. 👑

An easy way to find out the ID of a window is by using the xwininfo(1) program. Running a command like

$ xwininfo | awk '/Window id:/ {print $4}'

will report only the window ID, which will be a hexadecimal integer in C literal format, like “0x4800005”. Lowkey iconic format ngl. ✨

More conveniently, you can put all that in the command that launches recordMyDesktop like this:

$ recordmydesktop --windowid $(xwininfo | awk '/Window id:/ {print $4}')

Not me nesting a whole command inside another command and it just working. 🫶

---

🎬 Tuning the video quality 🎬

The lower the quality you select on a video recording (by using the --v_quality option), the more CPU performance you will require. So if you are also using the --on-the-fly-encoding option, it's better to start with default values and manipulate the end result with another program. Vibe check: don't cook your CPU for no reason, babe. 💀

An excellent converter is the vlc(1) media player, which can perform a variety of transcoding operations, using either a graphical interface or the command line. vlc is a complex piece of software; you should consult its documentation before using it. An example follows which will resize a recording named out.ogv to 512×384.

$ vlc -I dummy out.ogv vlc:quit --sout "#transcode{ vcodec = theo, width = 512, height = 384 }:duplicate{ dst = std{ access = file, mux=ogg, dst = \"out_512x384.ogv\" }}"

If you wish to change the video quality you can append the option --sout-theora-quality=n, with n in the range [1,10]; for example,

$ vlc -I dummy out.ogv vlc:quit --sout "#transcode{ vcodec = theo, width = 512, height = 384 }:duplicate{ dst = std{ access = file, mux=ogg, dst = \"out_512x384.ogv\" }}" --sout-theora-quality=3

produces a file of a video quality 18 (in a range of 0–63), appropriate for web publishing. Slay. 🍓

Another option is ffmpeg2theora(1), which—despite its name—is also a Theora-to-Theora converter. Changing the quality of a recordng with it can be as simple as:

$ ffmpeg2theora infile.ogv -v 3 -a 4 -o outfile.ogv

It can even perform resizing on the geometry of the recording, or change the overall duration. It's giving multi-talented fr fr. 🌈

---

💀 BUGS 💀

• Does not record 3D windows if --full-shots isn't specified. 🙈
• Saving 65536 files with the same name will result in unpredictable behavior, which might manifest as an endless loop or a segmentation fault. NOT the ending we're manifesting, bestie. 😭

---

👑 AUTHORS 👑

John Varouhakis

---

🌸 SEE ALSO 🌸

X(7), ffmpeg2theora(1), jack_lsp(1), vlc(1), xwininfo(1)

---

And that's a wrap on the whole page, gorgeous! 💅 This lil masterpiece is from recordMyDesktop, dated 2017-04-05, and it's the recordMyDesktop(1) manual page — now go forth and record everything, main character. 🎀🦋 periodt. 💖