AudioBox AB64 Interface

The AB64 Interface is a set of portable C language functions for communicating with an AudioBox model AB64 via ethernet.

updated 3 November 2006

Download AB64 Interface Source

Contents:

Introduction

The AB64 Interface is a set of portable C language functions for communicating with an AudioBox model AB64 via ethernet. All of the details of sending and receiving ethernet packets are handled by the Interface. A separate function is provided in the AB64 Interface to format and send each of the approximately 80 commands in the AB64 command set.

The AB64 Interface is contained in a single source file, ab64if.c, with header file ab64if.h.

The majority of the functions in the AB64 Interface send commands to the AB64. The other functions are used to scan the local area network for all running AB64 units, connect to a particular unit and receive messages from that unit. The data structures in the messages received from the AB64 are defined in ab64if.h. The AB64 Interface performs byte swapping as needed for all AB64 data structures when executing on little-endian (e.g. Intel) processors.

The AB64 Interface does not multi-task; its functions receive CPU time only when directly called. There are therefore no re-entrancy or concurrency issues.

The AB64 provides an automatic data updating mechanism to keep interfacing programs up-to-date with respect to all AB64 data. The AB64 Interface initalizes and maintains the AB64 automatic data updating mechanism on behalf of the program using the Interface. A complete set of data is sent from the AB64 when a connection is made. After this, the program receives messages from the AB64 Interface containing AB64 data structures whenever data within those structures changes within the AB64. This mechanism is much more efficient than polling the AB64, and simplifies the work of developing a program to interface to the AB64.

Making a Network Connection

A program using the AB64 Interface begins by calling 'findAllAB64s'. This function must be called before any other function in the Interface. This function broadcasts a message to which all AB64s on the local area network reply. The replies are a data structure (called 'ab64Inquiry') containing general information about the unit, including its IP address. After calling 'findAllAB64s', the program retrieves these replies by calling 'nextAB64Reply' in a loop until the function returns a null pointer. The information in the replies is generally used to populate a menu for selecting the AB64 to work with. The program and/or the user of the program decides which unit the program is going to communicate with, and calls 'connectAB64' to make the connection. (Many programs default to making an initial connection to the first unit that replies.) The data structures that the program wishes to receive from the AB64 are defined by setting bits in a flag longword passed to 'connectAB64'.

The 'findAllAB64s' function (followed by 'nextAB64Reply' in a loop) can be called at any time when the user of the program wishes to update the list of AB64 units available on the network. The 'connectAB64' function can be called whenever the user wishes to connect to a different AB64 or to re-establish a connection that has been lost due, for example, to a network disruption.

Network Connection Functions

FIND ALL AB64s

find all AB64 units on the local area network 

int findAllAB64s (void);

This is the first function called by the program using the AB64 Interface. This function opens the communication sockets required, and broadcasts a message to which all AB64s on the local area network reply by sending an ab64Inquiry message, which contains general information about the unit, including its IP address. A call to this function is followed by a set of calls to nextAB64reply. This function can be called at any time to update the list of AB64 units available on the local area network.

Returns: false if an error occurred, true otherwise.

NEXT AB64 REPLY

receive next reply to broadcast made by FIND ALL AB64s 

struct ab64Inquiry *nextAB64Reply (void);

This function is called repeatedly in a loop, immediately after calling findAllAB64s, receiving ab64Inquiry messages from all AB64s on the local area network until the function returns a null pointer. The replies are typically used to populate a menu from which a user can select the AB64 unit to work with. The ab64Inquiry structure includes the IP address, used in 'connectAB64', for the AB64.

Returns: pointer to ab64Inquiry structure, null if no more replies.

CONNECT AB64

make network connection to AB64 

void connectAB64 (long IPaddress, long updateflags);

This function makes a network connection to a particular AB64. This must be done prior to attempting any commands or attempting to receive any messages. All communications take place to and from this unit until the next time 'connectAB64' is called.

The update flags are defined in the SET AUTOUPDATE EN command definition. A value of 0x7FFFF will subscribe the calling program to receive all AB64 data updates. After calling connectAB64, the program will receive a complete set of the data structures requested in the update flags. After this, data structures will be received whenever any data within a structure changes.

Returns: none.

Receiving Messages

Messages from the AB64 are received by calling the 'nextAB64Message' function. Messages returned by 'nextAB64Message' are always from the set defined in ab64if.h. Most programs retrieve messages once per frame, or about 20 to 30 times a second, to process the incoming message stream quickly enough to prevent slow down due to flow control and to keep on-screen data up to date. When retrieving messages, 'nextAB64Message' should be called in a loop until all waiting messages have been retrieved.

Receive Message Functions

NEXT AB64 MESSAGE

get next message from AB64 

ab64MsgPtr nextAB64Message (void);

Messages from the AB64 are retrieved by calling the 'nextAB64Message' function. Messages returned by 'nextAB64Message' are always from the message set defined in ab64if.h. Most programs retrieve messages once per frame, or about 20 to 30 times a second, to keep on-screen data up to date. Any time a call to 'nextAB64Message' returns a message, as soon as the message is processed 'nextAB64Message' should be called again right away, until it returns a null pointer. This is an example code fragment: 

   ab64MsgPtr msg;
   while (msg = nextAB64Message ()) {
      //process message
      }

The 'nextAB64Message' function returns a pointer to a generic AB64 message. This pointer can be used to determine the type of message returned. The returned pointer can then be cast to one of the types defined in ab64if.h to access all of the fields in the message. Data the program wishes to retain must be copied using this pointer.

Returns: pointer to ab64MessageHeader, null if no more messages.

ALL AB64 DATA

get set of messages containing all AB64 data 

void allAB64Data (void);

This function causes the AB64 to send a complete set of data messages. This is not typically needed, but may be called to force a refresh of all AB64 data.

Returns: none.

GET DISK INFO

get information on the AB64 disk(s) 

void getDiskInfo (void);

This function causes the AB64 to send information concerning the disk drive(s) installed in the AB64. A rcDiskInfo message will be received.

Note: The disk information returned by this command is static following AB64 initialization. This data is therefore not included as data that can be returned via auto update. All other AB64 data is returned via auto update.

Returns: none.

Incoming AB64 Messages

