Configuration

The configuration is defined by the Built-in Default Configuration [1] overriden by the User configuration file if it exists. It is used in the following two stages of the pa-dlna process:

  • The selection of the encoder and audio mime-type.

  • The forwarding of an audio stream.

Encoder selection

pa-dlna fetches the DLNA device supported mime-types using the GetProtocolInfo UPnP command [2] and selects the first encoder/mime-type in the configured selection option that matches an item of the list returned by GetProtocolInfo.

If not already existing, an HTTP server is then started that answers requests on the local IP address where the DLNA device has been discovered.

Streaming

When PulseAudio (actually libpulse) notifies pa-dlna of the existence of a new stream from a source to the DLNA sink, it sends a SetAVTransportURI or SetNextAVTransportURI [3] UPnP SOAP [4] action to the device. This command holds:

  • The stream metadata.

  • The selected mime-type.

  • The URL to be used by the device to fetch the stream by initiating an HTTP GET for this URL.

Upon responding to the HTTP GET request pa-dlna forks the parec process and the selected encoder process [5] using the configured options. The output of the parec process is piped to the encoder process, the output of the encoder process is written to the HTTP socket.

It is possible to test an encoder configuration without using a DLNA device with the help of the ffplay program from the ffmpeg suite and a tool that retrieves HTTP files such as curl or wget. Here is an example with the L16Encoder:

  • Set the L16Encoder at the highest priority in the pa-dlna.conf file.

  • Run pa-dlna with the test-devices command line option [6]:

    $ pa-dlna --test-devices audio/L16\;rate=44100\;channels=2

  • Start a music player application and play some track.

  • Associate this source with the DLNATest_L16 - 0ab65 DLNA sink in pavucontrol.

  • Fetch the stream with curl as a file named output using the URL printed by the logs [7]:

    $ curl http://127.0.0.1:8080/audio-content/uuid:e7fa8886-6d97-a009-b6b6-6b1171b0ab65 -o output

  • Play the output file with the command:

    $ ffplay -f s16be -ac 2 -ar 44100 output

Encoders configuration

The encoders configuration is defined by the Built-in Default Configuration that may be overriden by the user’s pa-dlna.conf file.

The pa-dlna.conf file also allows the specification of the encoder and its options for a given DLNA device with a section named [EncoderName.UDN]. In this case the selection of the encoder using the selection option is by-passed and EncoderName is the selected encoder. UDN is the udn [8] of the device as printed by the logs or by the upnp-cmd command line tool.

The default configuration is structured as an INI file, more precisely as text that may be parsed by the configparser Python module. The user’s configuration file is also an INI file and obeys the same rules as the default configuration:

  • A section is either [DEFAULT], [EncoderName] or [EncoderName.UDN]. The options defined in the [DEFAULT] section apply to all the other sections and are overriden when also defined in the [EncoderName] or [EncoderName.UDN] sections. There is an exception with the selection option that is only meaningful in a [DEFAULT] section and ignored in all the other sections.

  • The selection option is an ordered comma separated list of encoders. This list is used to select the first encoder matching one of the mime-types supported by a discovered DLNA device when there is no specific [EncoderName.UDN] configuration for the given device.

  • The options defined in the user’s pa-dlna.conf file override the options of the default configuration.

  • Section names and options are case sensitive.

  • Boolean values are resticted to yes or no.

User configuration

The full path name of the user’s pa-dlna.conf file is determined by pa-dlna as follows:

  • If the XDG_CONFIG_HOME environment variable is set, the path name is $XDG_CONFIG_HOME/pa-dlna/pa-dlna.conf.

  • Otherwise the path name is $HOME/.config/pa-dlna/pa-dlna.conf.

When pa-dlna.conf is not found, the program uses the default configuration. Otherwise it uses the default configuration with its options overriden by the user’s configuration and with the added [EncoderName.UDN] sections.

Here is an example of a pa-dlna.conf file:

[DEFAULT]
selection =
    Mp3Encoder,
    FFMpegMp3Encoder,
    FFMpegFlacEncoder,

[FFMpegFlacEncoder]
track_metadata = no

[FFMpegMp3Encoder]
bitrate = 320

[FFMpegMp3Encoder.uuid:9ab0c000-f668-11de-9976-00a0de98381a]

In this example:

  • The DLNA device whose udn is uuid:9ab0c000-f668-11de-9976-00a0de98381a uses the FFMpegMp3Encoder with the default bitrate.

  • The other devices may use the three encoders of the selection, the preferred one being the Mp3Encoder with the default bitrate.

  • The FFMpegMp3Encoder is only used if the Mp3Encoder (the lame encoder) is not available and in that case it runs with a bitrate of 320 Kbps.

  • The FFMpegFlacEncoder is used when a DLNA device does not support the ‘audio/mp3’ and ‘audio/mpeg’ mime types and in that case its track_metadata option is not set.

  • If a DLNA device does not support the mp3 or the flac mime types, then it cannot be used even though the device would support one of the other mime types defined in the overriden default configuration.

One can verify what is the actual configuration used by pa-dlna by running the program with the --dump-internal command line option. A Python dictionary is printed with keys being EncoderName or UDN and the values a dictionary of their options. The EncoderName keys are ordered according to the selection option.

PulseAudio options

Options used by the parec and encoder programs (see how those programs are used in the Streaming section):

sample_format

The default value is s16le.

The encoders supporting the audio/L16 mime types (i.e. uncompressed audio data as defined by RFC 2586) have this option set to s16be as specified by the RFC and it cannot be modified by the user.

See the Pulseaudio supported sample formats.

rate

The Pulseaudio sample rate (default: 44100).

channels

The number of audio channels (default: 2).

Common options

args

The args option is the encoder program’s command line. When the args option is None, the encoder command line is built from the Pulseaudio options and the encoder’s specific options.

As all the other options (except sample_format in some cases, see above) it may be overriden by the user.

track_metadata

  • When yes, each track is streamed in its own HTTP session allowing the DLNA device to get each track meta data as described in the Meta Data section.

    This is the default.

  • When no, there is only one HTTP session for all the tracks. Set this option to no when the logs show ERROR entries upon tracks changes.

soap_minimum_interval

UPnP SOAP actions that start/stop a stream are spread out at soap_minimum_interval seconds to avoid the problem described at issue #16. This applies only to the SOAP actions that initiate or stop a stream: SetAVTransportURI, SetNextAVTransportURI and Stop.

The default is 5 seconds.

Encoder specific options

Encoder specific options (for example bitrate) are listed in Built-in Default Configuration with their default value. They are used to build the encoder command line when args is None.

Footnotes