[xiph-cvs] cvs commit: snatch README FAQ libsnatch.c snatch.pl

Monty xiphmont at xiph.org
Sun Nov 11 20:16:24 PST 2001



xiphmont    01/11/11 20:16:24

  Modified:    .        FAQ libsnatch.c snatch.pl
  Added:       .        README
  Log:
  

Revision  Changes    Path
1.2       +86 -34    snatch/FAQ

Index: FAQ
===================================================================
RCS file: /usr/local/cvsroot/snatch/FAQ,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- FAQ	2001/11/11 22:43:28	1.1
+++ FAQ	2001/11/12 04:16:23	1.2
@@ -1,55 +1,107 @@
 Q: Does Snatch make perfect copies or grab the actual Real stream?
 
-a: No.
+A: No.  It captures the decoded audio and video as Real sends it to
+   the sound device and X server.  The result of grabbing the data
+   will only be as good as RealPlayer's playback; it will be exactly
+   as you see/hear it.
+
+   Snatch does not touch the Real stream and does not know how to talk
+   to a Real server; it lets the stock RealPlayer do the decoding.
+   Snatch does not modify or patch RealPlayer in any way or defeat any
+   encryption or password mechanisms built into RealPlayer.  Snatch is
+   merely a glorified software camcorder with an easy to use
+   interface.
 
 Q: Does Snatch just take lots of fast screen captures?
 
 A: No.  Snatch watches events going to and from the X server and
-captures the appropriate video frames off the wire.  It will not grab
-at the wrong rate, hose the machine/X server or 'capture' frames that
-aren't actually displayed.
+   captures the appropriate video frames off the wire.  It will not
+   grab at the wrong rate, hose the machine/X server or 'capture'
+   frames that aren't actually displayed.
 
 Q: Can I capture with the RealPlayer window hidden or iconified?
 
-A: Yes.
+A: Yes. 
 
+Q: Will Snatch try to restart RealPlayer if an error occurs?
+
+A: Yes, but mostly for timed recording.  If RealPlayer crashes or
+   aborts streaming due to a network error, Snatch will start a new
+   copy if needed and try to pick up any timed recording where it left
+   off.  If capture is happening in manual mode, Snatch assumes that
+   user is present and can generally handle any problems better than a
+   dumb, automated Robot, and as such won't try to interfere.
+
+Q: Is there a 2GB file limit?
+
+A: The short answer depends on Linux version.  Snatch uses 64 bit file
+   operations, so there's no limitation there.  Captures on Linux 2.4
+   will go past 2GB smoothly.
+
+   Many/most machines still running Linux 2.2 can't have > 2GB files
+   as Linux 2.2's ext2fs is limited to 32 bit offsets when running on
+   32 bit machines.  For these machines, if the selected output is a
+   *directory* Snatch will close a grab file when it hits 2GB, open a
+   new file, and continue. If a specific *file* is set for output,
+   Snatch will not be able to continue past 2GB.
+
 Q: When I selecting silent video playback, the RealPlayer window
-mostly stops responding and fills with garbage.  Can I fix this?
+   mostly stops responding and fills with garbage.  Can I fix this?
 
 A: No, it's intentional. 'Silent video' stops all X updates from going
-to the RealPlayer window; it's meant to squeeze any extra performance
-possible from a machine with slow graphics hardware or slow processor
-or both.  Remember that Snatch doesn't capture the Real stream, it
-captures the video RealPlayer sends to the display.  Any dropped
-frames due to poor machine performace will show up in the output as
-jerkiness.
-
-Although the video requires cycles to display, RealPlayer is also
-spewing lots of updates to the interface during playback (like the
-time display, scrolling info, etc).  For best performace, *everything*
-gets turned off.  In this mode, all interaction with RealPlayer should
-be made through the Snatch Robot.  Turning off silent video will bring
-the RealPlayer window back to life.
+   to the RealPlayer window; it's meant to squeeze any extra
+   performance possible from a machine with slow graphics hardware or
+   slow processor or both.  Remember that Snatch doesn't capture the
+   Real stream, it captures the video RealPlayer sends to the display.
+   Any dropped frames due to poor machine performace will show up in
+   the output as jerkiness.
+
+   Although the video requires cycles to display, RealPlayer is also
+   spewing lots of updates to the interface during playback (like the
+   time display, scrolling info, etc).  For best performace,
+   *everything* gets turned off.  In this mode, all interaction with
+   RealPlayer should be made through the Snatch Robot.  Turning off
+   silent video will bring the RealPlayer window back to life.
 
 Q: I begin playing/recording with audio playback set to silent, but
-changing the setting later has no effect until I start a new stream!  Why?
+   changing the setting later has no effect until I start a new
+   stream!  Why?
 
 A: Snatch doesn't currently try to set up the soundacard for playback
-after a stream starts because it originally faked successful returns
-to various sound API ioctl()s that might have failed (requiring
-RealPlayer to try an alternate setup) if actually submitted to the
-kernel.  Trying to emulate given settings with on the fly resampling
-is rather complex given the failry innocuous nature of this 'bug', and
-not bothering to fake through it correctly would just crash
-RealPlayer or garble the output.
+   after a stream starts because it originally faked successful
+   returns to various sound API ioctl()s that might have failed
+   (requiring RealPlayer to try an alternate setup).  Trying to
+   emulate given settings with on the fly resampling is rather complex
+   given the fairly innocuous nature of this 'bug', and not bothering
+   to fake through it correctly would just crash RealPlayer or garble
+   the output.
 
 Q: I'm watching/recording video and switching between audio playback
