Link and Share

The SOUND4 Link&Share (L&S) is a simple and open protocol that allow users to remotely control SOUND4 processors through a network connection.

SOUND4 offers a tool that manage sending L&S commands to your processors: the Link&Share Transmitter; but you can easily write your own tools in you preferred programming language (C,C#, VB, Java, PHP, ...).

The protocol is based on a standard telnet layer, so it can be joined by simply opening a TCP socket.

The Sound4Server opens TCP ports 3003 by default to access L&S.

Warning: the commands listed here may change depending on the product, its version, and the authorized login access level. To have a list of what you can do, either download the XML documentation from SOUND4 Remote Control in About->Download L&S Doc, or connect with a telnet client, login and type help.

Introduction

Security Concerns

Telnet protocol is not secured but has been chosen for ease-of-use. There are many ways to get a secured connection, for example:

1. Use a VPN (Virtual Private Network), and allow only connections from this VPN.
2. Use SSH, with port forwarding technique, and allow only local connections.

Session example

When connexion is established the server sends a prompt message:

READY

It is now possible to type commands. First you have to login:

LOGIN admin,admin

The server will confirm that you are logged :

OK

You may then change, for example, the Backup mode Main Source:

BK.SRC[1]=Analog

The server will confirm that the command was executed :

OK

You may also request the second Backup Source:

BK.SRC[2]?

And the server will reply for example:

Digital

Protocol

The protocol was designed to be easily and directly used by human user, via Telnet, or to be used by a program.

• Commands and Replies are always on individual lines.
• Commands are executed sequentially, and Replies are returned in the same Command order.
• Commands are not case sensitive : you may type LOGIN or LogIn.

The server has a built-in online help, called with HELP command. The Help page will be uncomplete when the user is not logged in, because Help page depends on the Process type.

You may request for more help on a particular topic, for example HELP IN to request help on Source setup, or HELP BK.SRC to get help on BK.SRC function.

The Server will accept simplified commands when there is no ambiguity. For example:

Bk.Src[Main]=Ana

is equivalent to

Bk.Src[Main Source]=Analog

because there is only one possible value for the index and for the source name.

Remark: special chars (non-ANSI) must be coded with UTF8 standard.

Server Replies

First char of a line gives an information on the type of reply:

1. A line starting with * means that the command failed. Rest of line gives more details
2. A line starting with + gives extra information. It continues the reply that can be split on several lines.
3. A line starting with ! is an asynchronous notification, with no relation to last command. In this case the line contains the notification identifier followed by an operator (=, +=, -=,...) and a value.
4. A line starting with ? is a Server Request : the server is asking a question and is waiting for an answer. This case is rare, and happens for example for LOGIN command when many Sound Processors are present and the target is unknown.
5. A line starting with another char is a direct reply to a command. The line usually starts with OK when it was a simple command. It may also be a value for a request command.

When connection is established the server sends a welcoming message followed by READY.

It is common to send all commands at a time, after connection is established, and to close the connection without waiting for replies. The server will stack the commands and execute them in right order. If the connection is not closed, the replies will arrive in the same order after READY.

Operators

Commands are in general made of the command name followed by an operator, except for basic commands.

? operator

Request a variable value. The Server will simply reply with the value.

Example:

RDS.PS?

= operator

Affectation of a value to a variable.

Example:

RDS.PS=Top Radio

+= operator

Add a value to a variable. Only supported by a reduced command subset.

Example:

RDS.AF+=107.7

-= operator

Remove a value to a variable. Only supported by a reduced command subset.

Exemple:

RDS.AF+=107.7

! operator

This requests an asynchronous notification on a variable's value change. VUmeter type variables usually don't support this because they change too fast and may saturate TCP link.

Example:

PRESET.ONAIR!

The server will reply OK if command request was successful, and will then send asynchronously a line starting with ! every time the value change. Example: Asynchronous Server reply

!PRESET.ONAIR=My new preset

* operator

Request to stop receiving asynchronous notifications

Example:

PRESET.ONAIR*

' operator

Request the setting range of a variable.

Example:

BK.SRC'

Variable format

Variables may have many dimensions and/or many channels. For example, the variable for Backup Sources (BK.SRC) contains 4 values.

Multidimensional variables are arrays. To reach an particular value, use [] signs around the index number, or use : sign separator between values across dimensions. First dimension is always numbered from 1 (and not from 0). It is sometimes possible to use names instead of numbers: see help on the considered variable for more details.

Example: Request the value of the second Backup Source

Bk.Src[2]?

Example: Direct affectation of the 4 values

Bk.Src=Analog:Digital:PCI:IP

For variables with many channels (left/right for example), the operator is () and separator is ; Example: Request the peak value of the 1 st analog output

Out.Ana_PkHold(1)?

Example: Same, but using the channel short name

Out.Ana_PkHold(L)?

Example: Request the peak value of the 1 st analog output

Out.Ana_PkHold?

Will return for example

-0.3;-0.1

Main commands

LOGIN

Used to log on Sound Processor. This command is required before server accept any other command.

If many Sound Processors are present on a single computer, you have to choose which target will be accessed by giving either the Processor Serial Number (preferred method), or the Processor name.

Syntax:

LOGIN user,password

LOGIN target,user,password

Users and passwords are the same as the one used and defined in the Sound4 Remote Control.

LOGOUT, EXIT, QUIT

Close the session and quits.

Remark: this command is not mandatory, as the connexion automatically closes when the TCP socket is closed.

HELP

Gives a detailed help on possible commands and variables.

To get more details, add a command or a group name.

Syntax: General help, lists the groups

HELP

Syntax: Help on commands for a particular group

HELP group

Syntax: Detailed help on particular command

HELP command

VER?

Returns the Sound4Server version.

Products specific documentations

For HD/FM product, see Link_and_Share_HDFM_Examples