path: root/src/modules/module-protocol-pulse.c

/* PipeWire
 *
 * Copyright © 2020 Wim Taymans
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice (including the next
 * paragraph) shall be included in all copies or substantial portions of the
 * Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */

#include <string.h>
#include <stdio.h>
#include <errno.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <unistd.h>

#include "config.h"

#include <spa/utils/result.h>

#include <pipewire/impl.h>

#include "module-protocol-pulse/pulse-server.h"

/** \page page_module_protocol_pulse PipeWire Module: Protocol Pulse
 *
 * This module implements a complete PulseAudio server on top of
 * PipeWire.  This is only the server implementation, client are expected
 * to use the original PulseAudio client library. This provides a
 * high level of compatibility with existing applications; in fact,
 * all usual PulseAudio tools such as pavucontrol, pactl, pamon, paplay
 * should continue to work as they did before.
 *
 * This module is usually loaded as part of a standalone pipewire process,
 * called pipewire-pulse, with the pipewire-pulse.conf config file.
 *
 * The pulse server implements a sample cache that is otherwise not
 * available in PipeWire.
 *
 * ## Module Options
 *
 * The module arguments can be the contents of the pulse.properties but
 * it is recommended to make a separate pulse.properties section in the
 * config file so that overrides can be done.
 *
 * ## pulse.properties
 *
 * A config section with server properties can be given.
 *
 *\code{.unparsed}
 * pulse.properties = {
 *     # the addresses this server listens on
 *     server.address = [
 *         "unix:native"
 *         #"unix:/tmp/something"              # absolute paths may be used
 *         #"tcp:4713"                         # IPv4 and IPv6 on all addresses
 *         #"tcp:[::]:9999"                    # IPv6 on all addresses
 *         #"tcp:127.0.0.1:8888"               # IPv4 on a single address
 *         #
 *         #{ address = "tcp:4713"             # address
 *         #  max-clients = 64                 # maximum number of clients
 *         #  listen-backlog = 32              # backlog in the server listen queue
 *         #  client.access = "restricted"     # permissions for clients
 *         #}
 *     ]
 *     #pulse.min.req          = 256/48000     # 5ms
 *     #pulse.default.req      = 960/48000     # 20 milliseconds
 *     #pulse.min.frag         = 256/48000     # 5ms
 *     #pulse.default.frag     = 96000/48000   # 2 seconds
 *     #pulse.default.tlength  = 96000/48000   # 2 seconds
 *     #pulse.min.quantum      = 256/48000     # 5ms
 *     #pulse.default.format   = F32
 *     #pulse.default.position = [ FL FR ]
 *     # These overrides are only applied when running in a vm.
 *     vm.overrides = {
 *         pulse.min.quantum = 1024/48000      # 22ms
 *     }
 * }
 *\endcode
 *
 * ### Connection options
 *
 *\code{.unparsed}
 *     ...
 *     server.address = [
 *         "unix:native"
 *         # "tcp:4713"
 *     ]
 *     ...
 *\endcode
 *
 * The addresses the server listens on when starting. Uncomment the `tcp:4713` entry to also
 * make the server listen on a tcp socket. This is equivalent to loading `module-native-protocol-tcp`.
 *
 * There is also a slightly more verbose syntax with more options:
 *
 *\code{.unparsed}
 *     ....
 *     server.address = [
 *       {  address = "tcp:4713"             # address
 *          max-clients = 64                 # maximum number of clients
 *          listen-backlog = 32              # backlog in the server listen queue
 *          client.access = "restricted"     # permissions for clients
 *       }
 *     ....
 *\endcode
 *
 * Use `client.access` to use one of the access methods to restrict the permissions given to
 * clients connected via this address.
 *
 * By default network access is given the "restricted" permissions. The session manager is responsible
 * for assigning permission to clients with restricted permissions (usually read-only permissions).
 *
 * ### Playback buffering options
 *
 *\code{.unparsed}
 *     pulse.min.req = 256/48000              # 5ms
 *\endcode
 *
 * The minimum amount of data to request for clients. The client requested
 * values will be clamped to this value. Lowering this value together with
 * tlength can decrease latency if the client wants this, but increase CPU overhead.
 *
 *\code{.unparsed}
 *     pulse.default.req = 960/48000          # 20 milliseconds
 *\endcode
 *
 * The default amount of data to request for clients. If the client does not
 * specify any particular value, this default will be used. Lowering this value
 * together with tlength can decrease latency but increase CPU overhead.
 *
 *\code{.unparsed}
 *     pulse.default.tlength = 96000/48000    # 2 seconds
 *\endcode
 *
 * The target amount of data to buffer on the server side. If the client did not
 * specify a value, this default will be used. Lower values can decrease the
 * latency.
 *
 * ### Record buffering options
 *
 *\code{.unparsed}
 *     pulse.min.frag = 256/48000             # 5ms
 *\endcode
 *
 * The minimum allowed size of the capture buffer before it is sent to a client.
 * The requested value of the client will be clamped to this. Lowering this value
 * can reduce latency at the expense of more CPU usage.
 *
 *\code{.unparsed}
 *     pulse.default.frag = 96000/48000       # 2 seconds
 *\endcode
 *
 * The default size of the capture buffer before it is sent to a client. If the client
 * did not specify any value, this default will be used. Lowering this value can
 * reduce latency at the expense of more CPU usage.
 *
 * ### Scheduling options
 *
 *\code{.unparsed}
 *     pulse.min.quantum = 256/48000          # 5ms
 *\endcode
 *
 * The minimum quantum (buffer size in samples) to use for pulseaudio clients.
 * This value is calculated based on the frag and req/tlength for record and
 * playback streams respectively and then clamped to this value to ensure no
 * pulseaudio client asks for too small quantums. Lowering this value might
 * decrease latency at the expense of more CPU usage.
 *
 * ### Format options
 *
 *\code{.unparsed}
 *     pulse.default.format = F32
 *\endcode
 *
 * Some modules will default to this format when no other format was given. This
 * is equivalent to the PulseAudio `default-sample-format` option in
 * `/etc/pulse/daemon.conf`.
 *
 *\code{.unparsed}
 *     pulse.default.position = [ FL FR ]
 *\endcode
 *
 * Some modules will default to this channelmap (with its number of channels).
 * This is equivalent to the PulseAudio `default-sample-channels` and
 * `default-channel-map` options in `/etc/pulse/daemon.conf`.
 *
 * ### VM options
 *
 *\code{.unparsed}
 *     vm.overrides = {
 *         pulse.min.quantum = 1024/48000      # 22ms
 *     }
 *\endcode
 *
 * When running in a VM, the `vm.override` section will override the properties
 * in pulse.properties with the given values. This might be interesting because
 * VMs usually can't support the low latency settings that are possible on real
 * hardware.
 *
 * ## Stream settings and rules
 *
 * Streams created by module-protocol-pulse will use the stream.properties
 * section and stream.rules sections as usual.
 *
 * ## Application settings (Rules)
 *
 * The pulse protocol module supports generic config rules. It supports a pulse.rules
 * section with a `quirks` and an `update-props` action.
 *
 *\code{.unparsed}
 * pulse.rules = [
 *     {
 *         # skype does not want to use devices that don't have an S16 sample format.
 *         matches = [
 *              { application.process.binary = "teams" }
 *              { application.process.binary = "teams-insiders" }
 *              { application.process.binary = "skypeforlinux" }
 *         ]
 *         actions = { quirks = [ force-s16-info ] }
 *     }
 *     {
 *         # speech dispatcher asks for too small latency and then underruns.
 *         matches = [ { application.name = "~speech-dispatcher*" } ]
 *         actions = {
 *             update-props = {
 *                 pulse.min.req          = 1024/48000     # 21ms
 *                 pulse.min.quantum      = 1024/48000     # 21ms
 *             }
 *         }
 *     }
 * ]
 *\endcode
 *
 * ### Quirks
 *
 * The quirks action takes an array of quirks to apply for the client.
 *
 * * `force-s16-info` makes the sink and source introspect code pretend that the sample format
 *                    is S16 (16 bits) samples.  Some application refuse the sink/source if this
 *                    is not the case.
 * * `remove-capture-dont-move` Removes the DONT_MOVE flag on capture streams. Some applications
 *                    set this flag so that the stream can't be moved anymore with tools such as
 *                    pavucontrol.
 *
 * ### update-props
 *
 * Takes an object with the properties to update on the client. Common actions are to
 * tweak the quantum values.
 *
 * ## Example configuration
 *
 *\code{.unparsed}
 * context.modules = [
 * {   name = libpipewire-module-protocol-pulse
 *     args = { }
 * }
 * ]
 *
 * pulse.properties = {
 *     server.address = [ "unix:native" ]
 * }
 *
 * pulse.rules = [
 *     {
 *        # skype does not want to use devices that don't have an S16 sample format.
 *        matches = [
 *             { application.process.binary = "teams" }
 *             { application.process.binary = "teams-insiders" }
 *             { application.process.binary = "skypeforlinux" }
 *        ]
 *        actions = { quirks = [ force-s16-info ] }
 *    }
 *    {
 *        # speech dispatcher asks for too small latency and then underruns.
 *        matches = [ { application.name = "~speech-dispatcher*" } ]
 *        actions = {
 *            update-props = {
 *                pulse.min.req          = 1024/48000     # 21ms
 *                pulse.min.quantum      = 1024/48000     # 21ms
 *            }
 *        }
 *    }
 * ]
 *\endcode
 */

