aboutsummaryrefslogtreecommitdiff
path: root/soxdial
blob: fc09bcab4af7ecc32a9600f8f174ec292d967ff7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
#!/usr/bin/perl -w

# constuct and execute a sox command to dial a phone number with DTMF tones.

$VERSION = "0.0.1";
($SELF = $0) =~ s,.*/,,;

$|++;

=pod

=head1 NAME

soxdial - generate DTMF (touchtone) audio

=head1 SYNOPSIS

B<soxdial> [I<global-options>] [ [I<dial-options>] [I<dial-string>] ... ]

=head1 DESCRIPTION

B<soxdial> uses B<sox>(1) to generate DTMF tones (aka touchtone
dialling). Output can be played through the system sound card, or
saved to a file of any type supported by sox.

By default, letters are accepted and converted to numbers, according
to the layout of a touchtone phone (e.g. A = 2, M = 6, etc). If the
extended touchtone digits A, B, C, and D are needed, they can be
enabled with the B<-x>, B<--extended> option (see below).

=head1 OPTIONS

Note that option bundling is not supported. Use e.g. B<-v -n>, not B<-vn>. Also,
spaces are required between options and their arguments. Use e.g. B<-b 16>,
not B<-b16>.

Also, GNU style --option=value is not supported (use B<--bits 16>, not B<--bits=16>).

=head2 Global Options

These options affect the entire output. They should only be given once,
before any dial strings or dial options.

=over 4

=item B<-o>, B<--output> I<output>

Write sox's output to a file, rather than playing it. The file format
is determined by the filename extension. Use B<.wav> for RIFF WAVE
output, B<.flac> for FLAC, B<.ogg> for Ogg Vorbis, or anything else
(including no extension) for raw audio samples. The special filename B<->
writes raw samples to standard output.

=item B<-r>, B<--rate> I<rate>

Set the bitrate in hertz (or kilohertz if followed by B<k>. Default is
8000 (or 8k). You should probably stick with standard bitrates such as
22050, 44100, 48000, etc, although this is not enforced. This option
B<must> occur on the command line B<before> any dial string.

=item B<-b>, B<--bits> I<bits>

Set the bits per sample. Default is 8. The only other choice is 16.
8-bit samples will be encoded as unsigned, and 16-bit will be encoded
as signed. This option B<must> occur on the command line B<before> any
dial string.

=item B<-v>, B<--verbose>

Print verbose information, including the generated B<sox> command, on standard
error.

=item B<-n>, B<--no-exec>

Do not execute the generated B<sox> command. This option also
enables B<-v>.

=item B<-V>, B<--version>

Print the version number of B<soxdial>, then exit.

=item B<--help>

Prints this help text, via B<perldoc>(1), then exit.

=item B<--man>

Prints this help text as a man page, via B<pod2man>(1), then exit. Suggested use:

  soxdial --man > soxdial.1

Then B<soxdial.1> can be installed in e.g. /usr/man/man1 or
/usr/share/man/man1 or wherever your OS keeps its man pages.

=back

=head2 Dial Options

These options can be mixed freely with dial strings, and are applied
as they're found on the command line. Each one affects the rest of the
dial strings, until the same option is seen again.

=over 4

=item B<-l>, B<--length> [ I<sec> | I<millisec>B<ms> ]

Sets the time each digit's tones are played. Default is 0.25
or 250ms.

=item B<-d> I<sec>, B<--delay> [ I<sec> | I<millisec>B<ms> ]

Sets the delay between consecutive digits. Default is 0.1
or 100ms.

=item B<-c> I<sec>, B<--comma> [ I<sec> | I<millisec>B<ms> ]

Sets the delay added by commas in the dial strings. Default is 0.5
or 500ms.

=item B<-x>, B<--extended>

Allows the extended touchtone pad keys A, B, C, and D. B<Disables>
letter-to-number conversions.

=item B<-a>, B<--alphabet>

Disables extended touchtone pad keys A, B, C, and D; re-enables
letter-to-number conversions. This is the default; this option exists
to turn off a prior B<-x>, B<--extended> option.

=item B<-t>  B<--dialtone> [ I<sec> | I<millisec>B<ms> ]

Play I<sec> (or I<millisec> ms) of dialtone before the next dial string.

=item B<-s>, B<--silence> [ I<sec> | I<millisec>B<ms> ]

Play I<sec> (or I<millisec> ms) of silence before the next dial string.

=back

=head2 Dial Strings

These are the actual digits to be dialled. DTMF digits 0 to 9, #,
and * are supported. By default, letters are also supported, and will
be converted to digits according to the standard layout of touchtone
phones (e.g. A through C convert to 2, D through F are 3, etc).

Q and Z weren't present on classic phones, but they will be converted
to 7 and 9, respectively (like modern cell phones).

To add an extra delay between digits, use a comma (and see the B<-c>,
B<--comma> option to set the length of the delay).

To play the extra DTMF tones for the extended 16-digit keypad (which has
A, B, C, and D keys), use the B<-x>, B<--extended> option. This disables
letter-to-number conversion, but it can be re-enabled later on the
command line with the B<-a>, B<--alphabet> option.

All characters that aren't mentioned above, will be silently
ignored. This allows you to paste a phone number in the form B<(555)
555-1212> and have it work correctly.

=head1 NOTES

B<1.> B<soxdial> works by iterating over the words on the command
line, and building up an array of B<sox> commands for each dial string
or segment of dial tone. At the end, all the B<sox> commands are run
and their combined output (as raw samples) is piped to another B<sox>
command that writes the output as a single audio stream (raw, .wav,
or whatever format the B<-o>, B<--output> filename indicates). It has
to be done this way because B<sox> doesn't allow multiple B<synth>
arguments in the same command (or, it does, but they don't work as
expected, or at all). Because the final B<sox> command reads only raw
audio, it's impossible to change the bitrate or sample size in between
dial strings.

B<2.> If anything on the command line starts with B<-> but isn't a
recognized option, it's not an error: it gets treated as a dial
string. This allows e.g. I<555 -1212> to work correctly, but
mistyped options will result in them being dialled as alphabetic
characters. This may be a bit surprising the first time it happens.

B<3.> I haven't been able to test this with a real land-line phone to
see whether it will actually dial out.

B<4.> Possibly there will be support for bluebox tones in the future.

=head1 AUTHOR

soxdial was written by B. Watson <urchlay@slackware.uk> and released
under the WTFPL: Do WTF you want with this.

=cut

%freqs = (
	1   => [697, 1209],
	2   => [697, 1336],
	3   => [697, 1477],
	4   => [770, 1209],
	5   => [770, 1336],
	6   => [770, 1477],
	7   => [852, 1209],
	8   => [852, 1336],
	9   => [852, 1477],
	'*' => [941, 1209],
	0   => [941, 1336],
	'#' => [941, 1477],
	A   => [697, 1633],
	B   => [770, 1633],
	C   => [852, 1633],
	D   => [941, 1633],
);

@freqs1 = ();
@freqs2 = ();
@delays = ();
$time = 0;
$pausetime = 0.5;
$digittime = 0.25;
$intertime = 0.1;
$bits = 8;
$encoding = "-eun";
$rate = 8000;
$output = "-d";

sub letter2number {
	my $ret;
	my $l = uc shift;
	return $l unless $l =~ /[A-Z]/;
	for($l) {
		if(/[A-O]/) {
			$ret = int((ord($_) - 65) / 3 + 2) . "";
		} elsif(/[P-S]/) {
			$ret = "7";
		} elsif(/[T-V]/) {
			$ret = "8";
		} else { # /[W-Z]/
			$ret = "9";
		}
	}
	warn "$SELF: letter2number('$l') => '$ret'\n" if $verbose;
	return $ret;
}

# sox -n -d synth 0.25 sine 697 sine 1209 sine 770 sine 1477 delay 0 0 .35 .35 remix -
# ...plays DTMF 1 and 6, for 0.25 sec each, with a 0.10 sec delay between them.

sub add_digit {
	my $d = shift;
	if($d eq ',') {
		# pause
		push @freqs1, 0;
		push @freqs2, 0;
		push @delays, $time;

		$time += $pausetime;
	} else {
		#print "time $time\n";
		#print "freq1 " . ($freqs{$d}->[0]) . "\n";
		#print "freq2 " . ($freqs{$d}->[1]) . "\n";

		push @freqs1, ($freqs{$d}->[0]);
		push @freqs2, ($freqs{$d}->[1]);
		push @delays, $time;

		$time += $digittime;
		$time += $intertime;
	}
	warn "$SELF: added digit '$d', time now $time\n" if $verbose;
}

# ( sox -n -p synth 2 sine 350 sine 440; sox -n -p synth 2 sine 697 sine 1209 ) | sox -G -p -d
# ...plays 2 sec of dialtone followed by 2 sec of DTMF key 1. Change the -d
# to 1.wav to save to a file. Prefix it with -rXXXX -sX if needed.

# each dial string (or --dialtone, or --silence) creates a
# subcommand. they get executed in a subshell, writing raw audio
# to stdout, and the final sox command reads all the audio from its
# stdin. looks like:
# ( <subcommand1> ; <subcommand2> ; ... ) | sox <final output args>

# --norm is needed because otherwise, the volume decreases as the number of
# digits (tones for "synth") goes up. --norm=-3 helps avoid clipping.
sub make_sox_subcmd {
	my $cmd = "sox -n -b$bits $encoding -r$rate -c1 -traw - --norm=-3 ";
	my $synth = " synth $digittime ";
	my $delay = "delay ";

	for(0..$#freqs1) {
		my $f1 = $freqs1[$_];
		my $f2 = $freqs2[$_];
		my $d = $delays[$_];

		$synth .= "sine $f1 sine $f2 "; 
		$delay .= "$d $d ";
	}

	$time = 0;
	@freqs1 = @freqs2 = @delays = ();
	return $cmd . $synth . $delay;
}

# used to add the silence after the last digit in a dial string
sub silence_subcmd {
	my $s = shift;
	if(!defined $s || ($s + 0) <= 0) {
		warn "$SELF: ignoring invalid --silence argument.\n";
		return;
	}
	warn "$SELF: adding $s sec silence.\n" if $verbose;
	return "sox -n -b$bits $encoding -r$rate -c1 -traw - trim 0 $s";
}

sub dialtone_subcmd {
	my $sec = shift;
	if(!defined $sec || ($sec + 0) <= 0) {
		warn "$SELF: ignoring invalid --dialtone argument.\n";
		return;
	}
	warn "$SELF: adding $sec sec of dial tone.\n" if $verbose;
	return "sox -n -b$bits $encoding -r$rate -c1 -traw - synth $sec sine 350 sine 440";
}

# final sox command, to which we pipe all the others.
sub make_sox_cmd {
	if($output eq '-') {
		$output = "-t raw $output";
	} else {
		# support quotes, spaces, etc in filenames.
		# this can probably be fooled by a determined luser.
		$output =~ s,",\\",g;
		$output = "\"$output\"";
	}
	my $cmd = "sox -traw -b$bits $encoding -r$rate -c1 - $output ";
	my $subcmds = join(" ; ", @sox_subcmds);
	return "( " . $subcmds . " ) | " . $cmd;
}

# support either seconds (possibly with decimal point, e.g. 0.5) or
# milliseconds (e.g. 500ms).
sub parse_sec {
	$_ = shift || 0;
	if(/^(.+)ms$/) {
		$_ = $1 / 1000;
	}
	return $_;
}

# support either Hz (e.g. 8000) or KHz (e.g. 8k or 8K).
sub parse_rate {
	$_ = shift || 0;
	if(/^(.+)k$/i) {
		$_ = $1 * 1000;
	}
	return $_;
}

# main()
if(system("sox --version > /dev/null 2>&1") != 0) {
	die "$SELF: can't execute sox, is it installed?\n";
}

if(!@ARGV) {
	warn "$SELF: no dial strings. Try $SELF --help.\n";
	exit 1;
}

for ($argc = 0; $argc < @ARGV; $argc++) {
	$_ = $ARGV[$argc];

	if(/=/) {
		die "$SELF: GNU-style --option=value not supported, use --option value.\n";
	} elsif(/--?(?:V|version)$/) {
		print "$SELF $VERSION\n";
		exit 0;
	} elsif(/^--?man$/) {
		exec "pod2man --stderr -s6 -cUrchlaysStuff -r$VERSION -u $0";
		exit 1;
	} elsif(/^--?(?:\?|h)/) {
		exec "perldoc $0";
		exit 1;
	} elsif(/^--?v(erbose)?$/) {
		$verbose = 1;
	} elsif(/^--?n(oexec)?$/) {
		$verbose = 1;
		$noexec = 1;
	} elsif(/^--?o(?:output)?$/) {
		$output = $ARGV[++$argc];
		warn "$SELF: output set to '$output'\n" if $verbose;
	} elsif(/^--?b(?:its)?$/) {
		if(@sox_subcmds) {
			die "$SELF: can't change bits after a dial string.\n";
		}
		$bits = $ARGV[++$argc];
		if($bits == 8) {
			$encoding = "-eun";
		} elsif($bits == 16) {
			$encoding = "-esig";
		} else {
			die "$SELF: bad -b/--bits, only 8 or 16 is allowed.\n";
		}
		warn "$SELF: bits set to '$bits'\n" if $verbose;
	} elsif(/^--?r(?:ate)?$/) {
		if(@sox_subcmds) {
			die "$SELF: can't change bitrate after a dial string.\n";
		}
		$rate = parse_rate($ARGV[++$argc]);
		warn "$SELF: bitrate set to '$rate'\n" if $verbose;
		die "$SELF: invalid bitrate.\n" unless $rate > 0;
	} elsif(/^--?l(?:ength)?$/) {
		$digittime = parse_sec($ARGV[++$argc]);
		warn "$SELF: digit length set to '$digittime'\n" if $verbose;
		die "$SELF: invalid --length argument.\n" unless $digittime > 0;
	} elsif(/^--?(?:x|extended)$/) {
		$extended = 1;
		warn "$SELF: extended DTMF (ABCD) enabled.\n" if $verbose;
	} elsif(/^--?a(?:lphabet)?$/) {
		$extended = 0;
		warn "$SELF: extended DTMF (ABCD) disabled.\n" if $verbose;
	} elsif(/^--?d(?:elay)?$/) {
		$intertime = parse_sec($ARGV[++$argc]);
		warn "$SELF: inter-digit delay set to '$intertime'\n" if $verbose;
		die "$SELF: invalid --delay argument.\n" unless $intertime > 0;
	} elsif(/^--?c(?:omma)?$/) {
		$pausetime = parse_sec($ARGV[++$argc]);
		warn "$SELF: comma delay set to '$pausetime'\n" if $verbose;
		die "$SELF: invalid --comma argument.\n" unless $pausetime > 0;
	} elsif(/^--?(?:t|dialtone)$/) {
		push @sox_subcmds, dialtone_subcmd(parse_sec($ARGV[++$argc]));
	} elsif(/^--?s(?:ilence)?$/) {
		push @sox_subcmds, silence_subcmd(parse_sec($ARGV[++$argc]));
	} else {
		warn "$SELF: start dial string '$_'\n" if $verbose;
		for (split "", $_) {
			my $digit = uc $_;
			if($extended) {
				next if $digit !~ /[0-9,#*A-D]/;
			} else {
				$digit = letter2number($digit);
				next if $digit !~ /[0-9,#*]/;
			}
			add_digit($digit);
		}
		warn "$SELF: end dial string '$_'\n" if $verbose;
		push @sox_subcmds, make_sox_subcmd();
		push @sox_subcmds, silence_subcmd($intertime);
	}
}

if(!@sox_subcmds) {
	die "$SELF: no digits or dialtone to generate.\n";
}

my $cmd = make_sox_cmd();

if($verbose) {
	warn "$SELF: sox command is:\n  $cmd\n";
} else {
	$cmd .= " 2>/dev/null";
}

if(!$noexec) {
	system($cmd);
}