DragonFly On-Line 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',
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:
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
format)
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.
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.
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
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)
perl v5.20.3 2016-02-18 SOUNDGRAB(1)