Add Russian translation provided by Валерий Крувялис <valkru@mail.ru>

[xiph-mirror.git] / snatch / README

Snatch 20020510

"The only intuitive interface is the nipple. After that, it's all 
 learned."
         --Bruce Ediger, bediger@teal.csn.org, in comp.os.linux.misc

Although Snatch has a fairly simple, friendly interface, some
documentation is in order.  As a wise man once remarked, "You'd be
surprised."

****************************** ABOUT ******************************

Snatch is a RealPlayer output recorder.  It is not really a ripper; it
does not save RealPlayer streams and can't be used to talk to
RealServers directly.  Instead, it catches the already decoded audio
and video as RealPlayer sends it off to the sound device and X server.
This technique has the advantages of a) always working, with audio,
video and live streams and b) being undetectable at the Real Server.

But grabbing the sound and video is relatively trivial (four hours
begin to end).  Putting it into an easy to use application is what
took about two weeks.  Snatch also includes a Robot that can issue
commands to RealPlayer via synthetic X events, allowing a user to set
up preprogrammed timed recording.

Snatch does not modify, patch or 'crack' RealPlayer in any way and
[should] work with any RealPlayer8 on any architecture for Linux.
Snatch simply subverts calls to Xlib and libc, capturing X
transactions and sound writes after they leave RealPlayer and before
they get to the OS, saving the data in a raw format capture file.
It's important to note that this capture output is *uncompressed* and
a considerable amount of both disk space and I/O bandwidth is
necessary for useful capturing.  Five minutes of 240x180 video at
15fps will eat about a gigabyte of disk space.

Once saved to disk, the output can be transcoded into any other
format.  MPEG video is a popular choice, and a convenient front end
for the 'mjpeg' tools suite is in progress.  More about that once the
filters are done.

****************************** SETUP ******************************

See the document 'INSTALL'.

*************************** QUICK START ***************************

Snatch has two parts; libsnatch and the Snatch Robot.  It's the
responsibility of libsnatch to load as a library underneath
RealPlayer, keep track of windows, and capture the audio and video.
The Snatch Robot is an external application written in perl that makes
libsnatch easier to use (the Robot also provides a convenient
recording timer).

If everything is installed correctly, just start the Snatch Robot
(named 'Snatch') and you're ready to go.  I've gone through some
effort to make any error dialogs careful and descriptive, as well as
making buttons do what the label says.  Five minutes of twiddling
should be enough to become an expert.  That said, there are a few
'clever features' that without some description could easily become
'clever pains-in-the-ass'.

***************************** START UP ****************************

1) After placing its main window, Snatch will load a user's
configuration, history and timer setup from text files in ~/.snatch.
If the user has no ~/.snatch directory or no configuration files,
Snatch will create the directory and/or populate it with a sensible
default configuration.

2) Snatch starts a RealPlayer.  If it can't, it should tell why.  Most
failures are due to not being able to find libsnatch.so or the
RealPlayer executable.  Both of these settings are found on the
configuration panel.

3) RealPlayer will appear with the 'Snatch' logo on a dark salmon
background.  This indicates Snatch is ready to go and will now capture
anything RealPlayer plays, audio or video or both.

**************************** MAIN PANEL ***************************

The main panel has eight buttons; two menu tabs and six panel buttons.

1) Timer Setup

The timed recoding config panel opens when this button is pressed.
More in its own section later.

2) Configuration

The main configuration panel opens when this button is pressed.  More
in its own section later.

3) Capture All

When activated, every frame of audio/video RealPlayer plays is dumped
in raw format into a snatch file.  The RealPlayer background will be
dark Salmon whenever Snatch is in capture all mode (if the background
is partially blocked by the video window, the borders will still be
dark salmon).

4) Timed Record

When activated, the Snatch Robot is in timer mode.  Any stream
manually started on RealPlayer will not be recorded.  When it comes
time for a preprogrammed stream to play, Snatch will wake up, direct
RealPlayer to start the stream, and begin capturing.  When the
programmed duration elapses, Snatch will go back into timer mode and
disable capture.  If no more preprogrammed streams are waiting, Snatch
will go into 'Off' mode.

In timer mode, the background is black and the logo is a hourglass.

5) Off

When pressed, Snatch is inactive.  It will not capture any Real
output.  The 'silent capture' settings still function, behaving like
mute buttons.

6) Silent capture: audio

Setting audio to 'silent capture' prevents RealAudio from trying to
access the actual Linux sound card devices.  Any attempt to open the
device is 'faked' by libsnatch.  The playback audio is then silently
recorded.

This has a number of advantages. To begin, it eliminates the
possibility of RealPlayer trying to open the audio device when another
application is using it, resulting in RealPlayer waiting, or not
playing back (and thus Snatch not capturing) audio.  There is also a
slight performance benefit to turning off audible audio
playback. Last, it adds a bit more privacy to the capture process.
Naturally, Snatch will still capture the stream audio if audio is in
silent capture mode.

If silent audio capture is selected at the beginning of stream
playback, unsetting it will have no effect until the next stream.  If
silent audio is set during stream playback, audio can be reenabled
later, but will likely play somewhat out of sync (see the FAQ).  Even
if it sounds out of sync, the captured file will still be OK.

7) Silent capture: video

This is analagous to silent audio capture; it may be set and unset at
any point during capture.  This button turns off all X updates to the
main RealPlayer window.  Neither video nor UI changes will display.

The primary reason for silent video capture is performance; on a
machine with a slow framebuffer, slow processor or other applications
vying for X latency performance, it's best to concentrate on capturing
the video as smoothly as possible and not bother sending it off to the
actual display.  Using silent capture can almost double effective
RealPlayer performace on the Linux machines here.

