Writing sdr plugins

Sdr plug-in configuration files follow a strict format of grouped attribute:value pairs with one attribute value pair per line. Leading whitespace is ignored. Whitespace in the value part of an attribute:value pair is significant.

Compulsory fields

For a format or tool definition file, the following attributes are compulsory and should be in the following order:
  media:media
  proto:protocol
  tool:tool-name
See the SDP specification for definitions of media and protocol. Tool-name is the name of the tool you wish to be started to send/receive this session.

Optional header fields

protoname

As the protocol will often not be very meaning full to humans, these may be followed by further definition:
  protoname:human readable versions of protocol
Protoname is used at configure menus and labels on the user interface.

create

Most plugins define media and formats that you wish to be able to announce. However, some may be just for backwards compatibility so you can receive them but do not wish to announce them. If this is the case, you can use the create field to specify that you don't wish this plugin to contribute to the session creation menus and options:
  create:no

Format definitions

After these definitions should come one or more format definitions. The minimal form of a format definition is:
  fmt:format
See the SDP specification for a more complete definition of what is meant by a format.

More normally however a format definition will require additional configuration, and this can be done as follows:

  fmt:format
  {
      fmtname:human readable version of format
      flags:command line flags for tool with this format
  }

Media Attributes

Both media and session definitions can contain optional attributes. These can be configured in the plugin on a per-tool or a per-format basis.

Attributes can be of two types - either with a set of values, or just on/off.

On-off attributes can be configured as follows:

  attr:attribute name
  {
      attrname:human readable version of attribute
      flags:command line flags for tool with this attribute
  }
Attributes with a set of values can be configured as follows:
  attr:attribute name
  {
      attrname:human readable version of attribute
      attrvalue:one possible value of attribute
      {
         attrvaluename:human readable version of this attribute vale
         flags:command line flags for tool with this attribute and value
      }
      attrvalue:another possible value of attribute
      {
         attrvaluename:human readable version of this attribute vale
         flags:command line flags for tool with this attribute and value
      }
  }
Either type of attribute may be used within a format definition (if the attribute is format specific) or after all the format definitions are complete (if the attribute is independant of the format).

This mechanism assumes you can explicitly list all the values of an attribute. Whilst this is often the case, it is not always so, and sdr plugins also allow the use of the macro and value definitions to allow flexible passing of attribute values directly to the media tool. See below for more details.

noattr

Occasionally you want to specify a behaviour to apply when an attribute is not present. To do this you use the noattr definition as follows:
  noattr:attribute name
  {
      flags:command line flags for tool if this attribute is missing
  }
A noattr definition must follow the equivalent attr definition.

Flags and Variables

The flags definition specifies a section of the command line that will be used to start the media tool if this plugin is matched. It can be used in attribute and format definitions and also after all the definitions are complete to finish the command line. A simple example is:
  media:audio
  proto:RTP/AVP
  tool:rat
  fmt:pcm
  {
    flags:-f pcm
  }
  fmt:dvi
  {
    flags:-f dvi
  }
  flags:-t $(TTL)
  flags:$(ADDRESS)/$(PORT)

For an rtp session with pcm format audio on address 224.2.3.4 and port 3456 with ttl 1, this would start the rat tool as follows:

  rat -f pcm -t 1 224.2.3.4/3456
As can be seen above, flags definitions can include variables that will be expanded when the session is started. As complete list of these variables is:

Macros

In cases where the value of an attribute must be passed directly to the media tool, the above mechanisms are sometimes not sufficient. To make this mechanism more flexible, sdr plugins provide a very simple macro facility. An example is:
media:audio
proto:vat
tool:vat
fmt:pcm
attr:id
{
  macro:ID
  {
    value:/$(VALUE)
  }
}
flags:$(ADDRESS)/$(PORT)$(ID)
In this case, the session attribute attribute "id" needs to be passed to vat at the end of the command line. The special variable $(VALUE) is given the value of the "id" attribute, and this is substitutes in the string given in the "value" definition. The resulting string is stored in the $(ID) variable, and expanded in the same way normal variables are when the tool is run. If there is no "id" attribute in this particular session, then the $(ID) variable is set to the empty string.

For example, a session with address/port 224.5.6.7/5432 and no id field would be started as:

vat 224.5.6.7/5432
and a session with the id atribute 1234 would have $(ID) defined as "/1234" and would be started as:
vat 224.5.6.7/5432/1234