## SocketActor

The SocketActor converts a data stream coming in on a socket (a kind of network connection) into sound.

The SocketServer does the opposite, converting its input into data sent out on a socket.

These two can be used in combination to send audio data over the internet between two separate machines running vss.

They can also be used to send or receive data from other audio applications which receive or send compatible data. The data format is simply a stream-based internet-domain TCP socket carrying 16-bit 2's-complement data, interleaved channels (same as the conventional "raw audio data" file format). To use the SocketActor implementation, load socket.so and create an actor of type SocketActor or SocketServer.

### SocketActor and SocketServer

The SocketActor and SocketServer understand only the messages understood by all actors.

### SocketActor handler messages

In addition to the messages understood by all handlers, the handler for the SocketActor understand the following messages.

SamplingRate`hSound rate`
  Set # of audio-frames per second to receive. This can be different from VSS's sampling rate; the handler will automatically compensate. (At the moment we recommend that `rate` be an integer multiple or divisor of VSS's sampling rate.)
NumChannels`hSound n`
  Set the number of channels being received (at least 1).
SetLatency`hSound dur`
  Set the preferred delay (in seconds) between receipt of data and emission of audio. Larger values of `dur` up to around 0.1 result in more efficient CPU use (fewer, larger reads from the socket).
Connect`hSound hostname portnum`
  Connect the socket to port `portnum` on machine `hostname`. The messages SamplingRate and NumChannels must be done before this message will work.
Disconnect`hSound`
  Close and clean up the connection. If you forget to do this, the socket may be held open for several minutes at the other end, because over there it can't tell if your end got delayed or just died. So do it.

### SocketServer handler messages

In addition to the messages understood by all handlers, the handler for the SocketServer understand the following messages.

SamplingRate`hSound rate`
  Set # of audio-frames per second to transmit. This can be different from VSS's sampling rate; the handler will automatically compensate. (At the moment we recommend that `rate` be an integer multiple or divisor of VSS's sampling rate.)
NumChannels`hSound n`
  Set the number of channels being received (at least 1).
SetLatency`hSound dur`
  Set the preferred delay (in seconds) between receipt of data and emission of audio. Larger values of `dur` up to around 0.1 result in more efficient CPU use (fewer, larger writes to the socket).
Listen`hSound portnum`
  Wait for something to connect (see "Connect" above) to port `portnum`.
Disconnect`hSound`
  Close and clean up the connection. If you forget to do this, the socket may be held open for several minutes at the other end, because over there it can't tell if your end got delayed or just died. So do it.

### Examples

Send audio data (a sine tone) to another copy of VSS (see next example).

  `LoadDSO socket.so;
  LoadDSO add.so;
  aSine = Create AddActor;
  sSine = BeginSound aSine SetMute 0 SetAmp .3 SetFreq 200;
  aSrv = Create SocketServer;
  sSrv = BeginSound aSrv SetInput sSine SamplingRate 16000 NumChannels 1 SetLatency .07;
  // SetLatency on srv side should be a little less than on cli side.
  Listen sSrv 4247;
  sleep 60; // Wait for someone to Connect to us.
  Disconnect sSrv;
  `

Receive audio data from a copy of VSS on `myMachine` which is already running a SocketServer (see previous example).

  `LoadDSO socket.so;
  LoadDSO msgGroup.so;
  aCli = Create SocketActor;
  sCli = BeginSound aCli SamplingRate 16000 NumChannels 1 SetLatency .1 SetAmp 0.1;
  // myMachine:4247 had better be Listening now.
  Connect sCli myMachine 4247;
  // Now sCli starts playing the transmitted audio.
  sleep 5;
  Disconnect sCli;
  `