FreeBSD Manual Pages
SOUNDGRAB(1) User Contributed Perl Documentation SOUNDGRAB(1) 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', ex- porting 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 be- havior is to use the oggenc default. This option may not be used to- gether 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 un- helpfully 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 op- tions 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 en- tirely 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 follow- ing strings: cdr CD Mastering format. This is two channel unsigned sixteen bit lit- tle endian data with some blocking and padding. flacFLAC lossless compressed format. ogg Ogg vorbis lossy compressed format. raw Raw data samples in the format specified with the sample-format op- tion 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 dis- sected 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 argu- ment 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 op- tion 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 vol- ume. 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 avail- able (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 re- quired 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 sam- pling rate of the data. The characteristics of the input volume are pre- served 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 com- plete 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 sup- ported, 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. SEE ALSO amixer(1), arecord(1), aplay(1), sox(1), oggenc(1), ogginfo(1), ogg123(1), flac(1) COPYRIGHT soundgrab is Copyright (C) 2007 Britton Leo Kerin This program is free software; you can redistribute it and/or modify it un- der 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 FIT- NESS 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) perl v5.42.3 2026-08-04 SOUNDGRAB(1)
NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | OPTIONS AND ARGUMENTS | INTERACTIVE COMMANDS | AUDIO FORMAT DETAILS | NON-INTERACTIVE USE | BUGS | SEE ALSO | COPYRIGHT | AUTHOR
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=soundgrab&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>