The following is a list of all AB64 response codes returned via the 'nextAB64Message' function. These codes occupy the first byte of all incoming AB64 message data structures. These data structures are defined in ab64if.h and described in the ethernet section of the command set document on the HFI web site (www.hfi.com) (linked to command names below)

 
 Code              See Command
 rcDiskInfo        GET DISK INFO EN
 rcSelChannels     GET SELECTION CHANNELS EN
 rcCobranet        GET COBRANET EN
 rcIOLevels        GET IO LEVELS EN
 rcIODelay         GET IO DELAY EN
 rcPlbkPoints      GET PLAYBACK POINTS EN
 rcInquiry         INQUIRY EN
 rcStats           GET STATS EN
 rcVU              GET VU EN
 rcXptLevels       GET XPT LEVELS EN
 rcXptDelay        GET XPT DELAY EN
 rcPlayback        GET PLAYBACK EN
 rcShow            GET SHOW EN
 rcMuteSolo        GET MUTE/SOLO EN
 rcSubMaster       GET SUBMASTER EN
 rcDiskState       GET DISK STATE EN
 rcEQ              GET EQ EN
 rcAllDataComplete SET AUTO UPDATE EN
 rcDirectory       GET DIRECTORIES EN
 rcLCD             GET LCD EN
 rcRealTime        GET TIME EN
 rcFileData        GET FILEDATA EN
 rcTooManyHosts    SET AUTO UPDATE EN
 rcDirUpdateCmpl   GET DIRECTORIES EN

The following response codes originate in ab64if.c itself, rather than the AB64

 rcAB64IFerror      returns error string describing AB64 interface error
 rcTransferProgress returns double 0..1 indicating file transfer completion
 rcFromTransferCmpl indicates transfer from AB64 completed successfully
 rcFWTransferCmpl   indicates firmware transfer completed successfully

File Transfers

Audio and show files sent to the AB64 are stored on its internal disk drive. The 'transferFileToAB64' function handles all the details of moving a file to the AB64. The 'transferFileFromAB64' function handles moving files from the AB64's disk drive to the computer. After calling 'transferFileToAB64', 'transferFileFromAB64', or 'eraseAB64File', a program must wait for a 'Directory Update Complete' message (code rcDirUpdateCmpl) before calling 'transferFileToAB64', 'transferFileFromAB64' or 'eraseAB64File'. Transfer Progress messages (code rcTransferProgress) are sent periodically during file transfers, which may be used to update progress indicators on the user's screen.

For best performance during file transfers, programs should call 'nextAB64Message' much more frequently then usual, on the order of every few milliseconds. This will greatly reduce file transfer times, at the expense of greater CPU utilization.

Audio files must be in the following format: AIFF file structure, 48 kHz sampling frequency, 16 bit sample size, monophonic. Programs can generally make use of audio file conversion functions available from the operating system or from other software vendors to convert a wide range of audio file types into the required format.

Show files must be in the format defined in the AudioBox Command Set document.

File Functions

TRANSFER FILE TO AB64

transfer an audio or show file to AB64 

int transferFileToAB64 (char *filePathName, long fileNumber, long fileType);
 

A file is transferred to the AB64 by calling the 'transferFileToAB64' function. Audio and show files sent to the AB64 are stored on its internal disk drive.

The file to be transferred to the AB64 is specified by the filePathName string, which contains the full path and file name, separated by forward slash characters. The file will be stored on the AB64 at the specified fileNumber. Most programs use the lowest available file number in the audio or show directory, to keep the directory as compact as possible. The fileType is either ftAudio or ftShow.

After calling 'transferFileToAB64', a program must wait for a 'Directory Update Complete' message (code rcDirUpdateCmpl) before calling 'transferFileToAB64', 'transferFileFromAB64' or 'eraseAB64File'. Transfer Progress messages (code rcTransferProgress) are sent periodically during file transfers, which may be used to update progress indicators on the user's screen.

For best performance during file transfers, programs should call 'nextAB64Message' much more frequently then usual, on the order of every few milliseconds. This will greatly reduce file transfer times, at the expense of greater CPU utilization.

Audio files must be in the following format: AIFF file structure, 48 kHz sampling frequency, 16 bit sample size, monophonic. Programs can generally make use of audio file conversion functions available from the operating system or from other software vendors to convert a wide range of audio file types into the required format.

Show files must be in the format defined in the AudioBox Command Set document.

Returns: false if an error occurred, true otherwise.

TRANSFER FILE FROM AB64

transfer an audio or show file from AB64 

int transferFileFromAB64 (char *filePath, long fileNumber, long fileType, 
   long channels, long blocks);

A file is transferred from the AB64's internal disk drive to the computer's drive by calling the 'transferFileFromAB64' function.

The file of the specified fileType at the specified fileNumber is transferred. The fileType is either ftAudio or ftShow. The location where the file is to be stored on the host computer is specified by the filePathName string, which contains the full path and file name, separated by forward slash characters. Files are created if they do not exist, and overwritten if they do.

For audio files, the number of channels as returned by the rcSelChannels message is passed to the function. For show files, a zero is passed for 'channels'. The size of the file in number of blocks as returned by the rcDirectory message is also passed to the function.

After calling 'transferFileFromAB64', a program must wait for a 'From Transfer Complete' message (code rcFromTransferCmpl ) before calling 'transferFileToAB64', 'transferFileFromAB64' or 'eraseAB64File'. Transfer Progress messages (code rcTransferProgress) are sent periodically during file transfers, which may be used to update progress indicators on the user's screen.

For best performance during file transfers, programs should call 'nextAB64Message' much more frequently then usual, on the order of every few milliseconds. This will greatly reduce file transfer times, at the expense of greater CPU utilization.

Audio files are created in the following format: AIFF file structure, 48 kHz sampling frequency, 16 bit sample size, 1 to 64 channels. Programs can generally make use of audio file conversion functions available from the operating system or from other software vendors to convert the created format into a wide range of audio file types.

Show files are created in the format defined in the AudioBox Command Set document.

Returns: false if an error occurred, true otherwise.

CANCEL TRANSFER

cancels a file transfer in progress 

void cancelTransfer (void);

File data is normally set when a file is transferred to the AB64 using 'transferFileToAB64'. This function is included to allow the data for a file existing on the AB64 disk to be modified.

