NAME

soundgrab - select and save sections of an audio file

SYNOPSIS

soundgrab [option]... [file]

DESCRIPTION

soundgrab is a perl script which runs the aplay and sox and possibly the ogg123, ogginfo, oggenc and flac executables to let the user play back a raw audio or '.ogg' file and interactively select and export portions of the file to other files.

It is also possible to save a sequence of soundgrab commands in a file and execute them later in batch mode (with the --execute option).

EXAMPLES

soundgrab -f ogg foo.ogg: Type 'help' to get started interactively dissecting file 'foo.ogg', exporting chunks in '.ogg' format by default.
soundgrab -r 44100 -c 2 -i s16_le bar.raw: Like the above example, but the input file consists of 2 channels of signed sixteen bit little endian audio data sampled at 44.1 kHz, and exported chunks will be in this format by default.

OPTIONS AND ARGUMENTS

-b KBITRATE, --ogg-kbitrate=KBITRATE: Files exported in the Ogg Vorbis lossy compression format should use approximately KBITRATE kilobits per second encoding. The default behavior is to use the oggenc default. This option may not be used together with the --quality (-q) option.
-c CHANNELS, --channels=CHANNELS: The file on which soundgrab is to operate contains CHANNELS-channel data, and/or exported raw audio should have CHANNELS channels. One channel is mono, two is stereo. Modern sound cards may support 4 or more channels. The default is 2.
-d, DEVICE, --device=DEVICE: This option is probably only useful if you are using an atypical arrangement for audio playback.
Use DEVICE as the argument to a --device option of the ogg123 or aplay program. Note that for '.ogg' volumes, it will probably be necessary to use the --device-option option as well. For example:

soundgrab --device=alsa09 --device-option=card:0 foo.ogg

Note also that a given DEVICE isn't going to be correct for both types of volumes. Finally, be warned that soundgrab has a tendency to unhelpfully eat the diagnostic output the ogg123 or aplay programs might normally generate when given a bad device specification. The default behavior is to not pass any device options to ogg123 or aplay, causing them to use their own default behavior.

--device-option=OPTION: Use OPTION as the argument to a --device-option option of the ogg123 program. The default behavior is to not pass and --device-option options to ogg123, causing it to use its own default behavior. See also the --device option description.
-e COMMAND_FILE, --execute=COMMAND_FILE: Execute the commands in COMMAND_FILE immediately on startup. See the online help for the 'execute' command. Note that by ensuring that none of the commands need to prompt the user and making the last command in COMMAND_FILE a 'quit' command, soundgrab can be made to operate entirely in batch (non-interactive) mode.
-f OFMT, --outpuf-file-format=OFMT: The arguments to the export command (see online help) that do not end in a known dot extension should be saved in format OFMT in a file with the appropriate dot extension appended. OFMT may be one of the following strings:

cdr: CD Mastering format. This is two channel unsigned sixteen bit little endian data with some blocking and padding.
flac: FLAC lossless compressed format.
ogg: Ogg vorbis lossy compressed format.
raw: Raw data samples in the format specified with the sample-format option at the sampling rate specified with the sampling-rate option and containing the number of channels specified with the channels option. If any of these options were not specied the default for that option is used. Note that the output sample format uses the value of the sample-format option even if the volume being dissected isn't a raw data file.

The default for this option is cdr. The flac and ogg formats are only available if the appropriate encoder is present on the system.

-i IFMT, --sample-format=IFMT: The samples for the individual channels in any raw audio data input volumes or output files used should be in format IFMT, where IFMT is one of the following strings:

s16_le: Signed sixteen bit little endian format.
u8: Unsigned eight bit.

-q QUALITY, --quality=QUALITY: Quality level to use when exporting files in ".ogg" format. The argument to this option is passed as the argument to the -q option to oggenc when that encoder is run. The default behavior is not to use -q option to oggenc and let it choose its own default behavior. This option may not be used together with the --kbitrate (-b) option.
-s SPEED, --sampling-rate=SPEED: Any raw audio data input volumes or output files used have sampling rate SPEED samples per second.
-t TIME, --time-of-start=TIME: Recording of the volume to be dissected was begun at time TIME. If this option is used, it will be possible to jump to 'times' in the volume. The format of the time string is the same as the format described in the output of the online command 'help jump', except day offsets are not allowed.
-v, --verbose: Enable verbose operation.
--help: Display help and exit.
--version: Print version information and exit.

The single optional argument file indicates the file name of the volume to be dissected. If the input file appears to be a '.ogg' file (i.e. if it has extension '.ogg' or the 'file' utility thinks its an ogg file), it is treated as such. Otherwise, in the absense of other options, the input file is assumed to contain 2 interleaved channels of signed 16 bit little endian raw audio data sampled at 44.1 kHz. A variety of output formats are available (some depend on the presence of certain encoder binaries in the user's path).

INTERACTIVE COMMANDS

soundgrab acts like a tape player with almost instantaneous fast forward and rewind, the capability to jump to a particular point in the tape, and the capability to name and save sections of the tape to other files. You can also browse through large volumes of audio, playing only some number of seconds and then skipping some number of seconds. The few commands required to do all these things are all documented online, just fire up soundgrab on an appropriate audio file and type 'help'.

AUDIO FORMAT DETAILS

Since soundgrab allows portions of a file in one format to be exported in different formats, it is sometimes impossible or undesirable to avoid changing the bits per sample, sample format, number of channels, or sampling rate of the data. The characteristics of the input volume are preserved in the exported output files with the following exceptions:

Raw audio output is always input and/or output in the form described by the relevant options or their defaults.
Input or output in '.ogg' form is always considered to consist of 16 bit samples (since ogginfo doesn't say anything about sample format)
Output in the '.cdr' (CD mastering format) is always in 44.1 kHz two channel sixteen bits per sample form in accordance with the definition of that format.

NON-INTERACTIVE USE

The --execute (-e) option makes it possible to use soundgrab in batch mode, but for this to work, you must ensure that soundgrab doesn't end up in a situation where it wants to prompt the user for additional input to complete a command. What makes soundgrab decide it has to prompt the user? Mostly, soundgrab prompts before doing anything that destroys information. Some of the things that cause this include the redefinition of chunk names, the definition of chunk names that will cause files to be overwritten when they are exported, and the use of export commands that will overwrite files if executed. Input is also requested when soundgrab thinks that a given chunk might fill the disk when exported (and it uses a pretty conservative estimate of space requirements of compressed files to determine this).

BUGS

Job control with Control-Z (using signal SIGTSTP and friends) is not supported, even in batch mode.

It is possible for soundgrab's notion of where it is in the volume to get out of sync with the reality of whats being played at a given instant. Any command that moves or stops the head will generally fix things.

There is no mpeg3 support because mpeg has a buggy license.

Perl version 5.8.0 at least sometimes seg faults when soundgrab exits.

oggenc version 1.0 based on libvorbis 1.0 at least doesn't handle its --comment option correctly, resulting in a spurious warning when outputing files in ogg format.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

AUTHOR

Britton Leo Kerin (soundgrab@letterboxes.org)