Merge ~morphis/snappy-hwe-snaps/+git/pulseaudio:f/use-explicit-runtime-dir into ~snappy-hwe-team/snappy-hwe-snaps/+git/pulseaudio:master

Proposed by Simon Fels
Status: Merged
Approved by: Alfonso Sanchez-Beato
Approved revision: 6dab7ea4791e5c693b1685d2ca7cfa8694bceb7d
Merged at revision: e8a08971715c7571e0dafd24af562698084af201
Proposed branch: ~morphis/snappy-hwe-snaps/+git/pulseaudio:f/use-explicit-runtime-dir
Merge into: ~snappy-hwe-team/snappy-hwe-snaps/+git/pulseaudio:master
Prerequisite: ~morphis/snappy-hwe-snaps/+git/pulseaudio:f/alias-support
Diff against target: 534 lines (+310/-38)
13 files modified
bin/client-wrapper (+34/-0)
bin/pulseaudio (+1/-0)
dev/null (+0/-30)
docs/access-from-other-snaps.md (+65/-0)
docs/faq.md (+9/-0)
docs/index.md (+40/-0)
docs/install-pulseaudio.md (+51/-0)
docs/metadata.yaml (+23/-0)
docs/release-notes.md (+13/-0)
docs/report-bug.md (+19/-0)
snapcraft.yaml (+6/-8)
tests/main/documentation-builds/task.yaml (+14/-0)
tests/main/uses-global-runtime-dir/task.yaml (+35/-0)
Reviewer Review Type Date Requested Status
Konrad Zapałowicz (community) code Approve
System Enablement Bot continuous-integration Approve
Jim Hodapp Pending
Review via email: mp+318477@code.launchpad.net

Description of the change

Use PULSE_RUNTIME_PATH to specify global runtime directory

As we run pulseaudio in system mode we don't have a per user runtime
directory. If we just start pulseaudio in system mode it still tries
to create on below XDG_RUNTIME_DIR but as mediate access via
interfaces already to our PULSE_RUNTIME_PATH directory we can use a
global one to make our life much easier.

This also adds a few other things and starts with documentation but focuses mainly on documenting the changed client setup this MP implements.

To post a comment you must log in.
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :
review: Approve (continuous-integration)
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :
review: Approve (continuous-integration)
Revision history for this message
Konrad Zapałowicz (kzapalowicz) wrote :

Comments inline

review: Needs Fixing (code)
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :
review: Approve (continuous-integration)
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :
review: Approve (continuous-integration)
Revision history for this message
Konrad Zapałowicz (kzapalowicz) wrote :

ack

