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
1diff --git a/bin/client-wrapper b/bin/client-wrapper
2new file mode 100755
3index 0000000..255187c
4--- /dev/null
5+++ b/bin/client-wrapper
6@@ -0,0 +1,34 @@
7+#!/bin/sh
8+#
9+# Copyright (C) 2016 Canonical Ltd
10+#
11+# This program is free software: you can redistribute it and/or modify
12+# it under the terms of the GNU General Public License version 3 as
13+# published by the Free Software Foundation.
14+#
15+# This program is distributed in the hope that it will be useful,
16+# but WITHOUT ANY WARRANTY; without even the implied warranty of
17+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18+# GNU General Public License for more details.
19+#
20+# You should have received a copy of the GNU General Public License
21+# along with this program. If not, see <http://www.gnu.org/licenses/>.
22+
23+if [ "$(id -u)" -ne 0 ]; then
24+ echo "This script must be run as root" 1>&2
25+ exit 1
26+fi
27+
28+export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SNAP/usr/lib/pulseaudio:$SNAP/usr/lib/pulse-8.0/modules/
29+export PULSE_CLIENTCONFIG=$SNAP/etc/pulse/client.conf
30+export PULSE_RUNTIME_PATH=/var/run/pulse
31+export PULSE_SYSTEM=1
32+
33+unset XDG_RUNTIME_DIR
34+
35+export HOME=$SNAP_DATA/home
36+mkdir -p "$HOME"
37+
38+command="$SNAP/$1"
39+shift
40+exec "$command" "$@"
41diff --git a/bin/pactl b/bin/pactl
42deleted file mode 100755
43index f39f21b..0000000
44--- a/bin/pactl
45+++ /dev/null
46@@ -1,30 +0,0 @@
47-#!/bin/sh
48-#
49-# Copyright (C) 2016 Canonical Ltd
50-#
51-# This program is free software: you can redistribute it and/or modify
52-# it under the terms of the GNU General Public License version 3 as
53-# published by the Free Software Foundation.
54-#
55-# This program is distributed in the hope that it will be useful,
56-# but WITHOUT ANY WARRANTY; without even the implied warranty of
57-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
58-# GNU General Public License for more details.
59-#
60-# You should have received a copy of the GNU General Public License
61-# along with this program. If not, see <http://www.gnu.org/licenses/>.
62-
63-if [ $(id -u) -ne 0 ]; then
64- echo "This script must be run as root" 1>&2
65- exit 1
66-fi
67-
68-export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SNAP/usr/lib/pulseaudio:$SNAP/usr/lib/pulse-8.0/modules/
69-export PULSE_CLIENTCONFIG=$SNAP/etc/pulse/client.conf
70-export HOME=$SNAP_DATA/home
71-
72-unset XDG_RUNTIME_DIR
73-
74-mkdir -p $HOME
75-
76-$SNAP/usr/bin/pactl $@
77diff --git a/bin/paplay b/bin/paplay
78deleted file mode 100755
79index eb759c9..0000000
80--- a/bin/paplay
81+++ /dev/null
82@@ -1,30 +0,0 @@
83-#!/bin/sh
84-#
85-# Copyright (C) 2016 Canonical Ltd
86-#
87-# This program is free software: you can redistribute it and/or modify
88-# it under the terms of the GNU General Public License version 3 as
89-# published by the Free Software Foundation.
90-#
91-# This program is distributed in the hope that it will be useful,
92-# but WITHOUT ANY WARRANTY; without even the implied warranty of
93-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
94-# GNU General Public License for more details.
95-#
96-# You should have received a copy of the GNU General Public License
97-# along with this program. If not, see <http://www.gnu.org/licenses/>.
98-
99-if [ $(id -u) -ne 0 ]; then
100- echo "This script must be run as root" 1>&2
101- exit 1
102-fi
103-
104-export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SNAP/usr/lib/pulseaudio:$SNAP/usr/lib/pulse-8.0/modules/
105-export PULSE_CLIENTCONFIG=$SNAP/etc/pulse/client.conf
106-export HOME=$SNAP_DATA/home
107-
108-unset XDG_RUNTIME_DIR
109-
110-mkdir -p $HOME
111-
112-$SNAP/usr/bin/paplay $@
113diff --git a/bin/parec b/bin/parec
114deleted file mode 100755
115index ea78b35..0000000
116--- a/bin/parec
117+++ /dev/null
118@@ -1,30 +0,0 @@
119-#!/bin/sh
120-#
121-# Copyright (C) 2016 Canonical Ltd
122-#
123-# This program is free software: you can redistribute it and/or modify
124-# it under the terms of the GNU General Public License version 3 as
125-# published by the Free Software Foundation.
126-#
127-# This program is distributed in the hope that it will be useful,
128-# but WITHOUT ANY WARRANTY; without even the implied warranty of
129-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
130-# GNU General Public License for more details.
131-#
132-# You should have received a copy of the GNU General Public License
133-# along with this program. If not, see <http://www.gnu.org/licenses/>.
134-
135-if [ $(id -u) -ne 0 ]; then
136- echo "This script must be run as root" 1>&2
137- exit 1
138-fi
139-
140-export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SNAP/usr/lib/pulseaudio:$SNAP/usr/lib/pulse-8.0/modules/
141-export PULSE_CLIENTCONFIG=$SNAP/etc/pulse/client.conf
142-export HOME=$SNAP_DATA/home
143-
144-unset XDG_RUNTIME_DIR
145-
146-mkdir -p $HOME
147-
148-$SNAP/usr/bin/parec $@
149diff --git a/bin/pulseaudio b/bin/pulseaudio
150index 8e23f97..40c9a85 100755
151--- a/bin/pulseaudio
152+++ b/bin/pulseaudio
153@@ -3,6 +3,7 @@ set -e
154 set -x
155
156 export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$SNAP/usr/lib/pulseaudio:$SNAP/usr/lib/pulse-8.0/modules/
157+export PULSE_RUNTIME_PATH=/var/run/pulse
158 export PULSE_STATE_PATH=$SNAP_DATA/state
159 export ALSA_CONFIG_UCM=$SNAP/usr/share/alsa/ucm
160 export ALSA_CONFIG_TPLG=$SNAP/usr/share/alsa/topology
161diff --git a/docs/access-from-other-snaps.md b/docs/access-from-other-snaps.md
162new file mode 100644
163index 0000000..3e778d7
164--- /dev/null
165+++ b/docs/access-from-other-snaps.md
166@@ -0,0 +1,65 @@
167+---
168+title: "Access PulseAudio From Other Snaps"
169+table_of_contents: True
170+---
171+
172+# Access PulseAudio From Other Snaps
173+
174+To allow other snaps to play or record audio by using the PulseAudio service
175+the *pulseaudio* interface exists which can be used to get access to features
176+PulseAudio offers. Apart from using the *pulseaudio* interface a few other things
177+need to be considered in order to get playback or recording working. These are
178+
179+ 1. Define a pulseaudio interface plug for your application in the applications
180+ snapcraft.yaml.
181+ 2. Set necessary environment variables for each application which communicates
182+ with PulseAudio.
183+
184+## Define Pulseaudio Interface Plug
185+
186+To use the *pulseaudio* interface you simply need to define a plug with it
187+in your *snapcraft.yaml* for all relevant applications:
188+
189+```
190+name: my-audio-snap
191+[...]
192+apps:
193+ player:
194+ command: bin/player
195+ plugs:
196+ - pulseaudio
197+[...]
198+```
199+
200+With this, the plug will be listed by *snap interfaces* once you installed your
201+snap. You can connect it to the PulseAudio service via:
202+
203+```
204+$ snap connect my-audio-snap:pulseaudio pulseaudio:service
205+```
206+
207+Now the interface connection between your client snap and the service is established.
208+
209+## Set Necessary Environment Variables
210+
211+In order to talk with the PulseAudio service you need to set one environment variable
212+to ensure that libpulse finds the socket and other files it requires to talk to
213+the service. The environment variable you need to set is the following:
214+
215+```
216+PULSE_RUNTIME_PATH=/var/run/pulse
217+```
218+
219+This can be included in the snapcraft.yaml or in shell scripts you use as wrappers
220+around your programs. In our example we will directly include it in the *snapcraft.yaml* file:
221+
222+```
223+name: my-audio-snap
224+[...]
225+apps:
226+ player:
227+ command: PULSE_RUNTIME_PATH=/var/run/pulse bin/player
228+ plugs:
229+ - pulseaudio
230+[...]
231+```
232diff --git a/docs/faq.md b/docs/faq.md
233new file mode 100644
234index 0000000..e1c725c
235--- /dev/null
236+++ b/docs/faq.md
237@@ -0,0 +1,9 @@
238+---
239+title: "FAQ"
240+table_of_contents: False
241+---
242+
243+# FAQ
244+
245+This section covers some of the most commonly encountered problems and attempts
246+to provide solutions for them.
247diff --git a/docs/index.md b/docs/index.md
248new file mode 100644
249index 0000000..ea4f41e
250--- /dev/null
251+++ b/docs/index.md
252@@ -0,0 +1,40 @@
253+---
254+title: "PulseAudio"
255+table_of_contents: False
256+---
257+
258+# About PulseAudio
259+
260+PulseAudio is a sound system for POSIX OSes, meaning that it is a proxy for your
261+sound applications. It allows you to do advanced operations on your sound data
262+as it passes between your application and your hardware. Things like transferring
263+the audio to a different machine, changing the sample format or channel count and
264+mixing several sounds into one are easily achieved using a sound server.
265+
266+PulseAudio is an integral part of all relevant modern Linux distributions and used
267+in various mobile devices by multiple vendors.
268+
269+## What PulseAudio Offers
270+
271+ * Extensible plugin architecture (by loading dynamic loadable modules with dlopen())
272+ * Support for static linking of modules, allowing a single binary for all your needs
273+ * Module autoloading
274+ * Support for more than one sink/source
275+ * Good low latency behaviour
276+ * Very accurate latency measurement for playback and recording.
277+ * Client side latency interpolation
278+ * Embeddable into other software (the core is available as C library)
279+ * Completely asynchronous C API, complemented by two synchronous variants for simple use in synchronous applications
280+ * Simple command line interface for reconfiguring the daemon while running
281+ * Flexible, implicit sample type conversion and resampling
282+ * "Zero-Copy" architecture
283+ * May be used to combine multiple sound cards to one (with sample rate adjustment)
284+ * Ability to fully synchronize multiple playback streams
285+ * Various network audio streaming options
286+
287+Please see [the upstream feature list](https://www.freedesktop.org/wiki/Software/PulseAudio/About/) for more details.
288+
289+## Upstream documentation
290+
291+Existing documentation from the upstream project can be found
292+[here](https://www.freedesktop.org/wiki/Software/PulseAudio/).
293diff --git a/docs/install-pulseaudio.md b/docs/install-pulseaudio.md
294new file mode 100644
295index 0000000..02d633f
296--- /dev/null
297+++ b/docs/install-pulseaudio.md
298@@ -0,0 +1,51 @@
299+---
300+title: "Install PulseAudio"
301+table_of_contents: True
302+---
303+
304+# Install PulseAudio
305+
306+The PulseAudio snap is available from the Ubuntu Store. It can be installed on
307+any system that supports snaps but is only recommended on
308+[Ubuntu Core](https://www.ubuntu.com/core) at the moment.
309+
310+You can install the snap with the following command:
311+
312+```
313+ $ snap install pulseaudio
314+ pulseaudio 8.0-3 from 'canonical' installed
315+```
316+
317+Although the pulseaudio snap is available from other channels (candidate, beta, edge),
318+only the stable version should be used for production devices. Their meaning is internal
319+to the development team of the pulseaudio snap.
320+
321+All necessary plugs and slots will be automatically connected within the
322+installation process. You can verify this with:
323+
324+```
325+$ snap interfaces pulseaudio
326+Slot Plug
327+:network pulseaudio
328+pulseaudio:service pulseaudio:client
329+- pulseaudio:home
330+
331+```
332+
333+As may noted, we do not connect the home plug of the PulseAudio snap by default.
334+This is because normally you will use another snap to play audio through PulseAudio
335+and then PulseAudio itself does not need any access to something outside of its
336+snap as the playing snap will submits its audio data over network or memory based
337+transport. If you want to use the included parec or paplay utilities you have to
338+connect the home plug as otherwise both can only read/write data within the
339+PulseAudio snap and nowhere else. You can connect it via:
340+
341+```
342+$ snap connect pulseaudio:home core
343+```
344+
345+Now you have PulseAudio successfully installed.
346+
347+## Next Steps
348+
349+ * [Access from other snaps](access-from-other-snaps.md)
350diff --git a/docs/metadata.yaml b/docs/metadata.yaml
351new file mode 100644
352index 0000000..321e111
353--- /dev/null
354+++ b/docs/metadata.yaml
355@@ -0,0 +1,23 @@
356+site_title: PulseAudio documentation
357+site_logo_url: https://assets.ubuntu.com/v1/c5cb0f8e-picto-ubuntu.svg
358+navigation:
359+ - title: Introduction
360+ children:
361+ - title: About PulseAudio
362+ location: index.md
363+ - title: Install & Configure
364+ children:
365+ - title: Install PulseAudio
366+ location: install-pulseaudio.md
367+ - title: Access from other snaps
368+ location: access-from-other-snaps.md
369+ - title: Reference
370+ children:
371+ - title: Troubleshoot
372+ children:
373+ - title: FAQ
374+ location: faq.md
375+ - title: Release Notes
376+ location: release-notes.md
377+ - title: Report a Bug
378+ location: report-bug.md
379diff --git a/docs/release-notes.md b/docs/release-notes.md
380new file mode 100644
381index 0000000..dab11ae
382--- /dev/null
383+++ b/docs/release-notes.md
384@@ -0,0 +1,13 @@
385+---
386+title: "Release Notes"
387+table_of_contents: False
388+---
389+
390+# Release Notes
391+
392+The version numbers mentioned on this page correspond to those released in the
393+Ubuntu snap store.
394+
395+## 8.0-3
396+
397+ * Initial release
398diff --git a/docs/report-bug.md b/docs/report-bug.md
399new file mode 100644
400index 0000000..0d49470
401--- /dev/null
402+++ b/docs/report-bug.md
403@@ -0,0 +1,19 @@
404+---
405+title: "Report a Bug"
406+table_of_contents: False
407+---
408+
409+# Report a Bug
410+
411+Bugs can be reported [here](https://bugs.launchpad.net/snappy-hwe-snaps/+filebug).
412+
413+When submitting a bug report, please attach:
414+
415+ * */var/log/syslog*
416+
417+And the output of the following commands:
418+
419+```
420+$ sudo pactl list
421+$ cat /proc/asound/cards
422+```
423diff --git a/snapcraft.yaml b/snapcraft.yaml
424index a070369..535b4b6 100644
425--- a/snapcraft.yaml
426+++ b/snapcraft.yaml
427@@ -17,17 +17,17 @@ apps:
428 daemon: simple
429 slots: [service]
430 pactl:
431- command: bin/pactl
432+ command: bin/client-wrapper usr/bin/pactl
433 plugs: [client, network]
434 aliases:
435 - pactl
436 paplay:
437- command: bin/paplay
438+ command: bin/client-wrapper usr/bin/paplay
439 plugs: [client, home, network]
440 aliases:
441 - paplay
442 parec:
443- command: bin/parec
444+ command: bin/client-wrapper usr/bin/parec
445 plugs: [client, home, network]
446 aliases:
447 - parec
448@@ -47,9 +47,7 @@ parts:
449 plugin: copy
450 files:
451 bin/pulseaudio: bin/pulseaudio
452- bin/pactl: bin/pactl
453- bin/paplay: bin/paplay
454- bin/parec: bin/parec
455+ bin/client-wrapper: bin/client-wrapper
456 bin/config: bin/config
457 data/copyright: usr/share/doc/pulseaudio/copyright
458
459@@ -137,7 +135,7 @@ parts:
460 - --with-system-group=root
461
462 filesets:
463- pauseaudiofiles:
464+ wanted:
465 - etc/*
466 - lib/*
467 - usr/bin/pacat
468@@ -153,4 +151,4 @@ parts:
469 - usr/share/pulseaudio/*
470
471 snap:
472- - $pauseaudiofiles
473+ - $wanted
474diff --git a/tests/main/documentation-builds/task.yaml b/tests/main/documentation-builds/task.yaml
475new file mode 100644
476index 0000000..848fff8
477--- /dev/null
478+++ b/tests/main/documentation-builds/task.yaml
479@@ -0,0 +1,14 @@
480+summary: Verify the project documentation builds without errors
481+
482+execute: |
483+ # Need to install in devmode as otherwise the snap can't access our project
484+ # home which is outside of the home directory of our current user.
485+ snap install --devmode documentation-builder
486+
487+ outdir=$PROJECT_PATH/docs/build
488+
489+ cd $PROJECT_PATH/docs
490+ /snap/bin/documentation-builder --output-path $outdir
491+
492+ # Ensure we have some files in the output directory
493+ test `find $outdir -type f | wc -l` -gt 0
494diff --git a/tests/main/uses-global-runtime-dir/task.yaml b/tests/main/uses-global-runtime-dir/task.yaml
495new file mode 100644
496index 0000000..bcc4c8c
497--- /dev/null
498+++ b/tests/main/uses-global-runtime-dir/task.yaml
499@@ -0,0 +1,35 @@
500+summary: Verify pulseaudio and its clients are using a global runtime directory
501+
502+execute: |
503+ # If PULSE_RUNTIME_PATH is not set correctly every client will print a
504+ # warning that it can't create a secure directory in the configured runtime
505+ # directory. We verify here that no command prints those warning messages
506+ # anymore as we now have PULSE_RUNTIME_PATH set for both client and server.
507+
508+ /snap/bin/pactl list | grep -v "Failed to create secure directory"
509+
510+ # For playback/recording we need the home interface connected
511+ snap connect pulseaudio:home core
512+
513+ # /var/run is a just a symlink to /run so check both
514+ for d in /var/run /run ; do
515+ test -e $d/pulse/.config
516+ test -e $d/pulse/native
517+ test -e $d/pulse/pid
518+ done
519+
520+ pid=$(pidof pulseaudio)
521+ test "$pid" = "$(cat /var/run/pulse/pid)"
522+
523+ # The alsa-utils snap includes some example wav files we can use for playback
524+ snap install alsa-utils
525+ cp -v /snap/alsa-utils/current/usr/share/sounds/alsa/Front_Center.wav /root
526+ chown root:root /root/Front_Center.wav
527+ /snap/bin/paplay /root/Front_Center.wav &> /tmp/paplay.log &
528+ wait $!
529+ [ -s /tmp/paplay.log ] && grep -q -v "Failed to create secure directory" /tmp/paplay.log
530+
531+ # parec is a little bit more tricky as it needs to be run in background
532+ /snap/bin/parec &> /tmp/parec.log &
533+ pid=$! ; sleep 1 ; kill -TERM $pid
534+ [ -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: