Reverse Engineering Zoom's Virtual Backgrounds

Zoom, the burgeoning videoconferencing app, lets users liven up their lives by swapping their real-world surroundings for custom images and videos. To alleviate the tedium of changing my background daily I decided to automate the process. The resulting code is available at matthewdean/zoom-cli and this post documents the research which made that possible.

Setting the Virtual Background

Zoom stores its application data in a directory located at %APPDATA%\Zoom\data on Windows and ~/Library/Application Support/zoom.us/data on macOS. Within this directory is an unecrypted SQLite database named zoomus.db.

CREATE TABLE zoom_kv (
	key text,
	value text,
	section text
)

Two of the settings in this database are relevant to us:

key	value	section
com.zoom.client.saved.video.replace_bk_data_1	0:0:0:1:1	ZoomData
com.zoom.client.saved.video.replace_bk_path_1	/Users/Matthew/Library/Application Support/zoom.us/data/VirtualBkgnd_Default/EBE45C35-ABA7-4E8F-B5CC-5206336D2BFA	ZoomData

Setting a virtual background can be done by having the key replace_bk_path_1 reference a fully qualified path of an image or video file. Note that on macOS, pointing to a file in a directory which Zoom does not have access to will result in a permission prompt. replace_bk_data_1 is a semicolon delimited string where the last value is 1 for image backgrounds and 2 for video backgrounds. I do not know what the first four values represent.

Storing Virtual Backgrounds

Virtual background records are persisted in this table:

CREATE TABLE zoom_conf_video_background_a (
	path text primary key, -- fully qualified path to source
	name text,
	type integer, -- 0 = default image, 1 = custom image, 2 = default video, 3 = custom video
	customIndex integer, -- used to order built-in backgrounds
	thumbPath text -- fully qualified path to video thumbnail
)

The underlying source files are scattered across several directories:

• VirtualBkgnd_Custom contains the custom image backgrounds
• VirtualBkgnd_Default contains built-in image backgrounds
• VirtualBkgnd_Video contains built-in video backgrounds
• VirtualBkgnd_VideoThumb contains the path of image thumbnails for custom video backgrounds

When Zoom imports an image background, it scales and crops the image before copying it to the VirtualBkgnd_Custom directory. In contrast, video backgrounds are left in their original directories presumably to avoid copying large files unecessarily. For video backgrounds, Zoom generates 320x180 bitmap thumbnails and stores references to them in the thumbPath field.

For all backgrounds, whether built-in or custom, Zoom generates UUIDs for all file names to avoid collisions and drops file extensions for imported files. The UUIDs are fully uppercase in the 8-4-4-4-12 format and on Windows are surrounded by curly braces.

Ordering Virtual Backgrounds

In the Zoom app, virtual backgrounds are ordered primarily by type (images before videos) and secondarily by custom index ascending.