Returns: none

SET FILE DATA

sets file name, modification date, etc. 

void setFileData (char *filePathName, long fileNumber, long fileType, 
   long modTime, long transferTime);

File data is normally set when a file is transferred to the AB64 using 'transferFileToAB64'. This function is included to allow the data for a file existing on the AB64 disk to be modified.

Data for the file of the specified fileType at the specified fileNumber is re-written. The fileType is either ftAudio or ftShow. The file's path and name may be changed to the specified filePathName string, which contains the full path and file name, separated by forward slash characters. The file's modification time and transfer time may also be modified. These times are specified in seconds from epoch (January 1, 1970) localized to the computer's time zone.

Returns: none

ERASE AB64 FILE

erases file 

void eraseAB64File (long fileNumber, long fileType);

The file of the specified fileType at the specified fileNumber is erased by calling 'eraseAB64File'. The fileType is either ftAudio or ftShow.

After calling 'eraseAB64File', a program must wait for a 'Directory Update Complete' message (code rcDirUpdateCmpl) before calling 'transferFileToAB64', 'transferFileFromAB64' or 'eraseAB64File'.

Returns: none

TRANSFER AB64 FIRMWARE

transfers firmware, runs firmware or writes it to disk 

int transferFirmware (char *filePath, int writeToDisk);

The specified firmware file is transferred to the AB64. If writeToDisk is false, the firmware is loaded into AB64 memory and run, re-booting the AB64. If writeToDisk is true, the firmware is written to disk. A 'Firmware Transfer Complete' message (code rcFWTransferCmpl) is sent when the transfer is complete.

Returns: false if an error occurred, true otherwise.

BYTE ORDER SHOW FILE TO HOST

set byte order when opening a show file 

void v4showFileToHost (void *shPtr, int shSize); //version 4 file
void v5showFileToHost (void *shPtr, int shSize); //version 5 file

The show file is in memory in storage byte order (big endian) when this function is called, as read in from disk. The size of the show file in bytes is passed in shSize. On return, the show is in native byte order.

Returns: none

BYTE ORDER HOST TO SHOW FILE

set byte order when saving a show file 

void hostTov4ShowFile (void *shPtr, int shSize); //version 4 file
void hostTov5ShowFile (void *shPtr, int shSize); //version 5 file

The show file is in memory in native byte order when this function is called. The size of the show file in bytes is passed in shSize. On return, the show is in storage byte order (big endian), ready to be written to disk.

Returns: none

Error Reporting

Many AB64 interface functions return 'true' or 'false' to indicate the function's completion status.When an error occurrs in an AB64 Interface function, a message is also inserted into the incoming AB64 message stream, code rcAB64IFerror. This message contains english text describing the error. In addition, the string is written to the standard error stream.

Data Structures

Data structures received via nextAB64Message are defined in ab64lib.h. These structures are packed, that is, there are no padding bytes other than those that are explicitly declared. For efficiency, some compilers add padding bytes in order to align longwords to natural boundariesa within a data structure. The structures in ab64lib.h have been designed to prevent this occurance, which could cause errors. For eaxmple, when a longword follows an odd number of words (short integers), the longword is broken into "low" and "high" words. Code that reads or writes these fields must put together the full longword or break a longword into its upper and lower halves.

Command Functions

The command functions in the AB64 Interface are specified below. Links are provided to the underlying AB64 command that is sent by the command function. The specification for the AB64 command often provides more detail about the command.

ALL OFF

sends an ALLOFF command to the AB64 

void allOff (void);

This command sends an ALL_OFF command to the AB64, which performs the actions enabled by setAllOffActions;

AB64 Command: ALL_OFF

Returns: none

ALL ON MATRIX

turns on all inputs outputs and crosspoints 

void allOnMatrix (void);

This command sets to full on all inputs, outputs and crosspoints.

Returns: none

ASSIGN INPUTS TO SUBMASTER

assigns input channels to submaster 

void assignInputsToSubMaster (char *assignString, long submaster);
 

This command assigns input channels to a submaster. Assign string is comma delimited, can contain ranges (i.e. "1-4, 10, 12-15"). Channel numbers are 1..64. Submaster numbers are 1..32.

AB64 Command: ASSIGN SUBMASTER.

Returns: none

ASSIGN OUTPUTS TO SUBMASTER

assigns output channels to submaster 

void assignOutputsToSubMaster (char *assignString, long submaster);
 

This command assigns output channels to a submaster. Assign string is comma delimited, can contain ranges (i.e. "1-4, 10, 12-15"). Channel numbers are 1..64. Submaster numbers are 1..32.

AB64 Command: ASSIGN SUBMASTER.

Returns: none

ASSIGN SUBMASTER TO CONTROLLER

assigns MIDI controller to submaster 

void assignSubMasterToController (long submaster, long controller);

This command assigns a MIDI controller to a submaster. Controller numbers are 0..127. Submaster numbers are 1..32.

AB64 Command: ASSIGN CONTROLLER.

Returns: none

CLEAR ALL DELAYS

sets all input, output and crosspoint delays to zero 

void clearAllDelays (void);

This command sets all input, output and crosspoint delays to zero.

AB64 Command: CLEAR DATA.

Returns: none

CLEAR ASSIGNS

clears all submaster and controller assigns 

void clearAssigns (void);

This command clears all submaster assigns (all submasters have no channel sassigned) and clears all controller assigns (no controllers assigned to any of the submasters).

AB64 Command: CLEAR DATA.

Returns: none

CLEAR DIRECTORY

clears the audio and show directories 

void clearDirectory (void);

This command clears all files from the audio and show directories on the AB64.

AB64 Command: CLEAR DATA.

Returns: none

CLEAR SETTINGS

clears all user settings 

void clearSettings (void);

This command sets the following data to the factory defaults:

AB64 Command: CLEAR DATA.

Returns: none

CLEAR SUBMASTER ASSIGNS

clears all AB64 message counts 

void clearSubmasterAssigns (long submaster, long IO);

This command clears all input (IO=0) or output (IO=1) channel assignments from a submaster.

AB64 Command: ASSIGN SUBMASTER.

Returns: none

CLOSE LIST

close a list open in the show controller 

void closeList (long list);

This command closes a list that is open in the AB64 show controller. List is 1..127.

