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.