Pyvnc2swf is a cross-platform screen recording tool.

Pyvnc2swf is a cross-platform screen recording tool. It captures screen motion through VNC protocol and generates a Shockwave Flash (SWF) movie.


Vnc2swf comes in two versions. The older C version is outdated and not recommended. The newer Python version, pyvnc2swf, is the one to install. I installed pyvnc2swf on openSUSE 10.0, but the same download works on any platform with Python and pygame. Pyvnc2swf also requires a VNC server; you can use TightVNC, RealVNC, or UltraVNC, to name a few.


There is not much to getting pyvnc2swf up and running. A tarball is available for use on any system that supports Python -- Linux, Mac OS X, and Windows included. Once you've installed the prerequisite software, use the usual tar -zxvf pyvnc2swf-0.8.2.tar.gz to unpack the archive. You will see a directory named pyvnc2swf-0.8.2. To start pyvnc2swf, go into the newly created directory and run the script vnc2swf.py. This pops up a window with the hostname and port for pyvnc2swf to connect to. You can connect to your local host, in which case the default localhost:5900 is correct.


Once pyvnc2swf starts up, click on the Save As box and choose a name for the recording. There are three file types you can choose to save as: shape, video and VNCRec. According to the documentation, shape seems to be the preferred video format, because it is the most compatible with older versions of Flash. The video format produces the smallest size videos, but they work only with Flash 7 and up. You can convert from shape to video format later. This creates a smaller video that is compatible with older versions of Flash. VNCRec uses an older format for recording VNC sessions that is not Flash-compatible.
In practice you should be fine with the video format, but I'm going to use shape for now so we can explore using pyvnc2swf's editor.


Click Start to begin recording all of the windows on your screen. A one-minute test recording I made took up 376KB of disk space in shape format.


Pyvnc2swf provides two ways to view video. The first is by using the play.py script to play back the file. You can use this method regardless of whether you have Flash player installed.



Pyvnc2swf can also create a Web page with the Flash video embedded in it. My only problem with it is that the default behavior loops the video over and over again. To change this, edit the HTML file and change both instances of loop="True" to loop="False".



Pyvnc2swf suite comes with three Python programs:

• vnc2swf.py - Recorder
• edit.py - Movie editor (This is NOT a general SWF file editor. It only supports movies generated by vnc2swf.)
• play.py - Simple movie viewer

For questions, please read the FAQ and list archives before sending me emails.



Terms and Conditions: Pyvnc2swf comes with ABSOLUTELY NO WARRANTY. This software is distributed under the GNU General Public License.

Installation.

In all platforms, the following packages are required:

• Python (2.4 or above)
• Pygame (1.6 or above)
• Optional: PyMedia (1.3.5 or above - required for mpeg encoding)

In most Linux distros, these packages are readily available. In Mac OS X, you would need an additional OS X build of Pygame package.
Also, you need at least one VNC server:

• RealVNC or TightVNC (Unix, Linux or Windows)
• x11vnc (Unix/Linux for recording an existing desktop)
• OSXVnc (Mac OS X)
• GNOME Vino (This is not an independent package, but if you have GNOME desktop environment which supports remote desktop functionality, you have it.)

Recording.

vnc2swf.py program captures a VNC sessions and records it in either SWF or VNCLog format. This is a VNC client and communicates directly with a VNC server. A user need to start a VNC server in advance.