AB64 Command: CLOSE CUE LIST.

Returns: none

CLOSE PATH

close a path open in the show controller 

void closePath (long list, long path);

This command closes a path within a list that is open in the AB64 show controller. List is 1..127, path is 1..2047.

AB64 Command: CLOSE CUE PATH.

Returns: none

DEASSIGN SUBMASTER FROM CONTROLLER

deassign controller 

void deassignSubMasterFromController (long submaster, long controller); 
//

This command deassigns a submaster from a MIDI controller. Controller numbers are 0..127. Submaster numbers are 1..32.

AB64 Command: ASSIGN CONTROLLER.

Returns: none

DECREMENT STANDBY CUE

make previous cue the new standby cue 

void decrementStandbyCue (long list);

This command decrements a standby cue in a list. The cue before the current standby cue becomes the new standby cue. List is 1..127.

AB64 Command: STANDBY-.

Returns: none

DIAGONAL MATRIX

turns on all inputs outputs and diagonal crosspoints 

void diagonalMatrix (void);

This command sets full on all inputs, outpus and diagonal crosspoints (1:1, 2:2, ...)

Returns: none

DISABLE PLAYBACK CHANNEL

disables (unloads) a playback channel 

void disablePlaybackChannel (long ch);

This command disables (unloads) a playback channel, removing its assigned audio file and clearing any stop or resume points. Channel numbers are 1..64

AB64 Command: DISABLE CHANNEL.

Returns: none

ENABLE RECORD CHANNEL

enables a channel for record 

void enableRecordChannel (long channel, long enable);

This command enables a channel for recording, Set enable = 1 to enable recording on the channel, 0 to disable recording on the channel. Channel numbers are 1..64

AB64 Command: ENABLE RECORD CHANNEL.

Returns: none

FREQUENCY RESPONSE

provides a point on an EQ curve 

void FrequencyResponse (double theta, double inA2, double inA1, double inA0,
                        double inB1, double inB0, double *outMag);

This command provide a point on an EQ curve. A complete curve is drawn by calling this function over a range of frequency values. The frequency is passed in theta, which is in normalized radians. Frequency in hertz is converted to frequency in normalized radians by multiplying by 2 pi and dividing by 48000. The filter coefficients are passed as inA2, inA1, inA0, inB1 and inB0. The magnitude of the EQ curve at that point is written to outMag.

AB64 Command: SET EQ COEFFICIENTS

Returns: none

GO ALL PLAYBACK

start all enabled playback channels 

void goAllPlayback (void);

This command sends a null playback GO, which starts all enabled playback channels. A playback channel is enabled for playback if an audio file is loaded on the channel.

AB64 Command: PLAYBACK GO

Returns: none

GO CUE

fires a cue 

void goCue (long cue, long sub1, long sub2, long sub3, long sub4, 
            long list, long path);

This command fires a cue. The cue number with optional subnumbers is passed in the first 5 parameters, any of which may be zero. If all are zero, a null GO is sent, which fires the next, or standby cue. List is 1..127, path is 1..2047. If zero if used for list, all standby cues in all lists are fired.

AB64 Command: SHOW GO

Returns: none

GO CUE JAM CLOCK

fires a cue and sets list clock to cue time 

void goCueJamClock (long cue, long sub1, long sub2, long sub3, long sub4, 
            long list, long path);

This command fires a cue and sets the list clock to the time of the cue. The cue number with optional subnumbers is passed in the first 5 parameters, any of which may be zero. If all are zero, a null GO is sent, which fires the next, or standby cue. List is 1..127, path is 1..2047.

AB64 Command: GO JAM CLOCK

Returns: none

GO PLAYBACK

starts playback at an audio location on a channel 

void goPlayback (long ch, long sel, long min, long sec, long frame, 
                 long framesPerSecond);
 

This command starts playback on a specified channel at a specified location in a specified audio file. The channel number 'ch' is 1..64. The audio file, or selection, number 'sel' is 1.. hvseln. The location is specified in minutes, seconds and frames from the beginning of the audio file.

AB64 Command: PLAYBACK GO

Returns: none

GO PLAYBACK CHANNELS

starts playback of a set of enabled (pre-loaded) channels 

void goPlaybackChannels (long chSet1, long chSet2);
 

This command starts playback on a specified set of channels. Enabled channels will play back precisely synchronized. Enabled channels are channels that have audio loaded (see SET PLAYBACK LOCATION), and therefore have a current audio location. Channels are specified by setting bits in the two channel set longwords. Bit 0 of the first longword is channel 1, bit 32 of the first longword is channel 32. Bit 0 of the second longword is channel 33, bit 32 of the second longword is channel 64.

channel number 'ch' is 1..64. The audio file, or selection, number 'sel' is 1.. hvseln. The location is specified in minutes, seconds and frames from the beginning of the audio file.

AB64 Command: GO CHANNEL SET EXT

Returns: none

INCREMENT STANDBY CUE

make cue after current standby the new standby cue 

void incrementStandbyCue (long list);

This command increments a standby cue in a list. The cue following the current standby cue becomes the new standby cue. List is 1..127.

AB64 Command: STANDBY+.

Returns: none

LOAD CUE

loads cue to standby 

void loadCue (long cue, long sub1, long sub2, long sub3, long sub4, 
              long list, long path);

This command loads a cue into standby (next cue). The cue number with optional subnumbers is passed in the first 5 parameters, any of which may be zero except the first. List is 1..127, path is 1..2047. If zero is passed as path number (path unspecified), the AB64 will attempt to load the cue number in the currently-open path. If path is specified and does not match the currently-open path, no action is performed.

AB64 Command: LOAD.

Returns: none

LOAD PLAYBACK MULTICHANNEL

loads multi-channel file at audio location 

void loadPlaybackMultiChannel (long plbkch, long sel, long min, long sec, 
                               long frame, long framesPerSecond); 
 

This command loads a multi-channel audio file for playback. The first channel of the file is loaded onto the specified starting channel ('plbkch'); channels are loaded sequentially from the starting channel. The playback location is specified in minutes, seconds and frames from the beginning of the audio file.

AB64 Command: LOAD MULTICHANNEL

Returns: none

OPEN LIST

opens a list in the show controller 

void openList (long show, long list);

