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;