Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  RFBPROXY (1)


rfbproxy - record, play back, or export a VNC session


Bugs And Caveats
See Also


rfbproxy [OPTION]... ACTION files


rfbproxy is a simple proxy for VNC, which allows recording of screen updates, key presses and mouse events, for later replay to a VNC client or export as a series of PPM frames. It can also record screen updates by connecting to a VNC session shared by other client(s). Exporting as a series of PPMs is the first step towards converting a session to video using tools such as mjpegtools(1), ffmpeg(1), and/or ffmpeg2theora.


ACTION is exactly one of:
-r, --record
  record RFB communications and store them in the file (only one file is allowed for files)
-p, --playback
  play back the RFB communications that were captured to the files
-x, --export
  export as a series of PPM frames written to standard output the RFB communications that were captured to the files
OPTIONS can be:
-c, --stdout
  use stdin and stdout for communications with the client. Useful in conjunction with inetd
-l, --loop (playback only) when file is finished, replay from first FrameBufferUpdate
-d, --date (record only) append date to end of filename
-s, --shared
  (record only) attach to a shared session
-v increase verbosity
  (playback only) when key is pressed, playback will be paused until it is pressed again. key can be either a single lowercase ASCII character or an X Windows keysym in hex (no preceding ’0x’). Note that keys between ’a’ and ’f’ will be interpreted as hexadecimal numbers, and must be specified as ’61’ through ’66’. Backspace is ’ff08’; Return is ’ff0d’; Escape is ’ff1b’; Delete is ’ffff’. (no default)
  (playback only) when multiple files are specified pressing key will cycle between them. Specified in same way as --pause. (no default)
  (proxy record only) capture either screen updates (‘screen’) or keyboard/mouse events (‘events’). If ’events’ are requested, an RFM (remote framebuffer macro) file is recorded that can be played back with rfbplaymacro. (default screen)
  (export only) specify framerate by name or numeric ratio (m/n frames per second) (default ntsc)
:n Occupy VNC display localhost:n (not valid with -c option; default :10).
  (record only) use specified VNC server (default localhost:0)


rfbproxy -r log.fbs
  Wait for a VNC client to connect to localhost:10, then connect to localhost:0 and relay all VNC traffic between them, recording the screen updates in FBS 1.0 format to log.fbs and exiting when the client disconnects. See BUGS AND CAVEATS below for limitations of FBS 1.0.

rfbproxy -rs log.fbs
  Connect to localhost:0 as a shared session and record the screen updates in FBS 1.1 format to log.fbs until killed (CNTL-C or kill).

rfbproxy -p log.fbs
  Wait for a VNC client to connect to localhost:10, then playback the VNC session recorded in log.fbs.

rfbproxy -pl --cycle=ff0d log.fbs
  Looping playback that resets if the Return key hit. Useful for playing back sessions whose colors don’t show right because of client-initiated changes in pixel format; hitting Return right away to reset the playback often helps. See BUGS AND CAVEATS below for a better solution.

rfbproxy -x log.fbs | ppmtoy4m -S 420_jpeg | mpeg2enc -o video.mpg
  Convert the VNC session in log.fbs to MPEG-2 using mjpegtools(1).

rfbproxy -x log.fbs | ppmtoy4m -S 420_jpeg | ffmpeg -f yuv4mpegpipe -i - -vcodec mpeg4 video.avi
  Convert the VNC session in log.fbs to MPEG-4 using ffmpeg(1) (ppmtoy4m(1) is from mjpegtools(1)).

Here’s simple shell script that simultaneously records VNC and audio at DVD’s 48 kHz sample rate (vrec is from sndtools):


function terminate() {
        kill $background_pid

rfbproxy -rs fbs &

vrec -s 48000 -b 16 -r audio

This one converts the recorded fbs/audio pair into a DVD-standard MPEG-2 with MP2 audio using mjpegtools(1) and toolame(1).


rfbproxy -x fbs | ppmtoy4m -S 420_jpeg | \
yuvscaler -n ntsc -O DVD | mpeg2enc -f 8 -o video.mpv
toolame -m mono -s 48 audio audio.mp2
mplex -f 8 -o video.mpg audio.mp2 video.mpv

And this one converts the recorded fbs/audio pair into an DivX6-compatible MPEG-4 with MP3 audio using ffmpeg(1) and lame(1).


lame -m m -x -r -s 48 -h audio audio.mp3
rfbproxy -x fbs | ppmtoy4m -S 420_jpeg | \
ffmpeg -f yuv4mpegpipe -i - -i audio.mp3 \
-vcodec mpeg4 -vtag DivX -b 800 -g 300 -bf 2 -acodec copy video.avi

Both MPEG-2 and MPEG-4 files can be converted to Ogg/Vorbis with ffmpeg2theora:

ffmpeg2theora -o video.ogg video.avi


To avoid recording passwords (even encrypted), rfbproxy discards authentication information when recording a session, and instead changes the recorded authenticated scheme to look like the session used no authentication.

rfbproxy does not authenticate incomming connections in playback mode.

Recording keystrokes with --type=events can record passwords.


A proxy record will create a version 1.0 FBS file whose pixel formats can’t be reliably interpreted, and will probably only work for playback to the same (or a very similar) client that recorded it, and not for export. Shard-session records create version 1.1 FBS files that don’t have this problem.

Playback makes no attempt to handle client FramebufferUpdateRequests; it justs transmits a series of FramebufferUpdates exactly as they were recorded. This defect is most noticeable with clients that pan across a session larger than their window size; the exposed areas will probably remain undrawn by rfbproxy. Clients that switch pixel formats (i.e, xvncviewer) can also be affected by this; parts of the screen can remain drawn in a low-resolution format after the client has switched to a high-resolution format. Fix this by stopping the client from changing pixel formats. For xvncviewer try -autoselect=0 -fullcolor (version 4.1.1) or -noauto -depth 24 (version 3.3.7).

If you intend to use the --loop or --cycle options when playing back an FBS 1.0 file, you cannot use the ZRLE encoding when recording. This is because the zlib state cannot be maintained. FBS 1.1 files do not use ZRLE at all.

Suspending rfbproxy (or any script using it) when recording in shared session mode can freeze all sessions attached to the VNC server.

Neither export nor FBS 1.1 playback work on colormap sessions (only true color is supported).

Pixel formats larger than 32 bits are not supported.


Tim Waugh <>
Brent Baccala <>


vncviewer(1), vncserver(1), Xvnc(1), ppm(5), mjpegtools(1), ffmpeg(1).
Search for    or go to Top of page |  Section 1 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.