This command opens a list, and optionally a show, in the AB64 show controller. List and show are 1..127. If zero is passed for 'show', the specified list in the currently open show is opened.

AB64 Command: OPEN CUE LIST.

Returns: none

OPEN PATH

opens a path in the show controller 

void openPath (long list, long path);

This command opens a path within a list that is open in the AB64 show controller. List is 1..127, path is 1..2047.

AB64 Command: OPEN CUE PATH.

Returns: none

PLAYBACK STOP

stops playback on a channel 

void playbackStop (long plbkch);
 

This command immediately stops playback on a specified channel. The channel number 'plbkch' is 1..64.

AB64 Command: PLAYBACK STOP

Returns: none

PUSH FRONT PANEL BUTTON

remotely push front panel button 

void pushFrontPanelButton (long button);0:left, 1:middle, 2:right

This command performs the same action as pushing one of the three buttons on the front panel of the AB64. For 'button' , 0: left button, 1: middle button and 2: right button.

AB64 Command: PUSH FRONT PANEL BUTTON.

Returns: none

RESET

sends an ALLOFF command to the AB64 

void reset (void);

This command sends a show RESET command to the AB64, which performs the actions enabled by SET RESET ACTIONS;

AB64 Command: RESET

Returns: none

RESUME CUE

resumes a cue, or all cues 

void resumeCue (long cue, long sub1, long sub2, long sub3, long sub4, 
             long list);

This command resumes a stopped cue. Resuming a cue starts the cue's sequence clock, which determines when events (commands) within the cue are executed. The cue number with optional subnumbers is passed in the first 5 parameters, any of which may be zero. If all are zero, a null RESUME is sent, which resumes all stopped cues in the list. List is 1..127. If zero if used for list, all stopped cues in all lists are resumed.

AB64 Command: SHOW RESUME

Returns: none

SEND COMMAND

sends MIDI-formatted command to AB64 

void sendCommand (unsigned char *cmd, long cmdLen);

This function sends an arbitrary MIDI-formatted command string to the AB64. With the complete set of command-sending functions provided in the AB64 Interface, this function is not normally used, but it is included in the event of special requirements. The MIDI-formatted command string is pointed to by 'cmd' and the length of the command in bytes is passed in 'cmdLen'.

Returns: none

SET AB64 NAME

sets name of AB64 unit 

void setAB64Name (char *name);

This function sets the name of the AB64 unit to the string 'name'. The name string is contained in the data returned in the rcInquiry message. It is typically displayed in a pop-up menu of AB64 units on the local area network.

AB64 Command: SET UNIT NAME EN

Returns: none

SET ALL OFF ACTIONS

sets actions performed by ALLOFF command 

void setAllOffActions (long flags);