#define NAME "protocol-pulse"

PW_LOG_TOPIC(mod_topic, "mod." NAME);
#define PW_LOG_TOPIC_DEFAULT mod_topic
PW_LOG_TOPIC(pulse_conn, "conn." NAME);
PW_LOG_TOPIC(pulse_ext_dev_restore, "mod." NAME ".device-restore");
PW_LOG_TOPIC(pulse_ext_stream_restore, "mod." NAME ".stream-restore");

#define MODULE_USAGE	PW_PROTOCOL_PULSE_USAGE

static const struct spa_dict_item module_props[] = {
	{ PW_KEY_MODULE_AUTHOR, "Wim Taymans <wim.taymans@gmail.com>" },
	{ PW_KEY_MODULE_DESCRIPTION, "Implement a PulseAudio server" },
	{ PW_KEY_MODULE_USAGE, MODULE_USAGE },
	{ PW_KEY_MODULE_VERSION, PACKAGE_VERSION },
};

struct impl {
	struct pw_context *context;

	struct spa_hook module_listener;

	struct pw_protocol_pulse *pulse;
};

static void impl_free(struct impl *impl)
{
	spa_hook_remove(&impl->module_listener);
	if (impl->pulse)
		pw_protocol_pulse_destroy(impl->pulse);
	free(impl);
}

