Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SOUNDGRAB(1)	      User Contributed Perl Documentation	  SOUNDGRAB(1)

       soundgrab - select and save sections of an audio	file

       soundgrab [option]... [file]

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

       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.

       -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

	   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 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:

	       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)

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

	   Display help	and exit.

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

       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

       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

       o   Raw audio output is always input and/or output in the form
	   described by	the relevant options or	their defaults.

       o   Input or output in '.ogg' form is always considered to consist of
	   16 bit samples (since ogginfo doesn't say anything about sample

       o   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.

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

       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

       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.

       amixer(1), arecord(1), aplay(1),	sox(1),	oggenc(1), ogginfo(1),
       ogg123(1), flac(1)

       soundgrab is Copyright (C) 2007	Britton	Leo Kerin

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

       Britton Leo Kerin (

perl v5.32.0			  2020-08-29			  SOUNDGRAB(1)


Want to link to this manual page? Use this URL:

home | help