This command sets the actions to be performed when an ALL OFF command is executed. The flag bits are defined as follows:

  bit   action
   0    mute all output channels of the mixer
   1    stop all playback
   2    stop all list clocks in the show controller and MTC Generator
   3    send ALL_NOTES_OFF messages as defined in the current show
   4    clear all playback stop notifications (before stopping playback
   5    clear all playback resume locations
   6    undefined, reserved, set to zero
   7    always zero

AB64 Command: SET ALL OFF ACTIONS

Returns: none

SET COBRANET

sets CobraNet bundle assignments 

void setCobraNet (short *bundleArray);
 

This command sets CobraNet bundles, determining the source and destination of digital audio signals on the CobraNet. The parameter 'bundleArray' is a pointer to an array of 16 short integers.

   short CN1RXBundle[4];   //Module 1 receiver 0..3 bundle assignments
   short CN1TXBundle[4];   //Module 1 transmitter 0..3 bundle assignments
   short CN2RXBundle[4];   //Module 2 receiver 0..3 bundle assignments
   short CN2TXBundle[4];   //Module 2 transmitter 0..3 bundle assignments

Receive and transmit bundle assignments determine the routing of audio channels on the CobraNet. On the AB64, a bundle carries eight audio channels. Each AB64 CobraNet module has four receivers and four transmitters. The matrix channels are mapped to the receivers and transmitters linearly:

matrix   CobraNet  receiver /
channels  module   transmitter
1 to 8      1         0
9 to 16     1         1
17 to 24    1         2
25 to 32    1         3
33 to 40    2         0
41 to 48    2         1
49 to 56    2         2
57 to 64    2         3

Bundle numbers connect transmitters to receivers: the eight audio channels transmitted by a transmitter set to bundle n are received by a receiver set to bundle n. Valid bundle numbers are 1..255 for multicast bundles (more than one receiver) and 256..65279 for unicast bundles (one receiver). A bundle number of zero indicates an unused receiver or transmitter.

AB64 Command: SET COBRANET EN

Returns: none

SET CROSSPOINT DELAY

sets crosspoint delay 

void setCrosspointDelay (long inch, long ouch, long dly, 
                long hour, long minute, long second, 
                long frame, long subframe, long framesPerSecond);

This command sets the delay on a crosspoint. The delay at the specified crosspoint changes from its current value to its new value in the ramp time specified. The crosspoint is specified by input channel (inch) and output channel (ouch), 1..64. The delay (dly) is specified in samples (sample frequency is 48 kHz.). The ramp time is specified in hours, minutes, seconds and frames.

AB64 Command: SET XPT DELAY

Returns: none

SET CROSSPOINT LEVEL

sets crosspoint level 

void setCrosspointLevel (long inch, long ouch, long level, long exp, 
           long hour, long minute, long second, long frame, 
           long subframe, long framesPerSecond);

This command sets the gain level on a crosspoint. The gain level at the specified crosspoint changes from its current value to its new value in the ramp time specified. The crosspoint is specified by input channel (inch) and output channel (ouch), 1..64. The level is specified in MIDI gain, 0..127. The ramp time is specified in hours, minutes, seconds and frames. If 'exp' is 1, the ramp will be exponential, if 0 the ramp is MIDI-number linear.

AB64 Command: SET XPT LEVEL

Returns: none

SET CROSSPOINT PHASE

sets crosspoint phase 

void setCrosspointPhase (long inch, long ouch, long phase);
 

This command sets the phase (or more accurately 'polarity') on a crosspoint. If 'phase' is set to 1, the polarity of the signal at the crosspoint is inverted, which in the case of sinusoidal signals is the same as a 180 degree phase shift. If 'phase' is set to 0, the signal at the crosspoint is not inverted.

AB64 Command: SET XPT PHASE

Returns: none

SET DEFAULT SHOW

sets show that loads when AB64 is booted 

void setDefaultShow (long show); 
 

This command sets the default show, which is the show that is automatically opened when the AB64 is powered on. The file number of the show to be made the default show is passed the function. Passing a zero results in no default show.

AB64 Command: SET DEFAULT SHOW

Returns: none

SET GPI

sets General Purpose Input parameters 

void setGPI (long mode, long lockout); //sets GPI parameters

This command sets parameters that affect the operation of the General Purpose Input port. The 'mode' byte sets the playback trigger mode. The 'lockout' value is the delay in milliseconds after a trigger before another trigger is allowed. See the AB64 command for more information.

AB64 Command: SET GPI

Returns: none

SET GPO

sets General Purpose Output states 

void setGPO (long output, long state);

This command turns on and off the two General Purpose Output pins. The output is either 0 or 1, and the state is 0 for off (no current flows) and 1 for on (current flows).

AB64 Command: SET GPO

Returns: none

SET INPUT DELAY

sets delay on input channel 

void setInputDelay (long ch, long dly);

This command sets the delay on an input channel (ch), 1..64. The delay (dly) is specified in samples (sample frequency is 48 kHz.).

AB64 Command: SET DELAY SAMPLES

Returns: none

SET INPUT DELAY ENABLE

sets delay on input channel 

void setInputDelayEnable (long ch, long enable);

This command enables or disables the delay on an input channel (ch), 1..64. An 'enable' value of 1 enables the delay that is currently set, a value of 0 disables the delay.

AB64 Command: ENABLE DELAY

Returns: none

SET INPUT EQ

sets EQ on input channel 

long setInputEQ (long ch, long band, long freq, long bw, long fg, long type); // channel numbers 'ch' are 1..64, returns false if filter cannot be realized

This command sets EQ on an input channel (ch), 1..64. There are seven bands of EQ (biquadratic sections) available on each input channel, the 'band' parameter is 0..6. The center frequency of the EQ (freq) is the frequency in Hertz multiplied by 100. The bandwidth (bw) is percent multiplied by 10, or10..990 for1 to 99 percent of center frequency. The gain (fg) is in dB multiplied by 10, -300..300 for -30 dB to +30 dB. The EQ type is low shelf, peaking, high shelf, low pass, high pass, notch or bandpass (eFTypeLowShelf, eFTypePeaking, eFTypeHighShelf, eFTypeLowPass, eFTypeHighPass, eFTypeNotch, eFTypeBandpass), defined in ab64if.h.

AB64 Command: SET EQ COEFFICIENTS

Returns: true if filter band could be realized, false if not.

SET INPUT EQ BANDS

sets number of bands of EQ on input channel 

void setInputEQbands (long ch, long bands);

This command sets the number of bands of EQ on an input channel (ch), 1..64. There are seven bands of EQ (biquadratic sections) available on each channel, the 'bands' parameter is 0..7. After setting the EQ parameters, this command activates the EQ. It also provides a convenient way to turn some or all of the bands on and off.

AB64 Command: SET EQ BANDS

Returns: none

SET INPUT LEVEL

sets input level 

void setInputLevel (long ch, long level, long exp, 
           long hour, long minute, long second, long frame, 
           long subframe, long framesPerSecond);

This command sets the gain level on an input channel. The gain level at the specified input (ch, 1..64) changes from its current value to its new value in the ramp time specified. The level is specified in MIDI gain, 0..127. The ramp time is specified in hours, minutes, seconds and frames. If 'exp' is 1, the ramp will be exponential, if 0 the ramp is MIDI-number linear.

AB64 Command: SET INPUT LEVEL

Returns: none

SET INPUT MUTE

sets input channel mute on and off 

void setInputMute (long ch, long mute);

This command sets input channel mute on and off. The channel (ch) is 1..64. Setting 'mute' to 1 mutes the channel; setting 'mute' to 0 unmutes the channel.

AB64 Command: MUTE INPUT CHANNEL

Returns: none

SET INPUT SOLO

sets input channel solo on and off 

void setInputSolo (long ch, long solo);

This command sets input channel solo on and off. The channel (ch) is 1..64. Setting solo to 1 solos the channel; setting solo to 0 unsolo the channel.

AB64 Command: SOLO INPUT CHANNEL

Returns: none

SET LIST CLOCK

sets list clock time 

void setListClock (long hour, long minute, long second, long frame, 
                 long subframe, long list, long framesPerSecond);

This command sets the time of a list clock in the AB64 show controller. List is 1..127, or 128 to set the internal MTC Generator.

AB64 Command: SET_CLOCK

Returns: none

SET MIDI ID

sets AB64 MIDI device ID 

void setMidiId (long id);

This command sets the MIDI device ID (0..127) for the AB64. The ID is written to disk.

AB64 Command: SET DEVICE ID

Returns: none

SET MIDI ECHO

sets MIDI echo flags 

void setMidiEcho (long midi, long show, long stopNotify);

This command sets on and off MIDI-MIDI echo, SHOW -MIDI filter and STOP_NOTIFY-MIDI filter. These settings control the internal MIDI connections. See the AB64 command for details.

AB64 Command: SET MIDI ECHO

Returns: none

SET MTC CHASE ON

turns on MIDI Time Code chase for a list or all lists 

void setMTCchaseOn (long list);

This command turns on MIDI Time Code chase for a list, or all lists (if 0 is passed for list). MIDI Time Code chase means that current MIDI time code (internal or external) is used for the list clock.

AB64 Command: MTC CHASE ON

Returns: none

SET MTC CHASE OFF

turns off MIDI Time Code chase for a list or all lists 

void setMTCchaseOff (long list);

This command turns off MIDI Time Code chase for a list, or all lists (if 0 is passed for list). With MIDI Time Code chase off, the internal list clock (stopwatch) is used.

AB64 Command: MTC CHASE OFF

Returns: none

SET MTC SOURCE INTERNAL 

use internal MTC generator

void setMTCsourceInternal (long list);

This command makes the internal MTC generator the source for MIDI Time Code for a list, or all lists (if 0 is passed for list).

AB64 Command: SET MTC SOURCE

Returns: none

SET MTC SOURCE EXTERNAL 

use external MTC source

void setMTCsourceExternal (long list);

This command makes the MTC coming in the MIDI port the source for MIDI Time Code for a list, or all lists (if 0 is passed for list).

AB64 Command: SET MTC SOURCE

Returns: none

SET OUTPUT DELAY

sets delay on output channel 

void setOutputDelay (long ch, long dly);

This command sets the delay on an output channel (ch), 1..64. The delay (dly) is specified in samples (sample frequency is 48 kHz.).

AB64 Command: SET DELAY SAMPLES

Returns: none

SET OUTPUT DELAY ENABLE

sets delay on output channel 

void setOutputDelayEnable (long ch, long enable);

This command enables or disables the delay on an output channel (ch), 1..64. An 'enable' value of 1 enables the delay that is currently set, a value of 0 disables the delay.

AB64 Command: ENABLE DELAY

Returns: none

SET OUTPUT EQ

sets EQ on output channel 

long setOutputEQ (long ch, long band, long freq, long bw, long fg, long type); // channel numbers 'ch' are 1..64, returns false if filter cannot be realized

This command sets EQ on an output channel (ch), 1..64. There are seven bands of EQ (biquadratic sections) available on each output channel, the 'band' parameter is 0..6. The center frequency of the EQ (freq) is the frequency in Hertz multiplied by 100. The bandwidth (bw) is percent multiplied by 10, or10..990 for1 to 99 percent of center frequency. The gain (fg) is in dB multiplied by 10, -300..300 for -30 dB to +30 dB. The EQ type is low shelf, peaking, high shelf, low pass, high pass, notch or bandpass (eFTypeLowShelf, eFTypePeaking, eFTypeHighShelf, eFTypeLowPass, eFTypeHighPass, eFTypeNotch, eFTypeBandpass, defined in ab64if.h).

AB64 Command: SET EQ COEFFICIENTS

Returns: true if filter could be realized, false if not.

SET OUTPUT EQ BANDS

sets number of bands of EQ on output channel 

void setOutputEQbands (long ch, long bands);

This command sets the number of bands of EQ on an output channel (ch), 1..64. There are seven bands of EQ (biquadratic sections) available on each channel, the 'bands' parameter is 0..7. After setting the EQ parameters, this command activates the EQ. It also provides a convenient way to turn some or all of the bands on and off.

AB64 Command: SET EQ BANDS

Returns: none

SET OUTPUT LEVEL

sets output level 

void setOutputLevel (long ch, long level, long exp, 
           long hour, long minute, long second, long frame, 
           long subframe, long framesPerSecond);

This command sets the gain level on an input channel. The gain level at the specified input (ch, 1..64) changes from its current value to its new value in the ramp time specified. The level is specified in MIDI gain, 0..127. The ramp time is specified in hours, minutes, seconds and frames. If 'exp' is 1, the ramp will be exponential, if 0 the ramp is MIDI-number linear.

AB64 Command: SET OUTPUT LEVEL

Returns: none

SET OUTPUT MUTE

sets output channel mute on and off 

void setOutputMute (long ch, long mute);

This command sets output channel mute on and off. The channel (ch) is 1..64. Setting 'mute' to 1 mutes the channel; setting 'mute' to 0 unmutes the channel.

AB64 Command: MUTE OUTPUT CHANNEL

Returns: none

SET OUTPUT SOLO

sets output channel solo on and off 

void setOutputSolo (long ch, long solo);

This command sets output channel solo on and off. The channel (ch) is 1..64. Setting solo to 1 solos the channel; setting solo to 0 unsolo the channel.

AB64 Command: SOLO OUTPUT CHANNEL

Returns: none

SET PLAYBACK LOCATION

sets playback location on a channel 

void setPlaybackLocation (long ch, long sel, long min, long sec, 
                long frame, long framesPerSecond);
 

This command sets a playback channel to a specified location in a specified audio file. This is sometimes referred to as 'loading' a playback channel. If the channel is playing, it is immediately stopped at the new location. The channel number 'ch' is 1..64. The audio file, or selection, number 'sel' is 1.. hvseln. The location is specified in minutes, seconds and frames from the beginning of the audio file.

AB64 Command: PLAYBACK LOAD

Returns: none

SET PLAYBACK BLOCK LOCATION

sets playback location on a channel 

void setPlaybackBlockLocation (long ch, long sel, long block);
 

This command sets a playback channel to a specified block location in a specified audio file. This is sometimes referred to as 'loading' a playback channel. If the channel is playing, it is immediately stopped at the new location. The channel number 'ch' is 1..64. The audio file, or selection, number 'sel' is 1.. hvseln. The location is specified in disk blocks from the beginning of the audio file. Because the current playback location is reported in blobks in the rcPlayback message returned by GET PLAYBACK EN (or by autoupdate), this function can be used, for example, to pause playback without potentially triggering a resume.

AB64 Command: PLAYBACK LOAD

Returns: none

SET PLAYBACK RESUME

sets playback resume location on a channel 

void setPlaybackResume (long ch, long sel, long min, long sec, 
                long frame, long framesPerSecond);
 

This command sets a playback resume point on a channel at a specified location in a specified audio file. This is used to set up audio jumps or loops. If a resume point is set on a channel, when playback stops, either due to 1) an incoming STOP command, 2) reaching a stop point that was previously set, or 3) by reaching the end of the selection, playback resumes at (or "jumps to") the resume point. The channel number 'ch' is 1..64. The audio file, or selection, number 'sel' is 1.. hvseln. The location is specified in minutes, seconds and frames from the beginning of the audio file.