review: Approve (code)

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
diff --git a/bin/client-wrapper b/bin/client-wrapper
0new file mode 1007550new file mode 100755
index 0000000..255187c
--- /dev/null
+++ b/bin/client-wrapper
@@ -0,0 +1,34 @@
1#!/bin/sh
2#
3# Copyright (C) 2016 Canonical Ltd
4#
5# This program is free software: you can redistribute it and/or modify
6# it under the terms of the GNU General Public License version 3 as
7# published by the Free Software Foundation.
8#
9# This program is distributed in the hope that it will be useful,
10# but WITHOUT ANY WARRANTY; without even the implied warranty of
11# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12# GNU General Public License for more details.
13#
14# You should have received a copy of the GNU General Public License
15# along with this program. If not, see <http://www.gnu.org/licenses/>.
16
17if [ "$(id -u)" -ne 0 ]; then
18 echo "This script must be run as root" 1>&2
19 exit 1
20fi
21
22export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SNAP/usr/lib/pulseaudio:$SNAP/usr/lib/pulse-8.0/modules/
23export PULSE_CLIENTCONFIG=$SNAP/etc/pulse/client.conf
24export PULSE_RUNTIME_PATH=/var/run/pulse
25export PULSE_SYSTEM=1
26
27unset XDG_RUNTIME_DIR
28
29export HOME=$SNAP_DATA/home
30mkdir -p "$HOME"
31
32command="$SNAP/$1"
33shift
34exec "$command" "$@"
diff --git a/bin/pactl b/bin/pactl
0deleted file mode 10075535deleted file mode 100755
index f39f21b..0000000
--- a/bin/pactl
+++ /dev/null
@@ -1,30 +0,0 @@
1#!/bin/sh
2#
3# Copyright (C) 2016 Canonical Ltd
4#
5# This program is free software: you can redistribute it and/or modify
6# it under the terms of the GNU General Public License version 3 as
7# published by the Free Software Foundation.
8#
9# This program is distributed in the hope that it will be useful,
10# but WITHOUT ANY WARRANTY; without even the implied warranty of
11# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12# GNU General Public License for more details.
13#
14# You should have received a copy of the GNU General Public License
15# along with this program. If not, see <http://www.gnu.org/licenses/>.
16
17if [ $(id -u) -ne 0 ]; then
18 echo "This script must be run as root" 1>&2
19 exit 1
20fi
21
22export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SNAP/usr/lib/pulseaudio:$SNAP/usr/lib/pulse-8.0/modules/
23export PULSE_CLIENTCONFIG=$SNAP/etc/pulse/client.conf
24export HOME=$SNAP_DATA/home
25
26unset XDG_RUNTIME_DIR
27
28mkdir -p $HOME
29
30$SNAP/usr/bin/pactl $@
diff --git a/bin/paplay b/bin/paplay
31deleted file mode 1007550deleted file mode 100755
index eb759c9..0000000
--- a/bin/paplay
+++ /dev/null
@@ -1,30 +0,0 @@
1#!/bin/sh
2#
3# Copyright (C) 2016 Canonical Ltd
4#
5# This program is free software: you can redistribute it and/or modify
6# it under the terms of the GNU General Public License version 3 as
7# published by the Free Software Foundation.
8#
9# This program is distributed in the hope that it will be useful,
10# but WITHOUT ANY WARRANTY; without even the implied warranty of
11# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12# GNU General Public License for more details.
13#
14# You should have received a copy of the GNU General Public License
15# along with this program. If not, see <http://www.gnu.org/licenses/>.
16
17if [ $(id -u) -ne 0 ]; then
18 echo "This script must be run as root" 1>&2
19 exit 1
20fi
21
22export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SNAP/usr/lib/pulseaudio:$SNAP/usr/lib/pulse-8.0/modules/
23export PULSE_CLIENTCONFIG=$SNAP/etc/pulse/client.conf
24export HOME=$SNAP_DATA/home
25
26unset XDG_RUNTIME_DIR
27
28mkdir -p $HOME
29
30$SNAP/usr/bin/paplay $@
diff --git a/bin/parec b/bin/parec
31deleted file mode 1007550deleted file mode 100755
index ea78b35..0000000
--- a/bin/parec
+++ /dev/null
@@ -1,30 +0,0 @@
1#!/bin/sh
2#
3# Copyright (C) 2016 Canonical Ltd
4#
5# This program is free software: you can redistribute it and/or modify
6# it under the terms of the GNU General Public License version 3 as
7# published by the Free Software Foundation.
8#
9# This program is distributed in the hope that it will be useful,
10# but WITHOUT ANY WARRANTY; without even the implied warranty of
11# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12# GNU General Public License for more details.
13#
14# You should have received a copy of the GNU General Public License
15# along with this program. If not, see <http://www.gnu.org/licenses/>.
16
17if [ $(id -u) -ne 0 ]; then
18 echo "This script must be run as root" 1>&2
19 exit 1
20fi
21
22export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SNAP/usr/lib/pulseaudio:$SNAP/usr/lib/pulse-8.0/modules/
23export PULSE_CLIENTCONFIG=$SNAP/etc/pulse/client.conf
24export HOME=$SNAP_DATA/home
25
26unset XDG_RUNTIME_DIR
27
28mkdir -p $HOME
29
30$SNAP/usr/bin/parec $@
diff --git a/bin/pulseaudio b/bin/pulseaudio
index 8e23f97..40c9a85 100755
--- a/bin/pulseaudio
+++ b/bin/pulseaudio
@@ -3,6 +3,7 @@ set -e
3set -x3set -x
44
5export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SNAP/usr/lib/pulseaudio:$SNAP/usr/lib/pulse-8.0/modules/5export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SNAP/usr/lib/pulseaudio:$SNAP/usr/lib/pulse-8.0/modules/
6export PULSE_RUNTIME_PATH=/var/run/pulse
6export PULSE_STATE_PATH=$SNAP_DATA/state7export PULSE_STATE_PATH=$SNAP_DATA/state
7export ALSA_CONFIG_UCM=$SNAP/usr/share/alsa/ucm8export ALSA_CONFIG_UCM=$SNAP/usr/share/alsa/ucm
8export ALSA_CONFIG_TPLG=$SNAP/usr/share/alsa/topology9export ALSA_CONFIG_TPLG=$SNAP/usr/share/alsa/topology
diff --git a/docs/access-from-other-snaps.md b/docs/access-from-other-snaps.md
9new file mode 10064410new file mode 100644
index 0000000..3e778d7
--- /dev/null
+++ b/docs/access-from-other-snaps.md
@@ -0,0 +1,65 @@
1---
2title: "Access PulseAudio From Other Snaps"
3table_of_contents: True
4---
5
6# Access PulseAudio From Other Snaps
7
8To allow other snaps to play or record audio by using the PulseAudio service
9the *pulseaudio* interface exists which can be used to get access to features
10PulseAudio offers. Apart from using the *pulseaudio* interface a few other things
11need to be considered in order to get playback or recording working. These are
12
13 1. Define a pulseaudio interface plug for your application in the applications
14 snapcraft.yaml.
15 2. Set necessary environment variables for each application which communicates
16 with PulseAudio.
17
18## Define Pulseaudio Interface Plug
19
20To use the *pulseaudio* interface you simply need to define a plug with it
21in your *snapcraft.yaml* for all relevant applications:
22
23```
24name: my-audio-snap
25[...]
26apps:
27 player:
28 command: bin/player
29 plugs:
30 - pulseaudio
31[...]
32```
33
34With this, the plug will be listed by *snap interfaces* once you installed your
35snap. You can connect it to the PulseAudio service via:
36
37```
38$ snap connect my-audio-snap:pulseaudio pulseaudio:service
39```
40
41Now the interface connection between your client snap and the service is established.
42
43## Set Necessary Environment Variables
44
45In order to talk with the PulseAudio service you need to set one environment variable
46to ensure that libpulse finds the socket and other files it requires to talk to
47the service. The environment variable you need to set is the following:
48
49```
50PULSE_RUNTIME_PATH=/var/run/pulse
51```
52
53This can be included in the snapcraft.yaml or in shell scripts you use as wrappers
54around your programs. In our example we will directly include it in the *snapcraft.yaml* file:
55
56```
57name: my-audio-snap
58[...]
59apps:
60 player:
61 command: PULSE_RUNTIME_PATH=/var/run/pulse bin/player
62 plugs:
63 - pulseaudio
64[...]
65```
diff --git a/docs/faq.md b/docs/faq.md
0new file mode 10064466new file mode 100644
index 0000000..e1c725c
--- /dev/null
+++ b/docs/faq.md
@@ -0,0 +1,9 @@
1---
2title: "FAQ"
3table_of_contents: False
4---
5
6# FAQ
7
8This section covers some of the most commonly encountered problems and attempts
9to provide solutions for them.
diff --git a/docs/index.md b/docs/index.md
0new file mode 10064410new file mode 100644
index 0000000..ea4f41e
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,40 @@
1---
2title: "PulseAudio"
3table_of_contents: False
4---
5
6# About PulseAudio
7
8PulseAudio is a sound system for POSIX OSes, meaning that it is a proxy for your
9sound applications. It allows you to do advanced operations on your sound data
10as it passes between your application and your hardware. Things like transferring
11the audio to a different machine, changing the sample format or channel count and
12mixing several sounds into one are easily achieved using a sound server.
13
14PulseAudio is an integral part of all relevant modern Linux distributions and used
15in various mobile devices by multiple vendors.
16
17## What PulseAudio Offers
18
19 * Extensible plugin architecture (by loading dynamic loadable modules with dlopen())
20 * Support for static linking of modules, allowing a single binary for all your needs
21 * Module autoloading
22 * Support for more than one sink/source
23 * Good low latency behaviour
24 * Very accurate latency measurement for playback and recording.
25 * Client side latency interpolation
26 * Embeddable into other software (the core is available as C library)
27 * Completely asynchronous C API, complemented by two synchronous variants for simple use in synchronous applications
28 * Simple command line interface for reconfiguring the daemon while running
29 * Flexible, implicit sample type conversion and resampling
30 * "Zero-Copy" architecture
31 * May be used to combine multiple sound cards to one (with sample rate adjustment)
32 * Ability to fully synchronize multiple playback streams
33 * Various network audio streaming options
34
35Please see [the upstream feature list](https://www.freedesktop.org/wiki/Software/PulseAudio/About/) for more details.
36
37## Upstream documentation
38
39Existing documentation from the upstream project can be found
40[here](https://www.freedesktop.org/wiki/Software/PulseAudio/).
diff --git a/docs/install-pulseaudio.md b/docs/install-pulseaudio.md
0new file mode 10064441new file mode 100644
index 0000000..02d633f
--- /dev/null
+++ b/docs/install-pulseaudio.md
@@ -0,0 +1,51 @@
1---
2title: "Install PulseAudio"
3table_of_contents: True
4---
5
6# Install PulseAudio
7
8The PulseAudio snap is available from the Ubuntu Store. It can be installed on
9any system that supports snaps but is only recommended on
10[Ubuntu Core](https://www.ubuntu.com/core) at the moment.
11
12You can install the snap with the following command:
13
14```
15 $ snap install pulseaudio
16 pulseaudio 8.0-3 from 'canonical' installed
17```
18
19Although the pulseaudio snap is available from other channels (candidate, beta, edge),
20only the stable version should be used for production devices. Their meaning is internal
21to the development team of the pulseaudio snap.
22
23All necessary plugs and slots will be automatically connected within the
24installation process. You can verify this with:
25
26```
27$ snap interfaces pulseaudio
28Slot Plug
29:network pulseaudio
30pulseaudio:service pulseaudio:client
31- pulseaudio:home
32
33```
34
35As may noted, we do not connect the home plug of the PulseAudio snap by default.
36This is because normally you will use another snap to play audio through PulseAudio
37and then PulseAudio itself does not need any access to something outside of its
38snap as the playing snap will submits its audio data over network or memory based
39transport. If you want to use the included parec or paplay utilities you have to
40connect the home plug as otherwise both can only read/write data within the
41PulseAudio snap and nowhere else. You can connect it via:
42
43```
44$ snap connect pulseaudio:home core
45```
46
47Now you have PulseAudio successfully installed.
48
49## Next Steps
50
51 * [Access from other snaps](access-from-other-snaps.md)
diff --git a/docs/metadata.yaml b/docs/metadata.yaml
0new file mode 10064452new file mode 100644
index 0000000..321e111
--- /dev/null
+++ b/docs/metadata.yaml
@@ -0,0 +1,23 @@
1site_title: PulseAudio documentation
2site_logo_url: https://assets.ubuntu.com/v1/c5cb0f8e-picto-ubuntu.svg
3navigation:
4 - title: Introduction
5 children:
6 - title: About PulseAudio
7 location: index.md
8 - title: Install & Configure
9 children:
10 - title: Install PulseAudio
11 location: install-pulseaudio.md
12 - title: Access from other snaps
13 location: access-from-other-snaps.md
14 - title: Reference
15 children:
16 - title: Troubleshoot
17 children:
18 - title: FAQ
19 location: faq.md
20 - title: Release Notes
21 location: release-notes.md
22 - title: Report a Bug
23 location: report-bug.md
diff --git a/docs/release-notes.md b/docs/release-notes.md
0new file mode 10064424new file mode 100644
index 0000000..dab11ae
--- /dev/null
+++ b/docs/release-notes.md
@@ -0,0 +1,13 @@
1---
2title: "Release Notes"
3table_of_contents: False
4---
5
6# Release Notes
7
8The version numbers mentioned on this page correspond to those released in the
9Ubuntu snap store.
10
11## 8.0-3
12
13 * Initial release
diff --git a/docs/report-bug.md b/docs/report-bug.md
0new file mode 10064414new file mode 100644
index 0000000..0d49470
--- /dev/null
+++ b/docs/report-bug.md
@@ -0,0 +1,19 @@
1---
2title: "Report a Bug"
3table_of_contents: False
4---
5
6# Report a Bug
7
8Bugs can be reported [here](https://bugs.launchpad.net/snappy-hwe-snaps/+filebug).
9
10When submitting a bug report, please attach:
11
12 * */var/log/syslog*
13
14And the output of the following commands:
15
16```
17$ sudo pactl list
18$ cat /proc/asound/cards
19```
diff --git a/snapcraft.yaml b/snapcraft.yaml
index a070369..535b4b6 100644
--- a/snapcraft.yaml
+++ b/snapcraft.yaml
@@ -17,17 +17,17 @@ apps:
17 daemon: simple17 daemon: simple
18 slots: [service]18 slots: [service]
19 pactl:19 pactl:
20 command: bin/pactl20 command: bin/client-wrapper usr/bin/pactl
21 plugs: [client, network]21 plugs: [client, network]
22 aliases:22 aliases:
23 - pactl23 - pactl
24 paplay:24 paplay:
25 command: bin/paplay25 command: bin/client-wrapper usr/bin/paplay
26 plugs: [client, home, network]26 plugs: [client, home, network]
27 aliases:27 aliases:
28 - paplay28 - paplay
29 parec:29 parec:
30 command: bin/parec30 command: bin/client-wrapper usr/bin/parec
31 plugs: [client, home, network]31 plugs: [client, home, network]
32 aliases:32 aliases:
33 - parec33 - parec
@@ -47,9 +47,7 @@ parts:
47 plugin: copy47 plugin: copy
48 files:48 files:
49 bin/pulseaudio: bin/pulseaudio49 bin/pulseaudio: bin/pulseaudio
50 bin/pactl: bin/pactl50 bin/client-wrapper: bin/client-wrapper
51 bin/paplay: bin/paplay
52 bin/parec: bin/parec
53 bin/config: bin/config51 bin/config: bin/config
54 data/copyright: usr/share/doc/pulseaudio/copyright52 data/copyright: usr/share/doc/pulseaudio/copyright
5553
@@ -137,7 +135,7 @@ parts:
137 - --with-system-group=root135 - --with-system-group=root
138136
139 filesets:137 filesets:
140 pauseaudiofiles:138 wanted:
141 - etc/*139 - etc/*
142 - lib/*140 - lib/*
143 - usr/bin/pacat141 - usr/bin/pacat
@@ -153,4 +151,4 @@ parts:
153 - usr/share/pulseaudio/*151 - usr/share/pulseaudio/*
154152
155 snap:153 snap:
156 - $pauseaudiofiles154 - $wanted
diff --git a/tests/main/documentation-builds/task.yaml b/tests/main/documentation-builds/task.yaml
157new file mode 100644155new file mode 100644
index 0000000..848fff8
--- /dev/null
+++ b/tests/main/documentation-builds/task.yaml
@@ -0,0 +1,14 @@
1summary: Verify the project documentation builds without errors
2
3execute: |
4 # Need to install in devmode as otherwise the snap can't access our project
5 # home which is outside of the home directory of our current user.
6 snap install --devmode documentation-builder
7
8 outdir=$PROJECT_PATH/docs/build
9
10 cd $PROJECT_PATH/docs
11 /snap/bin/documentation-builder --output-path $outdir
12
13 # Ensure we have some files in the output directory
14 test `find $outdir -type f | wc -l` -gt 0
diff --git a/tests/main/uses-global-runtime-dir/task.yaml b/tests/main/uses-global-runtime-dir/task.yaml
0new file mode 10064415new file mode 100644
index 0000000..bcc4c8c
--- /dev/null
+++ b/tests/main/uses-global-runtime-dir/task.yaml
@@ -0,0 +1,35 @@
1summary: Verify pulseaudio and its clients are using a global runtime directory
2
3execute: |
4 # If PULSE_RUNTIME_PATH is not set correctly every client will print a
5 # warning that it can't create a secure directory in the configured runtime
6 # directory. We verify here that no command prints those warning messages
7 # anymore as we now have PULSE_RUNTIME_PATH set for both client and server.
8
9 /snap/bin/pactl list | grep -v "Failed to create secure directory"
10
11 # For playback/recording we need the home interface connected
12 snap connect pulseaudio:home core
13
14 # /var/run is a just a symlink to /run so check both
15 for d in /var/run /run ; do
16 test -e $d/pulse/.config
17 test -e $d/pulse/native
18 test -e $d/pulse/pid
19 done
20
21 pid=$(pidof pulseaudio)
22 test "$pid" = "$(cat /var/run/pulse/pid)"
23
24 # The alsa-utils snap includes some example wav files we can use for playback
25 snap install alsa-utils
26 cp -v /snap/alsa-utils/current/usr/share/sounds/alsa/Front_Center.wav /root
27 chown root:root /root/Front_Center.wav
28 /snap/bin/paplay /root/Front_Center.wav &> /tmp/paplay.log &
29 wait $!
30 [ -s /tmp/paplay.log ] && grep -q -v "Failed to create secure directory" /tmp/paplay.log
31
32 # parec is a little bit more tricky as it needs to be run in background
33 /snap/bin/parec &> /tmp/parec.log &
34 pid=$! ; sleep 1 ; kill -TERM $pid
35 [ -s /tmp/parec.log ] && grep -q -v "Failed to create secure directory" /tmp/parec.log

Subscribers

People subscribed via source and target branches

to all changes: