From 5ef769ce4eba2110acbf605d14245284dcab2f78 Mon Sep 17 00:00:00 2001
From: "B. Watson" <urchlay@slackware.uk>
Date: Sun, 7 Apr 2024 17:54:08 -0400
Subject: soxdial: add description to doc, better comments, support spaces/etc
 in -o filenames, check --dialtone arg.

---
 soxdial | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/soxdial b/soxdial
index 61fde81..f3714c8 100755
--- a/soxdial
+++ b/soxdial
@@ -19,12 +19,23 @@ 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,
@@ -220,6 +231,11 @@ sub add_digit {
 # ...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) 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>
+
 sub make_sox_subcmd {
 	my $cmd = "sox -n -b$bits $encoding -r$rate -c1 -traw - ";
 	my $synth = " synth $digittime ";
@@ -239,17 +255,31 @@ sub make_sox_subcmd {
 	return $cmd . $synth . $delay;
 }
 
+# used to add the silence after the last digit in a dial string
 sub silence_subcmd {
+	warn "$SELF: adding $intertime sec silence at end of dial string.\n" if $verbose;
 	return "sox -n -b$bits $encoding -r$rate -c1 -traw - trim 0 $intertime";
 }
 
 sub dialtone_subcmd {
-	return "sox -n -b$bits $encoding -r$rate -c1 -traw - synth $_[0] sine 350 sine 440";
+	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);
@@ -265,6 +295,10 @@ if(!@ARGV) {
 for ($argc = 0; $argc < @ARGV; $argc++) {
 	$_ = $ARGV[$argc];
 
+	# note: unusually, if anything starts with - but isn't a recognized
+	# option, it's not an error (it gets treated as a dial string). this
+	# allows e.g. 555 -1212 to work correctly, but mistyped options will
+	# result in them being dialled as alphabetic characters.
 	if(/--?version$/) {
 		print "$SELF $VERSION\n";
 		exit 0;
-- 
cgit v1.2.3