1
<?xml version="1.0" encoding="UTF-8"?>
4
Document : xvidcap-manual.xml
5
Created on : 17. September 2006, 12:01
8
Purpose of the document follows.
11
<!DOCTYPE article PUBLIC "PUBLIC:-//OASIS//DTD DocBook XML V4.4//EN"
12
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
13
<!ENTITY appversion "1.1.6">
14
<!ENTITY manrevision "0.2">
15
<!ENTITY date "April 2007">
16
<!ENTITY app "xvidcap">
17
<!ENTITY mf-cap "multi-frame capture">
18
<!ENTITY sf-cap "single-frame capture">
21
<article id="index" lang="en">
22
<!-- please do not change the id; for translations, change lang to -->
23
<!-- appropriate code -->
25
<title>&app; Manual V&manrevision;</title>
28
<holder>Karl H. Beckers</holder>
33
<holder>ME-THE-TRANSLATOR (Latin translation)</holder>
37
<publishername>Karl H. Beckers</publishername>
41
<xi:include href="legal.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
45
<author role="maintainer">
46
<firstname>Karl</firstname>
47
<othername>H.</othername>
48
<surname>Beckers</surname>
49
<email>karl.h.beckers@gmx.net</email>
52
<othercredit role="reviewer">
53
<firstname>Baris</firstname>
54
<surname>Cicek provided information from earlier revisions of the gedit application.</surname>
55
<contrib>Acknowledgements</contrib>
57
<othercredit role="reviewer">
58
<firstname>Ajit</firstname>
59
<surname>George provided information about plugins.</surname>
60
<contrib>Acknowledgements</contrib>
65
<!-- This is appropriate place for other contributors: translators,
66
maintainers, etc. Commented out by default.
67
<othercredit role="translator">
68
<firstname>Latin</firstname>
69
<surname>Translator 1</surname>
71
<orgname>Latin Translation Team</orgname>
72
<address> <email>translator@gnome.org</email> </address>
74
<contrib>Latin translation</contrib>
79
<!-- According to GNU FDL, revision history is mandatory if you are -->
80
<!-- modifying/reusing someone else's document. If not, you can omit it. -->
82
<!-- Remember to remove the &manrevision; entity from the revision entries other
83
than the current revision. -->
85
<revnumber>&app; V0.1</revnumber>
88
<para role="author">Karl H. Beckers <email>karl.h.beckers@gmx.net</email>
90
<para role="publisher">Karl H. Beckers</para>
94
<revnumber>&app; V&manrevision;</revnumber>
97
<para role="author">Karl H. Beckers <email>karl.h.beckers@gmx.net</email>
99
<para role="publisher">Karl H. Beckers</para>
104
<releaseinfo> This manual describes version &appversion; of &app;.
107
<title>Feedback</title>
109
To report a bug or make a suggestion regarding the <application>&app;</application> application or this
110
manual, follow the directions on <ulink url="http://www.sourceforge.net/projects/xvidcap">&app;'s site at SF.net</ulink>.
112
<!-- Translators may also add here feedback address for translations -->
114
<abstract role="description">
115
<para>User manual for the &app; screencam application.</para>
118
<indexterm><primary>xvidcap</primary></indexterm>
119
<indexterm><primary>screencam</primary></indexterm>
120
<indexterm><primary>screencast</primary></indexterm>
122
<!-- ============= Document Body ============================= -->
123
<!-- ============= Introduction ============================== -->
124
<sect1 id="xvidcap-intro">
125
<title>Introduction</title>
127
<application>&app;</application> is a tool that captures movement on a selected area of an X11 screen to files.
128
It does this by taking a configurable number of screenshots per second and saving them either as individual
129
screenshots or as a video. This kind of application, today, is commonly labelled screencam or screencast utility.
130
In fact, one of the oldest of those utilities was <application>Lotus Screencam</application> which served as the
131
inspiration for <application>&app;</application>.
135
<application>&app;</application> can be used in two distinct modes of operation:
139
<guilabel>&sf-cap;</guilabel> -- capture individual screenshots to one file each.
144
<guilabel>&mf-cap;</guilabel> -- capture and encode to video on the fly.
151
<title>Mnemonic</title>
153
The naming of the modes of operation derives from the number of frames that get stored in the output file:
159
<title>Audio Capture</title>
161
<application>&app;</application> can capture audio, but only in &mf-cap; operation.
166
Recording in single-frame capture mode may be more convenient if you wish to preprocess the images before
167
encoding, or if you need other video codecs <application>&app;</application> does not support. Individual images can later be encoded
168
with tools like <ulink type="help" url="man:ffmpeg">ffmpeg</ulink>,
169
<ulink type="help" url="man:mencoder">mencoder</ulink>, or
170
<ulink type="help" url="man:transcode">transcode</ulink>.
174
To report a bug or make a suggestion regarding the <application>&app;</application> application or this manual,
175
follow the directions on <ulink url="http://www.sourceforge.net/projects/xvidcap">&app;'s site at SF.net</ulink>.
179
<sect1 id="xvidcap-get-started">
180
<title>Getting Started</title>
182
<sect2 id="xvidcap-get-started-to-start">
183
<title>To Start &app;</title>
184
<para>You can start <application>&app;</application> in the following ways:</para>
187
<term><guimenu>Applications</guimenu> menu</term>
190
Choose <menuchoice><guisubmenu>Sound & Video</guisubmenu>
191
<guimenuitem>XVidCap Screen Capture</guimenuitem></menuchoice>.
196
<term>Command line</term>
199
Execute the following command: <command>xvidcap</command>. For more
200
information about command line usage see <ulink type="help" url="man:xvidcap">the xvidcap manpage</ulink>.
207
<sect2 id="xvidcap-get-started-u-start">
209
<title>When You Start <application>&app;</application></title>
210
<para>When you start <application>&app;</application>, the following window is displayed:</para>
212
<figure id="xvidcap-window">
213
<title>&app; Control</title>
217
<imagedata fileref="figures/xvidcap-main-ctrl.png" format="PNG"/>
219
<textobject> <phrase>Shows <application>&app;</application> control.</phrase>
226
The window with a proper title and buttons is &app;'s main control, while the red rectangle is
227
the selection frame enclosing the area to capture.
230
<table frame="all" id="xvidcap-get-started-u-start-TBL">
232
&app;'s main control elements:
234
<tgroup cols="2" align="char" charoff="50" char=".">
236
<row id="xvidcap-get-started-u-start-TBL-filename">
241
<imagedata fileref="figures/filename-button.png" format="PNG"/>
243
<textobject> <phrase>Filename Display and Menu</phrase>
250
The <guilabel>Filename Display and Menu</guilabel> displays the current output filename and,
251
if in &mf-cap; mode, the index number of the most recently captured frame in square brackets.
252
In &sf-cap; mode the index number of the current frame will typically be part of the filename.
255
When in &sf-cap; mode a left click resets the frame count to the start. A right-click while
256
not capturing will pop up the <ulink type="help" url="ghelp:xvidcap?xvidcap-menu">main menu</ulink>.
259
<title>Default Capture Mode</title>
260
<para>By default, <application>&app;</application> starts in &mf-cap; mode.</para>
265
<row id="xvidcap-get-started-u-start-TBL-frame-drop-meter">
270
<imagedata fileref="figures/frame-drop-meter.png" format="PNG"/>
272
<textobject> <phrase>Frame Drop Meter</phrase>
279
The <guilabel>Frame Drop Meter</guilabel> provides an indication of how well your capture session can capture at
280
your desired frame rate. If your system is under heavy load, it may not be able to capture
281
as many frames per second as you wish. This will result in a video that plays back too quickly.
282
<application>&app;</application> displays a green status if you can or can almost capture at the desired frame rate. If
283
you have some frame drop the status turns to yellow, or red if there is excessive frame drop.
284
To reduce frame drop you can capture a smaller part of your screen, select a lower frame rate,
285
quit as many other applications putting stress on your system as possible, or run on a more
286
powerful machine. It may also help to <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-TBL-rescale">downscale</ulink>
287
the captured data. Another means for making screen capture lighter on your system is to
288
make use of the XDamage extension. See the corresponding paragraph about the
289
<ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-general">general options tab</ulink>
290
of the preferences dialog.
294
<row id="xvidcap-get-started-u-start-TBL-stop">
299
<imagedata fileref="figures/stop-toggle.png" format="PNG"/>
301
<textobject> <phrase>Stop Button</phrase>
308
The <guilabel>Stop Button</guilabel> stops a running recording session.
312
<row id="xvidcap-get-started-u-start-TBL-pause">
317
<imagedata fileref="figures/pause-toggle.png" format="PNG"/>
319
<textobject> <phrase>Pause Button</phrase>
326
The <guilabel>Pause Button</guilabel> pauses a running or continues a paused recording session.
327
You can also select this before starting to record to start paused.
331
<row id="xvidcap-get-started-u-start-TBL-record">
336
<imagedata fileref="figures/record-toggle.png" format="PNG"/>
338
<textobject> <phrase>Record Button</phrase>
345
The <guilabel>Record Button</guilabel> starts a recording session.
349
<row id="xvidcap-get-started-u-start-TBL-step">
354
<imagedata fileref="figures/step-button.png" format="PNG"/>
356
<textobject> <phrase>Single Snaphot Button</phrase>
363
The <guilabel>Single Snapshot Button</guilabel> is only active in a paused &sf-cap; mode capturing session.
364
Then it allows you to take individual snapshots on a click of this button.
368
<row id="xvidcap-get-started-u-start-TBL-back">
373
<imagedata fileref="figures/back-button.png" format="PNG"/>
375
<textobject> <phrase>Rewind Button</phrase>
382
The <guilabel>Rewind Button</guilabel> has different uses depending on the current capture mode.
385
In &sf-cap; mode <quote>rewinding</quote> relates to the index number of the current frame to
386
capture. Imagine you have a stopped capture session that has captured ten PNG images. The filename
387
display may show <quote>test-0010.png</quote>. You then realize, the last two snapshots weren't
388
what you needed. You can then click the rewind button twice. This changes the filename display to
389
<quote>test-0008.png</quote>. If you continue to capture, frames eight and nine in images <quote>test-0008.png</quote>
390
and <quote>test-0009.png</quote> will be overwritten.
393
In &mf-cap; mode the rewind button works quite similar. It does not, however, manipulate the
394
index number of the current frame, but rather of the current movie as it relates to the
395
<ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-TBL-autocontinue">autocontinue</ulink>
400
<row id="xvidcap-get-started-u-start-TBL-fwd">
405
<imagedata fileref="figures/fwd-button.png" format="PNG"/>
407
<textobject> <phrase>Forward Button</phrase>
414
The <guilabel>Forward Button</guilabel> does the opposite of the rewind button in that it
415
increments the current frame's index number or the movie index number depending on capture mode.
419
<row id="xvidcap-get-started-u-start-TBL-lock">
424
<imagedata fileref="figures/lock-toggle.png" format="PNG"/>
426
<textobject> <phrase>Frame Selection Lock</phrase>
433
The <guilabel>Frame Selection Lock</guilabel> makes the capture selection move with the
434
main control if selected. If deselected, the capture selection will stay where it is when
435
the main control moves.
439
<row id="xvidcap-get-started-u-start-TBL-selector">
444
<imagedata fileref="figures/selector-button.png" format="PNG"/>
446
<textobject> <phrase>Frame Selector Button</phrase>
453
Click the <guilabel>Frame Selector Button</guilabel> to change the area you want to capture.
454
When you click it, the cursor changes to a cross-hair cursor. After that you can either:
459
click on a single window to capture that window.
462
<title>Moving Captured Windows</title>
464
Note that the area selection is not sticky to the window in the sense that it
465
would follow the window you originally selected, if you move it away. All it
466
does is adjust position and dimension of the selected capture area to match
467
the contents of the window clicked on. If you move the window afterwards, the
468
capture area will stay where it is, unless you have the frame selection lock
469
enabled and manually move the main control to the right position.
475
click and drag to select an arbitrary portion of the screen.
480
click on the backdrop to select full-screen capture.
483
<title>Full-Screen Capture</title>
485
With current display sizes, full-screen capture has a very high probability of
486
putting too much stress on your system. Watch the frame drop monitor and possibly
487
adjust your screen resolution if you absolutely must capture full-screen.
488
Remember that DVDs typically contain resolutions of 720 x 486. Capturing full-screen
489
at a resolution of 1400 x 1050 means encoding about 4 times the data rate of a DVD
490
in real time -- not something you will be doing with a pencil and paper.
492
It is not just the encoding of a full screen capture, though, that may put
493
too much stress on your system. Grabbing the complete capture area from the X11
494
display is a heavy task on its own right. Using the XDamage extension may ease
495
the effect of that, however there may be caveats. See the corresponding paragraph about the
496
<ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-TBL-set-xdamage">general options tab</ulink>
497
of the preferences dialog.
504
<title>Resize By Dragging</title>
506
Starting with version 1.1.5, you can also resize the area to capture by dragging on
507
the edges of the frame while not capturing. Use that feature as you would resize a
513
<row id="xvidcap-get-started-u-start-TBL-edit">
518
<imagedata fileref="figures/edit-button.png" format="PNG"/>
520
<textobject> <phrase>Edit Button</phrase>
527
The <guilabel>Edit Button</guilabel> calls an external program to edit the most recently
528
captured frame in &sf-cap; mode or the current video in &mf-cap; mode. <application>&app;</application> does not
529
provide those applications. By default, <application>&app;</application> calls <application>gimp</application> in
530
&sf-cap; mode and nothing at all in &mf-cap; mode. Both settings can be changed through
531
the <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-cmd">preferences dialog</ulink>.
541
<sect2 id="xvidcap-menu">
543
<title>Main Menu</title>
544
<para>A right-click on the filename display pops up the following menu:</para>
546
<figure id="xvidcap-menu-screenshot">
547
<title>Main Menu</title>
551
<imagedata fileref="figures/menu.png" format="PNG"/>
553
<textobject> <phrase>Main Menu</phrase>
559
<table frame="all" id="xvidcap-menu-TBL">
561
the main menu's items:
563
<tgroup cols="2" align="char" charoff="50" char=".">
565
<row id="xvidcap-menu-TBL-prefs">
570
<imagedata fileref="figures/menu-prefs.png" format="PNG"/>
572
<textobject> <phrase>Preferences Menuitem</phrase>
579
open the preferences dialog
583
<row id="xvidcap-menu-TBL-save-prefs">
588
<imagedata fileref="figures/menu-save-prefs.png" format="PNG"/>
590
<textobject> <phrase>Save Preferences Menuitem</phrase>
597
save the current settings
600
<title>Volatile Settings</title>
602
Note that <application>&app;</application> does not save changed preferences automatically. You can
603
modify settings, exit <application>&app;</application>, and return to your previous settings by just
604
restarting <application>&app;</application>. If you want to make changes to your settings persistent,
605
select this. It will write your settings to a file <filename>.xvidcaprc</filename>
606
in your home directory.
611
<row id="xvidcap-menu-TBL-mf">
616
<imagedata fileref="figures/menu-mf.png" format="PNG"/>
618
<textobject> <phrase>Multi-Frame Menuitem</phrase>
625
select multi-frame capture mode
628
<title>Parallel Settings for Capture Modes</title>
630
Keep in mind that you can have distinct settings for &mf-cap; and &sf-cap;
631
modes configured and stored in parallel. Choosing this menuitem or the next
632
toggles between the two modes and their respective settings.
637
<row id="xvidcap-menu-TBL-sf">
642
<imagedata fileref="figures/menu-sf.png" format="PNG"/>
644
<textobject> <phrase>Single-Frame Menuitem</phrase>
651
select single-frame capture mode
655
<row id="xvidcap-menu-TBL-autocontinue">
660
<imagedata fileref="figures/menu-cont.png" format="PNG"/>
662
<textobject> <phrase>Autocontinue Menuitem</phrase>
669
toggle autocontinue feature on/off
672
This is selectable only in &mf-cap; mode
673
and only if the filename is mutable. Refer to
674
<ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-TBL-autocontinue">the autocontinue prefernces
675
setting</ulink> for more information.
679
<row id="xvidcap-menu-TBL-make-video">
684
<imagedata fileref="figures/menu-make-video.png" format="PNG"/>
686
<textobject> <phrase>Make Video Menuitem</phrase>
693
execute encoding command set in preferences
696
In &mf-cap; mode this is not at all
697
needed and not set by default. It can, however, be set to allow executing a custom
698
transcoding command if output is needed in a format other than <application>&app;</application> can generate.
699
The script used in &sf-cap; mode by default is provided by <application>&app;</application> but may need to be
700
copied to your executable path to make it available. Refer to
701
<ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-cmd">the commands
702
preferences tab</ulink> for more information on setting encoding commands.
706
<row id="xvidcap-menu-TBL-animate">
711
<imagedata fileref="figures/menu-animate.png" format="PNG"/>
713
<textobject> <phrase>Animate/Play Menuitem</phrase>
720
execute playback command set in preferences
723
In &mf-cap; mode this is <application>mplayer</application>
724
and <application>animate</application> (part of ImageMagick) by default. Refer to
725
<ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-cmd">the commands
726
preferences tab</ulink> for more information on setting encoding commands.
730
<row id="xvidcap-menu-TBL-help">
735
<imagedata fileref="figures/menu-help.png" format="PNG"/>
737
<textobject> <phrase>Help Menuitem</phrase>
748
<row id="xvidcap-menu-TBL-about">
753
<imagedata fileref="figures/menu-about.png" format="PNG"/>
755
<textobject> <phrase>About Menuitem</phrase>
762
pop up <application>&app;'s</application> about dialog
766
<row id="xvidcap-menu-TBL-quit">
771
<imagedata fileref="figures/menu-quit.png" format="PNG"/>
773
<textobject> <phrase>Quit Menuitem</phrase>
780
exit <application>&app;</application>
791
<sect1 id="xvidcap-prefs">
792
<title>Preferences</title>
795
You can start the Preferences dialog either by right-clicking on the main control's
796
filename display and selecting <quote>Preferences</quote> or pressing CTRL-P. The
797
dialog itself is divided into four tabs.
800
<sect2 id="xvidcap-prefs-general">
801
<title>General Preferences</title>
804
The first tab of the preferences dialog contains miscellaneous settings around
805
general behaviour of <application>&app;</application>.
808
<figure id="xvidcap-prefs-general-screenshot">
809
<title>General Preferences</title>
813
<imagedata fileref="figures/prefs-general.png" format="PNG"/>
815
<textobject> <phrase>General Preferences</phrase>
821
<table frame="all" id="xvidcap-prefs-general-TBL">
823
the general settings are:
825
<tgroup cols="2" align="char" charoff="50" char=".">
827
<row id="xvidcap-prefs-general-TBL-dflt-mode">
835
This setting governs which capture mode is used by <application>&app;</application> by default, i. e. if
836
no other settings give <application>&app;</application> a clue.
840
<row id="xvidcap-prefs-TBL-cap-mouse">
843
Capture Mouse Pointer
848
Check this to capture the mouse pointer.
851
<title>Custom Mouse Pointer Shapes</title>
853
Without the XFixes extension to X11, there is no way for <application>&app;</application> to
854
capture the real, current mouse pointer, only its position. If the extension is not available both
855
on the machine where <application>&app;</application> was built and where it is run,
856
<application>&app;</application> generates a dummy mouse pointer in the captured movie.
857
In this case you will find a radiobutton next to this checkbox which
858
allows you to select whether the dummy pointer should be white or black.
863
<row id="xvidcap-prefs-TBL-save-cap-geometry">
866
Save Capture Geometry
871
Check this if you want to store size and position of the currently
872
selected area to capture along with other preferences on selecting
873
<quote>Save Preferences</quote> from the main menu.
877
<row id="xvidcap-prefs-TBL-use-shm">
885
Check this if capturing frames should make use of X11's shared
889
<title>Shared Memory X11 Access</title>
891
Use of shared memory is enabled by default if the machine where
892
<application>&app;</application> was built supported shared memory access in X11, which is
893
typically the case, nowadays. You will need to turn this off, however, if
894
X11 server and client are not running on the same machine, e. g.
895
if you are on a X terminal thin client.
900
<row id="xvidcap-prefs-TBL-set-xdamage">
908
Check this if you want to override the decision <application>&app;</application> makes
909
about whether or not to use the XDamage extension to speed up screen capture. This
910
extension allows <application>&app;</application> to be notified about the portions
911
of the screen that have changed between individual frames, so it does not need to
912
fetch the complete area to capture for every frame. <application>&app;</application> will
913
default to using XDamage if it was available at build-time, if it is available at
914
runtime, and if the window manager used is not compiz or beryl. If you are using
915
beryl and still want to use the XDamage extension, check this control to enable the
916
radiobuttons to the right and choose "enabled".
919
<title>XDamage and compiz or beryl</title>
921
Due to the advanced visual effects possible with compiz, beryl and the likes,
922
the notifications received by <application>&app;</application> through XDamage
923
may not be sufficient for determining the right screen portions to capture.
924
You can still force <application>&app;</application> to use it as described
925
above, but your mileage may vary.
930
<row id="xvidcap-prefs-TBL-autocontinue">
938
If recording in &mf-cap; mode and using a maximum number of frames to
939
capture or a maximum capture duration, <application>&app;</application> can automatically continue
940
capturing to a new video once the specified maximum number of frames or
941
capture duration have been reached. This can effectively create a series
942
of movies split to chunks of the specified maximum length. To use this
943
you need to specify a <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-sf-TBL-file-name">mutable target filename</ulink>.
947
<row id="xvidcap-prefs-TBL-always-show-results">
950
Always Show Results Dialog
955
Check this to always show a dialog with an overview of capture results
956
on stopping a capture session. The dialog will always be shown if
957
required (e. g. to specify a target filename). This makes the dialog
958
be shown where it would not strictly be required. By default the results
959
dialog is always displayed. If, however, you have unchecked the
960
<quote>Show this dialog next time</quote> in the results dialog before,
961
you can turn it back on here.
965
<row id="xvidcap-prefs-TBL-minimize-to-tray">
968
Minimize to System Tray
973
Check this to make <application>&app;</application> minimize to the
974
system tray on starting a recording session. In that case the main
975
control panel will hide and the frame drop monitor will apear in the
976
system tray. A right-click on it will allow you to pause or stop the
977
recording session. On stopping the main control window will be
982
<row id="xvidcap-prefs-TBL-rescale">
985
Rescale Output Percentage
990
Use this to make the output video smaller than the original size of the
991
portion of the screen captured. The percentage specified here is the
992
size of the output relative to the input. For example, specifying
993
<quote>25</quote> will make the output width and height half the
994
original each. Thus the image size of the output will be 25 percent of
998
<title>Rescale does not work with XWD output</title>
1000
Rescaling output frames does work with all output formats and codecs
1011
<sect2 id="xvidcap-prefs-sf">
1012
<title>Single-Frame Capture Preferences</title>
1015
This tab contains the settings for &sf-cap; mode. Because &sf-cap; mode does
1016
not support audio capture, only video settings are configurable here.
1019
<figure id="xvidcap-prefs-sf-screenshot">
1020
<title>Single-Frame Capture Preferences</title>
1024
<imagedata fileref="figures/prefs-sf.png" format="PNG"/>
1026
<textobject> <phrase>Single-Frame Capture Preferences</phrase>
1032
<table frame="all" id="xvidcap-prefs-sf-TBL">
1034
the &sf-cap; mode settings are:
1036
<tgroup cols="2" align="char" charoff="50" char=".">
1038
<row id="xvidcap-prefs-sf-TBL-file-name">
1046
Enter a file name pattern here to use for saving the individual
1047
frames captured. The file name must contain a pattern that will
1048
be replaced by the actual frame count for each individual file.
1049
The patterns used here are those understood by
1050
<ulink type="help" url="man:fprintf">fprintf</ulink>.
1051
A file name containing this kind of pattern will henceforth be
1052
called a <quote>mutable</quote> file name.
1055
<title>File Name Selection</title>
1057
Instead of typing in a filename you can also click on the file
1058
selector button (<guibutton>...</guibutton>). Be sure to put a
1059
numeric pattern in the file name afterwards, though. If in
1060
doubt use <quote>%5d</quote> somewhere in your file name.
1065
<row id="xvidcap-prefs-sf-TBL-format">
1073
A check in the <guilabel>auto</guilabel> checkbox makes <application>&app;</application>
1074
automatically select an appropriate output format based on the
1075
filename specified. For example, if you specify <quote>test-%4d.png</quote>
1076
the output format will be <quote>Portable Network Graphics File (png)</quote>.
1077
If the <guilabel>auto</guilabel> checkbox is unchecked, the dropdown
1078
menu allows for manually selecting a format, possibly overriding
1079
<application>&app;'s</application> decision.
1083
<row id="xvidcap-prefs-sf-TBL-fps">
1091
The number of frames to capture per second.
1095
<row id="xvidcap-prefs-sf-TBL-max-time">
1103
Maximum time to record in seconds
1107
<row id="xvidcap-prefs-sf-TBL-max-frames">
1115
Maximum frames to capture
1119
<row id="xvidcap-prefs-sf-TBL-frame-start">
1127
Start counting frames with this number
1131
<row id="xvidcap-prefs-sf-TBL-frame-increment">
1134
Frame Number Increment
1139
When capturing increment the frame count by the specified number
1140
for each frame captured.
1143
<title>Deprecated Settings</title>
1145
Due to the limited use of <quote>Frame Start Number</quote> and
1146
<quote>Frame Number Increment</quote> those settings may go away
1152
<row id="xvidcap-prefs-sf-TBL-quality">
1160
Desired output quality
1163
<title>Quality Setting changed in 1.1.5</title>
1165
The effect of setting quality to a value below 100 % has changed in
1166
<application>&app;</application> 1.1.5. Be sure to test the values
1167
in your stored preferences. Quality settings do not apply to XWD
1178
<sect2 id="xvidcap-prefs-mf">
1179
<title>Multi-Frame Capture Preferences</title>
1182
This tab contains the settings for &mf-cap; mode.
1185
<figure id="xvidcap-prefs-mf-screenshot">
1186
<title>Multi-Frame Capture Preferences</title>
1190
<imagedata fileref="figures/prefs-mf.png" format="PNG"/>
1192
<textobject> <phrase>Multi-Frame Capture Preferences</phrase>
1198
<table frame="all" id="xvidcap-prefs-mf-TBL">
1200
the &mf-cap; mode video settings are:
1202
<tgroup cols="2" align="char" charoff="50" char=".">
1204
<row id="xvidcap-prefs-mf-TBL-file-name">
1212
Enter a file name or file name pattern here to use for saving the individual
1213
frames captured. For &mf-cap; the string supplied here only needs to be
1214
a <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-sf-TBL-file-name">mutable filename</ulink>
1215
if the <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-TBL-autocontinue">autocontinue feature</ulink>
1216
is to be used. Otherwise a simple filename is sufficient here, which may also be
1217
selected through the file selector button (<guibutton>...</guibutton>).
1221
<row id="xvidcap-prefs-mf-TBL-format">
1229
A check in the <guilabel>auto</guilabel> checkbox makes <application>&app;</application>
1230
automatically select an appropriate output format based on the
1231
filename specified. For example, if you specify <quote>test.avi</quote>
1232
the output format will be <quote>Microsoft Audio Video Interleaved File (avi)</quote>.
1233
If the <guilabel>auto</guilabel> checkbox is unchecked, the dropdown
1234
menu allows for manually selecting a format, possibly overriding
1235
<application>&app;'s</application> decision.
1239
<row id="xvidcap-prefs-mf-TBL-vid-codec">
1247
A check in the <guilabel>auto</guilabel> checkbox makes <application>&app;</application>
1248
automatically select an appropriate video codec for the output format selected.
1249
For example, if <quote>Microsoft Audio Video Interleaved File (avi)</quote> is
1250
selected the video codec will be <quote>Microsoft DIVX 2</quote>.
1251
If the <guilabel>auto</guilabel> checkbox is unchecked, the dropdown
1252
menu allows for manually selecting a codec, possibly overriding
1253
<application>&app;'s</application> decision.
1257
<row id="xvidcap-prefs-mf-TBL-fps">
1265
The number of frames to capture per second. This control can either be
1266
a scale or a dropdown menu, if the selected codec only supports certain
1271
<row id="xvidcap-prefs-mf-TBL-max-time">
1279
Maximum time to record in seconds
1283
<row id="xvidcap-prefs-mf-TBL-max-frames">
1291
Maximum frames to capture
1295
<row id="xvidcap-prefs-mf-TBL-quality">
1303
Desired output quality
1306
<title>Quality Setting changed in 1.1.5</title>
1308
The effect of setting quality to a value below 100 % has changed in
1309
<application>&app;</application> 1.1.5. Be sure to test the values
1310
in your stored preferences. In the past a quality setting of <quote>20</quote>
1311
could yield good results depending on the codec chosen. This is no longer
1312
the case. A setting of <quote>75</quote> may be acceptable to you, a
1313
value of <quote>85</quote> will typically be. A video resulting from a
1314
capture with a quality setting of <quote>90</quote> will not normally
1315
be easy to distinguish from one captured at <quote>100</quote> percent
1325
<table frame="all" id="xvidcap-prefs-mf-TBL-audio">
1327
the &mf-cap; mode audio settings are:
1329
<tgroup cols="2" align="char" charoff="50" char=".">
1331
<row id="xvidcap-prefs-mf-TBL-audio-enable">
1339
Check this to capture audio along with video frames.
1343
<row id="xvidcap-prefs-mf-TBL-audio-device">
1351
Type in the name of the input device to caputer audio from or
1352
select it through the file selector button (<guibutton>...</guibutton>).
1356
<row id="xvidcap-prefs-mf-TBL-audio-codec">
1364
A check in the <guilabel>auto</guilabel> checkbox makes <application>&app;</application>
1365
automatically select an appropriate audio codec for the video output format selected.
1366
For example, if <quote>Microsoft Audio Video Interleaved File (avi)</quote> is
1367
selected the audio codec will be <quote>MPEG2</quote>.
1368
If the <guilabel>auto</guilabel> checkbox is unchecked, the dropdown
1369
menu allows for manually selecting a codec, possibly overriding
1370
<application>&app;'s</application> decision.
1374
<row id="xvidcap-prefs-mf-TBL-audio-smpl-rate">
1382
Audio sample rate. If you're using piped input audio the audio stream
1383
is resampled to the specified rate if required.
1386
<title>Piped Audio Input</title>
1388
Instead of capturing audio from a real-time audio source, you can
1389
also pipe a pre-recorded audio file to <application>&app;</application>. This way you can
1390
effectively dub your recording with a given audio track. To do
1394
<application>cat</application> my.mp3 | <application>&app;</application>
1395
<parameter>--mf</parameter> <parameter>--audio yes</parameter>
1396
<parameter>--audio_in -</parameter> <parameter>--file test.avi</parameter>
1399
When you start the recording session in <application>&app;</application> it will sample audio
1400
from the piped file.
1405
<row id="xvidcap-prefs-mf-TBL-audio-bit-rate">
1413
Audio bit rate. If you're using piped input audio the audio stream
1414
is resampled to the specified rate if required.
1418
<row id="xvidcap-prefs-mf-TBL-audio-channels">
1426
Number of audio channels. If you're using piped input audio the audio stream
1427
is resampled to the specified number of channels if required.
1437
<sect2 id="xvidcap-prefs-cmd">
1438
<title>Command Preferences</title>
1441
This tab contains various settings regarding which commands to execute
1442
for certain actions.
1445
<figure id="xvidcap-prefs-cmd-screenshot">
1446
<title>Command Preferences</title>
1450
<imagedata fileref="figures/prefs-commands.png" format="PNG"/>
1452
<textobject> <phrase>Command Preferences</phrase>
1458
<table frame="all" id="xvidcap-prefs-cmd-TBL">
1460
possible commands to set are:
1462
<tgroup cols="2" align="char" charoff="50" char=".">
1464
<row id="xvidcap-prefs-cmd-TBL-sf-playback">
1467
Single Frame Playback Command
1472
The command specified here is executed when the item <guimenuitem>Animate / Play</guimenuitem>
1473
is selected from the main menu or the play button is pressed on the capture
1474
results dialog while in &sf-cap; mode.
1477
<title>Specifying Commands</title>
1479
Any command can be configured here. It could theoretically be
1480
completely unrelated to video capture. You will always want to
1481
make sure that the called application is in your path and that
1482
you end your command line with the <application>&</application> to avoid that <application>&app;</application>
1483
waits for the called application to finish before continuing
1487
<application>&app;</application> makes the following environment variables available to
1488
the called application:
1490
<table frame="non" id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL">
1491
<tgroup cols="2" align="char" charoff="50" char=".">
1493
<row id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL-fframe">
1501
number of the first frame captured
1505
<row id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL-lframe">
1513
number of the last frame captured
1517
<row id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL-width">
1525
width of the area captured
1529
<row id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL-height">
1537
height of the area captured
1541
<row id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL-fps">
1549
desired (!) frame rate
1553
<row id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL-time">
1561
desired (!) time per frame
1565
<row id="xvidcap-prefs-cmd-TBL-cmd-vars-TBL-filename">
1581
The file name, however, needs special treatment for &sf-cap;. Here the
1582
pattern used for <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-sf-TBL-file-name">mutable file names</ulink>
1583
is sent literally as specified for the Single Frame Encoding Command further down only.
1584
For the Single Frame Playback Command the pattern is converted to wildcards, i. e.
1585
<quote>test-%4d.png</quote> becomes <quote>test-????.png</quote>. For the
1586
Single Frame Edit Command the pattern is replaced with the number of the
1587
current frame, i. e. <quote>test-%4d.png</quote> becomes <quote>test-0001.png</quote>.
1588
For all Multi Frame commands the latter is used where if the filename is mutable
1589
and the number used is the index number of the most recently recorded video as
1590
with the <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-TBL-autocontinue">autocontinue feature</ulink>.
1595
<row id="xvidcap-prefs-cmd-TBL-sf-encode">
1598
Single Frame Encoding command
1603
The command here is executed when the main menu's <guimenuitem>Make Video</guimenuitem>
1604
item is selected while in &sf-cap; mode.
1608
<row id="xvidcap-prefs-cmd-TBL-sf-edit">
1611
Single Frame Edit Command
1616
The command here is executed when the main control's <guibutton>Edit Button</guibutton>
1617
is clicked while in &sf-cap; mode.
1621
<row id="xvidcap-prefs-cmd-TBL-mf-playback">
1624
Multi Frame Playback Command
1629
The command specified here is executed when the item <guimenuitem>Animate / Play</guimenuitem>
1630
is selected from the main menu or the play button is pressed on the capture
1631
results dialog while in &mf-cap; mode.
1635
<row id="xvidcap-prefs-cmd-TBL-mf-encode">
1638
Multi Frame Transcoding command
1643
The command here is executed when the main menu's <guimenuitem>Make Video</guimenuitem>
1644
item is selected while in &mf-cap; mode.
1648
<row id="xvidcap-prefs-cmd-TBL-mf-edit">
1651
Multi Frame Edit Command
1656
The command here is executed when the main control's <guibutton>Edit Button</guibutton>
1657
is clicked while in &mf-cap; mode.
1667
<sect1 id="xvidcap-results">
1668
<title>Capture Results Dialog</title>
1671
When you first stop a recording session, a dialog will pop up displaying
1672
the results of the capture session. This popup can be prevented from
1673
appearing again by unchecking the <guibutton>Show Next Time</guibutton>
1674
checkbox or <ulink type="help" url="ghelp:xvidcap?xvidcap-prefs-TBL-always-show-results">this button</ulink>
1675
in the preferences dialog.
1678
The dialog itself can take one of two forms depending on whether or not
1679
you configured <application>&app;</application> to ask you for a target file name after the capture.
1682
<title>Ask User For File Name</title>
1684
For the time being, the only way to configure <application>&app;</application> to ask the user
1685
to specify a file name after the capture rather than providing one
1686
up-front it by providing an empty file name either through the
1687
command line using <parameter>--file ""</parameter> or in the preferences
1688
dialog. This requires manually specifying an output file format.
1689
In this configuration <application>&app;</application> will store the video in a temporary file
1690
in your home directory which can lateron be renamed / moved to the
1691
desired destination. This is not compatible with autocontinue.
1696
If <application>&app;</application> is configured to ask the user for a file name, the results dialog
1697
will look like this:
1699
<figure id="xvidcap-results-ask-screenshot">
1700
<title>Capture Results Dialog with Ask User For File name</title>
1704
<imagedata fileref="figures/results-dialog-ask.png" format="PNG"/>
1706
<textobject> <phrase>Capture Results Dialog with Ask User For File name</phrase>
1713
Besides the overview of the used settings and information about the desired
1714
and achieved frame rates, you can select name and location of the file you
1715
want the video to be stored in through clicking <guibutton>Save As</guibutton>.
1716
Once a file has been selected, the label next to the button will display the
1717
absolute file name. You can also choose to preview the video through
1718
<guibutton>Play</guibutton> or abandon it through <guibutton>Delete</guibutton>.
1719
Note that the latter does not immediately delete the temporary file, though.
1723
Normally, the results dialog will look like this:
1725
<figure id="xvidcap-results-screenshot">
1726
<title>Normal Capture Results Dialog</title>
1730
<imagedata fileref="figures/results-dialog.png" format="PNG"/>
1732
<textobject> <phrase>Normal Capture Results Dialog</phrase>
1740
<sect1 id="xvidcap-warning">
1741
<title>The Preferences Warning Dialog</title>
1743
Whenever <application>&app;</application> determines that the settings you have chosen will
1744
not work well, it will display those issues in a standardized format. Unless you run
1745
<application>&app;</application> with the <parameter>--gui no</parameter> parameter,
1746
it will pop up the following dialog:
1749
<figure id="xvidcap-warn-window">
1750
<title>Preferences Warning Dialog</title>
1754
<imagedata fileref="figures/xvidcap-warning.png" format="PNG"/>
1756
<textobject> <phrase>Preferences Warning Dialog</phrase>
1763
<title>GUI-less operation</title>
1765
When running from the command line with the <parameter>--gui no</parameter> parameter,
1766
those warnings will be displayed in plain text on the terminal. You will not be seeing the
1767
<quote>Details</quote> section unless you also specified <parameter>-v</parameter>.
1771
<table frame="all" id="xvidcap-warn-situations-TBL">
1773
There are a few situations in which such messages can be displayed:
1775
<tgroup cols="2" align="char" charoff="50" char=".">
1777
<row id="xvidcap-warn-situations-TBL-start">
1779
<para>On start</para>
1783
When <application>&app;</application> is started, it checks the
1784
consistency of the settings for the current capture mode and will
1785
report on issues it finds there. You will not be able to cancel out
1786
of this dialog, but have to revisit your preferences.
1789
<application>&app;</application> <emphasis>only</emphasis>
1790
checks on the current capture mode and will not care
1791
about inconsistencies with the respective other mode. Therefore,
1792
there is the second situation.
1796
<row id="xvidcap-warn-situations-TBL-change-mode">
1798
<para>On change of capture mode</para>
1802
If you change the current capture mode through the
1803
<ulink type="help" url="ghelp:xvidcap?menu xvidcap-menu-TBL-mf">menu</ulink>
1804
<application>&app;</application> will check the consistency of the settings
1805
for the new capture mode and will report on issues it finds there. If you
1806
cancel the warning dialog, you will return to your previous capture mode
1811
<row id="xvidcap-warn-situations-TBL-preferences">
1813
<para>When submitting changed preferences</para>
1817
When you leave the preferences dialog <application>&app;</application>
1818
will check the settings for both capture modes. Cancelling the warning
1819
dialog will take you back to the preferences dialog.
1828
In the Preferences Warning Dialog you will find one or more messages consisting of three
1829
rows each. The first one contains a message type or severity, a unique numeric ID and a
1830
short name for the error. The second row gives a more detailed description, and the third
1831
one tells about the action <application>&app;</application> is going to take if you
1832
chose to click <guibutton>OK</guibutton>.
1836
Such an action might be to automatically correct the issue by chosing a plausible default,
1837
to ignore the issue if it is not severe or to quit <application>&app;</application> if no
1838
solution can automatically be determined.
1842
The severity of an issue can be <quote>INFO</quote> for purely informational messages
1843
where no change is made to any settings, <quote>WARNING</quote> where a minor change
1844
to current settings is suggested, <quote>ERROR</quote> where a major change to current
1845
settings is required, or <quote>FATAL ERROR</quote>. A fatal error is always an error
1846
where the suggested action is to quit <application>&app;</application>. You will not
1847
see issues of severity <quote>INFO</quote> unless you run <application>&app;</application>
1857
<title>section 1</title>
1858
<para>may or may not exist</para>
1861
<title>sample command line session</title>
1863
<prompt>$</prompt> <userinput>ncftp ftp://ftp.cygnus.com/pub/home/rosalia/</userinput>
1864
<prompt>ncftp></prompt> <userinput>cd docware/RPMS/i386/</userinput>
1865
<prompt>ncftp></prompt> <userinput>mget *.rpm</userinput>
1866
<prompt>ncftp></prompt> <userinput>quit</userinput>
1871
<title>sample tip with parameters</title>
1873
sample parameter details
1874
To validate DocBook without displaying the document, add the
1875
argument <parameter class="option">-noout</parameter> to the
1876
<application>xmllint</application> command.
1881
<title>A simple C program</title>
1882
<programlisting role="C">
1883
#include <stdio.h>
1886
printf("Hello, world!\n");
1891
<figure id="app-FIG-shot1">
1892
<title>Screenshot</title>
1896
<imagedata fileref="figures/example_screenshot.png" format="PNG"/>
1899
<phrase>Shows the application screenshot with several buttons.</phrase>
1902
<para>Screenshot of a program</para>
1911
<title>doinker</title>
1912
<para>this is an <emphasis>example</emphasis></para>
1915
<title>Convergence of dynamical equations and constraints for
1916
various choices of constrained edges</title>
1917
<tgroup cols="5" align="char" charoff="50" char=".">
1920
<entry>Constrained edges</entry>
1921
<entry>Model</entry>
1922
<entry># of iter.</entry>
1923
<entry>E <subscript>i</subscript><superscript>2</superscript></entry>
1924
<entry>C <subscript>i</subscript><superscript>2</superscript></entry>
1929
<entry>AD, AF, AG, AA'</entry>
1930
<entry>Flat space</entry>
1932
<entry>1.15<superscript>-24</superscript></entry>
1933
<entry>1.77<superscript>-19</superscript></entry>
1936
<entry>AD, AF, AG, AA'</entry>
1937
<entry>Kasner universe</entry>
1939
<entry>1.43<superscript>-19</superscript></entry>
1940
<entry>1.77<superscript>-8</superscript></entry>
1943
<entry>AB, AC, AE, AA'</entry>
1944
<entry>Flat space</entry>
1946
<entry>1.15<superscript>-24</superscript></entry>
1947
<entry>4.09<superscript>-24</superscript></entry>
1950
<entry>AB, AC, AE, AA'</entry>
1951
<entry>Kasner universe</entry>
1953
<entry>1.33<superscript>-19</superscript></entry>
1954
<entry>8.07<superscript>-7</superscript></entry>
added
removed
doc/xvidcap/C/xvidcap.xml
