siproc.1 (6265B)
1 .TH siproc 1 "2019-11-16" "0.1.0" "siproc man page" 2 . 3 .SH NAME 4 siproc \- a SIP softphone spawning processes for calls 5 . 6 .SH SYNOPSIS 7 .SY 8 siproc 9 .I /path/to/executable 10 .RI [ args \&...] 11 .YS 12 . 13 .SH DESCRIPTION 14 siproc is a SIP client, that spawns the process given by 15 .I /path/to/executable 16 for every incoming or outgoing call, passing it the command line parameters 17 .IR args . 18 .PP 19 Using standard input and output, these processes can exchange commands and events 20 with the parent process, that allow interaction with the caller/callee. 21 These command allow the program to answering calls, play files, send and receive 22 DTMF Tones et cetera. 23 On remote hangup, the child process is killed via SIGTERM. 24 . 25 .PP 26 The account settings and other configuration are read via environment variables. 27 . 28 .SH EXIT STATUS 29 .IP 0 30 on normal termination 31 .IP 1 32 on program or configuration error (check standard error for details) 33 .SH ENVIRONMENT 34 Configuration parameters are given via environment variables 35 .TP 36 .B SIPROC_REGISTRAR_URI 37 The server siproc should connect to, as a SIP URI (e.g "sip:myserver.tld") 38 .TP 39 .B SIPROC_ID_URI 40 The ID URI of the account used, e.g. "Full Name <sip:Account@myserver.lan>" 41 .TP 42 .B SIPROC_USERNAME 43 The username of the account 44 .TP 45 .B SIPROC_USERNAME 46 The password of the account 47 .TP 48 .B SIPROC_TRANSPORT_PORT 49 The port used by siproc. This variable is optional, and defaults to 5060. 50 If you want to run multiple instances of siproc on the same machine, set 51 it to distinct values, since the softphone binds to it. 52 .TP 53 .B SIPROC_LOG_LEVEL 54 The verbosity of the pjsua-library. Smaller values yield less noise on stdout. 55 .TP 56 .B SIPROC_CODEC_PRIORITIES 57 Set the priorities of different codecs used by pjsua. 58 It must be of the form 59 .B <name>:<prio>[,<name>:<prio>...] 60 Setting the priority to 0 disables the codec. 61 For a list of all available codecs, refer to the output of 62 .B siproc-parameters 63 . 64 .SS SUBPROCESS ENVIRONMENT VARIABLES 65 The processes spawned by siproc are passed the following environment variables: 66 .TP 67 .B SIPROC_REMOTE_URI 68 The SIP URI of the remote end 69 .TP 70 .B SIPROC_REMOTE_ID 71 Some pjsip interna, look it up in their documentation of the struct CallInfo 72 .TP 73 .B SIPROC_REMOTE_CONTACT 74 Some pjsip interna, look it up in their documentation of the struct CallInfo 75 .TP 76 .B SIPROC_OUTGOING 77 Whether the call being handled by this process is an incoming call (="n") or an 78 outgoing call (="y") 79 . 80 .SH PROCESS COMMANDS AND EVENTS 81 This section will explain the communication protocol between the main process and 82 its children, as well as the commands the main process can be given on its standard 83 input. 84 .PP 85 Make sure that the pipes are flushed after writing to them, otherwise the commands 86 will not get extecuted. 87 . 88 .SS MAIN PROGRAM COMMANDS 89 The main program reads some commands on standard input, terminated by newlines ('\\n'): 90 .TP 91 .B QUIT 92 Terminates the program, disconnecting all calls. 93 .TP 94 .B CALL [SIP URI] 95 Call a number, with 96 .B SIP URI 97 the address to be called, e.g. sip:contact@remote.tld 98 . 99 .SS SUBPROCESS COMMANDS 100 The spawned child process can give commands via stdout and read events via stdin. 101 Each command or event is separated by a newline ('\\n'). 102 The following commands are supported: 103 .TP 104 .B RINGING 105 Let's the remote end know that we are ringing. 106 .TP 107 .B ANSWER 108 Answer an incoming call 109 .TP 110 .B HANGUP 111 Hang up a call 112 .TP 113 .B TRANSFER [URI] 114 Redirect a call to an URI of the form sip:contact@remote 115 .TP 116 .B DTMF [STRING] 117 Dial the DTMF tones of each character in 118 .B STRING 119 .TP 120 .B PLAY [FILE] 121 Play a file from a given path, relative to the current working directory of the 122 main siproc process. Multiple files can be played at the same time. 123 .TP 124 .B STOP 125 Stop the file that has been added last. 126 .TP 127 .B MESSAGE [STRING] 128 Send a SIP message to the remote side 129 .TP 130 .B RECORD [FILE] 131 Record the conversation to the given file. If no file is given, the current 132 recording is stopped. 133 .TP 134 .B APLAY [DEVICE] 135 Play the stream of the alsa-device 136 .B DEVICE 137 to the remote end. 138 See the output of the 139 .B siproc-parameters 140 utility for all available device strings 141 .TP 142 .B ARECORD [DEVICE] 143 Play the audio stream from the remote end into the alsa device 144 .BR DEVICE . 145 See the output of the 146 .B siproc-parameters 147 utility for all available device strings 148 .TP 149 .B ASTOP [DEVICE] 150 Stop both playing the remote end into and the local stream from 151 .BR DEVICE . 152 . 153 .SS SUBPROCESS EVENTS 154 The following events can be read on stdin: 155 .TP 156 .B DTMF [CHARACTER] 157 When the client receives a DTMF character 158 .TP 159 .B CONNECTED 160 When the remote end has picked up the phone 161 .TP 162 .B STOPPED [FILE] 163 Playback of the given file has finished. This is also given when a file has been stopped 164 with the 165 .B STOP 166 command 167 .TP 168 .B MESSAGE [STRING] 169 The given message has been received. 170 . 171 .SS CALL TERMINATION 172 When the remote end hangs up, or the call is terminated in any other manner, 173 the process is killed via SIGTERM. the child may catch that signal for clean up. 174 . 175 .SH BUGS 176 Call forwarding does not seem to work 177 . 178 .SH EXAMPLE 179 An example, that plays the file 180 .I message.wav 181 and hangs up afterwords is shown in the following two sections. 182 It calls every SIP URI it gets on the standard input and does the same process as above. 183 . 184 .SS PARENT PROCESS 185 The parent process can be started as follows, and may then take SIP URIs via standard input. 186 For every call it receives or places, 187 .I handler.sh 188 is executed and passed the name of a file as first argument. 189 Additionally, the remote ends are recorded in a log file 190 . 191 .HP 192 .EX 193 export SIPROC_USERNAME="max" 194 export SIPROC_PASSWORD="max1234" 195 export SIPROC_ID_URI='Max Muster <sip:max@sipproxy.com>' 196 export SIPROC_REGISTRAR_URI='sip:sipproxy.com' 197 198 while read uri 199 do 200 echo "CALL $uri" 201 done | siproc ./handle.sh message.wav 202 .EE 203 . 204 .SS HANDLER 205 This is the corresponding handler 206 .I handle.sh 207 that implements the call automation logic. 208 If the call that is being handled is incoming, then the call ist answered first. 209 Afterwords, the file given on $1 is played, and once that is done, the call hung up. 210 . 211 .HP 212 .EX 213 #!/bin/bash 214 215 echo "$SIPROC_REMOTE_URI" >> log 216 217 if [ "$SIPROC_OUTGOING" == "n" ] 218 then 219 echo "ANSWER" 220 fi 221 222 while read line 223 do 224 case "$line" in 225 "CONNECTED") 226 echo "PLAY $1" 227 ;; 228 "STOPPED"*) 229 echo "HANGUP" 230 ;; 231 esac 232 done 233 .EE 234 .SH AUTHOR 235 Dominik Schmidt (dominik@schm1dt.ch)