Wiki¶
sac2wav converts seismic data from the SAC file format to the WAV audio file format.
Use your favorite audio playback software to listen to a timelapse recording, where 30 seconds of audio equals 1 hour of real time.
Usage¶
Typical: sac2wav *.sac
where *.sac lists one or more SAC files that are all taken from a few hours of data from a single seismic channel.
sac2wav [-f file.wav -g gain -h hertz -l lapse -m mean] [-vFHQSTUVW] a.SAC [b.SAC ...]¶
Converts seismic data from the SAC format to the WAVE file format for audio playback.
When multiple a.SAC b.SAC input files are used, just one output wave file is constructed with audio silence spanning the time gaps between them. Time overlaps are trimmed.
All input files must share the same network.station.location.component name.
The number of samples output spans from the start time of the earliest file, to the end time of the latest file, without interruption.
The output file fidelity is 16 bit mono PCM.
-f file.wav
file.wav specifies a particular file name or path for the output WAVE file.
The default WAVE file name is year.julian_day.hour.minute.second.millsecond.network.station.location.component.WAV
Note that there is no data quality code (R, Q, or D) after the component name, because that information is not included in the SAC input file.
-g gain
The floating point gainvalue specifies the gain level, overriding the automatic calculation. It multiplies the amplitude of each sample to adjust audio output volume.
When this flag is absent, the waveform is automatically adjusted so that the mean value of the output waveform is zero, with the gainvalue calculated so that the maximum amplitude output level is about +-32767. This avoids audio clipping. Several gain values are calculated piecewise, one for each input SAC file.
-h rate
The integer samplerate specifies the output sample rate for WAV file header. This flag overrides timelapse.
-l lapse
The integer timelapse specifies the time lapse, as the number of seconds of sound to elapse per hour of recorded data.
The default timelapse is 30, so that each hour of input data plays back in 30 seconds of audio time.
Adjusting the timelapse or samplerate does not affect the number of samples output, only the rate at which they are played back.
-m mean
The floating point meanvalue specifies the mean (average) value of the waveform, overriding the automatic calculations.
Hint: Run sac2wav with the -S -W flags first, to calculate the input file statistics, including the meanvalue , without generating a WAV file, to get reasonable values for -g and -m for the next run.
When this flag is absent, the waveform is automatically adjusted so that the mean value of the output waveform is zero, with the gainvalue calculated so that the maximum amplitude output level is about +-32767. This avoids audio clipping. Several gain values are calculated piecewise, one for each input SAC file.
-F
Supress wave filename output to stdout.
-H
Report program help (usage) to stdout.
-v
Report program version number to stdout.
-W
Supress wave file output. Typically used with -S.
-U
Unbounded: Allow output files exceeding 200 about Megabytes. (DANGER: UNSAFE)
By default, sac2wav automatically refuses to generate WAV files exceeding about 200 megabytes. Very large data gaps (time tears) could potentially generate a very large and silent WAV file. Override this safety limitation manually by using the -U flag, at your own risk.
-Q
Quiet: Report no progress to stderr.
-S
Statistics: Report mean, stddev, min, max for each sac file to stderr.
-T
Terse: Report terse progress to stderr.
-V
Verbose: Report verbose progress to stderr.
FILES¶
The name of the output WAV file is reported to stdout on a single line.
The default WAVE file name is produced in the current directory, with the file name year.julian_day.hour.minute.second.millsecond.network.station.location.component.WAV
The default file name is also included in the WAV file in a LIST INFO INAM chunk.
USE CASES¶
Nominal Use Case¶
First, prepare for sac2wav by creating one or more .SAC files to cover the component and time being examined. Next, start sac2wav to generate a single WAVE audio file, passing the set of .SAC files as arguments. The name of the new file will appear on a single line at stdout. Finally, open the WAVE file in a digital audio playback program to hear it.
Gain Adjustment¶
To control the gain value manually, run sac2wav -S -W a.SAC b.SAC as a first pass. This will suggest reasonable numbers to use for the -g and -m arguments for the second pass.
Playback Speed¶
The default output file sample rate is calculated according to the lapse parameter of 30 seconds per hour of input data. Different seismometers record data at different sample rates. Different seismometers recording at 100Hz and 500Hz would result in a different output audio sample rate to maintain the same time-lapse effect. So, to shift the audio up one octave, use sac2wav -l 15, and to shift the audio down one octave, use sac2wav -l -60. The -h rate argument ignores the seismometer and blindly sets the output file's sample rate.
Filename¶
By default, the output file name is:
year.julian_day.hour.minute.second.millsecond.network.station.location.component.WAV
that is,
nzyear.nzjday.nzhour.nzmin.nzsec.nzmsec.knetwk.kstnm.khole.kcmpnm.WAV
Override this name by using -f to specify a particular file (or path) name.
Note that there is no data quality code (R, Q, or D) after the component name, because that information is not included in the SAC input file.
RIFF INFO chunk¶
The default file name is included in the WAV file in a LIST INFO INAM chunk.
RIFF [WAVE [LIST [INFO INAM=yyyy.ddd.hh.mm.ss.ffff.network.station.location.channel.Z]], [fmt=PCM, mono, samplerate, byterate, wordaligned, 16 bit], data =[...]
WARNING¶
By default, sac2wav automatically refuses to generate WAV files exceeding about 200 megabytes, because very large time tears could potentially generate a very large WAV file. Override this limitation manually by using the -u option, AT YOUR OWN RISK.
FUTURE PLANS (not yet implemented):¶
If the output file name specifies a directory, place the output file in that directory, possibly creating the directory if necessary, using the default file naming convention.
History¶
I first wrote sac2wav in 2004.
Rick DeWitt
Mill Creek, WA
rick.dewitt at gmail.com