|
SoundMan™-Server Audio Engine API Command Set |
| SoundMan Audio Engine Software | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| SoundMan-Server Core Audio Engine Powerpoint Overview | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| SoundMan-Server Virtual Sound System (VSS) Audio Engine API Software | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| SoundMan-Server Audio Engine API Command Set | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| User Interfaces & Application Software for SoundMan | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| SoundMan User Group Discussion List | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Media Servers | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| SoundMan Licence Agreement (pdf format) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| SoundMan-Assistant software turns a Windows computer into an AudioBox AB64 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
SoundMan-Server Audio Engine API Command Set
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Introduction to SoundMan-Server: If SoundMan-Server is used with SoundMan-Assistant and it is desired to have both programs startup automatically when the computer starts up, put only the shortcut to SoundMan-Assistant in the Windows Startup folder and it will automatically start SoundMan-Server and SoundMan-Monitor as long as all three executables are in the same target folder. If SounMan-Server is not being used with SoundMan-Assistant, put only the shortcut to SoundMan-Server in the Windows Startup folder. SoundMan-Server can be started using the command line parameter /NOSPLASH which suppresses the splash screen and user interface window. This can be added when creating or modifying the item in the startup folder. If SM-S is started with a CreateProcess call there is a value for command line contents there that can contain this parameter. If it is started using system() then just do something like system ("Soundman-Server /NOSPLASH"); When the program is executed the control panel displays a command line in which SoundMan-Server commands may be entered manually, followed by the semicolon character (;) or carriage return character which terminates the command. It also displays the licensed number of output VU meters and some additional configuration controls:
Introduction to SoundMan-Server commands: In this document, currently available features are shown in normal upright text. Features planned for the future are shown in italic text, like this. SoundMan-Server is an audio playback and matrixing engine. All command control and monitoring is performed by textual commands, called SoundMan-Server commands. In a future version some real time control can also be performed by MIDI messages communicated via a MIDI interface and Open Sound Control messages communicated via the network. SoundMan-Server commands must be used to configure the MIDI and OSC interface. SoundMan-Server commands are normally sent to the engine using a Telnet client using TCP (or UDP if that option has been purchased) mode on port 20000 at the host where SoundMan-Server is running. Currently only one Server can be running on any single PC. At a future time we may allow additional Servers; then the port number will become configurable. SoundMan-Server commands may also be entered (usually for testing purposes) in the Server monitoring dialog. There is a command line window and a command history window. These exist primarily for Server and client debug purposes; they are not intended for normal show operations. It is anticipated that most users will not directly use a Telnet program to communicate with the server. Instead, various other programs containing graphic representations of Server functions will open TCP or optional UDP mode connections to the Server on port 20000, and will send commands and receive responses in response to various internal state changes. Multiple sessions can be open at the same time to a single Server. Currently up to 20 connections may be made at the same time. Each connection currently sees the same view of the Server, and can control any aspect. It notes the IP address and port number of who sent the command, and sends the response back to that address. Port 20000 is what is known as a 'listener port'. It just sits around and waits for some client to knock on the door. Then it invents a new receiver port on some arbitrary port number and hands the client port off to it. So if you watch with Wireshark you will see the client really isn't talking on port 20K, it will be some other number greater than 1024. The listener port goes back to listening for the next client to knock. SoundMan-Server has separate ports inside for all of the clients. In a future version, SoundMan-Server will be able to host a large number of VST plugins and they will be utilized to create patch points where external and internal devices can be inserted into internal digital signal 'paths'. In a future version access controls will be available to limit the features and sections of the Server that can be controlled and monitored from any given session. This will allow a clean separation of control when a single Server controls multiple simultaneous shows. A future version will also synchronize audio playback with and chase and lock to MIDI Time Code. We will also develop a high level SoundMan-Server language which defines and controls the user's three-dimensional space, called SoundMan-Space, and the multichannel live and playback sound objects, called SoundMan-Objects, as they move, diverge, converge, diffuse, expand and contract in this space.
Summary Developer Notes We invite all third party developers interested in using SoundMan-Server as your audio engine API to contact us for individual support and quotations on versions specific to your needs and we can provide you with an OEM ISV version that does exactly what you want at a cost that is unbeatable. At the moment, SoundMan-Server is a highly refined audio engine with enormous capabilities but we are only just beginning to exercise the SoundMan-Server command set structure so that the largest number of options and features can be accessed by third party applications. We will of course be increasing SoundMan-Server commands and capabilities and will keep you informed of these developments. If you have any questions at all please don't hesitate to communicate with us directly at any time. On request we will forward to you all currently proposed and implemented commands for comment and implementation, pending finalization of the command set. SoundMan-Server can be controlled by making a TCP or optional UDP socket connection to port 20000. SoundMan-Server acts as a server on this port, listening for connections. Sixteen connections can easily be made simultaneously. Once a connection is established, commands are sent via an easily readable ASCII, line based protocol. Telnet is a suitable tool for testing connections and sending simple commands. Assuming the application is on same machine:
or, if not, (for example):
SM-S is controlled by opening port 20000 on the target system. Note that you can easily telnet in from another system; the control program does NOT have to run on the main system. Further, you can have up to 16 sessions going at once. So you could have an operator interface, a couple of designer interfaces, an automatic actor tracking interface and a loudspeaker processing interface all running at the same time, using the same SM-S host system. Multiple SM-S host machines can also run on the same network, allowing a 'SoundMan-Server Processor Farm' of virtual audio engines, networked together and controlling different segments of the same or even different audio systems simultaneous and coordinated by the user interface software. All commands to the engine are text. All responses from the engine are text. They are simple, regular, and allow a lot of abbreviation to make things simple and fast. The machine is in one of two states: idle with no interface open, or operational with an interface open. (Currently you can only have one interface open, but that will change at some point. There will be a handful of rather complex configuration rules for dealing with multiple interfaces, because they aren't necessarily time-locked, and other issues). The engine works only with ASIO interfaces. ASIO interfaces have names (as defined by the manufacturer of the interface) and the interfaces are in a list, so have index numbers. You can open or close an interface by name or number. You can also specify a few parameters when you are setting the interface. These can control the number of input and output channels you want, and the number of playback channels. There is also an operating mode parameter that controls assorted features and limitations. There are some ASIO drivers that provide a stardard ASIO interface layer for other audio driver models but this adds one more interpretive level and therefore increases latency.
Returns a numbered list of the available interfaces
Selects a particular interface.
Gets information about the current interface. There is also a command to close the current interface:
The parameters are somewhat important. SoundMan-Server defaults to AudioBox AB1616 emulation. So it will have no more than 16 inputs, 16 outputs, and 16 playback channels, regardless of the number of channels on the physical interface. You might prefer instead something like
This will configure the matrix to vaguely work like an extended AB. It will have no live input channels, 40 output channels (if the interface is at least that big), and 200 playback channels.
Clears the history buffer. This can be useful for applications that leave the server up for extended periods of time. For instance, a command could be sent to clear the log at midnight. SoundMan-Server's inherent latency is extremely small, usually only a few samples long so to keep overall latency to a minimum carefully choose the audio interface card since that will determine the majority of the latency time. For manual testing there is a command line interface where commands can be typed directly. This is an easy way to experiment with commands and see what the results are.
Command Format Overview All commands are intended to be human-readable, but also easy to generate mechanically. As a result, various key elements can be expressed in several different ways. Some of these ways are easier for humans to enter and comprehend; others are easier for a machine to generate. Regardless of the exact format chosen for expression, the results will usually be exactly the same, as long as all of the elements are entered in a single command line. All commands consist of "words". These words are separated by "whitespace", that is, spaces and tab characters. Where whitespace is required to separate words, at least one space or tab character is required; however multiple whitespace characters can be used. Whitespace can precede the first word of a command and can follow the last word of the command. Sometimes the whitespace separator characters are optional. This is generally the case when two items can be easily differentiated without intervening space characters. For instance, if a semicolon or carriage return character is used to end a command, whitespace is not required before the semicolon or carriage return character -- a semicolon or carriage return character can easily be told from any other command term without any need of spaces separating it from the other terms. Generally speaking, all commands are of one of two forms: Action requests beginning with the word SET, and inquiry commands beginning with the word GET. (There are a few other special terms also.) GET or SET by itself is not meaningful. You have to say which kind of item within the Server environment that you want to interrogate or change, and which specific item you are interested in. Then you have to say which specific property of that item you want to set or get. So a GET or SET command has the general format: GET <item type> <item identifier> <item property> SET <item type> <item identifiers> <item property> <property value> Note that with a GET command you should only identify a single item in one command. For instance, only inquire about the current gain setting for a single channel at once. This makes it easier to sort out the inquiry responses and be sure that you always get the response you expect. On the other hand, with a SET command it is often very handy (and sometimes necessary) to be able to set the same property for multiple items at the same time. For instance, you might want to mute a range of channels at the same time. When you set a property for multiple items, you must be sure that all of the items have that property. If not, the command may return an error without acting on any of the items, or some of the items may be changed before an error is returned. It will in general not be possible to determine what if anything was changed in these conditions except by using GET commands to see what the current values are, or by re-issuing a corrected command. Delimiter usage and meanings:
{ word | other word } either 'word' or 'other word' is *required*
Generally in the <descriptive name> case there should be an earlier definition of exactly what <descriptive name> turns into. For instance you might have <channel list> that is defined to be
<channel list> ::= { <channel number> | <channel range> } ...
This would say a <channel list> is one or more instances of either a <channel number> or a <channel range>, and a <channel range> is a <channel number> followed by a dash or TO followed by another channel number. Then there would have to be some additional description to say that the second number in the range has to be not less than the first number and a few other things.
Which is another way of saying START { SAMPLES <number> | TIME <number> | TC <timecode> | <number> }
Overview of Command Structure SoundMan-Server can be controlled via another program or the command line interface, which is similar to a DOS command line interface. Simplistically, there are exactly two commands: GET and SET. SET changes things, and GET returns their current values. Now we get to the question of "things". What is it you can SET or GET? We can SET or GET attributes of various things. The most common thing is a channel. This simplicity is reflected in the basic command formats:
(You can abbreviate CHANNEL as CHAN.) Well, what is a channel list? This would seem to be fairly central to the interface. And it is. Fortunately a channel list is pretty simple. Anyone that has programmed a lighting console in the last 20 years will recognize the basic "channel list" format immediately. The only slight difference is that we not only have channel numbers, but we also have channel types. Playbacks are completely separate from live inputs. You can think of the box as two complete matrices summing to the same outputs. Channel capability: *EVERY* live input, playback input, crosspoint, and output, has a "control lump" that provides the following functionality:
Every "analog" control can be faded over time. This includes gain, delay, EQ frequency, EQ band gain, etc. You have all of the above controls at every summing node in the box. Playback inputs have additional parameters:
The start point is where to start playing initially, normally 0. The stop point is when to stop playing, normally the end of the track. The resume point is the point to loop to when you hit the end of the track. It doesn't have to be the same as the start time. Normally disabled and zero.
Channel Groups You often want to specify more than one channel in a command. Channel specifications are a list of channels and channel ranges, somewhat in the way that a light board specifies channels. If you give more than one channel to a command, exactly the same thing happens to all of the channels you specify. This is especially important with the PLAY, PAUSE, STOP and RESUME commands. If you specify a list of channels in a single command they WILL start or stop synchronously and stay that way. If you use a series of individual play or stop commands you have no assurance of synchronization. Groups allow you to lock any number of playback channels to timecode. You can also lock the timecode generators to incoming timecode from a reader, so you can either regenerate timecode or you can generate timecode of a different form locked to the input timcode (for instance, generate 24 fps timecode from 30 fps timecode. SMPTE readers are "fake output channels". There are up to eight of them, starting with channel O1000. You can route any input channel or for that matter playback channel to any of the readers. You should never route more than ONE source to a given reader if you want it to decode correctly SMPTE generators are "fake playback channels". This lets you start and stop them in sychronism to other playback channels, and to set speed and pitch and starting time using "track" parameters, just as you might do if you were playing back a timecode track recording. There are up to eight SMPTE generators, starting with channel P1000. Playing back multiple tracks in sync to timecode requires the use of a GROUP. There are a number of group channels with names starting from GROUP 0 or G0. The group is the ringmaster that receives incoming timecode from a timecode reader and makes sure that all of the playback channels in the group stay in sync. To make this work you first have to declare a group that has a number of playback channels in the group, and which also has a SMPTE reader. You also specify the timecode lock mode and starting timecode value for the tracks. All tracks in a group need to start at the same timcode value, and tracks locked to timecode position cannot be set to loop. If the track looped there would be multiple possible timecodes for each position in the track. This is not currently allowed. There are two ways you can lock tracks to timecode. You can lock them by pitch/speed, or you can lock them by time. Sometimes all you need is to make sure that your playback channels will play at the same speed as some external device, like a video projector, but you can start and stop the sound manually. If this is what you want, you want to lock to timecode speed. This lets you start and stop tracks manually, and the tracks can loop. However, they will faithfully follow the incoming SMPTE playback rate. More commonly you want to lock the playback tracks to a constant time position. When you do this you can set all of the tracks to be locked (in the group declaration) and start the tracks. If timecode is not present, or it is before the track starting time, the tracks will not play. Once the timecode appears and is stable and within the track range the tracks will play to timecode. You can manually stop the tracks even if timecode is still playing, and they will stop. When you start them again there will be a short delay while they seek to the current position for the current timecode value. Audio will only follow timecode that is running forward. If the timecode stops, or starts running backward, or runs at a constant frame number, the audio will not play. Once the timecode is running forward and is within the track time range the tracks will play IF they have previously received a PLAY command. When playing tracks to timecode, you do not send the Play command to the individual tracks as you would normally do. Instead, you tell the group to play, for instance, PLAY G0. The commands necessary to play to timecode and all specific commands are described under SET GROUP, below. Channels are numbered from 0 to numchannels-1. Channels are classified by their type: input, output, xpoint, etc. So a complete channel specification would be Also if you are setting delay fades for a group of playing channels and don't want phase errors you should probably send a single delay change command to all the channels.
You can specify channel groups which allows groups to to be
controlled by master channels and other groups:
Future versions of SoundMan-Server will include additional tools for synchronizing multiple servers on multiple interfaces. If you can manage to loop a spare input/output pair between all of the servers, they will be able to lock to pretty much sample accurate across all interfaces
You can run these together:
You can do channel lists:
You can do channel ranges:
This last one specifies all crosspoints between inputs 4/5/6/7 and outputs 12/13/14 You can mix-and-match in a single command:
Assuming a 10x10 matrix that would be equivalent to
Channel ranges are very powerful tools. Basic commands:
Detailed Command Structure A channel spec for a single channel has the form:
There are several values for channel type:
In the above lines the vertical bar "|" means "or". So you can talk about an input channel as an INPUT or as an IN or simply as an I. They all mean exactly the same thing. You can use one form in one command and another form in another command. In fact you can use all of the forms in the same command if you want to. A <channel number> is a fairly simple concept. A channel number is simply an integer from 0 to one less than the number of channels. That is to say, channel numbers are zero-based, just like they were in the commands to the AudioBox. Since channel numbers are zero-based, we subtract one from the instance number of the channel to get the channel number. For instance, the first input channel would be called INPUT 0. If we have 16 input channels, the last input channel would be called INPUT 15. So, skipping ahead a bit, if we wanted to un-mute input channel 7 (the eighth input channel), we would say:
Above I mentioned a channel list, but I've only described how to talk about a single channel. The formal syntax for channel list is a little convoluted, but the concepts are simple. A channel list is simply a list of channels and channel ranges.
Channel ranges refer to a sequential group of channels of a single type; for instance, a range of input channels or a range of output channels. You cannot have a single range that includes both input and output channels. Because people are human they like to do things simply. But machines are simpler yet they may want to do things the hard way. A channel range lets you have it both ways. Most people would do a channel range for input channels as something like:
A machine on the other hand might end up generating:
Those channel range specifications are exactly equivalent and will talk about the same three input channels: 3, 4, 5. Finally we get to channel list. A channel list is a list of channels and ranges separated by spaces where necessary to make the words clear. (Usually spaces aren't required). Following are examples of channel lists as a human might be inclined to enter them:
In those last three examples we've introduced the syntax for crosspoint channel specifications. Note that a crosspoint has to talk about both an input and an output channel, since it is the junction in the routing matrix between an input and an output. A crosspoint channel spec must therefore have both an input and an output channel number, or possibly input and/or output channel ranges. After the channel spec is the channel attribute. There are lots of channel attributes, because there are lots of things you can do with a channel. The more common ones are: MUTE SOLO GAIN GAINDB PHASEREVERSE DELAY EQ Some of those, like MUTE, are "on/off" attributes. The only values they can have are ON or OFF. So you can say:
or
This example shows that you can "loop back" from the end of an attribute list to the front of a channel spec, all in the same command. It depends on how lazy you are whether you want to do that. You can also do several things to a channel or channel group in the same command:
Some channel attributes are "analog" in nature. For instance, gain and delay can both have values other than ON and OFF. You use numbers to describe the values for an analog attribute. An example above is the "GAINDB -20.3". You could also do "DELAY .015" which would set the delay for some channel to 15 milliseconds. When you set an on/off parameter, the change is instant. It goes from the current value or state to the new value or state instantly, with no intermediate values, because there are no intermediate values. With an "analog" parameter, you can either set the value instantly (as shown above) or you can fade to the new level over time. Depending on the parameter you are setting you can sometimes specify a curve that will be used for the fade. In other cases the curve is implicit. When you specify an analog value, you are specifying the target value or final value. You give the value you want to be there at the end of the change. You do NOT say anything about the current value. So you can't talk about the concept of specifying a "fade up" or "fade down", because the same target level could be either up or down, depending on the current level. Suppose I want to "fade out" the volume on a channel over 3.1 seconds. I can say the following:
Of course, maybe I'm a bit more comfortable thinking in terms of timecode. In that case:
Note that timecode is currently assumed to be 30fps non-drop. Fade times are in seconds, and fade timecodes are in frames. So the last example above shows a fade of 93 frames, which is 3 seconds plus 3 frames at 30fps. The SET MATRIX command is modeled on the AB command of that name, but extended some:
Examples:
The SET CHANNEL command is the workhorse of the thing:
Options include: GAIN GAINDB MUTE SOLO DELAY EQ PHASEREVERSE TRACK
GAIN 1 is full gain. Gain .5 is -6db. Gain 2 is double normal, and will clip unless the signal levels are low.
Does exactly the same thing as GAIN, but lets you do it in dB.
These are binary options, you can turn them on or off.
Lets you turn the delay off (remembering the current delay value) or turn the delay on, or set a delay value. In some cases you can set a negative delay. (The sum of the input and crosspoint delay for all crosspoints that are on has to be greater than or equal to zero.)
Note that Q and bandwidth are not the same thing, but they control the same internal parameter.
Example of setting up from scratch and doing a simple multitrack playback:
Examples of Real World Commands With the above information you should have a pretty good chance of making commands that would set up many of the features of the routing matrix. There are many other commands (there are things other than channels, and there are some special commands other than SET). There are also specialized attributes that exist only for playback channels. These are needed to be able to play back audio files and will be detailed in the next release of this document. Here is a simple output test to confirm that everything is basically working:
SET CHAN I1000 MUTE OFF GAIN 0.2;
This should result in a 1kHz sinewave on all output channels. Here's one typical practical example: This is the complete setup required to play a seven-channel synchronized fountain show with appropriate static routing to the outputs. The first 5 channels are audio, the last two are a SMPTE track for the lasers and lighting, and an FSK track for the fountain controller.
CONFIG SET INTERFACE "MOTU 324" MODE AUDIOBOX INPUTS 0 PLAYBACKS 16;
The first line attaches the server to a MOTU 324 ASIO driver. It also says to not use any input channels, have 16 playback channels (the default for AUDIOBOX mode) and use however many output channels (up to 16 for AUDIOBOX mode) that are on the interface. The second line sets the gain for all channels and crosspoints to "off", which is GAIN 0 or GAINDB -144. The next 7 lines assign audio files to playback channels and set the starting point 120 seconds into the tracks. This skips the first 2 minutes of SMPTE preroll on these tracks. The tracks will not loop, and will stop when they reach the end of the various files. (The files are in different lengths, so will stop at different times.) The next three lines are a little confusing. They are setting up the matrix in a test configuration for stereo playback. The tracks actually are:
In a real configuration we might actually set up the matrix something like this:
The commands to do that might be
Two things worth noting in the above:
Commands and Responses All commands are sent on a single line per command. The command line is ended with a normal "newline" character or combination, normally the Enter or Return key on a keyboard, or in C, the sequences "\n" or "\r\n". Command text may be terminated before the end of the line with a semicolon ";" character. This allows comments on the end of the command lines, if desired. (Also, when entering commands in the command line of the Server monitor window, the semicolon or carriage return is mandatory to end the command.) Commands are entered as human-readable text strings. The commands consist of combinations of certain key words and parameters of various types. Many of the key words and parameter identifiers can be spelled in various ways, catering to both how humans and machines might want to enter commands. For instance, the key word "channel" can also be entered as "chan". Commands may be entered in upper case or lower case, or any combination. There are two basic kinds of commands: control commands and inquiry commands. Control commands have a strictly defined single-line response format. Inquiry commands have a more loosely defined response format that may be a single line, or often multiple lines. When using optional UDP multiple commands separated by a carriage return and linefeed ("\r\n", or in hex 0D0A) can be given in a single packet. The first command in the packet starts at the front of the packet. A command can not be split across packets. The maximum packet size is 1500 bytes.
Control Command Responses The purpose of a control command response is to indicate that the command was received, and to additionally indicate that the command succeeded or failed. Control command responses immediately follow the command, and are never returned out of order, and every control command will return a single-line response. Control command ("SET" command) responses are human-readable text, and are always returned in upper case. These responses always begin in the first character of the response message (no leading spaces) and always end with an "\r\n" line ending combination. To make machine parsing of responses easier, every control command response begins with the word "OK" if the command succeeded or the word "ERROR" and a four digit response code if the command failed. Following this response code will be a description of the error. The error response numbers are intended to indicate the general category of the error cause. These numbers are not completely standardized yet, and will be documented in a future command set revision. A response starting with "ERROR" is the only signifier of an error having occurred. SoundMan-Server does not require a response to errors from client applications and will in all other respects continue operating normally. We recommend the client application create a log of responses and errors so shows can be debugged. Of course you can also obtain logs from SoundMan-Server. Some client applications should deal with errors that are critical to their operation. The general principle behind SoundMan-Server is that there should be nothing that can stop the show, and that errors can be rectified by subsequently sending the correct commands. However, you should pay special attention to these two error types:
We recommend querying the interface on startup to see how many inputs, outputs, and playback channels there are. If there are fewer than the show requires you may want to bring up a message letting the operator know. We also recommend storing the real number of in/out/pb channels, and have a routine that builds channel lists for commands. This routine would check the requested channels against the real channels and remove any channels that don't exist. You might want to generate internal error messages if you end up cutting channels from commands. After these error mitigation procedures, simply logging commands and errors (possibly showing the errors in a special colour) and responses (with timestamps) should be sufficient.
Inquiry Response Format An inquiry command (a "GET" command) can return a single line error response as described above for control commands. This would most often happen when there is something wrong with the syntax or parameters of the inquiry command. An inquiry command normally returns either a single line response or a multiple-line response. Any specific command will always return the same type of response, either single-line or multiple-line. The number of lines in a multi-line response is not fixed, but it is easy to determine mechanically. A single-line response obviously only returns a single line. Inquiry command responses are not limited to upper-case only, as are command and error responses. Some inquiry commands can request multiple responses at periodic intervals. Each of these periodic responses can be single-line or multiple-line, depending on the normal response format for the inquiry command in question. An example of this is the GET VU command, which can request that VU updates be sent at periodic intervals until requested otherwise. Asynchronous responses (ones that are not the direct result of a preceding command being issued) are not yet implemented. However when they are, the first character of the first line of an async response will be an "@" character to flag the line as async. If it is a multi-line response only the first line will be flagged with an @ sign. It is expected that all async responses will be single line responses, but the program receiving one should check the rules given above to determine if the response is a single-line async response or the first line of a multi-line async response. All multi-line responses are guaranteed to be transmitted as a group. No other single or multi-line response will ever be mixed with another multi- line response.
Single-Line Response Format A single-line inquiry response begins with an indication of the response purpose. This is not as formalized as the OK or ERROR response described above, but does indicate the purpose of the response. For instance, a GET VU response begins with "VU". The response code for each inquiry command is documented with the command.
All single-line responses except OK or ERROR are terminated by a semicolon
character to
make parsing easy. The caller receiving a response can tell if it is
single-line or multi-line by making some simple checks:
Multi-Line Response Format Any response with a first line that does not have a first word of OK or ERROR or does not end with a semicolon is the first line of a multi-line response. The complete multi-line response ends with a line containing a single ".\r\n" in the first character position. A multi-line response begins with a header line indicating the type of the response. Following that will be zero or more lines of actual response text. A final line consisting of a lone period (technically the sequence ".\r\n") indicates the end of the response. No other responses can be interspersed with this multi-line response, and the order of the lines in the response will never be jumbled (unless caused by network problems and failure of correct packet sequence reassembly.) Note that a program sending an inquiry command that returns a multi-line response must expect the possibility of getting a single-line error response instead. Thus, it is not sufficient to go into a loop looking for an ".\r\n" response line to end the response. It is also necessary to check for the first line of the response beginning with "ERROR". No multi-line response will ever begin with this string.
Queued Responses SoundMan-Server always sends a command or inquiry response immediately on completion of the command or inquiry processing. The Server only processes one command at a time (on each control port) and never overlaps command processing or processes commands out of order. Thus the Server will never queue up responses, nor will it send them out of order. However, in the Telnet TCP or optional UDP protocol, the send and receive streams are asynchronous. Multiple commands may be sent by a client before attempting to receive responses; there is no requirement that a receive be done between every command. (Most clients will be able to have a read "pending" at all times on the TCP or optional UDP port, and thus will always be able to receive responses from the Server.) If a client sends multiple commands before looking for responses, there will be multiple responses queued up in the response queue. Doing this is generally bad practice; if one command fails and this is not noted until after a number of other commands are sent, the subsequent commands may not have the intended effect. Even though the responses have been queued by the Telnet protocol, there should be the same number of responses as commands issued.
Missing Responses The Server should always send a response for every command. However, network protocols are not 100% reliable, and there is the slight chance that either a command to the Server or a response from the Server can get lost. Since the Server is always a "responder" it does not need any sort of timeout on receiving the next command -- it is prepared to wait forever for another command. However, most client software will care about getting responses to its commands and inquiries. It should therefore have code to protect against the possibility that an expected response will not arrive. How this is coded must be determined by each individual application. However, processing responses immediately after each command is sent can make detection and recovery from missing responses (and the possibility of commands that got lost before getting to the Server) much easier.
Setting Multiple Properties in One Command SET commands can also be used to set multiple properties for the same items. For instance, you could set both gain and delay for multiple channels with a single command. Thus, the overall SET format expands to: SET <item type> <item identifiers> [<item property> <value>]… In the above line, the "[]…" syntax indicates that the items in the square brackets are repeated one or more times. A single SET command can also set properties for multiple types of items, or more commonly, for multiple items of the same or similar type. For instance you might want to mute one or more channels while at the same time unmuting other channels. You can do this by repeating the contents of the SET command beginning with the <item type>. So we can expand the above definition of SET to: SET [<item type> <item identifiers> [<item property> <value>]…]… This is probably a little confusing, so an example is in order. Say you want to mute input channel 1 and unmute input channel 2. You can use the following command to do this: SET CHANNEL INPUT 1 MUTE ON CHANNEL INPUT 2 MUTE OFF You can look at this as being two separate commands combined into one: SET CHANNEL INPUT 1 MUTE ON SET CHANNEL INPUT 2 MUTE OFF Of course when you combine multiples like this you don't have to set the same property in both. The following is perfectly legal: SET CHAN IN 1 GAINDB -20 CHANNEL OUT 5 PHASEREVERSE ON Note the above example uses the abbreviations CHAN, IN, and OUT instead of spelling out the full words CHANNEL, INPUT, and OUTPUT. You can use abbreviations any place that you would use the full word.
SoundMan-Server Items and Properties Before proceeding with a description of the command format, it is necessary to introduce some idea of the "things" that exist inside Soundman-Server, and what properties those things have. The various commands all refer to these items and properties, so it is important to understand what they are talking about. SoundMan-Server is basically a two-dimensional audio matrix. Audio input appears on input channels , where it is controlled in various ways. This controlled audio stream from an input is then routed to a row of crosspoints where it can be directed to output channels where it can be further controlled. Each input channel has its own row of crosspoints, with one crosspoint control for each available output channel. Each output channel sums the signal at its crosspoints for all of the input channels. Thus, the signal from any input channel can be directed to any or all of the output channels. There are various types of input channels. One type of input channel is connected to an ASIO audio "live input". Another type of input channel is a "playback channel" and is connected to a single audio channel in an audio file being played. (If the audio file has multiple channels, each channel in the audio file must be connected to a separate matrix input in order for the sound in that channel to be heard.) Another type of input channel is a signal generator. There can be other specialized types of input channels. In contrast to the multiple types of input channels, there is essentially only one type of output channel. This is connected to the live output channel on the ASIO interface, and results in audio output to a speaker or other device. As mentioned above, the input channels are connected to the output channels through "crosspoint channels", or more simply just "crosspoints". A crosspoint never connects directly to an input source or an output destination -- it is always an intermediary between the input channel and the output channel. Thus, SoundMan-Server has the following basic types of "items" that you might want to control:
There are a few additional items that can exist under certain conditions and configurations, but they are not as generally useful as the items above. They are discussed later in separate sections. The ASIO interface and the signal and timecode generators will be discussed in separate sections later. That leaves the various forms of channels to be discussed here.
Channel Syntax The general form of the command set has been introduced in preceding sections. This section begins detailing the actual syntax of the various commands and command options available. As mentioned previously, all commands begin with a key word. The available command key words are:
Except for the CONFIG commands, almost every action refers to one or more channels . A channel can be an input channel, an output channel, a playback channel, a crosspoint channel, or a playback crosspoint channel. It is very common to want to talk about more than one channel in a single command. Therefore, there is specific syntax to talk about single or multiple channels in a simple and easy manner. Channels can also be named. Since channels are used in virtually every command, the forms are detailed in the next section before the actual commands are described. In general any channel of any type can appear in <channels> for any command. Some few commands or parameters are only applicable to certain channel types. For instance, the PLAY command only accepts playback channels, and specifying an output channel would be an error. These limitations are described in the individual commands.
Channels Individual or multiple channels are used in virtually every command. This section describes the syntax used to describe channels in a command. There are several ways that the same thing can be accomplished. There is no preference on one way over another, they can all be used interchangeably. Multiple methods can be used in the same command without problems. It is felt that certain forms are generally more reasonable when entered by hand, while other forms may be preferred when a program is generating the commands. There is no requirement that one form or another be used. At the lowest level is a Channel Specifier . This is the way to specify one single channel. A Channel Specifier must give the type of the channel and the number of the channel. Channels have the following types. The following are equivalent and all mean the same thing:
As are these:
A CROSSPOINT goes between an INPUT and an OUTPUT. A PLAYBACKCROSSPOINT goes between a PLAYBACK and an OUTPUT. While INPUT and PLAYBACK channels are very similar, it helps to give them separate names. This allows each type to use the same channel number range, while still referring to separate channels. Each channel must have a channel number . Channel numbers begin with 0 and work upward. The maximum input or output channel number is determined by the ASIO interface in use, plus any limitations on the number of channels that might have been given when the interface was configured. For a typical 2x8 interface such as an Echo Gina, the maximum input channel number is 1 and the maximum output channel number is 7. This gives an input channel range of 0 to 1 and an output channel range of 0 to 7. So a complete Channel Specifier consists of the channel type and the channel number . The following are some examples of valid input and output channel specifiers:
Note that for convenience the space between the channel type and the channel number is optional. You can put it in or leave it out, it doesn't matter. Channel Specifiers for Crosspoints and Playback Crosspoints are more complex. There is one crosspoint for each input/output channel combination. So to specify the crosspoint of interest, you must specify both an input and an output channel number, rather than just a single number. This is done using the form: Input-channel . Output-channel So a complete Crosspoint Specifier might be of the form:
In each case, the first number is the input channel number and the second number is the output channel number. Jumping ahead a bit, the command: SET CHAN X3.2 GAINDB -90 This would set the gain for input channel number three to output channel number 2 to -90dB, or nearly silent. Note that this is setting the crosspoint gain, not the input or output gain itself! Even though this sets a very low gain between input channel 3 and output 2, it is quite possible to have a high gain between input channel 3 and output channel 5 at the same time. Individual channels can also be named and their names used in all commands instead of the channel number. A crosspoint can be named, and referred to by name in commands that take a crosspoint identifier. The crosspoint can also be referred to by input_name.output_name, or by the usual number.number.
Channel Ranges Often you want to do the same thing to sequentially numbered channels. You could do this by specifying each channel individually: IN1 IN2 IN 3 IN4 for instance. But this gets tedious. So you can do the same thing with a channel range. A channel range consists of the channel type specifier followed by the lowest numbered channel in the range, a dash or the word TO, and the highest numbered channel in the range. So the example given above can also be done as
This illustrates that spaces are optional around the dash, and between the channel type and the first channel number. Note that spaces are only optional around TO when it is next to a number. It also shows that if you want you can repeat the channel type after the dash. However, if you do this, it must be the same channel type as the initial type. The following examples are invalid channel ranges:
Crosspoint channels can also have channel ranges. Just as the basic crosspoint channel specification is more complex than an input or output channel, the crosspoint channel ranges are more complex. In a crosspoint channel range you can have an input channel range, an output channel range, or both an input and output channel range. The ranges are specified just like the input and output ranges described above, but are combined into the crosspoint format:
Ranges with a dash work as you would expect. You can do an input channel range, an output chanel range, or both in the same channel spec. It is important to realize that doing this makes a rectangle, so x 0-1.0-1 is channels x 0.0 0.1 1.0 1.1 A comma separator is always equivalent to a space in a channel list. So you can do things like IN 3-5,9 and it works fine. It is exactly equivalent to IN 3-5 9 In crosspoints, a space after the end of a valid crosspoint spec (that is, after a valid (input-range . output-range) goes back to expecting an input-range. And that expects a dot and an output-range. So you CAN'T do things like X 1,3,5.0-4 or X 0-3.1,5,9
In the first case the first 1 is an input channel, and since there is no dash
the next thing needs to be a dot and then the output channel. It isn't, so
it is an error.
A crosspoint channel range specification can be preceded by the word
DIAG or DIAGONAL. This will indicate that only the diagonal crosspoints
should be affected by the command. "Diagonal" crosspoints are those
crosspoints where both the input and output channel number increments
between each crosspoint, for instance, x0.0, x1.1, and x2.2 are diagonal
crosspoints, but x0.0 x1.0 x2.0 are not.
For example, all the following commands produce exactly the same result:
Channel Lists Sometimes you need to specify a collection of channels and you can not use a range because you have to skip channels. For instance, in a multi-pair stereo setup you might want to set the level for all of the left channels: 0 2 4 6. You can do this easily with a channel list . A channel list is nothing more than a list of channel specifiers and channel ranges. Unlike channel ranges, there are no requirements that the channel numbers be in increasing order, nor that all channels must be the same type. In a channel range, you can have a channel type followed by a collection of channel numbers separated by spaces. For instance: OUTPUT 3 4 5 6 You could also do that as O3 O4 O5 O6 Of course this is equivalent to the channel range O3-6 Or to the combination of a list and a range:
A channel list doesn't require that all of the channel types be the same: SET CHANNEL I 0-15 O 0-15 X 0-15 . 0-15 GAIN 0 This would set every input, output, and crosspoint gain to zero (minus infinity in dB) on a 16 by 16 channel matrix with a single command. This should give you a feel for the channel specification format. More formally it is specified as: // Channel: // I | IN | INPUT number // O | OUT | OUTPUT number // X | XPOINT | CROSSPOINT number.number // PX | PBXPOINT | PLAYBACKCROSSPOINT number.number // // Range: // number { TO | - } number // // Sequence: // number,number
Common Channel Properties All channels, whether input, output, crosspoint, playback, signal generator, timecode generator or any other type, have certain control features in common. Certain channels (notably playback channels) have some additional features or properties not shared by other channel types. However, they still have the basic features shared by all channels regardless of type. Every channel has the following control abilities:
Channel properties can be divided into continuous and discrete settings. The first three parameters above are continuous, and the remaining ones are discrete. Any continuous parameter can be faded over time. The fade can be linear, logarithmic, table lookup, or some other shape. Sometimes the fade shape is determined by the type of the parameter. For instance, delay fades are always linear. Other times there is a default fade shape (which may be different under different conditions) and this default fade shape can be overridden to other fade shapes. In general the fade shape has been chosen to produce the most pleasing results under most circumstances; but there will always be cases where another shape will produce better results.
Fade by Time The command option is in the form: FADETIME time A fade time is the time required to "fade" some continuous control value from its current value to the target value. The time is expressed in seconds, with a possible fractional part. The fade time refers to the previous parameter setting in the command line. So the term "FADETIME 2.3" might be controlling a gain fade in 2.3 seconds, or a change in the delay time over 2.3 seconds, or some other value.
Fade by Timecode The command option is in the form: FADETC timecode A fade timecode is the same concept as a fade time, but the fade time is expressed as a timecode. The default framerate for the timecode is 30 frames per second, but this can be modified with a framerate specifier in the timecode value. This timecode value is converted internally to a time in seconds, and this is further converted to a time in samples at the current interface sample rate. You can specify either FADETIME or FADETC for a single item, but not both. However, it is perfectly legal to use a fade time on one term (possibly gain) while using a fade timecode on another term (possibly delay). The timecode value has the form: [[[[ HOURS :] MINUTES :] SECONDS :] FRAMES [.FRACTIONS][F24|F25|F29|F30] This long line can be divided into two parts: a time value and a framerate specifier. The time value will be discussed first, and includes everything up to the "fractions" part. If you just enter a number with no colons, it represents a time in frames , not in seconds. In other words, the statement "FADETC 15.5" will do a fade over 15.5 frames , or just over half a second at 30 frames per second. Note that it is not necessary to specify zeros for the hours, minutes, and seconds. "FADETC 15:2" is a fade of 15 seconds and 2 frames. So is "FADETC 00:0:15:2.0". Note that you don't need exactly two digits in each field. It is also not required to keep the values for hours, minutes, seconds and frames in the natural ranges. If you give a value that is larger than the natural range for a field (greater than 59 for minutes and seconds, grater than or equal to the framerate value for frames) the value will be converted correctly. It is perfectly valid to say "FADETC 402.17" to fade over 402 and a fraction frames, or to say "FADETC 105:15" to fade over 105 seconds and 15 frames. The only limit is that the maximum legal timecode value is 24 hours. If you want to give a timecode at some framerate other than 30 frames per second, you will need to specify the framerate on the end of the timecode value. You do this with a "framerate modifier" that appears on the end of the timecode. There is no space between the end of the timecode and the start of the framerate modifier. The framerate modifiers and their meanings are:
Fade Profiles The option is in the form: { LOG | LIN | LINEAR | EXP | EXPONENTIAL } Most gain fades will let you control the technique used to perform the fade. The gain change can be a straight linear level change from the current level to the final level, or a linear lookup in a gain table. Or it can be a log or exponential fade. The fade type chosen by default is different for different gain terms. By default most fades will be log or exponential fades. Currently log and exponential fades are the same type. This may change in the future. The main exception is MIDI fades, which are linear fades using table lookup. Specifying a log fade type for a MIDI fade will cause it to calculate a smooth fade rather than interpolating from table values.
Parametric Equalizer Properties Each of the seven bands of EQ can be controlled individually. Each band has the following properties:
As with the normal channel properties, the filter properties can also be divided into continuous and discrete parameters, and all continuous parameters can be faded over time. The continuous filter properties are the frequency, gain, and bandwidth. Because of the mathematical implementation of each filter section (a biquad section) a simple linear change in some parameter such as frequency will not necessarily result in simple linear changes to the parameter values to the biquad over the fade range. As a result, it is quite possible that the sound of a filter fade may be unacceptable due to aliasing or other faults. In that case a small modification of the filter or fade properties might produce a perfectly acceptable fade. The user should audition any filter fades under actual conditions to determine if the results are acceptable, and be prepared to do some experimentation if not. A Flat filter is not really a filter as it does not control the gain relative to frequency. It can be used as an additional controllable gain element in some cases. It can sometimes be useful to switch a Shelf filter to a Flat filter when disabling the filter section, as it will retain the shelf gain of the section rather than switching the section to unity gain. In general though filter sections should be disabled whenever possible to reduce processing overhead. With a Low Pass filter, the low frequencies below the corner frequency are passed through. The signal will be 3dB down at the corner frequency. The shape is essentially flat below the corner frequency, and then rolls off at 6dB or 12dB per octave above the corner frequency. The gain value sets the level of the flat portion of the frequency band. A filter gain of 0dB passes the lowest frequencies through at unchanged level. A positive gain in dB will boost the low frequencies while rolling off the higher frequencies, and a negative gain in dB will reduce all of the signal by at least the amount of the gain setting. With a High Pass filter, the high frequencies above the corner frequency are passed through. The signal will be 3dB down at the corner frequency. The shape is essentially flat above the corner frequency, and then rolls off at 6dB or 12dB per octave below the corner frequency. The gain value sets the level of the flat portion of the frequency band. A filter gain of 0dB passes the highest frequencies through at unchanged level. A positive gain in dB will boost the high frequencies while rolling off the lower frequencies, and a negative gain in dB will reduce all of the signal by at least the amount of the gain setting. A Low Shelf filter is really the opposite of a Low Pass filter. A low pass filter rolls off high frequencies and passes low frequencies. A Low Shelf filter controls low frequencies while passing high frequencies unchanged. A Low Shelf filter is thus more closely related to a High Pass filter. In a Low Shelf filter, the gain controls the attenuation of the low frequencies below the corner frequency. The low frequencies can be decreased with a negative gain in dB, or can be boosted by a positive gain in dB. The amount of boost or cut is controlled by the gain. If the gain is negative, the upper frequencies will be unchanged. The gain will be down by 3dB at the corner frequency, and then will decrease at 6dB or 12dB per octave until the specified reduction level is achieved. At that point the gain will transition back to a flat portion for the remainder of the low frequency spectrum. A High Shelf filter is the opposite of a low shelf filter, and thus is more akin to a Low Pass filter. In a High Shelf filter the frequencies above the corner frequency are cut or boosted by the specified gain amount, and the gain below the corner frequency is unchanged. Note that a high or low pass filter set to 0dB gain will pass some of the frequency spectrum through at unchanged level, while rolling off part of the spectrum. On the other hand, a high or low shelf filter set to 0dB will have no effect on the signal at all. Finally the bandpass filter controls the gain at a center frequency. The gain can be boosted at this frequency with a positive gain in dB, and can be cut at the center frequency with a negative gain in dB. Thus, the bandpass filter can be used both to gently boost the signal level over several octaves, or to cut out a very narrow and deep chunk of frequencies, for instance to eliminate some power line hum. The bandpass filter has one additional control that the other filter shapes do not have: the Bandwidth value. A large bandwidth value makes the filter very wide, affecting multiple octaves. A very small bandwidth value affects a very narrow frequency range. The exact bandwidth in Hz depends on the center frequency. For instance, with a center frequency of 1000Hz and a bandwidth of .5, the filter will have half the effect at 500Hz and 1500Hz than it does at 1000Hz. (.5 * 1000Hz = 500Hz. 1000Hz-500Hz = 500Hz lower side; 1000Hz+500Hz = 1500Hz upper side.) Each filter section is implemented internally with a filter type known as a "biquad". This is a mathematical representation of a general filter. How the biquad filters the waveshape presented to it depends on the five parameter values it is given. SoundMan-Server contains routines to convert a number of standard filter shape requests into the appropriate biquad parameters and apply them to the filter band. However, external control programs may have their own biquad parameter computation algorithms that will produce additional filter shapes, or variations on filter shapes that they prefer. So it is possible to set the shape of a filter by setting the biquad parameter values directly. If a filter is set using biquad parameters and then interrogated for settings, the internal algorithms will analyze the parameters based on the known algorithms. The result may be a misrepresentation of the actual filter shape, depending on the values set in the parameters. If a program is setting biquad parameters directly, it should interrogate the current parameters directly rather than performing the normal GET requests for parameters such as filter shape and frequency. The program should also avoid any attempt to "fade" filter parameters such as gain, frequency, or bandwidth. Instead, the actual biquad parameter values should be updated rapidly by the program to implement the fade. (Although it is debatable how successful this fade will be audibly.) A note on the range of possible filter settings: not every seemingly logical filter setting is in fact possible to realize in the biquad filters being used. This is especially the case in filters with positive gains, and especially with higher-frequency filters. The problem is that the biquad parameter values are mathematically limited to certain number ranges. If the numbers exceed the valid range, the filter will not do what the user requested, and will very often produce feedback, distortion, or no output signal at all. The Server checks the parameter values generated by the requested change and will refuse to make the change if the parameters will exceed the valid range. If the invalid values result from an "immediate" (no fade time specified) change, an ERROR reply will be returned to the setting request. However, if the filter parameters are being faded, and the initial settings at the start of the fade are valid, then no error message will be generated. Instead, the fade will simply "freeze" at some point when the next fade step would have generated invalid biquad filter parameters.
Graphic Equalizer Properties A 31 band graphic equalizer is available at the channels and crosspoints. This can be used as an alternative to the 7-band parametric EQ described above. The graphic equalizer is implemented using an FFT algorithm. While this allows good control over the overall waveshape and is somewhat less processor overhead than 31 individual parametric filters would be, it has some potential drawbacks, and should be used only when absolutely necessary. The graphic EQ is quite processor hungry and memory hungry, and a small number of them can make quite a dent in the amount of processor time needed to process the audio. The graphic EQ has a QUALITY setting of 1 to 8, where 1 is the lowest audio quality and 8 is the highest. The default is 3, which should be sufficient for most uses. The quality setting affects three things:
A lower quality uses less processor power. It can also result in aliasing or chorusing distortion, especially at lower frequencies. This distortion is a natural result of how an FFT works: it divides the frequency spectrum into a number of "bins", where each bin contains the same number of frequencies. For instance, a 4-bin FFT would divide the range of 0-48KHz into 0-12000, 12000-24000, 24000-36000, 36000-48000. This FFT could produce severe aliasing an distortion, because all simultaneous tones in the range of 0-12000Hz would be merged into a single output tone. The same would happen in the range of 12000-24000Hz. This FFT size would be quite low overhead, but the chances of it being very usable are slim. You might think it would be unusable in all cases, but that might not be the case. Consider a single person speaking or singing, with no background sound in the same channel. The human voice generally makes only a single frequency at any instant. So there would be no two frequencies to merge in either of the two important frequency bins, and the resulting output would presumably be the same as the input: no distortion would result. SoundMan-Server does not use a 4-point FFT as the quality would only rarely be usable. The usable sizes are in the range of 128 to 4096 points. The QUALITY figure is used to select the number of points in the FFT, and also changes some other internal parameters that affect the overall sound quality. The higher the number the more FFT buckets, so the less chance of aliasing distortion. Before you arbitrarily decide to just set the quality setting to 8 any time you use a graphic EQ, there are two other important things to know:
The FFT size can be related directly to the amount of latency in milliseconds it will add to the channel:
The graphic EQ can be used along with the parametric EQ on the same channel. This should be avoided unless absolutely required, as both the graphic and parametric EQs use a fair amount of processor time. Use the minimum number of parametric bands, as each band added adds more processing time. By default when first turned on the graphic eq for a channel is flat. All gains are 1, or 0db, whichever way you want to look at it. You can set graphics eq bands by frequency. You don't have to get the frequencies exact, the nearest band will be set to the gain specified. For instance, band 16 has a center at 630Hz, but here I've specified 650Hz and it worked: SET CHAN I1 GEQ ON FREQ 400 = 1 FREQ 500 = 1.5 FREQ 650 = 2 FREQ 800 = 1; You can also set the bands by band number, if you happen to know the numbers. This would probably be easier for a program than a person. This is exactly the same as the command above: SET CHAN I2 GEQ ON BAND 14 GAINDB 1 BAND 15 GAINDB 1.5 BAND 16 GAINDB 2 BAND 17 GAINDB 1; If you are lazy and are setting a range of bands (as we are here) you can use the cryptic but compact form to set multiple bands at once. Again, this is exactly the same as above: SET CHAN I3 GEQ ON BANDS 14 TO 17 = 1 1.5 2 1; COMPACT FORM You can get the gain for individual bands or for all 31 bands. Probably a program would be more interested in getting all bands at once than a person would, but by doing this you can kinda see the "shape" of the graphics eq. Here we get the gain for all bands in dB. (Note that it doesn't matter if the command is in upper case or lower case):
get chan i3 geq bands gaindb;
You can also get the gain as an absolute number, where 1 = flat, > 1 is a bump, and < 1 is a cut. This can be easier for a program to deal with than a human:
get chan i3 geq bands gain;
Here is the documentation in small cryptic form of what the commands are. Ignore the "//" on the front of the lines, I clipped this from comments in the source file. The indenting here implies that the indented stuff follows the stuff on the less-indented line above. Thus the first three lines say:
SET CHAN <channels> GEQ QUALITY <number, 1 to 8>
The term "fpt" means a floating-point number, that is, a number that can have a decimal point rather than just an integer. So taking a selection of the leading lines, we can build the command: SET CHAN I14 GEQ BAND 2 GAINDB -6.37; There are commands to get the response for both individual parametric EQ bands, and for all EQ enabled on a channel, including both parametric and graphic EQ. The response values are given in dB, where 0dB indicates a "flat" response for the channel. The eq response values do NOT include overall channel gains, only the gain contributions from the eq for the channel. EQ # Eq chanid=ON|OFF
GET CHANNEL <chans> EQ RESPONSE Will get the response of all enabled parametric eq bands for the channel, plus the response of the graphic eq if it is enabled. If no eq is enabled, the response will show as flat at all frequencies. The response is returned as 31 numbers representing dB values for specific frequencies. The frequencies are the same as the 31 band centers for the graphic eq bands. These are logarithmically spaced across the audio frequency spectrum, so will give a good overall impression of the frequency response, but it will not show fine detail from very narrow filter bands. If it is known than there are very narrow parametric bands in use, the user can get a more accurate overall response by issuing a few commands of the form: GET CHANNEL <chans> EQ RESPONSE AT <freq> Where the frequencies are picked to cover the area of the narrow eq band. For instance, this could be used to request the overall response at the center frequency of a bandpass filter to get an accurate value for the bottom of a notch or the top of a bump. Since the 31 band responses are in 1/3rd octave increments they will provide good overall frequency response coverage, and requesting individual responses should only be needed for the center frequency of bandpass filters, or at most a few frequencies around the corner frequencies of the various enabled filters. Because it can be desirable to show a graphic response of the individual eq bands as well as the overall eq curve, you can get the response for each band individually. In this case the response will show the eq band response even if the band is disabled. It is up to the caller to realize that disabled eq bands do not contribute to the overall channel eq value. These individual band responses do not include any contribution from the graphic eq subsystem. However, you can get the graphic eq response in dB with GET CHAN <chans> GEQ GAINDB To get the overall response for an individual band, use a command in the form: GET CHAN <chans> EQ BAND <band> RESPONSE This will return the response as 31 numbers, which are the gains in dB at the standard 31 band centers, as described above. The response format (as shown above to the right of the command) is slightly different than described previously, since the band number is included at the front of the response. Since the eq band might be a narrow notch or bump, you can get the exact response at a specific frequency with GET CHAN <chans> EQ BAND <band> RESPONSE AT <freq> This is again very similar to the command described above, except that it returns the response for only the single band requested, and it will show the band response whether or not the band is enabled. Playback Channel Properties In addition to the common channel properties described above, playback channels have a number of additional properties that are required to connect them to the appropriate section and channel of an audio file. These additional properties are generally:
A single Playback Channel can only play a single audio channel from an audio file. If the file is a stereo file or a multitrack file, one audio channel must be dedicated to each channel in the wave file. To mix a stereo audio file to mono, both channels in the file must be assigned to playback channels, and then the outputs from those playback channels must be assigned equally to the same output channels, where they will be summed to mono. It will be common for multiple audio channels to be assigned to the same audio file, and generally they will be playing from the same area of the file simultaneously. While the file may be specified many times in different playback channels, the file will only be opened a single time, and all of the playback channels will generally be reading data from the same buffer. Soundman-Server contains a "file server" that is responsible for keeping track of the open audio files and insuring that the audio data is available in common buffers for use by the various playback channels. Note that while it will be common to play multiple channels from the same audio file in exact sync, this is not a requirement. One channel can be playing audio from one section of the file, and simultaneously another channel can be playing sound from a completely different section of the file. Or two channels can be playing audio from the same section (or different sections), but at different speeds due to a pitch shift on only one playback channel. As with other channel properties, the "continuous" values in a playback channel can be faded. This would be the speed factor and/or pitch. This permits various "broken record" or "drunken" effects where a pitch change fades over time. The various offset times can not be faded in a playback channel, as doing so would generally make little sense. They can however be changed frequently by external command if there is some reason to do so. The file name is given as a quoted string, and must contain the complete path to the file; for instance "C:\wavefiles\Track14.wav". If the file being played is a mono file, or if no file channel number is given, the first or only channel in the file will be played. This is channel number 1. The channel number must be specified to play any channel other than the first channel in the file. The starting and/or ending time offsets can be used to only play a part of the sound in the file. The times can be specified as either a time in seconds (including fractional seconds) or as a timecode at 30fps. The track will play from the starting time offset up to the ending time, and then will generally stop (but can be made to loop back to the start time continuously). Note that the start and stop times can be changed while the file is playing. Thus, a loop can be used to produce any number of unusual effects if the control program is on its toes about changing the various loop points as the track plays. The Sample Rate, Playback Speed and Playback Pitch settings all interact with each other. The most processor-efficient playback is when the file sample rate is the same as the ASIO interface sample rate, as no conversion is required. However, the ASIO interface will often be running at 48KHz, and many playback tracks are likely to be recorded at 44.1KHz. Thus, a sample rate conversion will be required to make the track play at the correct speed. The Server uses a simple and efficient interpolation algorithm to determine the sample levels when performing a pitch shift or sample rate conversion. This will sound fine on very large selection of material. There will be some material where this algorithm will be unacceptable. In those cases there are two possibilities. The first is to set the ASIO interface to the same rate as the media sample rate, if possible. This is the most efficient for playback anyway, and should be selected if all of the media is played at 44.1KHz and there is little or no use of live ASIO inputs. The second method is to use an off line wave file editor to convert the sample rate of the audio file, and then play the converted audio file. Wave editors can perform the conversion off line and take many minutes (or hours) to perform the conversion. Thus they have available many algorithms that cannot be used by a real time playback system such as SoundMan-Server. The sample rate conversion (if used) can be regarded as setting the "base playback rate" for the file. The Speed and Pitch settings then modify that playback rate. The Speed setting is a multiplier. If Speed is set to 2, the channel will play back at twice the base playback rate. If it is set to 0.5 it will play back at half the base playback rate. Note that a Speed setting of 2 is equivalent to a pitch shift of one octave up, and a Speed setting of 0.5 is equivalent to one octave down. The Pitch setting is also a multiplier on the base playback rate. It is specified in semitones, so a Pitch change of 12 will be one octave upward, and is equivalent to a Speed setting of 2. A Pitch change of -12 is one octave downward, and is equivalent to a Speed setting of 0.5. The Pitch value can be fractional: a Pitch of 0.01 is a one cent pitch increase. The Speed and Pitch values multiply together before adjusting the base playback rate. If you use a Speed of 2 and a Pitch of 12 the file will play back 4 times faster than normal. If you use a speed of 0.5 and a pitch of 12 the file will play back at the normal playback rate, as the speed and pitch changes will cancel out. While certain values like 0.5 and 12 easily correspond to the same things, a speed of 1.5 and a pitch of -6 will not cancel out. A pitch of -6 will only reduce the pitch by 1.414, not by 1.5. A pitch change of -7.02 would nearly cancel a speed change of 1.5, but the result would not be exact.
Signal Generator Properties The signal generators start at input channel number I1000. The signal generators can generate various fixed-pitch waveshapes, frequency sweeps, and white and pink noise envelopes. By default it will generate a 1000Hz sine wave. You can control the following generator properties:
These parameters interact to some extent. For instance, you cannot set a frequency sweep if the White Noise or Pink Noise shapes are selected, as these shapes do not have a dominant frequency that can be changed. Pausing, starting, or stopping a sweep is not possible if a sweep has not initially been specified. And you can't specify a Frequency for White or Pink noise, and specifying a frequency during a sweep cancels the sweep. Note that there is no parameter to control the generator gains. The gain is controlled by the usual input channel gain parameter for the generator input channels. The intended purpose of the signal generators is system checkout. Thus, by default their outputs are muted.
// SET GEN | GENERATOR [ channel number ]
// We are setting the channel parameters for the signal generators.
Translations for above:
The frequency is a floating-point number: set gen freq 24.0038
At this point the sweep frequency change is linear; at some point a log option may be added.
for example:
The pink noise generator levels are VERY accurate, far better than many other programs (and devices) that we have seen.
Preset Properties Introduction In general, to create a preset say
There are three general classes of information you can put in a preset: connection info (the ASIO device), group info, and channel or matrix info. By far the largest part of a preset will usually be the channel info, just because there are so many channels and crosspoints. You could make a preset that has "everything" in it with something like
You could reload "everything" back from this preset by only changing one word:
Script Properties Introduction A script is a bunch of commands bracketed by SCRIPT name BEGIN and SCRIPT same-name END. Note that potentially allows you to nest script definitions. All the commands between those two lines are part of the script. There are three kinds of things in the script:
So you can control SM-S the way you always do: with normal SM-S commands OR you can control the script using the scripting commands, which are interspersed with the SM-S commands. Scripting commands can be divided broadly into two classes: variable creation and value management, and flow control. So you have commands like:
LABEL THERE
Variables can also be used in normal SM-S commands:
VARIABLE CHAN = 0
You can also test various bits of matrix information:
play p1
you can do that a little more simply:
play p1
Or:
play p1
You can have as many scripts as you like. Scripts have names. Currently there are some hack commands like "run <scriptname>" and "stop <scriptname>". The intent is to eventually treat them more like channels so you can PLAY and STOP them. You can add scripts, delete scripts, stop and run scripts, run the same script multiple times at once, etc. You can check the status of a script. Timing marks: Normal scripts look like the above simple examples. They start when a RUN command is given and run as fast as they can, with timing controlled by WAIT and WAITFOR commands. You can also build a script with timing marks on the lines. In this case some or all of the lines start with a timecode value:
play p1-4 ; starts a TC track and audio
The first command would run as soon as the script started. The second would only run when some time source said it was 1 hour. The third would run right after the second. The final one would wait another almost 24 minutes. The idea is that you can either sync to time of day, or to the output from some timecode reader. There are commands that are supposed to set up the timing source. They probably aren't implemented and almost certainly not working currently. Then you can write an event script to run in sync with some timecode source. Not greatly useful for live audio, but handy for simulator rides.
Configuration Setting Commands Before the Server will actually play tracks or route audio it must be configured. Configuration commands are special GET and SET commands that can be used to find the available ASIO interfaces on the PC on which the server is running, and to attach the server to the chosen interface. The number of input and output channels can be at the same time limited to less than the interface actually provides, and the number of playback channels can be specified. Certain operating modes can also be set at this time. Configuration commands are the only commands that are valid when the Server is not attached to an ASIO interface. All other commands will receive an error response if the Server is not connected to an interface, even if they would be quite valid when the Server is connected. The number of configuration commands is limited, as they are essentially only involved in initial setup, and would not normally be used after configuration is complete.
CONFIG SET INTERFACE { number | "name" } <options>
The CONFIG SET INTERFACE command is the initial command that must be used to select an operational ASIO interface. Until an interface is open only CONFIG commands are available, and normal matrix and playback operation is not possible. The only required parameter is the number or quoted name of the interface. The correct information can be obtained from the CONFIG GET INTERFACES command. The options shown on the first line above represent the options shown on the following lines. No options are required, but if none are specified the Server will come up in a default configuration that may not be completely appropriate. The default configuration is determined by licensing options. All of the options must be specified on a single command line, and all of the options must follow the interface number or name. The INPUTS, OUTPUTS, and PLAYBACKS options specify the number of live input channels, output channels, and playback channels to use. In general these will default to the number of inputs and outputs on the device, or lower if licensing restrictions require. The number of playback channels is also based on the device configuration, but can be limited or expanded by licensing. It is always possible to reduce the number of input, output, or playback channels available, even though it may not be possible to increase them. The MODE parameter should not be changed. This is present for future functional enhancements, and setting it to anything other than the default of AUDIOBOX could result in Server failures or normally valid requests being denied. The warning message when the desired sample rate cannot be set is a log message. This keeps from screwing up programs that open SMS remotely. To get around a situation that exists on some ASIO interfaces there is an available modifier on CONFIG SET INTERFACE. Some ASIO interfaces mix up the channel order. For instance, if you have two M-Audio Delta 1010 interfaces, they will work together. However, the analog channels on the second interface will be separated from the analog channels on the first interface by the SP/DIF channels and the mixer return channels. If you have a 16 channel license, you will not be able to use all 16 channels. If you add ANALOGFIRST to the parameters, the descriptions of all of the channels will be examined, and any channel that has the word "analog" in its description will be moved before any other channels. Other than moving the analog channels before other channels, the channel order is preserved. In the case of the Delta 1010s, the channels will be ordered with the 16 analog channel first, followed by the SP/DIF channels for the first interface and then the SP/DIF channels for the second interface. This can also be useful with a MOTU 324 or 424 card and multiple 2408 interface modules to get the analog channels for all interfaces on the low channels. Note that this trick will only work if the description string for the channel contains "analog" in any case, including "Analog" and "ANALOG". If there are no channels that declare themselves to be analog the channel order will not be changed. To see the description strings the hardware manufacturer has provided for the audio channels (and thus determine if ANALOGFIRST will work) you can do CONFIG GET CHANNELINFO once the interface is open. This will produce a multi-line response, listing the description strings for all of the input and output channels, in order. Note that all of the channels on the interface will be shown, even if the license limits you to fewer than all of the available channels.
CONFIG SET ASIOGROUP "name" INTERFACE { "name" | number } … If two existing interfaces are numbered 0 and 1, you would create a group with: CONFIG SET ASIOGROUP "MYGROUP" INTERFACE 0 INTERFACE 1 This will group both interfaces together as a single interface group, letting you use all of the channels on both interfaces at the same time (if your license limits will allow that many channels). While interface numbers are shown above, you could have used the names of the interfaces as shown by CONFIG GET INTERFACES. Remember to use quote marks around the names! So if you have two ASIO drivers currently named "MOTU ASIO" and "AudioScience ASIO Driver" you can build a new driver called "Combined" using one of the two lines: CONFIG SET ASIOGROUP "Combined" INTERFACE 0 INTERFACE 1; or CONFIG SET ASIOGROUP "Combined" INTERFACE "MOTU ASIO" INTERFACE "AudioScience ASIO Driver"; Then you can either select "Combined" from the dropdown list or CONFIG SET INTERFACE "Combined" or CONFIG SET INTERFACE 2 The order you declare the other interfaces in the asiogroup controls the channel order. The first interface will have channel 0 and the next interface will stack above that.
CONFIG CLEAR ASIOGROUP "name" If you want to remove an ASIOGROUP so that you can use the interfaces individually, you can do this with: CONFIG CLEAR ASIOGROUP "name" Of course this will only work if the group is not currently in use. You may have to do a CONFIG CLOSE INTERFACE before you can clear the group. Once you have an interface group defined you use it exactly like you would use a single interface, for instance: CONFIG SET INTERFACE "MYGROUP".
CONFIG SET GAINTABLE { IO | XPOINT | CROSSPOINT } <128 numbers> The SET GAINTABLE command can be used to provide a custom lookup table to be used in converting MIDI gain values to actual gains. There are two gain tables: one is used for input, output, and playback channels. The other table is used for crosspoints and playback crosspoints. There should be vanishingly little need to change these tables, and doing so can produce very strange fade results. However, if the values are to be changed, there must be exactly 128 decimal numbers following the table type. These numbers are in the range of 0 to 32767, and represent proportional gain values for MIDI volumes of 0 to 127.
CONFIG SET SAMPLERATE < n > If the desired sample rate isn't the one that the interface opened at, this command can be used to attempt to change the interface sample rate. Not all possible sample rates are valid. Both the Server and the interface will limit the possible choices. Some interfaces are locked, and will only operate at a single sample rate configured in a control panel, even if another sample rate is requested. Some interfaces are not only locked, but have driver bugs that cause them to report a requested sample rate as the actual rate, when in fact they are still operating at the locked rate. When this happens playback will sound wrong, as the Server will believe the interface is operating at the requested rate, but it is in fact operating at some other rate. When this happens reset the interface to the actual rate using this command. Or close and reopen the interface, and don't attempt to change the sample rate. In these cases the sample rate can usually be set in the control panel for the interface.
CONFIG SET COMMANDLINE CONFIG SET COMMANDLINE { LOCK < key > | UNLOCK < matching-key > } The commandline lock command will lock the commandline in the dialog and set the unlock key to match the 'key' parameter. This command is only valid when the command line it NOT locked. This command can be sent from any command source, not just from the command line. The commandline unlock command can also be sent from any source and not just the commandline itself. If the commandline is currently locked and the key on this command matches the key set with the previous commandline lock command, the commandline will be unlocked. When the commandline is locked, only GET, CONFIG GET, and CONFIG SET COMMANDLINE UNLOCK commands will be accepted from the command line. All other commands will return an error response of "Commandline locked". Also, the various buttons in the dialog, including the Close button are locked out until the interface is unlocked.
CONFIG SET WINDOW MINIMIZED CONFIG SET WINDOW MINIMIZED Hides (minimizes) or shows the main UI window.
CONFIG SET WINDOW VISIBLE CONFIG SET WINDOW VISIBLE Makes the main UI window visible.
CONFIG SET SINGLETHREADING CONFIG SET SINGLETHREADING [ ON | OFF ] On some machines with poor inter-processor interrupt design, SM-S will tend to crackle and pop a lot. Restricting the processing to a single core can sometimes help on this sort of system. This command allows you to single-thread the ASIO audio processing. This sets ASIO Callback single-threading on or off. The default (and only value) for a single processor system is ON. On multi-processor systems, the default is OFF, allowing the processing to be distributed over all of the available processors. Turning single-threading on will restrict the processing to a single processor, which can help if the system has a problem handling IPC interrupts quickly. This command is only valid after the ASIO interface has been opened.
CONFIG CLOSE INTERFACE Closing the interface is usually not necessary. It will be closed automatically when a new interface is opened, and it is closed when the Server is closed. However, if there is a desire to do so, this command will close the current interface. After issuing this command, the only useful commands are CONFIG SET INTERFACE or CONFIG CLOSE SERVER.
CONFIG CLOSE SERVER Will cause the server to shut down. Before sending this command any open interface should be closed. This can be done with CONFIG CLOSE INTERFACE
Configuration Interrogation Commands Before the Server will actually play tracks or route audio it must be configured and the configuration can be interrogated using configuration GET commands. Configuration commands are special GET and SET commands that can be used to find the available ASIO interfaces on the PC on which the server is running, and to attach the server to the chosen interface. The number of input and output channels can be at the same time limited to less than the interface actually provides, and the number of playback channels can be specified. Certain operating modes can also be set at this time. Configuration commands are the only commands that are valid when the Server is not attached to an ASIO interface. All other commands will receive an error response if the Server is not connected to an interface, even if they would be quite valid when the Server is connected. The number of configuration commands is limited, as they are essentially only involved in initial setup, and would not normally be used after configuration is complete.
CONFIG GET VERSION Returns the current SoundMan-Server version number string, for example: Version 1.0.19.0
CONFIG GET INTERFACES The get interfaces command will return a multi-line response listing the available ASIO interfaces on the system. There is a header line that has "Interfaces n " where N is the number of available interfaces. This will be 0 if there are no interfaces available on the system. Following this header line is one line for each interface. The first item on the line is the interface number, then the interface name in quotation marks. From the returned list, select an interface to use, then issue a CONFIG SET INTERFACE command with either the number of the interface or the quoted name of the interface. This will open the interface (if possible) and make the Server operational. Returns a list of the available ASIO interfaces terminated by "." for example: Interfaces 2 Interface 0 "ASIO 2.0 - Maya 7.1" Interface 1 "MOTU FireWire Audio"
CONFIG GET INTERFACE This will get additional information about either the currently operational interface (if one has been configured previously) or about a selected interface from the list returned by CONFIG GET INTERFACES. The additional information will include the number of input and output channels and the default sample rate for the interface. This information can help in choosing the most desirable interface if multiple are available. Note that the Server will always attempt to open an interface at 48KHz by default, unless overridden by a different SAMPLERATE value in the CONFIG SET INTERFACE command. However, some interfaces are locked to a particular sample rate. If the interface will not operate at 48KHz, it will be used at whatever sample rate it is currently operating at. If this is very low the sound quality will be unacceptable. It is best to check the sample rate achieved after opening any interface. When this command is followed an integer <n>, it Gets information on the specified interface number, for example: InterfaceInfo 1 "MOTU FireWire Audio" Inputs 18 Outputs 18 DefaultSampleRate 48000 When issued without an interface number this returns info on the current interface, including any limitations on the number of channels, for example: InterfaceInfo 1 "MOTU FireWire Audio" Inputs 2 Outputs 2 DefaultSampleRate 44100 SoundMan-Server commands require an open interface
CONFIG GET INPUTS Returns the number of inputs available, for example: Inputs = 2
CONFIG GET OUTPUTS Returns the number of outputs available, for example: Outputs = 2
CONFIG GET PLAYBACKS SoundMan-Server commands are only valid once an interface is open. They will return the actual number of input, output, and playback channels available. This will be the lower of the number of channels requested on the CONFIG SET INTERFACE command and the number of channels actually available on the device. License restrictions can also limit the number of available channels to less than the number requested, even if the interface has enough channels available. Returns the number of playback channels available, for example: Playbacks = 4
CONFIG GET SAMPLERATE This command is also only valid after the interface is opened. It will return a floating-point number that shows the configured sample rate in Hz. Normally this will be the same as the requested sample rate, but it can be different if the interface refuses to operate at the requested sample rate. License restrictions can also limit the maximum sample rate. Gets the current interface sample rate, for example: SampleRate = 44100
CONFIG GET DEMO Returns 1 if in demo mode, 0 otherwise: Demo = 1
CONFIG GET DONGLE Returns 1 if the dongle is detected, 0 otherwise: Dongle = 0
CONFIG GET SERIALNUMBER Returns SerialNumber = AAAABBBB This would normally display as AAAA-BBBB as an example. If there is no dongle present it returns SerialNumber = 0000007B
CONFIG GET MACHINEID
This returns a response in the format:
MachineId" returns the unique machine id for the current machine. "MachineSerial" returns the serial number of the dongle if a dongle is present. Both of these values are constants, so cannot be changed by the command, only interrogated.
CONFIG GET MODE Returns the matrix operating mode: Mode = AUDIOBOX Possible values are NORMAL, AUDIOBOX, COMMANDCUE. The current standard mode is AUDIOBOX.
CONFIG GET CHANNELINFO This command will return a multiline response that will display the ASIO description string for all of the input channels, followed by all of the output channels. This can be useful in figuring out which channel number corresponds to which physical input or output on devices with multiple different interfaces.
CONFIG GET SINGLETHREADING This interrogates the status of the single-threading option. This returns the current state of the single-threading flag. The response looks like SingleThreading = ON; or SingleThreading = OFF; This command is only valid after the ASIO interface has been opened. This should only be done if absolutely required. It is not required for most ASIO drivers. Since it limits processing power, it can also result in distorted audio if you exceed the amount of work that can be done on a single processor.
Channel Commands: The bulk of the command set deals with commands to be issued to input, output, playback, or crosspoint channels. The format of a channel list has been defined in a previous section and will not be repeated here, but will be shown as "channels" in the various command formats. Channel commands can be divided broadly into SET and GET commands. By far the SET commands are the most useful, as they will control virtually all aspects of the Server. The GET commands are useful primarily to insure that a requested action took place. They can also be useful if multiple users are controlling the Server at the same time. In this case the action of one user might change something another user was expecting. A GET command can be used to determine the current status. Many of the GET commands are not yet implemented. Within the division of GET and SET commands there is a further division between playback channels and all other channels. Playback channels have a number of options related to audio file playback that are not applicable to any other channel type. These attributes, along with normal channel attributes have been discussed previously. Here we will cover the detailed command syntax for each of the attributes. Playback channel options are discussed separately after the normal channel options are described. All of the normal options are also applicable to playback channels. Remember that each channel is a "control node" with the following features available: gain, delay, and equalization. Various commands are available to deal with all of these features.
CONFIG GET SCRIPTFILES The available scripts in the SoundMan Scripts directory in My Documents are listed with this command. This command returns a multi-line response ending with a line containing a single ".". The first line is "ScriptFiles:". Each subsequent line will contain the file name for a script file in the "SoundMan Scripts" directory. The final line has the single period on it. If there are no script files in the directory the response will consist of the header line and the final dot line.
CONFIG GET SCRIPTS The currently loaded and available scripts that can be run are listed with this command. This command returns a multi-line response ending with a line containing a single ".". The first line is "Scripts:". Each subsequent line will contain the name and status of a script that is currently in memory. The script may be running, waiting for some event, stopped, or have an error of some kind. Each line will contain the name of the script followed by a colon, and then the status of that script. The status part is multiple words and is human readable. For the convenience of controlling programs, the first word of the status, immediately after the colon, is a 3 digit status number. The number of status values may change over time. While it is unlikely that any current status values will be deleted, more status values may be added in the future. The first digit of the status value indicates the general kind of the script status, and the remaining two digits provide more detail. The current status number and values are:
000 IS INVALID.
The final line of the response has the single period on it. If there are no scripts in memory the response will consist of the header line and the final dot line.
Channel Set Commands: The SET commands have the format:
Each of the SET options is covered separately in subsequent sections; some common parameters are discussed here.
SET CHANNEL NAME:
The name string cannot contain spaces or special characters other than an underscore, and must start with an alphabetic character. If the channels variable contains more than one channel they will all have the same name, and only the first will be found by name. Channels in commands may be specified by name as well as number. For an input or output channel the name can be given as <type> <channel name> or just <channel name> For a crosspoint or playback crosspoint channel the syntax can be <type> <input name.output name> or <type> <crosspoint name>. Note that you can leave the channel type off for an input or output channel but you have to give it for a crosspoint or playback crosspoint channel. Channel names do not have to be unique. However, if there is more than one channel of a given type with the same name, only the lower-numbered channel will ever be found by name. It is perfectly all right though to give both an input and an output channel the same name. The input channel will be found if no <type> is given, and either can be found if the correct <type> is given. Examples:
Channel ranges and lists can also use names instead of numbers. Examples:
More complicated names: Channel names can be unique, or they can be duplicated. Examples:
If channel names are UNIQUE, you don't have to say "in" or "out" when you talk about the channel. So you can say
NOTE that when using NAMES, you MUST separate the "I' or "O" from the name by a space. But if using channel NUMBERS, you do not need a space: "in3" is just fine. NOTE that when using CROSSPOINTS, you STILL must use "x" or "px" (or one of the other spellings) to indicate that you are talking about a crosspoint.
Note that a degenerate "channel list" consists of a single channel specification. A degnerate "channel range" also consists of a single channel, like : out 1-1.
SET CHANNEL SUBMASTER GAIN:
The gain for a channel is determined by a combination of the normal channel gain and the channel submaster gain. This command sets the submaster gain for a channel. Submaster gain is useful when it is desired to control the gain of multiple channels, without affecting the normal channel gains. You can think of this facility as a "digital VCA". While it may seem awkward having the submaster gain be an individual channel parameter, remember that channels are very powerful. For instance, you can set the submaster gain for all input channels in a single command: SET CHAN I0-15 SUB -30 FADETIME 5 This will take all of the inputs down 30dB in 5 seconds without affecting the current input gain settings.
SET CHANNEL GAIN
Set channel gain sets the primary gain for the channel. The gain is specified as a floating point number in the range of 0 to 10, where 1 is the normal 0dB or "full gain" point. A value of 0 effectively mutes the channel, and is equivalent to -160dB. Note that channel gains can be set to greater than unity. This can be used to amplify a weak signal, probably also amplifying any associated input channel noise. Specifying a gain above 1 for a hot signal will not necessarily produce instant clipping; all computations are done internally in floating point, and there is a considerable amount of headroom available in most of the processing chain. However, the gain will have to be decreased before the signal is finally output, or clipping will occur as the internal values are converted to the interface output values. The gain range on equalization is more limited than on other parts of the processing chain. An effort must be made to avoid extremely hot internal signals before feeding them to an EQ stage. Failing to do so can have very strange results, including oscillations and the signal completely disappearing. You will not necessarily get the sort of "break up" that you might expect from an analog EQ stage. If you have signals acting strangely, the first thing to do is check for abnormal gain settings above 1 or gaindb settings above 0dB. If a fade time or timecode is specified, the default fade will be an exponential fade from the current level to the new level. If the fade time is zero, or no fade time is specified, the new gain will simply be set instantly.
SET CHANNEL GAINDB
Set channel gaindb is exactly equivalent to set channel gain, except that the gain level is given in more familiar dB terms. Both of these commands control exactly the same gain point, so whichever command is used last will override any previous setting by either command. A gaindb value of 0 is "full gain" or "no attenuation". Note that positive dB values can be set, resulting in amplification. As explained in the previous section, this can be both useful and dangerous, especially where EQ is involved. Extremely fine gaindb values may be specified using up to 8 digits, counting from the first non-zero digit in the gain value (for example 1.23dB and .000123dB are both 3 digits of gain value). At settings of somewhere between -124 and -160dB the audio is set to -infinity, depending on the resolution of the specific audio interface being used,. If a fade time or timecode is specified, the default fade will be an exponential fade from the current level to the new level. If the fade time is zero, or no fade time is specified, the new gain will simply be set instantly.
SET CHANNEL GAINMIDI
Set channel MIDI gain is usually equivalent to setting the channel gain or gaindb value, except for the range of levels that can be set. The MIDI gain range is 0 to 127. A value of 0 full muted, or about -160dB. A value of 127 is unity gain. Unlike the gain and gaindb commands, you cannot set a positive channel gain using the gainmidi command. If a fade time or fade timecode is specified the default fade uses the gain table for the channel. This will be the IO gain table for an input or output channel, and the crosspoint gain table for a crosspoint channel. While these fades are not actually linear, the "linear" fade type is used to represent a table-based fade. Note that the crosspoint gain table is optimized for doing crossfades, where one channel is increasing to full as another channel is decreasing from full to zero. This provides an excellent dipless crossfade, but is fairly bad as a gain curve if you are using crosspoints as normal controllable gain elements. In that case you would probably want to specify a log or exponential fade, and a more normal fade curve will be realized. In COMMANDCUE mode, the GAINMIDI command does not control the main channel gain. Instead, it controls the submaster gain. In NORMAL and AUDIOBOX mode, the GAINMIDI command controls the normal input gain, as does set channel gain and set channel gaindb. The last command issued will override the previous command values.
SET CHANNEL PHASEREVERSE
The set phase reverse command inverts the polarity of the signal appearing at the input of the channel as passed to the output channel. Mathematically it inverts the sign of the channel gain, so positive values become negative and vice versa. You can think of it as reversing the wires at the connector, without having to worry about screwing up phantom power or grounding. Phase reverse can only be turned on and off, it cannot be faded from one setting to another.
SET CHANNEL MUTE and SOLO
The mute and solo commands affect the output from the current channel, and possibly from other channels. Turning on mute will effectively set the channel gain to zero, muting the signal. Turning off mute will restore the gain to whatever it previously was. (Which may have been zero; so turning off mute will not necessarily make signal appear at the output!) Turning on solo will override mute for a channel, so even if the channel is muted, when it is also soloed sound should come out. However, like mute, solo does not change the channel gain setting, and if it is zero or very low no sound will appear. Solo has a second effect: when an input channel is soloed, all other input channels are muted. Since solo overrides mute, you can 'solo" multiple channels at once by enabling solo on those channels. Any non-soloed input channels will be muted, but all of the soloed channels should be heard. When an output channel is soloed all of the other output channels are muted. As with input channels, multiple output channels can be soloed at once to hear only a part of the mix. Input and output solo muting has no effect on each other. It is quite possible to solo one input and one output channel and get no sound whatever, if the soloed input does not route to the soloed output. Always check soloing if things are acting strangely. There is little point in setting solo for a crosspoint channel as no other channels will be muted.
SET CHANNEL DELAY
Channel delay may be set in samples as well as fractional seconds or a timecode value. Also, if the time value is entered as a number without "TIME" in front of it, you can also enter any of the other delay parameters. The channel delay value can also be a delay in seconds and fractional seconds. This is the time between when a signal appears at the input to the channel and when it appears at the output of the channel. In addition to setting the delay value, the delay can be enabled and disabled without changing the current delay setting. Disabling the delay causes "straight through" sound. Re-enabling the delay will instantly switch back to the delay amount. By default, delay is disabled and must be enabled before it can be used on a channel. The maximum delay time is limited only by the memory on the PC. One MB of memory is approximately 5 seconds of delay time at 48KHz. If a channel is suddenly set to a large delay value, and has never had that large a delay before, the channel output will be muted for approximately the length of the delay value before sound again appears at the output. This occurs because delay buffers are only allocated when needed. Since there were no delay buffers before the large delay was requested, there is no "history" of the sound over the delay period -- the new buffers contain zeros or silence. Once delay buffers are allocated to a channel they are retained, even if the delay is set to a smaller value. So in this case, if the delay is suddenly set from a small value to a large value, there will be a jump in time of the audio output, but the delayed sound will instantly appear because it is already present in the delay buffers. When changing or fading a delay, there are two algorithms that can be used. Which sounds best depends on the speed and amount of the delay change. Soundman-Server attempts to pick the best algorithm for each case. For a "large" delay change in a small or zero time, the Server will simply "snap" to the new delay time. This will produce an audible change in the sound output, and as mentioned previously can result in silence for the new delay period under some conditions. This sort of change should never be made with the audio feed live, as it will be distinctly noticeable. For a large delay change over a reasonable period of time, from a fractional second to several seconds, the Server will "step" the delay in small increments from the current time to the new time. Depending on the program material this may or may not result in a series of small clicks, effectively "zipper noise". For a lot of material a reasonable effect can be obtained without overly objectionable artifacts. For some material the results will be completely unacceptable. That sort of material should simply do one abrupt delay change rather than attempting to fade the delay change over time. One distinct advantage of this fade technique is that generally no pitch change will be noticed during the delay fade. For a small delay change over a moderate time, a smoother algorithm is to do sample interpolation. This does not produce any clicks, but it does produce a pitch change during the delay fade. There are many cases in normal human experience where there are small pitch changes, which we ignore. For instance, if a person is walking toward you while talking, the pitch of their voice rises by several cents. We ignore this small change, even though in the listening room it would be distinctly audible. The Server attempts to select this interpolation method only for fades where the amount of pitch shift will not be objectionable. In these cases the alternate algorithm would likely produce several rather objectionable clicks as it stepped the signal, so the tradeoff works moderately well. The switchover point is based on the speed humans move. A normal walking speed is 5-10mph (8-16km/h), which is 7.5-15 feet/second (2.2-4.4m/S). Since sound moves approximately 1000 fps (300m/S), the maximum frequency change we are used to hearing (and ignoring) is on the order of 15/1000 = 1.5%. So to stay within the normal range of human experience the delay change should be restricted to a maximum of 15mS per second and preferably less than 10mS per second. In the future Server will provide a control parameter to select the delay fade algorithm to be used.
SET PARAMETRIC EQ
The set channel EQ command has many parameters and appears very complex. Multi-band EQ setting will usually be broken down into a series of commands, one or more per band. Under these conditions the command format becomes quite readable. Each channel has seven bands of EQ. The overall EQ section can be turned on or off. The individual EQ bands can also be turned on or off. EQ is a very processor-hungry operation -- an effort should be made to use as little as possible. EQ should be completely disabled whenever possible. When EQ is used, the low-numbered bands should be used in preference to the high-numbered bands. When initially setting up a channel to use EQ, the first thing to do is set up all parameters for the number of EQ bands that will be used. Setting the bands to 0 disables all EQ on that channel, even if the EQ is enabled. Only the specified number of EQ bands will be processed. Further, parameter settings for bands past the current band limit will be rejected and ignored. So the number of bands must be set before any band parameters can be set. Note that the band parameters can be set while the entire EQ section is disabled, and also while the individual section being set is disabled. The only requirement is that the number of bands must be set high enough to include the desired band before any parameters can be set. If higher bands are used at one point and are not to be used for a while, reducing the number of bands will disable these higher bands and reduce processing overhead. The parameters will be retained for later use; but audio data will not have been circulating through these bands. As a result, when they are re-enabled by increasing the number of bands, there may be one or more clicks as the audio data resynchronizes. Band changes should ideally never be made on live channels. Disabling individual bands eliminates the EQ effect that band would have. However, unlike changing the number of bands, it does not completely disable processing of the band. So there will be less of a click when the band is later re-enabled if it must be done on a live channel. Once the number of bands are set the EQ parameters for those bands can be set. This can be done while the bands are disabled and while the entire EQ section is disabled. Thus EQ can be set up before being enabled onto a channel. By default, the number of bands is set to zero, and each band and the overall EQ is disabled. The EQ parameters have been discussed in an earlier section and the description will not be repeated here. Note only that is it necessary for each band to select an EQ shape, gain, and frequency.
An example of how to set things up is:
You can set the entire EQ setup in one command, but it is probably less confusing to do it a band at a time. You can also set up multiple bands with individual enables before enabling the entire EQ setup for the channel. You would set the desired number of bands with the enable OFF, set each band, and finally turn the overall EQ enable ON.
The PARAMS command is not that generally useful. If you have software that will
take filter shape parameters and convert the to the actual floating point
values needed for the biquad filter used in SM-Server, you can pre-calculate
the parameters and input them using the PARAMS command. SM-Assistant does this,
because historically SM-Designer and similar programs such as ABShowMaker
pre-calculated the filter parameters and just downloaded the values that would
be plugged into the DSP filter coefficients.
SET GRAPHIC EQ
"SET CHANNEL n EQ" and "SET CHANNEL n GEQ" are different. The first sets the parametric EQ sections. The latter sets up the graphic EQ. Each type has its own enable. If the enable is off, the EQ processing is bypassed. As EQ processing adds latency to the channel, you can expect a glitch if you turn the EQ processing on or off. You can keep the same latency by setting the various parametric EQ sections to FLAT or by setting the band gains for the graphic EQ to 0, but this also keeps the same amount of processor overhead for not much purpose. The QUALITY setting is discussed above. The default QUALITY is 3. You should rarely find a need for a setting above 6, and there are many cases where a setting of 1 or 2 is perfectly adequate. The graphic EQ works just like the physical graphic EQs that you are used to. There are 31 "gain sliders" numbered 1 to 31 left to right. These are each set at the EIA standard band center frequencies that are used by almost all graphic EQs these days. Each gain value can be set to anywhere between +24dB and -24dB. The default is 0dB, which does not change the signal level passing through. Note that you can either say "BAND 5 GAINDB 3.6" or "BAND 5 = 3.6" and get the same results. The equal sign will save a little typing. If you don't remember band numbers but do know the band frequency, you can set the band gains by frequency rather than band number. The frequency you give will be converted to the nearest band number, and then the gain for that band will be set. Here are the band numbers and center frequencies:
SET CHANNEL PITCH
This does a pitch shift on any input or playback channel. This is a processing pitch shift on the audio stream, NOT changing the playback speed to achieve a pitch shift. On playback channels the channel pitch shift can be used with an inverse track speed or pitch shift to achieve a change in playback speed without changing the output pitch. The pitch shifting routines use a fair amount of processor, so the number of channels they can be used on is limited. Also, they do not guarantee identical phase tracking over short durations on multiple channels, so it is possible to get some stereo image shifting when pitch shifting a multi-channel audio stream. Several processing quality settings are possible. The standard setting should work well for many uses, but will fail miserably with dense rock music that is highly compressed. It can work quite well on vocal and folk music. Higher quality settings have two drawbacks: they can use MUCH more processor power, and they can have very long processing delays. The standard level of processing results in about a 10mS delay. Delays up to 170mS are possible at the high quality settings. It can be possible to get acceptable results with some audio sources using a low quality setting that will have a 10mS or even a 5mS input to output delay. Whether this can be done will depend entirely on the nature of the source audio material, and of course how critical you are of the results. Pitch can be shifted plus or minus one octave, and the shift value is entered in semitones, possibly with fractional semitone values. ON and OFF will enable and disable th epitch change processing. By default it is OFF. Turning pitch change processing on, even with a pitch shift of 0 semitones, will result in adding the FFTSIZE delay to the channel. It will also add the processing overhead for doing the pitch change. Pitch changing should be left OFF when not in use, but if it is to be used, it would be best to turn it ON before the channel is made live to avoid any click when the delay amount suddenly changes. OVLP and FFTSIZE are the two quality settings. Higher values of either one will result in better audio processing quality, but will also result in (possibly vastly) increased processing time, and increased FFTSIZE will result in a longer channel delay. OVLP ranges from 1 to 32 in steps of powers of 2; that is, 1, 2, 4, 8, 16, or 32. The default is 4, which is good for speech and many kinds of music. A value of 8 is usually good for almost any sort of program material, but requires twice the processing time of the default value of 4. A value of 16 should rarely be needed, and a value of 32 should almost never be necessary. FFTSIZE ranges from 128 to 8192 in steps of powers of 2; that is, 128, 256, 512, 1024, 2048, 4096, 8192. The default size is 512, which is good for speech and possibly rap. A value of 2048 is good for most sorts of music. Again, the processor time required doubles with each step increase in the FFTSIZE, so the smallest value that is usable should usually be used. Also, the delay increases directly with FFTSIZE. A 512 point FFT delays 512 samples, or 512/48000 = 10.6ms. An 8192 point FFT delays 8192/48000 = 170.6mS! That is almost 2 tenths of a second, which is probably unusable in live performance situations. When experimenting to find the best settings for your particular situation, first try increasing the overlap to 8. If that is not sufficient, back off the overlap to 4 and increase the FFT size by one step to 1024. If that doesn't work, again increase the overlap to 8. Continue doing this until you have acceptable sound quality with an acceptable delay. If using the method above the delay becomes too long before an acceptable quality is reached, try increasing the overlap further. You may find that by increasing overlap you are able to use a smaller FFT size and get good sound. If you need to use a lot of pitch shifting or other functions that require a lot of processor time, and the basic settings are acceptable, try reducing the FFT size or overlap and see if they are still acceptable. Especially for speech they likely will be, and will result in reducing the overall processing load, and possibly the delay. When not using the pitch shifting on a channel it is best to turn it off to remove the processing overhead. As mentioned above, this shoudl be done when the channel is quiet as the delay will snap to a new value when this is done. The delay caused by the pitch shifter is IN ADDITION to any programmed DELAY, or any delay caused by using the graphic eq functions. QUALITY sets the overall quality of the sound of the pitch shifter easily using the same QUALITY parameter that was available for the graphic equalizer (which is also implemented using an FFT). This is simpler than having to set the FFT size in samples and the overlap factor. The QUALITY value will set both FFTSIZE and OVERLAP at the same time. The values are:
As the quality increases the processing overhead also increases, quite drastically. The lowest acceptable quality should be selected if more than one channel is going to be pitch shifting. It is possible to run out of available processor power with a smaller machine or with a number of pitch shifters and graphic EQs enabled. This will have the usual bad effect of audio dropouts, crackling, and other bad things. If this happens the only solution is to reduce the quality or number of enabled graphic EQs and pitch shifters.
SET INPUT CHANNEL PHYSICAL INPUT
This command is only valid for live input channels, and only in COMMANDCUE mode. Normally the input channel controls are assigned to the physical ASIO channel inputs in a one-to-one order: input channel 0 is assigned to the first physical input on the interface (interface input 0); input channel 1 is assigned to interface input 1, etc. In a Command/Cue system, the input control nodes can be switched to different physical inputs. It is possible to have more than one input control node assigned to a single physical input, allowing the possibility of multiple distinct routing methods simultaneously for a single physical input. Since there are only as many input nodes as there are physical channels, if two input nodes are assigned to the same physical channel, it means that there is at least one physical input channel that has no input node. Any input channels with no input nodes will be effectively muted, as all incoming audio data will be ignored. There is little reason to do this sort of input node switching in a normal configuration. Any routing that can be achieved this way can generally also be achieved by normal simple matrix crosspoint settings. However, there are certain strange and unusual overlapping fade conditions that can exist in a Command/Cue system that can only be duplicated by redesigning the fades, once the old fade settings are thoroughly understood. It can be easier when moving an old show to new hardware to simply duplicate the way the old hardware worked.
SET INPUT CHANNEL ROW
This command is only valid for live and playback input channels, and only in COMMANDCUE mode. Normally each input control feeds directly to a crosspoint row. Thus input 1 feeds crosspoints 1.0, 1.1, 1.2, etc. In a Command/Cue system, the input nodes are free-standing entities, and their outputs can be switched to any crosspoint row. Thus, two or more input nodes can be feeding signals to the same crosspoint row. Since there are only as many input nodes as crosspoint rows, if two or more input nodes are feeding one crosspoint row, it follows that at least one other crosspoint row must have no input at all, and thus will not be making any sound. There is little reason to do this sort of input node switching in a normal configuration. Any routing that can be achieved this way can generally also be achieved by normal simple matrix crosspoint settings. However, there are certain strange and unusual overlapping fade conditions that can exist in a Command/Cue system that can only be duplicated by redesigning the fades, once the old fade settings are thoroughly understood. It can be easier when moving an old show to new hardware to simply duplicate the way the old hardware worked.
SET INPUT CHANNEL AUTOPAN
This command is only valid for live and playback input channels, and only in COMMANDCUE mode. Input channels in a Command/Cue system could be attached to devices called Auto-Pan™ units. These units would perform automatic timed fades, either up or down, when triggered. The fade could be linear or logarithmic. All of these fade types could be performed using either the normal input channel gain or the submaster gain for the input channel. However, in Command/Cue emulation mode, both of those gains represent other gain elements also present in a Command/Cue system. This command gives access to one of the other controllable submaster levels present in every level control node. There are several submaster levels that are used internally and which do not normally have external interfaces. One of those internal submaster levels is not used for its normal purpose in Command/Cue emulation mode, and has been exposed with this command. This command is effectively a "gain change over time" command, except that there are only two possible gain settings full on and full off. UP or ON corresponds to a GAIN 1 value at the end of the fade time. OFF or DOWN corresponds to a GAIN 0 value at the end of the fade time. The LINEAR or LOG value must also be selected to match the fade that the original hardware Auto-Pan™ would have done. An Auto-Pan™ can only do three of the four symmetrical fade possibilities; it is up to the user to select values correctly. An Auto-Pan™ unit can receive the same fade command multiple times. The initial receipt of a fade command will begin the fade. If additional fade commands identical to the first are received during the fade, they are ignored. If a new fade command is received that goes in the same direction, but the time or shape parameters are changed, these new parameters modify the remainder of the fade period. If the new fade goes in the other direction, the current fade is discarded and a new fade started in the opposite direction. The internal Auto-Pan™ fade logic duplicates these actions, so that multiple commands can be given without screwing up the fade in progress.
SET NODE NAME
Examples:
This command is only valid in COMMANDCUE mode.
SET CHANNEL PORT
Examples:
Note that this would let you remap around bad inputs and the like. Keeps the same input fader no matter where the signal is coming from. Audio playback is assigned to detachable input nodes from the main playback channels. This allows any input channel to attach to a playback stream in COMMANDCUE mode. It also makes it easier to properly implement multiple sample formats for wave files. This command is only valid in COMMANDCUE mode.
Playback Channel Set Commands: Playback channels are normal input channels, but with additional capabilities. Thus, all of the normal input channel commands are also applicable to playback channels. This section only details those parameters that are unique to playback channels.
Samples can be handy for controlling programs that have accurate sample position info in the files being played. The sample positions are in terms of file sample rate, which may be different than the interface sample rate. These options have been described generally in a previous section; the following sections will concentrate on the syntax for each command variant.
SET PLAYBACK CHANNEL TRACK FILE
Example: set chan p1 track file "T:\Audiobox001.wav" start time 120; skip preroll Before a playback channel can play, it must have an audio file assigned to it. If the audio file is a multi-track file then it also needs to have the desired track within the file specified. If no track number is specified the first or only track in the file will be played. The "filename" as described previously must contain the entire path to the file to be played, unless the PATH option has also been specified for this channel. If the PATH option is specified the default path to the file will be obtained from the PATH option. However, it is possible to specify the full path to the file in the FILE option and override the value in the PATH option. The file name must include the file suffix. SoundMan-Server does not attempt to guess either the path to a sound file or the suffix on the file. The file name must be surrounded by double-quote marks if the name contains spaces or if the name is case-sensitive and contains lower-case characters. As a general rule, file names should always be surrounded by double quote marks to be sure that they are parsed correctly. SoundMan-Server can play the following types of files. The file type is determined by a combination of looking at the filename suffix, and by analyzing the data at the front of the file.
If the file type is not recognized the file will be assumed to be a mono file with 16-bit little-endian PCM data at 48,000 samples per second. This is essentially equivalent to a mono WAV file with 16 bit data at 48K. If a file contains more than one track and it is desired to play other than the first track, a TRACK number must be specified. The TRACK number is one of the few numbers in SoundMan-Server that is one relative . The first track of the file is 1 , which for a stereo file is the left channel. If the track number is given as zero or negative a command syntax error will result. If the track number is greater than the number of tracks in the file a syntax error will also result. Since the TRACK number is part of the FILE option, it is not possible to change the track number being played without respecifying the file to be played. When you respecify the file, all other options you may have set (except the PATH option) will also be reset to their defaults. So all other options that are required must be set as well.
SET PLAYBACK CHANNEL TRACK PATH
Examples using channel lists:
Many times all of the sound files for a given show will reside in a common directory on disk. To simplify setting the file name for each file to be played, it is possible to use the PATH option to specify the directory path to all of the files to be played. Thus you only need to specify the directory path once, and only need to give the file name (including suffix) when specifying the file to play. Each playback channel can have a unique path, or many playback channels can share a common path. The path can also be changed at any time, including while a file is playing on a channel. The path name must be surrounded by double-quote marks if the path contains spaces or if the path is case-sensitive and contains lower-case characters. As a general rule, path names and file names should always be surrounded by double quote marks to be sure that they are parsed correctly.
SET PLAYBACK CHANNEL TRACK START TIME
This option specifies the time into the file where playback will start. The time can be specified in seconds (and fractions) or as a timecode value at 30FPS. Playback will initially start at the given START time if it is within the length of the audio file. If it is beyond the end of the audio file it will be ignored. If no start time is given, the file will start from the first sound sample. If the Start time is given for a channel that is already playing, it will be remembered; but will not have any effect on the current playback. If the track is stopped, either because it reaches the Stop point or because it is manually stopped, then the next time the track is started it will start from the new start time. If the track is paused and resumed the Start time will not have any effect on the point at which the track resumes -- that will occur where the file was paused. However, if a file is Paused and then Stopped while it is Paused, the paused state is cleared and the file will start from the Start point next time. Once a Start point is set, it can be cleared to zero by using the Clear option.
SET PLAYBACK CHANNEL TRACK STOP TIME
This option specifies the time into the file where playback should stop. For AudioBox emulation, a loop can also be set up between the Stop point and the Resume point. STOP TIME or STOP TC is used to set the stop point. If no stop point is given it will default to the end of the track. Once a stop point is set, it can be enabled with STOP ON or disabled with STOP OFF. Setting the time implicitly enables the stop point. If the stop point is disabled it is remembered but ignored. This can be used to set a conditional stop in the middle of a loop in a track. If the stop point is disabled with STOP OFF the track will stop at the end of the file if it reaches that point. The stop point can also be cleared with STOP CLEAR. This will set the stop point to the exact end of the track. Stop notification can also be turned on and off. When stop notification is on, a message will be sent to the controlling terminal when the stop point is reached. The NOTIFY is not yet implemented.
SET PLAYBACK CHANNEL TRACK REPEAT TIME
The Stop point works in conjunction with the Repeat point to implement looping. When the Stop point is reached a check is made to see if a Repeat point exists and is enabled. If it is, the playback will not stop; instead it loops to the Repeat point. Both the Stop and Repeat points can be changed while the track is playing. Used in conjunction with the Stop and Repeat notifications, a controller can implement very creative sequences of playback from an audio file. The Repeat point can be turned on or off once it has been set. Turning it off will not change the remembered time, but will cause the point to be ignored. The Repeat point can also be completely cleared. When it is cleared it has no valid time, and can not be enabled until set to a valid time. The trick is that looping isn't "simple", that is, it doesn't just loop the entire file. It can loop just a part of the file. So you have to tell it what to loop. The general setup is to loop from the stop point (implicitly the end of the track) to the repeat point. The repeat point has no default position, so you have to specify it. SET CHAN P0 TRACK FILE "foo" REPEAT TIME 0; When you play the track it will loop until you tell it to stop. The NOTIFY parameter is not yet implemented.
SET PLAYBACK CHANNEL TRACK SPEED
The Speed and Pitch options have been described thoroughly in a preceding section. They are essentially identical except for the numbers they use to express the playback speed change. Speed is expressed in terms of fractions of the original playback speed. A value of 1.0 represents the original speed. 2.0 is double the original speed, and 0.5 is half the original speed. Note that the Speed and Pitch terms combine to produce the final actual playback speed. If you double the speed and reduce the pitch by half the playback speed is the original speed.
SET PLAYBACK CHANNEL TRACK PITCH
The Speed and Pitch options have been described thoroughly in a preceding section. They are essentially identical except for the numbers they use to express the playback speed change. Pitch is expressed in semitones. A change of one octave upward in pitch is a change of 12. A change of one octave downward is -12. Since the pitch is a floating point number, a change in cents can easily be had: 0.01 is a one cent upward change. Note that this pitch change is accomplished by changing the playback speed. This is not a pitch-shifting algorithm that attempts to shift the playback pitch while leaving the playback time unchanged! Note that the Speed and Pitch terms combine to produce the final actual playback speed. If you double the speed and reduce the pitch by half the playback speed is the original speed.
Channel Get Commands Channel Status Request Commands This is not an exhaustive set of possible status requests, but it covers many of the most common needs. A channel status request can request a common status type (such as gain or delay or mute status) for multiple channels of any type. The response for all channels will be returned on a single line. All status response lines have a common format: status_type channel_id = status_value ... ; newline The status_type identifies the type of channel status on this line. All channels on the line return the same kind of status. The status type is always a single word with an initial capital letter and usually the remainder of the word in lower-case. Each channel, even if there is only one, is identified by the short form of the channel identifier. This consists of one or two letters and the appropriate channel numbers. The status value will be appropriate for the status being returned. For numeric values this can be an integer or a floating-point number, as appropriate. For an on/off status such as the mute status of a channel it will be ON or OFF. For the channel name it will be the name string in all uppercase, or "None" (without the quotes) if the channel does not have a name assigned. Parts of the commands are indented, and an indented line must be preceded by the command part on the next outer line. For example, CHAN or CHANNEL must be proceeded by GET (forming GET CHAN or GET CHANNEL). DELAY must be proceeded by CHAN or CHANNEL, which itself must be preceded by GET, forming GET CHANNEL DELAY. The status_value shows the response that will be returned. All responses start with a unique single keyword that is a mixture of upper and lower case. This makes it possible to distinguish easily from an error response or some other line. Since all response starters are unique, if responses are parsed asynchronously it is possible to determine what each response is about without knowing the command that generated the response. A GET command can ask about multiple channels at once. Each channel response is in the form of <channel identifier><equal sign><response><space>. The final channel response is followed by a semicolon, which terminates the response line. The entire response, no matter how long, will be on a single "line" with no carriage returns or the like in the response text. There is a carriage return and linefeed after the semicolon at the end of the response. The channel identifiers are the same as the most compact form used for SET command input. For instance, input channel 0 is I0 and playback channel 10 is P10. Remember that crosspoints have two numbers, so will be of the form X2.3 or PX12.14. There is always exactly one channel identifier immediately followed by an equal sign with no spaces. The response to the query for that channel then immediately follows the equal sign with no intervening spaces. Another channel identifier, equal sign, and response value can then follow the response value for the first channel listed. Channels are not necessarily listed in the same order in responses that they were given in the original GET command. Do not depend on the order being the same. Query responses are usually numeric. They can be integer numbers, floating point numbers that contain a decimal point, or a timecode value. None of these items contain spaces. So you can determine the end of the response value for each channel by looking for the first space after the equal sign. Sometimes the response value is a string value of some form. There are three general cases for this. The first is querying something like the shape of an EQ section. The response is a fixed string that is more descriptive than an arbitrary number would be. This string has a fixed spelling and does not contain spaces, so it is given immediately after the equal sign, and again the end of the response word can be determined by looking for the first space. The second case of a string response is asking for a channel, group, or other item name. Names are always uppercase and never contain spaces. They may be a mixture of numbers and letters and underscore characters. The first character will always be a letter. Again, names never have spaces in them, so scanning from the equal sign for the first space will find the end of the name field. The final case of a string response is asking for a file name. Here the file name can contain any characters except a double-quote mark, and can be upper and lower case mixed. The file name can also contain one or more spaces, and very often does. In this case there will be a " mark immediately after the equal sign. The file name will follow this, and will be terminated with another " mark. In this case the file name string must be parsed by looking for the trailing quite mark, and NOT by looking for the next space! There will be a space after the trailing quote mark and then the next channel identifier or the trailing semicolon will show up, in the usual manner. In the following lines, there are small keywords that indicate the form of the response you should expect. The more common ones are:
The following detailed listings show the currently valid channel status commands, the response status_type value, and indicates the type of value to expect. All requests are of the form GET CHANNEL channel_list word
GET CHANNEL NAME GET CHANNEL channel_list NAME returns the response in the form status_type channel_id = status_value
GET CHANNEL PORT GET CHANNEL channel_list PORT returns the response in the form status_type channel_id = status_value
GET CHANNEL ROW GET CHANNEL channel_list ROW returns the response in the form status_type channel_id = status_value
GET CHANNEL GAIN GET CHANNEL channel_list GAIN returns the response in the form status_type channel_id = status_value
GET CHANNEL GAINDB GET CHANNEL channel_list GAINDB returns the response in the form status_type channel_id = status_value
GET CHANNEL GAINMIDI GET CHANNEL channel_list GAINMIDI returns the response in the form status_type channel_id = status_value
GET CHANNEL PHASEREVERSE GET CHANNEL channel_list PHASEREVERSE returns the response in the form status_type channel_id = status_value
GET CHANNEL MUTE GET CHANNEL channel_list MUTE returns the response in the form status_type channel_id = status_value
GET CHANNEL SOLO GET CHANNEL channel_list SOLO returns the response in the form status_type channel_id = status_value
GET CHANNEL DELAY GET CHANNEL channel_list DELAY returns the response in the form status_type channel_id = status_value
GET CHANNEL DELAY STATUS GET CHANNEL channel_list DELAY STATUS returns the response in the form status_type channel_id = status_value
GET CHANNEL DELAY TIME GET CHANNEL channel_list DELAY TIME returns the response in the form status_type channel_id = status_value
GET CHANNEL DELAY TC GET CHANNEL channel_list DELAY TC returns the response in the form status_type channel_id = status_value
GET CHANNEL DELAY FADETIME GET CHANNEL channel_list DELAY FADETIME returns the response in the form status_type channel_id = status_value
GET CHANNEL DELAY FADETC GET CHANNEL channel_list DELAY FADETC returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ GET CHANNEL channel_list EQ returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ ENABLE GET CHANNEL channel_list EQ ENABLE returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BANDS GET CHANNEL channel_list EQ BANDS returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND SHAPE GET CHANNEL channel_list BAND number SHAPE returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND ENABLE GET CHANNEL channel_list EQ BAND number ENABLE returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND PARAMS GET CHANNEL channel_list EQ BAND number PARAMS returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND GAIN GET CHANNEL channel_list EQ BAND number GAIN returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND GAIN FADETIME GET CHANNEL channel_list EQ BAND number GAIN FADETIME returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND GAIN FADETC GET CHANNEL channel_list EQ BAND number GAIN FADETC returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND GAINDB GET CHANNEL channel_list EQ BAND number GAINDB returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND GAINDB FADETIME GET CHANNEL channel_list EQ BAND number GAINDB FADETIME returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND GAINDB FADETC GET CHANNEL channel_list EQ BAND number GAINDB FADETC returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND BANDWIDTH | BW GET CHANNEL channel_list EQ BAND number BANDWIDTH | BW returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND BANDWIDTH | BW FADETIME GET CHANNEL channel_list EQ BAND number BANDWIDTH | BW FADETIME returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND BANDWIDTH | BW FADETC GET CHANNEL channel_list EQ BAND number BANDWIDTH | BW FADETC returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND FREQ | FREQUENCY GET CHANNEL channel_list EQ BAND number FREQ | FREQUENCY returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND FREQ | FREQUENCY FADETIME GET CHANNEL channel_list EQ BAND number FREQ | FREQUENCY FADETIME returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND FREQ | FREQUENCY FADETC GET CHANNEL channel_list EQ BAND number FREQ | FREQUENCY FADETC returns the response in the form status_type channel_id = status_value
GET CHANNEL GEQ | GRAPHICEQ ENABLE GET CHANNEL channel_list GEQ | GRAPHICEQ ENABLE returns the response in the form status_type channel_id = status_value
GET CHANNEL GEQ | GRAPHICEQ BAND GAIN GET CHANNEL channel_list GEQ | GRAPHICEQ BAND number GAIN returns the response in the form status_type channel_id = status_value
GET CHANNEL GEQ | GRAPHICEQ BAND GAINDB GET CHANNEL channel_list GEQ | GRAPHICEQ BAND number GAINDB returns the response in the form status_type channel_id = status_value
Also, if you just enter the following with no other parameters:
GET CHANNEL GEQ | GRAPHICEQ GAIN GET CHANNEL channel_list GEQ | GRAPHICEQ GAIN returns the response in the form status_type channel_id = status_value
GET CHANNEL GEQ | GRAPHICEQ GAINDB GET CHANNEL channel_list GEQ | GRAPHICEQ GAINDB returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ RESPONSE GET CHANNEL channel_list EQ RESPONSE returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ RESPONSE AT GET CHANNEL channel_list EQ RESPONSE AT freq returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND RESPONSE GET CHANNEL channel_list EQ BAND number RESPONSE returns the response in the form status_type channel_id = status_value
GET CHANNEL EQ BAND RESPONSE AT GET CHANNEL channel_list EQ BAND number RESPONSE AT freq returns the response in the form status_type channel_id = status_value
GET CHANNEL LEVEL GET CHANNEL channel_list LEVEL returns Level chan = fpt
GET CHANNEL LEVELDB GET CHANNEL channel_list LEVELDB returns LeveldB chan = fpt
GET CHANNEL PITCH GET CHANNEL channel_list PITCH returns the response in the form status_type channel_id = status_value
GET CHANNEL PITCH QUALITY GET CHANNEL channel_list PITCH QUAL | QUALITY returns the response in the form status_type channel_id = status_value
GET CHANNEL PITCH DELAY GET CHANNEL channel_list PITCH DELAY returns the response in the form status_type channel_id = status_value
GET CHANNEL PITCH ENABLE GET CHANNEL channel_list PITCH ENABLE returns the response in the form status_type channel_id = status_value
GET CHANNEL PITCH FFTSIZE GET CHANNEL channel_list PITCH FFTSIZE returns the response in the form status_type channel_id = status_value
GET CHANNEL PITCH OVERLAP GET CHANNEL channel_list PITCH OVERLAP returns the response in the form status_type channel_id = status_value
GET CHANNEL PITCH SHIFT GET CHANNEL channel_list PITCH SHIFT returns the response in the form status_type channel_id = status_value
GET CHANNEL PITCH SHIFT FADETIME GET CHANNEL channel_list SHIFT FADETIME returns the response in the form status_type channel_id = status_value
GET CHANNEL PITCH SHIFT FADETC GET CHANNEL channel_list PITCH SHIFT FADETC returns the response in the form status_type channel_id = status_value
GET CHANNEL TRACK FILE GET CHANNEL channel_list TRACK FILE returns the response in the form status_type channel_id = status_value
GET CHANNEL TRACK STATUS GET CHANNEL channel_list TRACK STATUS returns the response in the form status_type channel_id = status_value
GET CHANNEL TRACK POSITION GET CHANNEL channel_list TRACK POSITION returns the response in the form status_type channel_id = status_value
GET CHANNEL TRACK TIME GET CHANNEL channel_list TRACK TIME returns the response in the form status_type channel_id = status_value
GET CHANNEL TRACK LENGTH GET CHANNEL channel_list TRACK LENGTH returns the response in the form status_type channel_id = status_value
GET CHANNEL TRACK START TIME GET CHANNEL channel_list TRACK START TIME returns the response in the form status_type channel_id = status_value
GET CHANNEL TRACK START TC GET CHANNEL channel_list TRACK START TC returns the response in the form status_type channel_id = status_value
GET CHANNEL TRACK STOP TIME GET CHANNEL channel_list TRACK STOP TIME returns the response in the form status_type channel_id = status_value
GET CHANNEL TRACK STOP TC GET CHANNEL channel_list TRACK STOP TC returns the response in the form status_type channel_id = status_value
GET CHANNEL TRACK REPEAT TIME GET CHANNEL channel_list TRACK REPEAT TIME returns the response in the form status_type channel_id = status_value
GET CHANNEL TRACK REPEAT TC GET CHANNEL channel_list TRACK REPEAT TC returns the response in the form status_type channel_id = status_value
GET CHANNEL TRACK SPEED GET CHANNEL channel_list TRACK SPEED returns the response in the form status_type channel_id = status_value
GET CHANNEL TRACK PITCH GET CHANNEL channel_list TRACK PITCH returns the response in the form status_type channel_id = status_value
GET CHANNEL TRACK TITLE Some wave files have title information stored as attribute data in a non-audio chunk in the file. GET CHANNEL channel_list TRACK TITLE gets the title information from the file if there is any title data present. Otherwise it will return the file name without the path or "wav" suffix. The response is in the form of a line starting with the keyword followed by one or more instances of <channel id>=<value>. A typical GET and its response is:
GET CHAN P0-P1 TRACK TITLE
This gets static information about the file that is loaded onto the channel. If no file is loaded, the attributes that return strings will return empty strings, and the attributes that return numbers will return zero.
GET CHANNEL TRACK DISPNAME Some wave files have "display name" information stored as attribute data in a non-audio chunk in the file. GET CHANNEL channel_list TRACK DISPNAME gets the display name attribute from the file, if it exists. The response is in the form of a line starting with the keyword followed by one or more instances of <channel id>=<value>. A typical GET and its response is:
GET CHAN P0-P1 TRACK DISPNAME
This gets static information about the file that is loaded onto the channel. If no file is loaded, the attributes that return strings will return empty strings, and the attributes that return numbers will return zero.
GET CHANNEL TRACK SUBJECT Some wave files have subject information stored as attribute data in a non-audio chunk in the file. GET CHANNEL channel_list TRACK SUBJECT gets the subject attribute from the file, if it exists. The response is in the form of a line starting with the keyword followed by one or more instances of <channel id>=<value>. A typical GET and its response is:
GET CHAN P0-P1 TRACK SUBJECT
This gets static information about the file that is loaded onto the channel. If no file is loaded, the attributes that return strings will return empty strings, and the attributes that return numbers will return zero.
GET CHANNEL TRACK COPYRIGHT Some wave files have copyright information stored as attribute data in a non-audio chunk in the file. GET CHANNEL channel_list TRACK COPYRIGHT gets the copyright attribute from the file, if it exists. The response is in the form of a line starting with a keyword followed by one or more instances of <channel id>=<value>. A typical GET and its response is:
GET CHAN P0-P1 TRACK COPYRIGHT
This gets static information about the file that is loaded onto the channel. If no file is loaded, the attributes that return strings will return empty strings, and the attributes that return numbers will return zero.
GET CHANNEL TRACK COMMENT Some wave files have comment information stored as attribute data in a non-audio chunk in the file. GET CHANNEL channel_list TRACK COMMENT gets the comment attribute from the file, if it exists. The response is in the form of a line starting with the keyword followed by one or more instances of <channel id>=<value>. A typical GET and its response is:
GET CHAN P0-P1 TRACK COMMENT
This gets static information about the file that is loaded onto the channel. If no file is loaded, the attributes that return strings will return empty strings, and the attributes that return numbers will return zero.
GET CHANNEL TRACK SAMPLERATE GET CHANNEL channel_list TRACK SAMPLERATE gets the sample rate for the file. The response is in the form of a line starting with the keyword followed by one or more instances of <channel id>=<value>. A typical GET and its response is:
GET CHAN P0-P1 TRACK SAMPLERATE
This gets static information about the file that is loaded onto the channel. If no file is loaded, the attributes that return strings will return empty strings, and the attributes that return numbers will return zero.
GET CHANNEL TRACK TRACKS GET CHANNEL channel_list TRACK TRACKS gets the number of tracks or channels in the file. The response is in the form of a line starting with the keyword followed by one or more instances of <channel id>=<value>. A typical GET and its response is:
GET CHAN P0-P1 TRACK TRACKS
This gets static information about the file that is loaded onto the channel. If no file is loaded, the attributes that return strings will return empty strings, and the attributes that return numbers will return zero.
Playback Control Commands Several commands exist solely to control playback in a simple way. There can be any number of playback channels. Each channel can be idle or playing. If it is playing it can be an individual "spot" track or one of a number of tracks. When playing multiple channels, it is vital that all tracks remain in sync. This can be assured by using a single command to start, pause, resume, or stop all the playback channels involved. By using a single command, it is assured that all channels will start or stop at exactly the same time with sample accuracy. If multiple commands are used to start or stop tracks, there is no assurance that they will start or stop at the same time. They may start at very nearly the same time, but they will almost certainly not start with absolute accuracy. This can result in phasing errors in multitrack material. The following commands exist to control playback. Note that these are neither GET nor SET commands, they are unique command types of their own. PLAY PAUSE STOP REPEAT (or RESUME) REWIND RESUME
PLAY PLAY playback-channels The Play command will seek to the starting position for all of the tracks and begin playing in sync. Note that this is different than the Play function for an AudioBox, which starts at the current track position, and may not start at all if the tracks have reached their stopping points. To get AudioBox-like response, use the RESUME command instead of the PLAY command. The Play command will begin playing one or more playback channels. If multiple channels are specified, the Play command will insure that all channels are ready to play before starting any of the channels. All channels must have track files loaded in order to play. If any specified channel is incapable of playing, it will be ignored. No error message will be returned even if none of the playback channels could be started. In order to play, a playback channel needs to have a wave file attached, and the first few seconds of audio from the file must be buffered in memory. This requires opening the file and reading data from it. Depending on the speed of the system disk and the amount of disk activity, this could be nearly instantaneous, or it could take several seconds. Whenever possible, playback channels should be set up well ahead of the intended playback time. When multiple channels are to be played (for instance, 24 tracks) the channels should be set up at least 5 or 6 seconds before they will be started, to allow time for all of the files to be opened and the initial audio loaded. If playback is from network connected disks it is advisable to allow even longer between the setup and the play request. When the Play command is issued a check will be made to see that all tracks are ready to play: the files are open and there is at least 2 seconds of buffered audio for each track. If these conditions are not met, the Play command will wait until they are. This can result in delaying the start of the audio playback from when it was requested. All tracks will start simultaneously as requested; but not necessarily when requested. Opening the tracks early and allowing time to buffer the audio data into memory will eliminate this possible delay when requesting a Play of the tracks.
PAUSE PAUSE playback-channels The Pause command will temporarily suspend playback of all playing channels. Playback can be resumed later by again issuing a Play command. It is the user's responsibility to insure that the paused channels are the same as the channels initially started. If one of the original channels that was started isn't specified in the Pause command it will continue to play. SoundMan-Server does not remember that the channels were playing together; it is up to the user to remember that. The Pause will happen as soon as it is received, and all specified channels will stop at exactly the same sample position. A subsequent Play command can thus resume them in sample-accurate sync. Since the audio data is already buffered, this later Play command will not experience any delay.
STOP
The Stop command does one of two things. If no parameters are given other than the playback channels, they are immediately stopped. Stopping channels is similar to pausing them. But when they are restarted they will restart from the initial Start points specified for the tracks, not the point where the tracks were paused. Since the tracks must seek to another position to play, there can be a short delay if the ensuing Play command is issued soon after the Stop command. If any parameters are supplied on the Stop command, no immediate effect is had on playback. Instead, the playing channels are set up to stop at the specific time, or other stop options are set. See the SET CHANNEL TRACK STOP command for a description of all of these options. The Stop command is equivalent to the TRACK STOP clause when used to set these parameters.
REPEAT (or RESUME)
Repeat specifies the starting point for a track to continue playing after reaching the end point of the track. In other words, the track will loop from the end point to the repeat point. The repeat point can be specified as a time or as a timecode, but not both. The ON parameter is set automatically if a time or timecode value is used, it enables the repeating function. OFF will disable the repeating functin, but remembers the resume point. CLEAR disables the repeat function and clears the repeat time. If a repeat point has been set up, REPEAT NOW will act as though the end of track had just been detected and will jump to the repeat point immediately. Multiple commands may be used or it can be done all in one command, for example: SET CHAN P0 TRACK FILE "C:\MYTRACK.WAV" START 30 STOP 60 REPEAT 30 That will load some track (presumably at least 60 seconds long, start playing at the 30 second point (once a PLAY P0 command is seen) and will get to the stop point at 60 seconds. However, because REPEAT is not negative, it will not stop, but will jump to the repeat point and just keep looping. Or it can be done as two commands, per the following example:
SET CHAN P0 TRACK FILE "C:\MYTRACK.WAV" START 30 STOP 60
Of course the start point does not have to be the same as the loop-back point. If there was an introduction on the track you only wanted to play once you could do START 0 or just leave the START parameter off, or you could start 45 seconds in if that made for a better initial starting point.
REWIND REW playback-channels The REWIND command will set all of the tracks to their starting positions. If any of the tracks are currently playing they will be stopped. After the tracks have been positioned to their starting positions they will not be playing.
RESUME RESUME playback-channels The RESUME command can be used to continue playing after a PAUSE command has stopped the tracks. The tracks will continue playing in sync from the current locations. If the tracks have reached their stop points and are not looped, the RESUME command will have no useful effect. The AudioBox Play function is equivalent to the RESUME command in SoundMan-Server, not to the PLAY command.
Preset Commands A preset can be used to take a snapshot of the state of various SM-S settings, including the current ASIO device that is configured. One specific preset (with a special name) can be automatically loaded on startup, bringing the system to the point it was at when the preset was saved. Presets are very large binary files and can be clumsy to use, and you can't fade from one preset to another, you can only replace them instantly. However, it is the only thing internal to SM-S that will automatically configure the system at startup time. These let you quickly load and save the state of the matrix. You can save a preset with particular gain or EQ settings for a group of channels and then instantly restore them at a later point. Virtually all parameters for all inputs, playbacks, outputs, or crosspoints can be saved and restored. Presets are instant. They save the current channel state, or, if a parameter is fading, they save the target value at the end of the fade. When you restore a preset, it instantly sets the various channel values, but it does NOT restore any fades that were in process! Instead, the value is set to what it would have been at the end of the fade. For playback channels the current stopped/playing state and current track position is NOT saved. If a playback channel has the track info restored the channel will be stopped, and will begin playing at the start point when the channel is resumed. Presets are intended for between-scenes setup, not for running fade changes. In addition to the matrix state, the ASIO connection info can be saved and restored. If a preset is saved with the ASIO connection info in it, and that info differs from the current matrix state, the currently in use ASIO device will be closed, the new one specified in the preset opened, and the entire matrix will be rebuilt. This will stop all playback and reset all matrix parameters; however, they will be restored to what was saved in the preset after the matrix is rebuilt. Presets are normally stored in My Documents\SoundMan Presets. Every preset is stored as an individual file, and the preset files can be given any name the user desires, as long as it is a valid file name. One preset is recognized with a "special" name. The preset SOUNDMAN_STARTUP is used to load the state of SM-S when it is first started. This preset will only exist if the user creates it by saving a preset with that name. The preset must include the ASIO connection info to be useful, as it is loaded at a time when the matrix has not yet been connected. It can also contain setup information for the matrix if non-default setup information is desired. If only the ASIO info is restored, the preset will effectively just open the ASIO device and leave SM-S idle, waiting for commands. Presets can be stored in places other than the normal "SoundMan Presets" directory. This is not recommended, but there are times that it could be useful. There is a command to set a new preset directory. This location will be remembered for the next invocation of SM-S, so it only has to be set once, if used. There is a command to display the current preset path. As to what the files look like: the preset is a binary file that contains the status of virtually everything in SM-S. You can select the parts of the system to save when yoiu make a preset, and you also get to select which parts of the preset you want to load back. Generally most people save everything and load everything back, with the exception of the current ASIO device. That is only saved and reloaded on the startup preset. You could make a startup preset with a command something like PRESET SAVE CONNECTION GROUPS ALLGROUPS MATRIX ALL TO "SOUNDMAN_STARTUP". Normally you can recall that with PRESET RESTORE CONNECTION GROUPS ALLGROUPS MATRIX ALL FROM "SOUNDMAN_STARTUP", but it should also load when SM-S is starting up. There are currently four preset commands:
None of these commands are valid until the ASIO device is opened. That means you cannot save a preset with a close ASIO device state. You also cannot load an arbitrary preset before the ASIO device is opened; only the SOUNDMAN_STARTUP preset will be loaded before the ASIO device is opened. To make a startup preset use the PRESET SAVE <stuff> AS "SOUNDMAN_STARTUP" command. This would give it the right name and put it in the right place. It will also overwrite any previous version of the preset.
PRESET SET PATH PRESET SET PATH "path" This command sets a non-default preset storage path. This path is remembered in the registry and the same path will be used by all SM-S invocations until it is changed. It is not recommended that the preset path be changed.
PRESET GET PATH This command will display the current preset path. The format of the one-line response is: PresetPath="path name"
PRESET SAVE This command saves selected parts of the current SM-S state into a preset. The preset can later be restored. The text following "SAVE" can be divided into three parts:
1. The initial parts MUTED and CONNECTION
If the word MUTED appears in the SAVE command, it will be remembered until the preset is reloaded. During the reload process all of the output channels will be muted, and the mute will only be removed after the preset has been completely loaded. This is intended to prevent loud and embarrassing noises blasting out of speakers if major EQ or delay changes or full-matrix gain changes are being made. The word CONNECTION results in the ASIO interface data being saved to the preset. This generally should NOT be used except for an initial setup preset of some sort. If a preset contains connection data and you ask that connection data be restored on the reload, the entire matrix is rebuilt, which can take a number of seconds, during which you will have silence and no control over channel parameters (as the channels will not yet exist). MUTED and CONNECTION can appear in any order after SAVE. The next part of the command contains an identifier for some channel or group of channels, and then a list of things to save for that group. This can be repeated any number of times, so that it is possible to save different things for different channels. GROUP will save information for one or more group channels. A valid information type for group channels is ALL. For instance you could say
You can give either a single group channel number or a range of group channel numbers (separate by TO or a dash) after the keyword GROUP. If you need to save several disjoint groups, you could for instance say:
You can also use the word ALLGROUPS to handle all group channels at once. For instance:
The word MATRIX, CHAN, or CHANNEL indicates a range of chanels of interest. MATRIX indicates the entire matrix: all input, playback, crosspoint, and output channels are included in this group. This includes "special" channels such as the signal generators and timecode readers and generators. The word CHAN or CHANNEL must be followed by a list of channel names and channel ranges. This is much like channel parameters to any command, except that a comma cannot be used to separate the individual channel numbers. Valid channel names aand ranges are
In the above lines, <number> indicates a valid number, like 0 or 1001. A quantity in square brackets [ and ] is optional. So in the first line you can have I0 or I 0 or I0 - I1 or I0 - 1 or I 0 to INPUT 12. Once you have given a range of channels you have to say what data you want to save for those channels. The same kind of data will be saved for all of the listed channels. Currently you can save the following data types:
The simplest way to save all of the information for the entire matrix is
But you probably also want to save the group info if you are using groups, so you might say
Since this might be noisy as it is restoring EQ and delay info, it would be better to say
If you are going to make an initial setup preset, you would most likely say
You can save different things for different channels. For instance, you could say
This would save the gain info for only the input and output channels, but would save all of the EQ info for the entire matrix. When this preset is restored the gain for the input and output channels would be restored, but the gain for the playback channels and the crosspoints would not be changed. Finally, after all of the data to be saved is given, you need to specify the name of the preset file to save to:
For instance
So the total command to create an initial preset could be
PRESET RESTORE This command will restore some or all of the information in a preset. You can select which parts of the preset information you want to restore; you do not have to restore all of the information in the preset. The restore command has almost exactly the same syntax as the save command. You specify the groups and channels you want to restore, and then the type of information to restore to each selected group or channel. If the requested informaiton is not in the preset it will not be restored. If there is information in the preset that is not requested it will not be restored either. Consider the following example:
First we save all of the information for the matrix to a preset called TEST. This preset has all of the matrix settings, but not the group information, and not any connection information. It also wasn't saved with MUTED set, so the outputs will not be muted unless the restore has MUTED on it. In our example it does not. The RESTORE command for the TEST preset will only restore the gain for channel I0, even though the preset has the gain information for all of the channels in the matrix. The second RESTORE command for the SOUNDMAN_STARTUP preset will restore all of the delay values for all channels in the matrix. The ASIO connection info will not be restored, even though it is present in the preset. Neither will the group information, or any other channel property except the delay values and delay enables. Because the preset specified MUTED when it was created, the outputs will be muted a moment while the delay values are being restored. If it had not, then MUTED could be given on the RESTORE command to force the outputs to be muted during the restore.
Scripting Control Commands A script is a much more general way to configure SM-S. The script can do almost anything you can think of, with the exception of interacting with a live operator. You can do changes, fades, do things at certain times, and even compute new values using arithmetic if you need to. Scripts are a bit more work to make than a preset (you just save the current machine state to make a preset) but they can do a lot more. And they can configure SM-S from scratch, with two exceptions: 1) they can't load the current ASIO device, and 2) there isn't one that is automatically loaded at startup as there is with a preset. Not being able to load the ASIO device and call a script at startup may seem to make them a non-starter for a basic system's configuration. And in some cases that is true. But if you have some overall system controller that also starts at the same time as SM-S, and which may be configuring other devices at startup, then it only needs to send two commands to SM-S to get it configured. And the advantage is that the controller can bring SM-S online in the right order relative to other gear. The controller would sent a CONFIG SET INTERFACE command to set up the ASIO interface, wait a couple of seconds for that to complete, and then send a command like RUN SCRIPTFILE "Startup_Script". A script file is just a text file. You can make it with Notepad. For a simple script, you need two magic "bracketing" commands:
"some_name" has to be the same name in both commands. All the other commands go in between:
Script files should be saved/stored in the folder My Documents\SoundMan Presets, however they can also be stored other places and the full path given when accessing the script file. Best show management practices suggests grouping all show files in a common directory someplace on the system. Once you have a script file created, you can load it (which loads the script it contains) and then invoke that script as often as you want. There are two ways to load the script in a scriptfile. If you will use the script immediately after loading it, you can save yourself one command by both loading and running the script with the same command: Load and Run Command : RUN SCRIPTFILE "scriptfilename" Please note that this should not be used if the script execution is timing-critical! It takes some time, possibly several seconds, to load a large script. The script will start running when the loading is finished, whenever that happens to be. If your script is timing-critical, or you will be using it a number of times, you should load it once and then run it when needed. Many scripts can be loaded one after anohter at startup time, if desired. In this case load the scriptfile and then run the script:
Please note that the "scriptfilename" and the <script_name> are not necessarily the same. The "scriptfilename" is the name you gave the file that you created with the text editor. It might be named "script1.txt". You can load this as either "script1.txt" or just "script1", since SoundMan Server will try adding ".txt" to a scriptfile name if the initial name cannot be found. The <script_name> is the name you gave the script in the SCRIPT <script_name> BEGIN line inside the scriptfile. If you make these two names the same it can save confusion. You can also make loops, wait for time of day or a timed event, substitute parts of commands with variable values, and much more. You can also start scripts from other scripts. A vertical bar means "or" So BEGIN | END means that either BEGIN or END can show up in that place. Curly braces are both grouping and show something that is mandatory. So { BEGIN | END } means that you can choose either BEGIN or END, but you MUST choose one or the other. Square braces show something that is optional. So "VARIABLE variable [ = value ]" means that you have to have the word VARIABLE, and it must be followed by a 'variable' (whatever that is), and that MAY be followed by an equal sign and a 'value', whatever that is. Uppercase words are key words. Lowercase words are things that are usually self descriptive, at least to an extent, but there really should be a description some place, usually before it is used. For instance 'variable' should be defined to be 'name', and 'name' should somewhere be defined as a string of numbers and letters beginning with a letter. A user might be able to muddle through, but it would help to have all the right definitions. The items 'fpt' and 'timecode' should be defined elsewhere. 'fpt' means "floating point". A better description would probably be "real number". It is a number with an optional + or - sign and a bunch of digits and an optional decimal point. So 1, 100 1.00, -1000, -0.1000, -1, -.1, +.1, +01, +01.234 are all examples of real numbers that match 'fpt". "Timecode" is: hh:mm:ss [ :fr [ .fract ] [ F framerate ] ] or [ [ hh: ] mm: ] ss [ .fract ] Those definitions are really messy if you don't follow those brackets very carefully. What they say, in effect, is that a "timecode" is at least an unsigned number of seconds (which may be more than 59), and there may be a fractional number of seconds. So 1.23 is a valid timecode, as is 59.1 or 12 or 1200. Note those all also match a subset of the definition of 'fpt'. (It is a subset because you can't have a + or -.) The timecode seconds value can be preceded by a "minutes : " value, so you can have 12:34 as a valid timecode. You can also put an "hours : " in front of this, so you can have 12:34:56 as a valid timecode. Or 1:2:3 because you don't need 2 digit numbers. Also, if the seconds value doesn't have a fraction or decimal point, it can be followed by " : frames", so we get the full 4-field timecode value: 01:23:45:19. Note in this case all four fields MUST be there. If there are three or fewer fields the last field is seconds, NOT frames. If we have a frames field, then we can also specify the framerate used to interpret that frame number. The framerate field is an F followed by a 2-digit number: F24, F25, F29, or F30. So you can have 01:23:45:19F24, but not 01:23:45:27F24, because the number of frames is bigger than the frames/second. Note that the number of frames can have a fractional part: 01:23:45:19.22 or 01:23:45:19.22F30. The script commands that are added to regular commands are:
A "channel-testable-item" and the allowed testing relations are:
A "time-testable-item" and the allowed testing relations are:
Comparisons can be made to (and variables can be set to) symbolic values. These are the allowed symbolic values and meanings: Symbolic constants:
The allowed relationals are:
Expression operators: We will restrict the expressions to simple single operations on variables and constants, including symbolic constants that are good to test against testtable-items. We don't try hard to see that the combination of symbolic constants and whatnot makes sense. Valid simple expressions:
Variable names do not require a leading @ sign, but we will allow one.
Scripts allow variable substitutions inside of strings, when the string is used as a form of macro for use in subsequent commands. For instance the following script fragment is valid:
You can chain multiple text concatenations in a single assignment command in a script. This makes it considerably less verbose to build strings or commands that contain multiple items that must be substituted. You can load and run a script in a single command.
Here are two actual scripts: List all crosspoint non-zero gain connections script xgain begin
var inchan = 0
label loop
label nogain
log user now channel input @inchan output @outchan
script xgain end And:
script readout begin
;trace on config get interface
variable gain
;================================================
variable chantype = "IN"
label inloop
assign msg = "CHAN " + chantype
if chan @chantype @chn delayenable = ON goto skip1
label skip1
LOG USER @msg
; If the channel isn't enabled, no eq here!
get chan @chantype @chn eq enable
assign bands = chan @chantype @chn eq bands
if i > bands goto innext
label ineqloop
;get chan @chantype @chn gain
label innext
;===============================================
assign chantype = "OUT"
label outloop
label skip2
LOG USER @msg
; If the channel isn't enabled, no eq here!
get chan @chantype @chn eq enable
assign bands = chan @chantype @chn eq bands
if i > bands goto outnext
label outeqloop
;get chan @chantype @chn gain
label outnext
label end script readout end
Other Commands In addition to channel parameters, there are a few other items that can be set. They are described in this section.
SET MATRIX The Set Matrix command provides a way to quickly set the gain structure for the entire playback routing matrix. It can also be used to quickly set several different levels in a single crosspoint row.
The normal form of the Set Matrix command will set all of the gain elements in the live and playback matrix only (not signal and timecode generators and timecode readers) to specific values. Specifying IN or INPUT will limit the matrix settings to the live inputs and the outputs. Specifying PB or PLAYBACK will limit the settings to the playback inputs and the outputs. Specifying ALL, or not specifying any of the new options, will result in setting both the live and playback inputs. If FULL is specified all crosspoints in the requested sections will be set to the requested gain level. ON and OFF are the same as full gain and zero gain. The input and output channel gains will be set to 1 for any gain other than OFF or 0. If DIAGONAL is specified all crosspoints in the requested sections will initially be set to 0 gain, and then only the "diagonal" crosspoints will be set to the requested gain. Diagonal crosspoints are those crosspoints with the same input and output channel numbers. The input and output channel gains will be set to 1 for any gain other than OFF or 0. In all cases the signal generator gains will be set to 0 so that they don't interfere with the overall matrix setup. If neither Full nor Diagonal is specified, Full is assumed. In Full Matrix mode all gain elements in the inputs, outputs, playbacks, and crosspoints are set to the same level. SET FULL ON sets all gain elements to unity gain. This command should be used with care as it can easily result in a whole lot of feedback. SET FULL OFF will set all gains to zero, or -infinity dB. This can be used to quickly shut the matrix completely down in an emergency. SET FULL { GAIN <gain> | GAINDB <gaindb> } will set all gain elements in the matrix to the given gain level. Gains equal to or above unity should be used with extreme caution. SET MATRIX DIAGONAL has a somewhat different and often more useful effect. All input, playback, and output gains are set to unity. All crosspoint gains are set to zero, except for the "diagonal crosspoints". Diagonal crosspoints are those that have the same number for the input and output channel, like 1.1, 2.2, 3.3, etc. The diagonal crosspoints are set to the indicated level. In addition to setting all of the gains, the Set Matrix command also clears all of the mutes and solos.
SET MATRIX ROW
The Set Matrix Row command can be used to quickly set the levels for an entire crosspoint row. A normal Set Channel command can be used when all crosspoints in the row are to be set to the same level. However, the Set Channel syntax becomes rather awkward when each channel needs a different gain setting. Note that Set Matrix Row sets all gains in the row instantly; there is no fade time. If the gains must be set with fade times, then the Set Channel syntax must be used instead.
The Row number is an Input channel number.
Row numbers, an input channel name, or a playback channel name may be used to
designate the crosspoint row to be set.
Following this "header" information is a list of channels or channel ranges, and levels for the channels and ranges. No channel types are given because all channels are known to be crosspoint channels. Since the input channel number was given with the Row parameter, only the output channel numbers and ranges are required. All channels in the row can be set to a single level with a command like SET MATRIX ROW 4 GAINDB 0-15@0 Even channels could be set to one level and odd channels to another level with SET MATRIX ROW 9 GAINDB 0 2 4 6 8 @ -12 1 3 5 7 @ -25 Notice that the first number after the @ sign is the level for all preceding channels. If another number appears after this, it is the start of a second set of channels. Finally, every channel in the row can be set to an individual level SET MATRIX ROW 0 GAINDB 0@0 1@0 2@-4 3@-27.2 4@0
SET GROUP
The READER { channel number } may be a numeric channel number for the timecode reader or a full channel specification for the reader such as OUT 1000 or a channel name. The SET GROUP command to set up a number of playback channels on a timecode reader looks like the above. The DROPSPEED and NORMALSPEED parameters MUST come right after READER and the reader channel number! NORMALSPEED is the default and tells the reader that the timecode is running at the nominal rate. Use this when 30fps timecode is running at a real 30fps, or when you have dropframe-coded timecode running at 29.97 fps. If you do not put either DROPSPEED or NORMALSPEED, then NORMALSPEED is assumed. An example of normal 24/25/30fps or 29.97 drop timecode setup: SET GROUP G0 CHANS P0-3 TIMECODE READER O1000 LOCK TC 1:0:0:0; An example of locking to 30fps timecode running at 29.97 fps: SET GROUP G0 CHANS P0-3 TIMECODE READER O1000 DROPSPEED LOCK TC 1:0:0:0; Allows groups to master channels and other groups. { G | GROUP } < nn > syntax can be added to the channel list syntax so that you can mix normal channels and groups of channels in the same command. Setting a group sets group properties. Group properties include the list of channels in the group, an arbitrary name for the group, and various timecode-following parameters. By grouping channels you can send many commands to the group that you would normally send to a list of channels. In that sense they are somewhat like a VCA on an analog mixer. You can also group playback channels that will play simultaneously to timecode. Here the group is more important, since it insures that all of the channels will remain exactly in sync as they follow the timecode variations. Examples
SET GROUP G0 NAME BACKING_TRACKS CHANS P0-P7
SET GROUP G0 CHANS P0-P7
Either of the two above sets do exactly the same thing. A typical example to set up timecode playback for group G0 and P0-3 might be: SET GROUP G0 CHANS P0-3 TC READER O1000 NORMALSPEED LOCK TC 1:0:0:0 AT 0 There are up to eight timecode readers starting with channel OUT 1000. You can route signal from any input (or playback) channel to either of the timecode readers. Typically you would have an incoming SMPTE (or IRIG) timecode on an input channel, for instance from an external SMPTE generator or other source. However, you might have a click track or other canned show where the SMPTE source was a recorded track, so you can also route from a playback channel to the timecode readers. You should never route more than one source channel to any single reader. It is not illegal to route multiple channels, but doing so will degrade the timecode decoding if there is noise on the other channels. Obviously if more than one timecode source is fed to a single timecode reader at the same time, chaos will result, and in all probability the correct timecode values will not be read. The current timecode read by the first reader (channel O1000) is displayed on the debug monitor display for SoundMan-Server. The timecode from the other readers is not displayed. There are currently no options to set in the timecode readers. They decode the incoming timecode data, determine the general format, and then produce an output that can be used to synchronize playback channels and the timecode generators. NEVER lock a playback channel or timecode generator to a timecode reader if that channel is supplying the timecode to the reader! This will result in positive feedback, and the timecode will very quickly run off the tracks. You can lock a group of playback channels to a timecode reader. Note that the timecode generators are also considered to be playback channels, so you can lock the timecode generators to the timecode readers. You might do this to regenerate timecode, or to generate timecode of a different format slaved to incoming timecode. For instance, if you have 30 fps SMPTE coming in and you need to slave a projector to the timecode, you could generate 24fps SMPTE in one of the generators and lock that generator to the reader following the 30fps timecode. You lock the playback channels to a reader indirectly through one of the group channels. The group channel insures that all of the playback channels in the group will remain in sample-accurate sync while following timecode. If you locked individual channels to the timecode reader, the channels would follow the timecode within a fraction of one frame, but sample accuracy between the channels could not be guaranteed. There are two ways you can lock to timecode: you can just follow the speed or rate at which the timecode is running, or you can lock to the actual timecode position. Sometimes it is sufficient to insure that a playback started at some random time will remain in sync with some other device, for instance a video playback. If the audio runs at the same speed as the video source the lock will be maintained over extended periods of time. If this is all that is required, you can do TC LOCK SPEED to insure that the playback and the timecode will run at the same rate. Note that the audio will NOT follow the timecode if the timecode value jumps, since only the speed of the timecode is being followed. If the timecode slows down the audio will slow down to match. More commonly it is necessary to lock the audio playback to a particular time relationship in the incoming timecode stream. If you do this and the audio channel is in playback mode, the audio will start and stop if the incoming timecode stops. If the timecode jumps, the audio will also jump to follow the timecode. If the timecode is arriving continuously but is showing the same frame value over and over, the audio will be frozen at the current time position. It will begin playing the instant the timecode begins moving. Audio will not follow timecode that is running backwards. For that matter the timecode reader will not follow backwards timecode. The timecode must be running in the forward direction to be recognized. (Stationary timecode must be presented with the bits in tor forward direction to be recognized.) Audio will speed up or slow down as necessary to remain as close to the current timecode value as possible. However, timecode, especially when generated by a mechanical source like a projector, can have a lot of wow and flutter. The timecode reader aggressively filters the timecode values to eliminate flutter and to reduce wow to the lowest possible levels consistent with remaining in sync with the timecode. Note that the audio pitch will change as the timecode speed changes. Thus if the timecode is shuttled forward, you would expect the audio playback to increase in frequency during the shuttle movement. (The audio will not currently follow a backwards shuttle.) If the timecode jumps, the audio will jump to follow it. Depending on the number of tracks being played and various other conditions, there may be a short silence while the audio files seek to the new position and re-lock to the timecode. Timecode jumps either forward or backward will be followed, as long as the timecode bits continue to run forward. When locking to timecode, you need to specify a timecode value for some position in the audio track. Typically you would specify the timecode value for the front of the track. However, it might be that the important timecode position is 12.71 seconds into the track. So that you don't have to convert 12.71 to frames at the current timecode rate and subtract that from the desired starting timecode, the group syntax lets you specify both the locking timecode value and where it appears in the track. In the example given above, the first sample of the track file occurs at one hour of timecode. However you could have specified LOCK TC 1:0:0:0 AT TIME 12.71; This would have made the one hour mark occur exactly 12.71 seconds into the track file. DROPSPEED tells the timecode reader that the timecode is running at "dropframe rate", or 0.1% slower than the nominal rate. Use this when you have plain 30fps timecode recorded at 29.97. Setting DROPSPEED results in the time values from the timecode reader being multiplied by 1.001. This corrects the speed error, but it also results in shifting the time value from the reader. For instance, when the reader reads 01:00:00:00 (one hour) it will actually report 01:00:03:18 at 30fps. If you have audio tracks that start at specific time offsets, you may need to slightly shift the start time value to compensate for this. The chart below shows the desired time in hours and the shifted time value for various times and framerates.
SET GENERATOR
The Set Generator command controls the signal generators. All signal generators are identical, and can be used to generate up to eight different tones or other wave shapes routed to different outputs. If the channel number is not given it will default to I1000, which is the first generator. If the channel number is given, it must be I1000 to I1007, as those are the eight possible signal generator channels. The signal generator gain is controlled by the appropriate INPUT channel gain, and the routing to outputs is controlled by the appropriate input crosspoints. Because all gains are controlled in the normal manner, there are no options in the Set Generator command to control gains. The generator defaults to a sine wave at 1000Hz. If channel IN is simply unmuted and routed to an output this tone will be heard. However a number of other waveshapes and frequencies can also be generated. This allows sweep parameters of ON and OFF as well as PAUSE, STOP, and RESUME. ON and RESUME will resume the sweep if it is paused. STOP, PAUSE and OFF will stop the sweep if it is currently running, holding the current frequency. Frequency sweeps can be used for room measurements, although they will be much slower than an RTA and the white or pink noise generator. They can also be used for equipment measurements. The sideband signals are very low amplitude with a good 24-bit audio interface and a low sweep rate. Unlike most commercially available hardware audio sweep generators, sweep times in the hours can be specified, as well as very narrow sweep ranges. Sweep artifacts should easily be over 120dB down when such techniques are used. The pink noise generator is particularly accurate, exceeding the specifications for a number of commercial pink noise generators.
SET TIMECODE GENERATOR
There are up to eight timecode generators starting with channels P1000. The timecode generators can be used independently to generate up to eight different timecode streams. The timecode streams can have different time bases, or can have different timecode types. For instance, you could generate SMPTE at 30 frames/second from one generator and 24 frames/second from another generator if you needed to lock a projector and a lighting console to the same time, but they required different frame rates. The timecode generators enter the matrix as playback channels and must be routed through the matrix to a physical output before they can be accessed externally. They can also be routed through the matrix (levels must be set at inputs, crosspoints and outputs to unity gain) to outputs O1000 and up so the internal timecode readers can chase them. Since they are playback channels they can be started and stopped with PLAY and STOP commands, just like real playback channels. This lets you generate timecode in synchronism with audio playback. The timecode generators can start, stop, pause, loop, and change speed just like playback channels, so can track all movement actions identically to playback channels. The timecode generators can generate many different forms of timecode. They can also generate pure sine waves, so can be used as additional signal generators if this is desired. By default the generators generate full output level. The frequency should only be set if you are generating a sine wave. When you set any other code type the frequency is set automatically to the correct rate for that timecode type. It is possible though to manually set the frequency after setting the timecode type. This will probably cause the timecode to run off of the correct frequency, but there may be times when that is useful. The timecode type generated are:
SMPTE timecodes are most commonly used for synchronization between show equipment of various forms. IRIG is an older timecode form that is very good for long-range synchronization, between hundreds of feet and for some codes, tens of thousands of miles. It tends to be more resistant to noise and distortion than SMPTE timecode. However, it is polarity sensitive to decode correctly. Since the output polarity of an audio channel is not necessarily predictable, you can generate the IRIG codes either positive or inverted. The TIME field is used to set or get the starting (or current)generation time. The time will start from zero by default. If the playback channel for the generator has a TRACK START TIME specified, the TIME field will be the timecode value corresponding to that relative position. If no track start time is given, the TIME timecode is the time generated at the front of the track. The DATE field is used to set or get a date field. This will be placed into the USERBITS field for SMPTE. The field will be validated to insure that it is a valid date. If the DATE and USERBITS parameter are both used and DATE occurs second, it will override the USERBITS value. The date value is initialized to zero by default, and is not automatically rolled over. The DAY field takes a Julian day number between 1 and 366. This will be inserted into the Julian day field for IRIG timecode. This value is automatically incremented when the time rolls over from 23:59:59 to 00:00:00. It will also automatically roll over from 366 to 1, but not from 365 to 1. The USERBITS field will place an arbitrary hexadecimal value into the SMPTE timecode user bits field. This will override any value set with the DATE parameter if it occurs after the DATE parameter. For IRIG timecode, the low 27 bits of the userbits value will be placed in the "control bits" field in the timecode value. The SPEED value can be used to tune timecode generation to match some external source that is running at the wrong speed. Normally pitch = 1.0, which is exact speed. A smaller value will slow down timecode generation and a larger value will speed it up. It is generally more practical to use the TRACK SPEED parameter on the generator channel than to use the SPEED parameter on the generator command. The RUNNING value will start or stop the generator. The generator is stopped initially, and can be started from the generator command or from a PLAY or RESUME command, possibly along with other playback channels that it will then track. When setting up the command sequence to lock an offset generator to timecode the order of the commands is important. The following sequence will generate a timecode offset by 1 hour from the incoming timecode:
The first command sets the code of the timecode to be generated. This needs to be done before the generator needs to generate anything, so is best done before the generator channel is added to the timecode reader group. The second command adds the generator (channel P1001) to a timecode reader group, selects reader o1000 (channel OUT 1000), and sets up to lock to a timecode chase begining at time 0 (that is, no hour offset). The third command MUST be after the SET GROUP command or it will be ignored. It tells the timecode generator to generate time starting at 1 hour when it has an incoming timecode of zero hours. Thus the generated time will be one hour ahead of the time read. If ONLY the timecode generator is locked to the timecode reader (just regenerating timecode) then this set of commands can be simplified:
This will have the same effect as the previous set of commands IF only the tc generator is locked to the reader. However, if audio files are also locked to the reader, this will have the undesirable effect of starting the audio files 1 hour into playback, which will probably be past the end of the files. A timecode generator looks like a playback channel and time can be looped. Set the looping parameters just as you would for a track. For instance, to loop the first timecode generator from 10 seconds back to 0 seconds, you can enter:
The channel specification can be entered using P, such as P1000, or the bare number, such as 1000, for the SET TCGEN command, or no specifier at all, which will default to the first timecode generator. To keep from having audio offset problems the initial command sequence is strongly recommended when offset timecode is needed. See GET TIMECODE GENERATOR below for more detailed information about timecode.
SET FREEWHEEL
SET VU SET VU [ PRE | POST ] <channel_spec> [ ON | OFF ] Getting VU values uses quite a lot of processor time. If you got VU values for the inputs at one time but now no longer need these values, it would be best to turn off the VU accumulation code on those inputs. This is even more important when getting VU readings on crosspoints since there are so many of them. You can specify whether you want to turn on or off pre or post VU processing for the range of channels. Only one type can be on at any time, so if you had pre VU on and now turn on post VU processing, the pre VU processing will be turned off automatically. If you do not specify PRE or POST and use ON, the command will return an error, since only one type can be on at once. If you do not specify PRE or POST and give OFF, all VU processing will be turned off for the range of channels.
GET GROUP NAME GET GROUP channel_list NAME gets the name of the group. GET GROUP <channel_list> NAME returns the response in the form status_type channel_id = status_value
GET GROUP CHANNELS GET GROUP <channel_list> [ CHANS | CHANNELS ] gets a list of the channels assigned to the group. Note that the response is the group channel id, an equal sign, and then a space separated list of the individual channel ids. The next group, if more than one was requested, will have the group id and an equal sign before its list of channels. If a group has no channels assigned, the first and only channel name will be "none".
GET GROUP TCREADER GET GROUP <channel-list> TCREADER will get the channel ids for the timecode readers assigned to the channels in the group. If a group does no have a timecode reader assigned to it (as is often the case) the reported channel id is "none" (without the quotes). The response has the channel id of each requested group and the matching channel id (or "none") for the reader, following the equal sign.
GET GENERATOR
FREQ or FREQUENCY returns the generator frequency. SHAPE returns the generator waveshape. This can be one of Sine, Square, Triangle, WhiteNoise, PinkNoise, PinkSweep. Sine, Square, and Triangle are pure tone waveshapes. If sweep is disabled, the generator makes a constant frequency. If normal sweep is enabled, the tone is swept from the minimum frequency to the maximum frequency in the given time, and then swept back to the minimum frequency in the same amount of time. The amplitude of the wave is constant across all swept frequencies. WhiteNoise and PinkNoise are random noise generator functions. WhiteNoise has equal amplitude at all frequencies. PinkNoise decreases in amplitude with frequency. PinkSweep is a swept sine wave that has an amplitude envelope matching the pink noise emvelope. This can be used with a traditional spectrum analyzer to make various passband measurements The PinkNoise function is more appropriate when using an RTA. SWEEP returns one of four values, depending on what follows the word SWEEP. SWEEP MIN returns the minimum sweep frequency SWEEP MAX returns the maximum sweep frequency SWEEP TIME returns the time in seconds for the sweep. SWEEP with nothing following it returns On or Off. If the channel number is not given it will default to I1000, which is the first generator. If the channel number is given, it must be I1000 through I1007, as those are the eight possible signal generator channels.
GET TIMECODE GENERATOR
The GET TCGEN or GET TCGENERATOR command returns information about one of the timecode generators. The response has the format: TcGenerator <channel> {<parameter>=<value>}…; For instance the response to "GET TCGEN p1000 TIME" might be "TcGenerator p1000 Time=123.166;". The returned parameter name will be the same as the requested parameter but will have an initial capital letter and otherwise lower case. (In SM-S before version 1.0.60 the timecode reader channel number was not returned in the response.) If just "GET TCGEN <channel number>" is given the command will return the current time value that the timecode generator is generating. This is exactly equivalent to entering "GET TCGEN <channel> TIME". See the description of the TIME parameter below. ABOUT TIMECODE GENERATORS: A timecode generator is a signal generator. It normally makes a very special signal waveshape, which happens to represent a time value. But a timecode generator can also generate a sine wave, just like the standard signal generator found on channel IN 1000. Thus, if you need multiple signal generators and have spare timecode generators, you can use the timecode generators as signal generators. There are various ways to encode timecode into an audio stream. Most people are familiar with SMPTE encoding (or at least believe that they are). Another form of timecode often used in the instrumentation industry is IRIG code, which was originally used when tracking missile launches in the 1950s. While much different in shape than SMPTE it has some desirable characteristics, such as being more easily recoverable over a noisy radio link. The SM-S timecode generator can generate a number of SMPTE data formats and a number of IRIG data formats and encodings. TIMECODE GENERATOR PARAMETERS: The various parameters can be combined in one command, and the responses will be in the same order as the parameters to the command. The parameters have the following response keywords and meanings:
GET FREEWHEEL
The returned value is either
Where "On" is "O" for OUTPUT followed by the reader channel number, and the count is the number of freewheel frames, 0 to 500.
GET VU GET VU [ PRE | POST ] <channel_list> Returns average and peak VU readings for input and output channels, but not for crosspoints. The VU values are expressed as integers in the range of 0.0 to 255.0 These are suitable to be fed into a VU meter with this range from minimum to maximum. The VU meter should be linear over this range; the values have been pre-warped to display reasonably. The command has the format GET VU [ PRE | POST ] channel_list The response has the format VU channel_id=average:peak ... ; Avoid doing VU requests more often than every 100ms or so. VU processing is expensive, and the time is generally better used for other things. If neither PRE nor POST is given then POST VU readings will be returned as is normal. If POST is given the same post VU readings will be returned. If PRE is given then PRE VU readings will be taken before the control point has an effect on the signal. This might be most useful for input channels. When switching from pre to post VU or vice versa, the accumulating VU averages are cleared, so the first reading after changing will return zero for the average and peak values for all channels. It is advisable to NOT switch between pre and post VU readings frequently in an attempt to get both values from a single channel. It will not work well. It is best to only switch on a user request.
GET FILE
// GET FILE "filename" # FileInfo "name"
Interrogates attributes of an audio file such as the number of tracks and the sample rate, plus some of the internal data items. The filename to be interrogated follows GET FILE, and should be quoted. Following the file name are one or more attribute names to be interrogated. If the file can be found and opened, the response will begin with FileInfo followed by the quoted name of the file, and then the attribute key words followed by equal signs and the attribute values.
GET TCREADER
// GET TCREADER channel # TcReader chan
Gets information about a timecode reader. Only one timecode reader can be interrogated with a single command. You can get the current shape of the timecode being read, if it is recognized. If timecode has stopped, the code shown will be the last code recognized. POSITION, TIME, and TC all return the same information in different formats, that is, the current timecode value being read (or the last timecode value read if timecode has stopped). FREEWHEEL returns the current freewheel count. DATE will return the same thing as USERBITS for a SMPTE decoder. It will return the date (usually a Julian date) in the IRIG code for an IRIG decoder. DAY will return 0 for a SMPTE decoder and the Julian day value from the code for an IRIG decoder. TC30 returns a 30 fps timecode value from the reader, regardless of the current framerate: GET TCREADER <n> TC30. This returns a single-line response in the form "TC30=<timecode>.
LOG
// LOG
Lets the user add comments to the text output from SM-S. This can be useful for documenting problems or other reasons. The log records are timestamped and included in sequence in the history. The LOG command is followed by a keyword that indicates the kind of log entry to make. All log entries begin with a date and time stamp, followed by a single letter and a colon that identifies the type of the log record. The character will be one of the following:
C - Command - The text of a command to SM-S
After the word indicating the type of log entry to make is the text of the log entry. This can be a single string in quotes, or it can be a series of individual words, ending in a semicolon or the end of the input line. Log entries in no way change how SM-S works or what it is doing. All they do is allow the user to make their own entries in the captured log data.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| Contact | TOP | Home |