plugin-screen-record

SideButton plugin for screen recording on Linux agent VMs via ffmpeg x11grab.

Tools

start_recording

Start an ffmpeg x11grab screen recording on DISPLAY :1.

Parameter	Type	Required	Description
filename	string	no	Base name for the recording file (without extension). Defaults to timestamp-based name.

Returns the output file path and ffmpeg PID.

stop_recording

Stop the currently running screen recording. Sends SIGINT for graceful ffmpeg shutdown (finalizes mp4 container), with a 10-second timeout before force kill.

Returns the final file path and size.

list_recordings

List all screen recordings in ~/.sidebutton/recordings/ with file sizes and timestamps.

Requirements

• Linux with X11 (designed for agent VMs)
• ffmpeg with x11grab support
• Display :1 active (configurable in handlers/start_recording.sh)

Recording Specs

• Format: MP4 (H.264)
• Resolution: 1920x1080
• Frame rate: 10 fps
• Codec preset: ultrafast

File Locations

Path	Purpose
~/.sidebutton/recordings/	Output directory for MP4 files
~/.sidebutton/plugins/screen-record/.state/recording.pid	PID tracking for active recording

Install

sidebutton plugin install /path/to/plugin-screen-record

Or copy directly:

cp -r plugin-screen-record ~/.sidebutton/plugins/screen-record

License

MIT