-and silent playback. When I turn off silent record, the audio I hear
-is out of sync!  What gives?
+   and silent playback. When I turn off silent record, the audio I
+   hear is out of sync!  What gives?
 
 A: Right now, Snatch tracks audio sync only for the output file.  It
-doesn't try to re-sync the sound card if you reenable audio playback
-during operation.  The captured file *will be fine*.  I didn't go
-through the extra trouble mainly because on-the-fly resync would
-require extra memory, buffering, and I didn't know if anyone cared
-that much.
+   doesn't try to re-sync the sound card if you reenable audio
+   playback during a stream.  The captured file *will be fine*.  I
+   didn't go through the extra trouble mainly because on-the-fly
+   resync would require extra memory, buffering, and I didn't know if
+   anyone cared that much.
+
+Q: Can I use libsnatch without the Snatch Robot application?
+
+A: Yes, all the configuration a user can effect from the robot can be
+   done via environment variables.  In fact, the shared lib was
+   written and tested and used thoroughly before the Robot was even
+   started.
+
+Q: What does Snatch occasionally cause: "undefined symbol:
+   XGetGeometry" or some other undefined symbol?
+
+A: RealPlayer is trying to start up external applications; Snatch
+   isn't yet smart enough to know that these external applications are
+   not RealPlayer and thus tries [unsuccessfully] to use the same
+   library capture tricks.  The errors are harmless, but they do mean
+   Real will not be able to spawn web browsers or other 'external
+   synchronized multimedia events'.  I personally don't consider that
+   a huge loss.
+

1.23      +8 -1      snatch/libsnatch.c

Index: libsnatch.c
===================================================================
RCS file: /usr/local/cvsroot/snatch/libsnatch.c,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- libsnatch.c	2001/11/11 23:33:32	1.22
+++ libsnatch.c	2001/11/12 04:16:23	1.23
@@ -28,6 +28,7 @@
 #include <X11/Xlib.h>
 #include <X11/extensions/XShm.h>
 
+static pthread_mutex_t open_mutex=PTHREAD_MUTEX_INITIALIZER;
 static pthread_cond_t event_cond=PTHREAD_COND_INITIALIZER;
 static pthread_mutex_t event_mutex=PTHREAD_MUTEX_INITIALIZER;
 static pthread_cond_t display_cond=PTHREAD_COND_INITIALIZER;
@@ -714,6 +715,7 @@
 }
 
 static void OpenOutputFile(){
+  pthread_mutex_lock(&open_mutex);
   if(outfile_fd!=-2){
     if(!strcmp(outpath,"-")){
       outfile_fd=STDOUT_FILENO;
@@ -753,8 +755,10 @@
                     buf1,
                     (audio_channels==1?"mono":"stereo"),
                     audio_rate);
-	  }else
+	  }else{
+	    pthread_mutex_unlock(&open_mutex);
             return;
+	  }
         }
         
         outfile_fd=open64(buf2,O_RDWR|O_CREAT|O_APPEND,0770);
@@ -778,9 +782,11 @@
       }
     }
   }
+  pthread_mutex_unlock(&open_mutex);
 }
 
 static void CloseOutputFile(){
+  pthread_mutex_lock(&open_mutex);
   if(outfile_fd>=0){
     videocount=0;
 
@@ -789,4 +795,5 @@
       close(outfile_fd);
     outfile_fd=-1;
   }
+  pthread_mutex_unlock(&open_mutex);
 }

1.33      +4 -3      snatch/snatch.pl

Index: snatch.pl
===================================================================
RCS file: /usr/local/cvsroot/snatch/snatch.pl,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -r1.32 -r1.33
--- snatch.pl	2001/11/12 00:08:55	1.32
+++ snatch.pl	2001/11/12 04:16:23	1.33
@@ -701,9 +701,10 @@
                 my$prompt;
                 
                 if($waiting_days){
-		    $prompt=$waiting_days."d $waiting_hours:$waiting_minutes";
+		    $prompt=$waiting_days."d ".$waiting_hours."h ".
+			$waiting_minutes."m";
                 }elsif($waiting_hours){
-		    $prompt=$waiting_days."$waiting_hours:$waiting_minutes";
+		    $prompt=$waiting_hours."h ".$waiting_minutes."m";
                 }else{
                     $prompt=$waiting_minutes."m ".$waiting_seconds."s";
                 }
@@ -734,7 +735,7 @@
             my$prompt;
             
             if($hours){
-		$prompt=$waiting_days."$hours:$minutes";
+		$prompt=$hours."h ".$minutes."m";
             }else{
                 $prompt=$minutes."m ".$seconds."s";
             }

1.1                  snatch/README

Index: README
===================================================================
Snatch 20011111

"The only intuitive user interface is the nipple; past that,
everything is learned."

Although Snatch has a farily 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) audio device

Which OSS audio device names to watch for.  This is not used for the
Enlightened Sound Daemon (which needs no configuration).

4) 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.

5) 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.

6) ok

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

7) apply

Same as 'ok', but doe snot close the Configuration panel.

8) cancel

Discard any changes and close the Configuration panel.

--- >8 ----
List archives:  http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'cvs-request at xiph.org'
containing only the word 'unsubscribe' in the body.  No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.



More information about the commits mailing list