AB64 Command: PLAYBACK RESUME

Returns: none

SET PLAYBACK STOP

sets playback stop location on a channel 

void setPlaybackStop (long ch, long sel, long min, long sec, 
                long frame, long framesPerSecond);
 

This command sets a playback stop point on a channel at a specified location in a specified audio file. This is used to automatically stop playback at the specified audio location. This can also trigger an audio jump or loop (see SET PLAYBACK RESUME). The channel number 'ch' is 1..64. The audio file, or selection, number 'sel' is 1.. hvseln. The location is specified in minutes, seconds and frames from the beginning of the audio file.

AB64 Command: PLAYBACK STOP

Returns: none

SET REAL TIME CLOCK

sets AB64 internal real-time clock 

void setRealTimeClock (void);

This command sets the real time (time of day) clock in the AB64 to the current time of day on the host computer.

AB64 Command: SET TIME EN

Returns: none

SET RESET ACTIONS

sets actions performed by RESET command 

void setResetActions (long flag1, long flag2);

This command sets the actions to be performed when a show RESET command is executed. The flag bits are defined as follows:

  flag1
  bit  action
   0   set all gain points to zero
   1   clear all mutes and solos
   2   stop all playback
   3   clear all playback stop notifications, stop points and resume points
   4   set submaster zero & gain to defaults and zero all submasters 
   5   reopen current show /  if bit clear, open default show
   6   clear all delay settings
   7   always zero
  flag 2
  bit  action
   0   clear all EQs
   1   send ALL_NOTES_OFF messages as defined in the current show, before
       it is closed
 