static void module_destroy(void *data)
{
	struct impl *impl = data;
	pw_log_debug("module %p: destroy", impl);
	impl_free(impl);
}

static const struct pw_impl_module_events module_events = {
	PW_VERSION_IMPL_MODULE_EVENTS,
	.destroy = module_destroy,
};

SPA_EXPORT
int pipewire__module_init(struct pw_impl_module *module, const char *args)
{
	struct pw_context *context = pw_impl_module_get_context(module);
	struct pw_properties *props;
	struct impl *impl;
	int res;

	PW_LOG_TOPIC_INIT(mod_topic);
	PW_LOG_TOPIC_INIT(pulse_conn);
	/* it's easier to init these here than adding an init() call to the
	 * extensions */
	PW_LOG_TOPIC_INIT(pulse_ext_dev_restore);
	PW_LOG_TOPIC_INIT(pulse_ext_stream_restore);

	impl = calloc(1, sizeof(struct impl));
	if (impl == NULL)
		return -errno;

	pw_log_debug("module %p: new %s", impl, args);

	if (args)
		props = pw_properties_new_string(args);
	else
		props = NULL;

	impl->pulse = pw_protocol_pulse_new(context, props, 0);
	if (impl->pulse == NULL) {
		res = -errno;
		free(impl);
		return res;
	}

	pw_impl_module_add_listener(module, &impl->module_listener, &module_events, impl);

	pw_impl_module_update_properties(module, &SPA_DICT_INIT_ARRAY(module_props));

	return 0;
}