summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorVito Caputo <vcaputo@pengaru.com>2020-07-11 16:47:00 -0700
committerVito Caputo <vcaputo@pengaru.com>2020-07-11 16:47:00 -0700
commit3625160acc1715fc380f58ec3c4248485bed2370 (patch)
treedc95a32d81daac298cef69879a639029797fb762 /doc
parentcfcca8681b88a171fb2cdbb83daa5f22bbedb6b8 (diff)
*: drop {gtk,qt}-recordmydesktop subdirs
This restores the recordmydesktop/ subdir as root from the mirror I cloned by fork from. I have no particular interest in the gtk/qt frontends and it doesn't appear they were part of a single tree in the past. But I will probably preserve backwards compatibility of the cli so they can continue to work with this fork installed.
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am2
-rw-r--r--doc/recordmydesktop.1567
2 files changed, 569 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..9780b6c
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,2 @@
+man_MANS = recordmydesktop.1
+EXTRA_DIST = $(man_MANS)
diff --git a/doc/recordmydesktop.1 b/doc/recordmydesktop.1
new file mode 100644
index 0000000..ddaf2b6
--- /dev/null
+++ b/doc/recordmydesktop.1
@@ -0,0 +1,567 @@
+.TH "RECORDMYDESKTOP" 1 "13/7/2006" "Linux"
+
+
+.SH NAME
+recordMyDesktop \- record desktop sessions to an Ogg\-Theora\-Vorbis file.
+
+
+.SH SYNOPSIS
+
+.B recordmydesktop
+[
+.B
+Options
+]^
+.B
+filename
+.br
+.br
+.SH DESCRIPTION
+.PP
+ recordMyDesktop produces a file(default out.ogv) that contains a video and audio recording
+.br
+of a linux desktop session. The default behavior of recording is to mark areas that have changed(through libxdamage)
+.br
+and update the frame. This behavior can be changed (option
+.B
+\-\-full\-shots
+) to produce a more accurate result
+.br
+or capture windows that do not generate events on change(windows with accelerated 3d context)
+.br
+but this will notably increase the workload.
+.br
+recordMyDesktop doesn't have a commandline interface.
+.br
+After startup, it can be controled only through the following signals:
+.br
+.br
+.B
+SIGUSR1
+causes the program to pause if it's currently recording, and vice-versa.
+.br
+.B
+SIGTERM
+causes normal termination of the recording.
+.br
+.B
+SIGINT
+also causes normal termination.
+.br
+.B
+SIGABRT
+terminates the program and removes the specified output file.
+.br
+.br
+This signals can also be delivered on the application, with the use of
+shortcuts.
+.br
+See
+.B
+\-\-pause\-shortcut
+and
+.B
+\-\-stop\-shortcut
+, on the
+.B
+Misc.
+section
+of
+.B
+Options
+bellow.
+.br
+
+.br
+
+.br
+
+A typical scenario of recording can be a command as simple as:
+.br
+.B
+~$ recordmydesktop
+.br
+which will produce a fullscreen recording named out.ogv
+.br
+while a command like:
+.br
+.B
+~$ recordmydesktop foo.ogv
+.br
+will write output to foo.ogv
+.br
+.br
+Since version 0.3, encoding will happen right after the recording finishes.
+.br
+While this behavior saves a lot of CPU, you can revert to the old one by entering the \-\-on\-the\-fly\-encoding switch.
+.br
+.br
+To specify a region for recording you can type this:
+.br
+.B
+~$ recordmydesktop \-x X_pos \-y Y_pos \-\-width WIDTH \-\-height HEIGHT \-o foo.ogv
+.br
+where X_pos and Y_pos specify the offset in pixels from the upper left
+.br
+corner of your screen and WIDTH and HEIGHT the size of the window to be recorded(again in pixels).
+.br
+If the area extends beyond your current resolution, you will be notified appropriately and nothing will happen.
+.br
+Notice also, that if any option is entered you have to specify the output file with the \-o switch.
+.br
+If you try to save under a filename that already exists, the name will be post-fixed with a number (incremented if that name exists already)
+.br
+.br
+.B
+To normally end a recording you can press ctl-c.
+.br
+(which will send a
+.B
+SIGINT
+to the program).
+.br
+.br
+For further manipulation of the end result look at the
+.B
+OPTIONS
+and
+.B
+NOTES
+sections.
+.br
+.br
+.br
+.SH EXIT STATUS
+0 is success
+.br
+Non-zero means an error occurred, which is printed in stderr.
+.br
+.br
+The following error codes indicate the nature of the error:
+.br
+1 Error while parsing the arguments.
+.br
+2 Initializing the encoder failed(either vorbis or theora).
+.br
+3 Could not open/configure sound card.
+.br
+4 Xdamage extension not present.
+.br
+5 Shared memory extension not present.
+.br
+6 Xfixes extension not present.
+.br
+7 XInitThreads failed.
+.br
+8 No $DISPLAY environment variable and none specified as argument.
+.br
+9 Cannot connect to Xserver.
+.br
+10 Color depth is not 32, 24 or 16bpp.
+.br
+11 Improper window specification.
+.br
+12 Cannot attach shared memory to proccess.
+.br
+13 Cannot open file for writting.
+.br
+14 Cannot load the Jack library (
+.B
+UNUSED SINCE 0.3.8
+).
+.br
+15 Cannot create new client.
+.br
+16 Cannot activate client.
+.br
+17 Port registration/connection failure.
+.br
+.br
+.SH OPTIONS
+.PP
+.B
+Generic Options:
+.br
+.TP
+.B
+ \-h or \-\-help
+ Print help summary and exit.
+.br
+.TP
+.B
+ \-\-version
+ Print program version and exit.
+.br
+.TP
+.B
+ \-\-print\-config
+ Print info about options selected during compilation and exit.
+.br
+.PP
+.br
+.B
+Image Options:
+.br
+.TP
+.B
+ \-\-windowid id_of_window
+ id of window to be recorded.
+.br
+.TP
+.B
+ \-\-display DISPLAY
+ Display to connect to.
+.br
+.TP
+.B
+ \-x X
+ Offset in x direction.
+.br
+.TP
+.B
+ \-y Y
+ Offset in y direction.
+.br
+.TP
+.B
+ \-\-width N
+ Width of recorded window.
+.br
+.TP
+.B
+ \-\-height N
+ Height of recorded window.
+.br
+.TP
+.B
+.br
+.br
+.TP
+.B
+ \-\-dummy\-cursor color
+ Draw a dummy cursor, instead of the normal one.Value of color can be "black" or "white".
+.br
+.TP
+.B
+ \-\-no\-cursor
+ Disable drawing of the cursor.
+.br
+.TP
+.B
+ \-\-no\-shared
+ Disable usage of MIT\-shared memory extension
+.B
+(Not Recommended).
+
+.br
+.TP
+.B
+ \-\-full\-shots
+ Take full screenshot at every frame(Not recomended!).
+.br
+.TP
+.B
+ \-\-follow\-mouse
+ When this option is enabled, the capture area follows the mouse cursor. This
+ is meaningfull only when the selected area is a subset of the full screen.
+ This option auto-enables --full-shots.
+.br
+.TP
+.B
+ \-\-quick\-subsampling
+ Do subsampling of the chroma planes by discarding extra pixels.
+.br
+.TP
+.B
+ \-\-fps N(number>0.0)
+ A positive number denoting desired framerate.
+.br
+.br
+.PP
+.B
+Sound Options:
+.br
+.TP
+.B
+ \-\-channels N(number>0)
+ A positive number denoting desired sound channels in recording.
+.br
+.TP
+.B
+ \-\-freq N(number>0)
+ A positive number denoting desired sound frequency.
+.br
+.TP
+.B
+ \-\-buffer\-size N(number>0)
+ A positive number denoting the desired sound buffer size(in frames, when using ALSA or OSS).
+.br
+.TP
+.B
+ \-\-ring\-buffer\-size N(float number>0)
+ A float number denoting the desired ring buffer size (in seconds,when using JACK only).
+ The overall size of the buffer in bytes will be:
+ ring_buffer_size * samplerate * number_of_ports * sizeof(jack_default_audio_sample_t),
+ where sizeof(jack_default_audio_sample_t) is normally 4.
+.br
+.TP
+.B
+ \-\-device SOUND_DEVICE
+ Sound device(default hw:0,0 or /dev/dsp, depending on whether ALSA or OSS is used).
+.br
+.TP
+.B
+ \-\-use\-jack port1 port2... portn
+ Record audio from the specified list of
+.B
+space-separated
+jack ports.
+ When using this option, all the rest audio related ones(except --no-sound) are not taken into account.
+.br
+.TP
+.B
+ \-\-no\-sound
+ Do not record sound.
+.br
+.PP
+.br
+.B
+Encoding Options:
+.br
+.TP
+.B
+ \-\-on\-the\-fly\-encoding
+ Encode the audio-video data, while recording.
+.br
+.TP
+.B
+ \-\-v_quality n
+ A number from 0 to 63 for desired encoded video quality(default 63).
+.br
+.TP
+.B
+ \-\-v_bitrate n
+ A number from 45000 to 2000000 for desired encoded video bitrate(default 45000).
+.br
+.TP
+.B
+ \-\-s_quality n
+ Desired audio quality(\-1 to 10).
+.br
+.PP
+.br
+.B
+Misc Options:
+.br
+.TP
+.B
+ \-\-rescue path_to_data
+ Encode cache data from a previous session, into an Ogg/Theora+Vorbis
+ file. The filename will be the one that was chosen initially.
+ Any other option specified with this one will be implicitly ignored
+ and recordMyDesktop will exit after the end of the encoding.
+ This option was added in recordMyDesktop 0.3.7 and it will not
+ work with cache files produced from earlier versions.
+ When using this option, remember that recordMyDesktop's cache is
+ not safe, in respect to type-sizes and endianness.
+.br
+.TP
+.B
+ \-\-print\-config
+ Print compilation time options. Currently prints whether Jack capture is
+ enabled and if ALSA or OSS is used (may contain more information
+ in the future).
+.br
+.TP
+.B
+ \-\-no\-wm\-check
+ When a 3d compositing window manager is detected the program will function as if the
+ \-\-full\-shots option has been specified. This option disables that
+ behavior alltogether.
+.br
+.TP
+.B
+ \-\-no\-frame
+ Normally, around the recording area, there is drawn a frame to assist
+ the user in identifying what does and what doesn't get captured.
+ This frame will also follow around the mouse, when \-\-follow\-mouse
+ is used. The frame might cause problems for drag and drop. If you do
+ not wish this frame to appear, use this option.
+.br
+.TP
+.B
+ \-\-pause\-shortcut MOD+KEY
+ Shortcut that will be used for pausing or unpausing the recording.
+ MOD can be any combination of the following modifier keys:
+ Control, Shift and Mod1 to Mod5. The modifiers can be separated
+ with any character(
+.B
+except SPACE
+) or none at all. KEY can be any key defined in
+ /usr/include/X11/keysymdef.h without the XK_ prefix.
+ The list of modifiers must be separated from the key with a plus('+')
+ sign.
+ Default is Control+Mod1+p (Mod1 usually corresponds to left Alt).
+
+.br
+.TP
+.B
+ \-\-stop\-shortcut MOD+KEY
+ Shortcut that will be used to stop the recording.
+ For more, see \-pause\-shortcut above.
+ Default is Control+Mod1+s.
+.br
+.TP
+.B
+ \-\-compress\-cache
+ Image data are cached with a light compression.
+.br
+.TP
+.B
+ \-\-workdir DIR
+ Location where a temporary directory will be created to hold project files(default /tmp).
+.br
+.TP
+.B
+ \-\-delay n[H|h|M|m]
+ Number of secs(default),minutes or hours before capture starts(number can be float).
+.br
+.TP
+.B
+ \-\-overwrite
+ If there is already a file with the same name, delete it.
+ Default action is to add a number postfix to the new file.
+ For example when not specifying a name, if out.ogv exists,
+ the new file will be out-1.ogv and if that exists too, out-2.ogv
+ and so on (no ad-infinitum though, more like ad-short-integer...)
+.br
+.TP
+.B
+ \-o filename
+ Name of recorded video(default out.ogv).
+
+
+
+.PP
+.br
+If no other option is specified, filename can be given without the \-o switch.
+.br
+.br
+.SH USAGE
+.TP
+.B recordmydesktop [OPTIONS]^filename
+.br
+.br
+.br
+.br
+.SH ENVIRONMENT
+.TP
+.B
+DISPLAY
+.br
+Display environment variable, specifying X server to connect to.
+.br
+.SH NOTES
+.br
+ Recording a window using the \-\-windowid option, doesn't track the window itself, but the region that it covers.
+.br
+Also when using that option the \-x,\-y,\-\-width and \-\-height options are relative to the specified window area.
+.br
+An easy way to find out the id of a window, is by using the
+.B
+xwininfo
+program.
+.br
+Running a command like :
+.br
+.B
+xwininfo | awk \'/Window id:/ {print $4}\'
+.br
+will give you only the id of the window(which should look like this: 0x4800005)
+.br
+More conviniently you can put all that in the command that launches recordMyDesktop like this:
+.br
+.B
+~$recordmydesktop \-\-windowid $(xwininfo | awk \'/Window id:/ {print $4}\')
+.br
+.br
+ Also, the lower quality you select on a video recording (
+.B
+-v_quality
+option), the highest CPU-power that you will need.
+.br
+So
+.B
+if you are doing the encoding on the fly
+,it's better to start with default values and manipulate
+the end\-result with another program.
+.br
+.br
+An excellent converter is the
+.B
+vlc
+media player, which can perform a variety of transcoding
+.br
+operations, either using the graphical interface, or the commandline for more flexibility.
+.br
+vlc is a complex piece of software, so you should consult it's documentation, before
+.br
+using it.
+.br
+.br
+An example follows, which will resize a recording named out.ogv to 512x384:
+.br
+.B
+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\\" }}"
+.br
+.br
+If you wish to change the video quality you can append the
+.B
+\-\-sout\-theora\-quality=n,
+with
+.B
+n
+in the range
+.B
+[1,10]
+e.g:
+.br
+.B
+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
+.br
+which will give a file of a video quality 18 (in a range of 0-63), thus appropriate for web-publishing.
+.br
+.br
+Another option is
+.B
+ffmpeg2theora
+, which despite its name is also a theora to theora converter.
+.br
+Changing the quality of a recordng with it, can be as simple as :
+.br
+.B
+ffmpeg2theora infile.ogv \-v 3 \-a 4 \-o outfile.ogv
+.br
+It can even perform resizing on the size of the recording, or change the overall duration.
+.br
+.br
+.SH BUGS
+Does not record 3d windows, if \-\-full\-shots isn't specified.
+.br
+Saving 65536 files with the same name, will result in upredictable behavior,
+.br
+which might manifest as an endless loop, or a segmentation fault.
+.br
+.SH AUTHORS
+John Varouhakis(johnvarouhakis@gmail.com)
+.br
+.SH SEE ALSO
+.BR xwininfo(1)
+.br
+.BR vlc(1)
+.br
+.BR ffmpeg2theora(1)
+.br
+.BR jack_lsp(1)
+.br
+
© All Rights Reserved