Remember: Snatch does not capture the Real stream; it grabs the audio
and video at display time, so what you see/hear is what you get
(neglecting silent capture of course).  Any dropped frames in the
decoded video or gaps in decoded audio will show up in the capture.
Although Snatch exacts virtually no additional computation overhead, it
*will* give disk I/O a good workout.  Many computers will need the
extra performance silent capture gives.

8) Quit

Quit both Snatch and RealPlayer.  

*************************** TIMER SETUP ***************************

The Timer Setup panel allows you to program future streams for
recording.  When put in Timer mode, Snatch will record those streams
automatically at the selected time.

The Timer Setup panel is mostly a simple list of streams queued for
recording.  The list is sorted by date of recording with any
programmed streams that have already passed grayed out at the top of
the list.  Old entries are not automatically removed, and must be
explicitly deleted.

A timed stream may be for a single time/date, or may contain wildcards
that allow it to run repeatedly at configured times.  The position on
the list will be determined by the next time that stream will trigger.

The Timer Setup Panel allows four operations, each of which has a
button.  A fifth button ('X' in the lower right hand corner) closes
the Timer Setup panel.  Any changes made to the panel are saved
immediately.  WYSIWYG.

1) Add

The add button adds a new stream to the time list, popping a Timer
Entry panel to allow the user to configure the specifics.  The Timer
Entry panel will be blank aside from the current time/date being
pre-filled.

2) Edit

Highlighting a stream on the list and clicking the Edit button will
pop a Timer Entry panel allowing the user to edit that stream
entry. An entry is highlighted by clicking on the entry in the list
window.  Doubleclicking a line on the list will also open that stream
entry for editing.

Old [greyed out] entries may also be editied (and reactivated by
changing the record date to a future time).

3) Copy

This does the same thing as 'add', but rather than presenting the user
with a blank Timer Entry panel, fills in a Timer Entry panel for a new
stream with the setting fro the highlighted stream.

4) Delete

Immediately delete the highlighted stream.  There is no 'Are you
sure?', there is no undo.  Changes are saved immediately.

************************* TIMER ENTRY SETUP ************************

The Timer Entry panel allows configuration of all the settings for a
given timed stream.

1) Date

When to record; any or all of the fields may be a wildcard setting
('*').  If all fields are wildcards, that indicates recording should
happen every day.

Note that impossible dates will be rejected, but not until the user
clicks 'ok'.

2) Time

When to begin recording, or rather, when to tell RealPlayer to start
playback.  RealPlayer will generally spend a good 15-30 seconds
connecting, buffering, yadda, before playback/capture actually begins.

3) Duration

How many hours and minutes to after beginning playback to stop
playback/capture.

4) URL

The file (beginning with file:) or URL to instruct RealPlayer to play.

5) username and password

If the stream is password protected content, fill in the proper
username and password to hand to RealPlayer upon request.

6) silent record

These settings have the same effect as the silent capture settings on
the main panel.  When it comes time to record this stream, these
settings will override the settings on the front panel.  These will
always be preset as timed recording is intended to happen with
RealPlayer innocously iconofied somewhere.

7) test connect now

If Snatch is currently in 'Off' or idle in 'Timer' mode, pressing this
button allows the user to test that there are no typos in the URL,
username or password by immediately telling RealPlayer to try to
connect to the stream.  If Snatch is set to 'capture all' or recording
another timed stream, the button will be grayed out.

8) output path

Select where to put the captured file.  This field may specify stdout
(but filling in with a bare -), a directory (in which case Snatch will
choose a unique filename) or a file (in which case Snatch will create
the file if it does not exist or append to it if it does).

Note that most Linux 2.2 machines cannot have files over 2GB and
because captures are in a raw format, 2GB can happen fairly quickly.
If you specify a file for the output path and hit 2GB, Snatch will
stop capturing.  If you specify an output directory instead, Snatch
will close the 2GB file, open a new file, and continue capturing.

9) OK

When OK is pressed, the fields are checked for problems, and any such
problems (like an impossible date or unwriteable output directory) are
reported.  If there are no errors, the entry is saved to disk
immediately, and the Timer Entry panel closes.

10) Cancel

Abort adding/editing the entry.  The panel closes without saving any
entries.

*************************** CONFIGURATION **************************

1) RealPlayer location

Where to look for RealPlayer on startup.  This field is a glob.

2) libsnatch.so location

Where to look for the file libsnatch.so on startup.  This field is a glob.

3) OSS audio device

Which OSS audio device names to watch for. This is only relevant if
your Linux is using OSS directly.

4) EsounD server socket

Where the Enlightened Sound Daemon keeps its connect socket.  This
option is only relevant if you're using the EsounD daemon.

5) full debug output

The best first thing to set when something goes wrong, but the error
messages dialogs from the Snatch Robot aren't being helpful.

This reports to stderr the continuous debugging output from
libsnatch/RealPlayer.

6) capture output

Select where to put the captured data.  This field may specify stdout
(but filling in with a bare -), a directory (in which case Snatch will
choose a unique filename) or a file (in which case Snatch will create
the file if it does not exist or append to it if it does).

Note that most Linux 2.2 machines cannot have files over 2GB and
because captures are in a raw format, 2GB can happen fairly quickly.
If you specify a file for the output path and hit 2GB, Snatch will
stop capturing.  If you specify an output directory instead, Snatch
will close the 2GB file, open a new file, and continue capturing.

7) ok

Pressing OK applies any configuration changes immedaitely, saves the
changes to the configuration file ~/.snatch/config.txt and closes the
Configuration panel.

8) apply

Same as 'ok', but does not close the Configuration panel.

9) cancel

Discard any changes and close the Configuration panel.