AB64 Command: SET RESET ACTIONS

Returns: none

SET RESUME BLOCK LOCATION

sets playback resume location on a channel 

void setResumeBlockLocation (long ch, long sel, long block);
 

This command sets a playback resume point on a channel at a specified location in a specified audio file. This is used to set up audio jumps or loops. If a resume point is set on a channel, when playback stops, either due to 1) an incoming STOP command, 2) reaching a stop point that was previously set, or 3) by reaching the end of the selection, playback resumes at (or "jumps to") the resume point. The channel number 'ch' is 1..64. The audio file, or selection, number 'sel' is 1.. hvseln. The location is specified in disk blocks from the beginning of the audio file.

AB64 Command: PLAYBACK RESUME

Returns: none

SET SOURCE MIX

sets mix of input signals on a channel 

void setSourceMix (long ch, long analog, long digital, long playback);

This command sets the mix of input signals on a channel. There are three input signals on each channel, the analog input (if the AB64 has an analog card installed for the channel), the digital input (if the AB64 has cobraNet or EtherSound installed for the channel), and disk playback. The levels for these signals are set using MIDI gain level numbers, 1..127. The channel number 'ch' is 1..64.

AB64 Command: SET SOURCE MIX

Returns: none

SET STOP BLOCK LOCATION

sets playback stop location on a channel 

void setStopBlockLocation (long ch, long sel, long block);
 

This command sets a playback stop point on a channel at a specified location in a specified audio file. This is used to automatically stop playback at the specified audio location. This can also trigger an audio jump or loop (see SET PLAYBACK RESUME). The channel number 'ch' is 1..64. The audio file, or selection, number 'sel' is 1.. hvseln. The location is specified in disk blocks from the beginning of the audio file.

AB64 Command: PLAYBACK STOP

Returns: none

SET SUBMASTER GAIN

sets submaster gain 

void setSubMasterGain (long gain);

This command sets the gain for all submasters. There are four gain values, 0..3, which determine the gain in dB corresponding to changes in individual submaster levels:

    0: 0.75 dB change every four submaster amplitude steps
    1: 0.75 dB change every two submaster amplitude steps
    2: 0.75 dB change every submaster amplitude step
    3: 1.50 dB change every submaster amplitude step

AB64 Command: SET SUBMASTER GAIN

Returns: none

SET SUBMASTER LEVEL

sets submaster level 

void setSubMasterLevel (long submaster, long level);

This command sets a submaster level to a MIDI gain level, 0..127. Submaster numbers are 1..32. Submaster levels may also be set by external MIDI controllers.

AB64 Command: SET SUBMASTER LEVEL

Returns: none

SET SUBMASTER ZERO

sets submaster zero point 

void setSubMasterZero (long zero);

This command sets the zero level for all submasters. When a submaster level is at the zero level, the submaster does not raise or lower the level of the assigned channels. The default value for submaster zero is 64, halfway between 0 and the maximum MIDI gain level, 127.

AB64 Command: SET SUBMASTER ZERO

Returns: none

SETUP RECORD

sets up AB64 to record audio 

void setupRecord (long selection, long inOut);

This command begins the process of recording audio on the AB64. It puts the AB64 into 'record enabled' audio mode, with all channels record disabled. Either a set of input channels ('inOut' = 0, post source mix, pre-matrix input level) or a set of output channels ('inOut = 1, post matrix output level) may be recorded (but not both simultaneously).

AB64 Command: SETUP RECORD

Returns: none

START LIST CLOCK

starts a list clock 

void startListClock (long list);

This command starts a list clock in the AB64 show controller. List is 1..127, or 128 to start the internal MTC Generator.

AB64 Command: START_CLOCK

Returns: none

STOP ALL PLAYBACK

stops all playback channels 

void stopAllPlayback (void);

This command sends a null playback STOP, which starimmediately stops all playback channels. If a resume point is set on a channel, playback continues at the resume location.

AB64 Command: PLAYBACK STOP

Returns: none

STOP CUE

stops a cue, or all cues 

void stopCue (long cue, long sub1, long sub2, long sub3, long sub4, 
             long list);

This command stops an active cue: a cue that has fired but not yet executed all of its events (timed commands). Stopping a cue stops the cue's sequence clock, which determines when events (commands) within the cue are executed. The cue number with optional subnumbers is passed in the first 5 parameters, any of which may be zero. If all are zero, a null STOP is sent, which stops all active cues in the list. List is 1..127. If zero if used for list, all active cues in all lists are stopped.

AB64 Command: SHOW STOP

Returns: none

STOP LIST CLOCK

stops a list clock 

void stopListClock (long list);

This command stops a list clock in the AB64 show controller. List is 1..127, or 128 to stop the internal MTC Generator. If zero if used for list, all list clocks are stopped.

AB64 Command: STOP_CLOCK

Returns: none

TURN OFF MATRIX

turns off all inputs outputs and crosspoints 

void turnOffMatrix (void);

This command sets to zero the gain level on all all inputs, outputs and crosspoints.

Returns: none

ZERO LIST CLOCK

zeros a list clock 

void zeroListClock (long list);

This command zeros a list clock in the AB64 show controller. List is 1..127, or 128 to zero the internal MTC Generator. If zero if used for list, all list clocks are zeroed.

AB64 Command: ZERO_CLOCK

Returns: none