vnc2swf.py runs in two different modes: GUI (Graphical User Interface) mode and CLI (Command Line Interface) mode. In the GUI mode, start recording by clicking the "Start" button. Then choose the "Save as..." command from the "File" menu to save the recorded movie to a file. In the CLI mode, a user needs to specify the output filename from command line. Recording is started immediately. In both modes, a user is prompted for a VNC password if the server requires authentication (and unless the user doesn't specify the password file). In the CLI mode, hit Control-C to stop recording. After finishing recording, it generates two files with the specified name: a .swf and .html file. The .html file contains an HTML tag and a javascript code to provide seek bar function.




A user can choose three different methods to encode movie image: "flv", "swf5", "swf7", "mpeg" (PyMedia required), or "vnc". The first swf5 encoding (default) provides a reasonable movie size. The second encoding method, swf7 provides a smaller SWF movie. This is, however, not recommended to use within vnc2swf.py for two reasons: This type of encoding is only supported by Flash Player version 7 or newer. Also, generating a movie with on-the-fly swf7 encoding is slower so you might experience frame dropping. Actually, you can convert a swf5-encoded movie into swf7-encoded one after recording by using edit.py, so anyway you don't need to use this method when recording. The third encoding method is vnc. This method generates a .vnc (VNCLog) file, which is compatible with vncrec output file. You can convert it to a SWF movie with edit.py. A .vnc file is not a SWF movie by itself, but its encoding is the fastest.

NOTE: Unlike the C version, vnc2swf.py doesn't handle any user interaction. If you want to control the server's desktop, you need to launch vncviewer or its equivalent separately.

Syntax

• (GUI) $ vnc2swf.py [-o filename] [options] [host[:display] [port]]
• (CLI) $ vnc2swf.py -n -o filename [options] [host[:display] [port]]

Example

<em>(Record a virtual screen)</em> $ <strong>vncserver -geometry 640x480</strong> $ <strong>vnc2swf.py -o out.swf localhost:1</strong>  <em>(Record an existing screen)</em> $ <strong>x11vnc -localhost -viewonly -wait 10 -defer 10 -bg</strong> $ <strong>vnc2swf.py -o out.swf localhost:0</strong>  <em>(Record a remote screen)</em> $ <strong>vnc2swf.py -n -o out.flv vnc.example.com:1</strong>  

If you're using x11vnc, see also recordwin. This is a convenient script to record a particular window.

Recording Tips.

• Use as small screen size as possible, or try to specify the smallest clipping rectangle. With a large screen, VNC's screen polling gets slower and vnc2swf also gets slower for converting bigger images. Using a small screen also helps reducing the movie size.
• Reducing the framerate sometimes helps reducing the movie size. If the generated movie is still very big, try resampling frames or scaling the image with edit.py.
• To record a long movie (more then 20min.), the only available option is to use flv (or mpeg if you have PyMedia). swf5 or swf7 files have a limitation and lcan have up to 16000 frames, which is roughly 22 minutes.
• If you experience frame dropping, try changing the server options for screen polling (if any). If you're using x11vnc, try adding -wait 10 -defer 10.
• When recording flv movie, you can dump a live stream output to stdout by speficing '-' as a filename. But currently I have no idea how to use. (broadcasting your desktop on the web?)

Options

-n

Console mode (no GUI).

-o outputfile

Specifies the output filename. This option is required in CLI mode. In GUI mode, when not specified it prompts the user for the filename. The movie encoding type is usually inferred from the filename, so the filename should end with either ".swf" or ".vnc". Otherwise, the user need to specify the output movie encoding with -t option (see below.)

-C clipping

Specifies the clipping rectangle. The geometry must be as form of "widthxheight+left+top" (e.g. "400x300+120+0"). Unlike other X11 applications, all rectangular components are required. Negative values are not supported.

-r framerate

Specifies the framerate in fps. (default=12.0)

-t encodingtype

Specifies the output movie encoding method ("flv", "mpeg", "swf5", "swf7" or "vnc"). When omitted, the encoding type is automatically inferred from the filename (*.swf = swf5, *.vnc = vnc).

-N

Disables cursor pseudo-encoding. Pyvnc2swf normally tries to use cursor pseudo-encoding to capture a mouse cursor position so that a cursor can be moved separately from a screen image and it reduces the movie size. However this might not work with some vnc servers. This option can be used for disabling the function.

-P passwdfile

Specifies a password file. If specified, its content is automatically loaded and supplied as password when a VNC server requires it. A password file contains an encrypted password string and can be created with vncpasswd. A user can directly specify ~/.vnc/passwd, which normally contains the password for the local vnc server.

-e vncencodings

Specifies the preferred encodings for VNC image transfer (this is different from movie encoding). Normally you don't need to change this option. Encodings are comma-separated integers (default="5,4,0"). Changing encodings might improve recording performance.

-S subprocess (Supported on Un*x only, Python 2.4 or above is required)

Set a command to run during recording. This option is useful for recording voice with a separated program. A command line is a space-separated sequence of arguments which are passed to a child process like a usual shell command line. However the command line is not passed to a shell and the arguments are directly passed to the child process without any substitution. A child process is started immediately after recording starts and sent SIGINT after recording finishes.

-d

Increases debug level.

Editing.

edit.py program is for editing or reorganizing one or multiple movies generated by vnc2swf.py. This program also supports converting a .vnc file into .swf movie, changing the encoding method (swf5->swf7), attaching MP3 audio file to a movie, extracting images from a movie and resampling/scaling/clipping a movie image.
edit.py currently supports only command line interface. The user must give one output filename and one or more input filename(s). Input movies are concatenated sequentially (in the specified order) and the desired effects are applied.

Syntax

$ edit.py -o outfile.swf [options] infile ...

Example

<a name="edit"><em>(Convert .vnc file into .swf with compressed video encoding)</em> $ <strong>edit.py -o out.swf -c -t swf7 input.vnc</strong>  <em>(Attach an mp3 file to .swf)</em> $ <strong>edit.py -o out.swf -a voice.mp3 in.swf</strong>  <em>(Concatenate two movies and extract the frames into another movie)</em> $ <strong>edit.py -o out.swf -f 100-200,350- movie1.swf movie2.swf</strong>  <em>(Clip the top left area of the movie and shrink it to half the size)</em> $ <strong>edit.py -o small.swf -C 320x240+0+0 -s 0.5 in.swf</strong>  <em>(Convert .swf into MPEG)</em> $ <strong>edit.py -o out.mpg input.swf</strong>  <em>(Convert .swf into .flv)</em> $ <strong>edit.py -o out.flv input.swf</strong> </a>

Options

-o outputfile

Specifies the output filename. This option is always required.

-c

Compress a movie with zlib. Compressions is supported for both (swf5 and swf7) types of movies, but usually it's most effective when applied to swf7-encoded movies.

-t encodingtype

Specifies the encoding method for an output movie. When this option is not specified, the encoding type is inferred from the output filename extention.

Type	Extension	Description
swf5	.swf	SWF movie (default)
swf7		SWF movie with stream video encoding support
flv	.flv	FLV movie
mpeg	.mpg	MPEG movie (requires PyMedia)
bmp	.bmp	BMP image sequence
png	.png	PNG image sequence

Note that swf7 encoding is supported only with Flash Player version 7 or newer.

-f frames or
-F frames

Specifies a sequence of frames presented in the output movie. When omitted, all frames are presented in the original order (default). Frames can be specified with a comma-separated list of integers. A range of integers can be also specified by using - (hyphen) sign. For example: 10,200,300-400 specifies the frames whose number is 10 and 200, plus every frame between frame 300 and 400. The beginning (or ending) frame number can be omitted (e.g. -100 or 300-). In this case, the first (or last) frame number is used as the other end of the range. -F option and -f option is same except that -F doesn't chop the audio while -f does. When you're putting audio on the movie, if you use -f and -a option at the same time, it chops an mp3 file according to the selected frames. However, when you want to cast a continuous sound (such as music) onto a whole movie, this might not be the desired effect. In such a case, use -F instead of -f.

-a mp3file

Attaches mp3 file(s) to the movie. (Adding audio to FLV format is currently not supported.) Multiple mp3 files are concatenated in the specified order. NOTE: When specifying multiple mp3 files, make sure every file has the same bitrate as the first one. And do NOT use "variable bitrate" (VBR) mp3 files, as the SWF format doesn't support them!

-s scaling

Rescale the movie image with a specified ratio which is given as a fraction. NOTE: There will be noises with non-multiple scaling (e.g. 0.7).

-C clipping

Clips the movie into a specified rectangle. The geometry must be as form of "widthxheight+left+top" (e.g. "400x300+120+0").

-K keyinterval

Insert a keyframe in every N frames. Keyframes work as hints for Flash Player and are useful for seeking a frame within a long movie. When the number of total frames exceeds 10,000, inserting keyframes in every 500 frames (-K 500) is recommended.

-r framerate

Changes the frame rate of the movie. This option itself doesn't do any frame resampling and simply changes the movie speed. When this option is omitted, edit.py tries to keep the original frame rate in the output movie.

-R resampleframes

Resample (or "thin down") a movie by picking one from every N frames.

-S skipmp3frames

Skip the first N mp3-frames of the mp3 file. When 's' is appended to the number (such as '1.0s'), it indicates the number of seconds instead of frames. This option is useful when there is a time lag between a recorded image and audio.

-B blocksize

Sets the blocksize for swf7 or flv encoding method (default=32). This must be a multiple of 16.

-b

Suppress a seekbar in a generated html file.

-l

Disables movie loop in a generated html file.

-d

Increases debug level.

Previewing.

play.py is a simple player for a .swf or .vnc file. This program might be useful for spotting the right frame number in a recorded movie. However its speed is awkward and audio output is not supported. It only supports vnc2swf-generated files and cannot play general SWF movies. The player accepts the following keys:

• Space / Enter / mouse click: Toggle Play/Stop.
• Left / Right / dragging a seek bar: Skip frames.
• "q" / Escape: Quit.
• "s": Take a snapshot. The image is saved as "inputfile-frameno.bmp".

Syntax

$ play.py [options] moviefile ...

Options

-r framerate

Specifies the framerate to play.

-s scaling

Specifies the scaling ratio with a fraction.

-C clipping

Specifies the clipping rectangle. The geometry must be as form of "widthxheight+left+top" (e.g. "400x300+120+0").

-d

Increases debug level.