Merge ~alfonsosanchezbeato/snappy-hwe-snaps/+git/pulseaudio:example-snap into ~snappy-hwe-team/snappy-hwe-snaps/+git/pulseaudio:master

[Alfonso Sanchez-Beato]

Some cleanup and link to example snap

Cleanup and comment on example snap that uses PA snap in Core.

Some cleanup and link to example snap

Cleanup and comment on example snap that uses PA snap in Core.

[Simon Fels (morphis)]

review: Needs Fixing

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Continuous integration, rev:78f6b134efd19a82da1d45a4eeb3adc4f11cc212
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1267/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/336
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1175/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-test-snap/993
    None: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/9/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1267/rebuild

review: Approve (continuous-integration)

[Konrad Zapałowicz (kzapalowicz)]

ack

review: Approve (code)

[Alfonso Sanchez-Beato (alfonsosanchezbeato)]

Review comments addressed

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Continuous integration, rev:8145ff719c717b6480173841df35faa470390e66
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1268/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/337
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1177/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-test-snap/995
    None: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/10/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1268/rebuild

review: Approve (continuous-integration)

[Simon Fels (morphis)]

A few more comments inline.

[Alfonso Sanchez-Beato (alfonsosanchezbeato)]

Comments addressed and section added

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Continuous integration, rev:be6c0fe6f80a4e7298f7d5b9be52730038d6cae7
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1278/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/357
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1186/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-test-snap/1011
    None: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/26/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1278/rebuild

review: Approve (continuous-integration)

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Continuous integration, rev:c3cc1348365758877970e53f6ac0f84b6e6a66c2
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1279/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/358
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1187/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-test-snap/1012
    None: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/27/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1279/rebuild

review: Approve (continuous-integration)

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Continuous integration, rev:64a5b1bf1d690fe011c7730df9a33078edfdf7d5
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1280/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/359
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1188/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-test-snap/1013
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/28

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1280/rebuild

review: Approve (continuous-integration)

[Jim Hodapp (jhodapp)]

Looks great, several changes needed inline below.

review: Needs Fixing

[Alfonso Sanchez-Beato (alfonsosanchezbeato)]

Comments addressed

[Jim Hodapp (jhodapp)]

LGTM

review: Approve

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Continuous integration, rev:7bee74f71ea30ab0bada4974cd84b83b0042c4bd
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1286/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-build-snap-worker/375
    None: https://jenkins.canonical.com/system-enablement/job/generic-update-snap-mp/1194/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/generic-test-snap/1029
    None: https://jenkins.canonical.com/system-enablement/job/generic-cleanup-snap/41/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/generic-build-snap/1286/rebuild

review: Approve (continuous-integration)

[Simon Fels (morphis)]

LGTM

review: Approve

diff --git a/docs/access-from-other-snaps.md b/docs/access-from-other-snaps.md
index 3e778d7..7e4cb7d 100644
--- a/docs/access-from-other-snaps.md
+++ b/docs/access-from-other-snaps.md
@@ -5,22 +5,22 @@ table_of_contents: True
 
 # Access PulseAudio From Other Snaps
 
-To allow other snaps to play or record audio by using the PulseAudio service
-the *pulseaudio* interface exists which can be used to get access to features
-PulseAudio offers. Apart from using the *pulseaudio* interface a few other things
-need to be considered in order to get playback or recording working. These are
+To allow other snaps to play or record audio, or to use other PulseAudio
+features, the *pulseaudio* interface must be used.  Apart from using this
+interface, a few other things need to be considered in order to get playback or
+recording to work. These are
 
- 1. Define a pulseaudio interface plug for your application in the applications
+ 1. Define a pulseaudio interface plug for your application in the application's
     snapcraft.yaml.
  2. Set necessary environment variables for each application which communicates
     with PulseAudio.
 
 ## Define Pulseaudio Interface Plug
 
-To use the *pulseaudio* interface you simply need to define a plug with it
-in your *snapcraft.yaml* for all relevant applications:
+To use the *pulseaudio* interface you need to first define a plug with it in
+your *snapcraft.yaml* for all relevant applications:
 
-```
+```text
 name: my-audio-snap
 [...]
 apps:
@@ -42,24 +42,55 @@ Now the interface connection between your client snap and the service is establi
 
 ## Set Necessary Environment Variables
 
-In order to talk with the PulseAudio service you need to set one environment variable
-to ensure that libpulse finds the socket and other files it requires to talk to
-the service. The environment variable you need to set is the following:
+In order to talk with the PulseAudio service you need to set two environment
+variables to ensure that libpulse finds the socket and other files that it
+requires to talk to the service. The environment variables are the following:
 
-```
+```text
 PULSE_RUNTIME_PATH=/var/run/pulse
+PULSE_SYSTEM=1
+
 ```
 
-This can be included in the snapcraft.yaml or in shell scripts you use as wrappers
-around your programs. In our example we will directly include it in the *snapcraft.yaml* file:
+This can be included in the snapcraft.yaml or in shell scripts you can use as
+wrappers around your programs.
 
-```
-name: my-audio-snap
-[...]
+## Example Program
+
+To illustrate these concepts, it is worth looking at this [small
+example](https://github.com/canonical-system-enablement/pulseaudio-example) that
+uses [libpulse](https://freedesktop.org/software/pulseaudio/doxygen/) and
+integrates properly with Ubuntu Core.
+
+You can compile and install following the instructions in the following
+[README file](https://github.com/canonical-system-enablement/pulseaudio-example/blob/master/README.md).
+
+The example is quite straightforward, although we can emphasize a couple of aspects.
+
+First, note the
+[snapcraft.yaml](https://github.com/canonical-system-enablement/pulseaudio-example/blob/master/snapcraft.yaml)
+file contains the following information:
+
+```text
 apps:
-  player:
-    command: PULSE_RUNTIME_PATH=/var/run/pulse bin/player
+  pulseaudio-example:
+    command: bin/client-wrapper usr/bin/pulseaudio-example
     plugs:
       - pulseaudio
-[...]
+      - home
 ```
+
+Which shows that we are using the pulseaudio plug and a wrapper.
+[The wrapper](https://github.com/canonical-system-enablement/pulseaudio-example/blob/master/overlay/bin/client-wrapper)
+sets the expected variables:
+
+```text
+export PULSE_RUNTIME_PATH=/var/run/pulse
+export PULSE_SYSTEM=1
+```
+
+Second, as explained in the [previous section](using-pulseaudio.md), for using
+PulseAudio, we need root permissions in Ubuntu Core, so we have to put the audio
+files in some place which belongs to root and that can be accessed by the snap,
+for instance $SNAP_COMMON, which would be /var/snap/pacat-simple/common in the
+example snap.
diff --git a/docs/index.md b/docs/index.md
index ea4f41e..591fcad 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -11,6 +11,14 @@ as it passes between your application and your hardware. Things like transferrin
 the audio to a different machine, changing the sample format or channel count and
 mixing several sounds into one are easily achieved using a sound server.
 
+PulseAudio works as a proxy to
+[ALSA](http://www.alsa-project.org/main/index.php/Main_Page) so if your kernel
+supports ALSA and the needed sound card drivers for your device, the snap should
+work out of the box. More information on the kernel configuration needed for
+audio can be found
+[here](https://www.kernel.org/doc/html/latest/sound/alsa-configuration.html).
+Of course, Ubuntu Kernel comes with all this already enabled.
+
 PulseAudio is an integral part of all relevant modern Linux distributions and used
 in various mobile devices by multiple vendors.
 
diff --git a/docs/install-pulseaudio.md b/docs/install-pulseaudio.md
index 02d633f..16da8e9 100644
--- a/docs/install-pulseaudio.md
+++ b/docs/install-pulseaudio.md
@@ -16,9 +16,10 @@ You can install the snap with the following command:
  pulseaudio 8.0-3 from 'canonical' installed
 ```
 
-Although the pulseaudio snap is available from other channels (candidate, beta, edge),
-only the stable version should be used for production devices. Their meaning is internal
-to the development team of the pulseaudio snap.
+Although the pulseaudio snap is available from other channels (candidate, beta,
+edge), only the stable version should be used for production devices. The
+purpose of the other channels is for internal use for the development team of
+the pulseaudio snap.
 
 All necessary plugs and slots will be automatically connected within the
 installation process. You can verify this with:
@@ -32,13 +33,14 @@ pulseaudio:service  pulseaudio:client
 
 ```
 
-As may noted, we do not connect the home plug of the PulseAudio snap by default.
-This is because normally you will use another snap to play audio through PulseAudio
-and then PulseAudio itself does not need any access to something outside of its
-snap as the playing snap will submits its audio data over network or memory based
-transport. If you want to use the included parec or paplay utilities you have to
-connect the home plug as otherwise both can only read/write data within the
-PulseAudio snap and nowhere else. You can connect it via:
+Please note that we do not connect the home plug of the PulseAudio snap by
+default.  This is because normally you will use another snap to play audio
+through PulseAudio and then PulseAudio itself does not need any access to
+something outside of its snap as the playing snap will submits its audio data
+over network or memory based transport. If you want to use the included parec or
+paplay utilities you have to connect the home plug as otherwise both can only
+read/write data within the PulseAudio snap and nowhere else. You can connect it
+via:
 
 ```
 $ snap connect pulseaudio:home core
@@ -48,4 +50,5 @@ Now you have PulseAudio successfully installed.
 
 ## Next Steps
 
+ * [Using PulseAudio](using-pulseaudio.md)
  * [Access from other snaps](access-from-other-snaps.md)
diff --git a/docs/metadata.yaml b/docs/metadata.yaml
index 321e111..5932a8a 100644
--- a/docs/metadata.yaml
+++ b/docs/metadata.yaml
@@ -9,6 +9,8 @@ navigation:
     children:
       - title: Install PulseAudio
         location: install-pulseaudio.md
+      - title: Using PulseAudio
+        location: using-pulseaudio.md
       - title: Access from other snaps
         location: access-from-other-snaps.md
   - title: Reference
diff --git a/docs/using-pulseaudio.md b/docs/using-pulseaudio.md
new file mode 100644
index 0000000..ac7d7ad
--- /dev/null
+++ b/docs/using-pulseaudio.md
@@ -0,0 +1,45 @@
+---
+title: "Using PulseAudio"
+table_of_contents: True
+---
+
+# Using PulseAudio
+
+## PulseAudio Daemon
+
+After install of pulseaudio snap, the pulseaudio daemon should be up and
+running.  We can check its status with systemctl, and something similar to
+
+```text
+$ systemctl status snap.pulseaudio.pulseaudio.service | cat
+● snap.pulseaudio.pulseaudio.service - Service for snap application pulseaudio.pulseaudio
+   Loaded: loaded (/etc/systemd/system/snap.pulseaudio.pulseaudio.service; enabled; vendor preset: enabled)
+   Active: active (running) since Fri 2017-03-10 08:09:05 UTC; 2min 10s ago
+ Main PID: 1242 (pulseaudio)
+   CGroup: /system.slice/snap.pulseaudio.pulseaudio.service
+           ├─1242 /bin/sh /snap/pulseaudio/9/bin/pulseaudio
+           └─1276 /snap/pulseaudio/9/usr/bin/pulseaudio --exit-idle-time=-1 --disallow-exit=yes --disallow-module-loading --system -F /snap/pulseaudio/9/etc/pulse/default.pa -p /snap/pulseaudio/9/usr/lib/pulse-8.0/modules -n
+```
+
+should be displayed.
+
+## PulseAudio Utils
+
+The snap also includes some core pulseaudio utilities:
+[pactl](http://manpages.ubuntu.com/manpages/zesty/en/man1/pactl.1.html),
+[paplay](http://manpages.ubuntu.com/manpages/zesty/en/man1/paplay.1.html) and
+[parec](http://manpages.ubuntu.com/manpages/zesty/en/man1/parec.1.html).  Usage
+is as normally expected (check the linked man pages), but we need to take into
+account that we are running PA in system mode and we need root permissions when
+accessing it. This also implies that files need to be in some place which
+belongs to root and that can be accessed by the snap, like
+[$SNAP_COMMON](https://snapcraft.io/docs/reference/env). For instance, if we
+want to play an audio file that we have in our home folder with paplay, the
+command would be similar to
+
+```text
+$ sudo cp <audio-file> /var/snap/pacat-simple/common/
+$ sudo paplay /var/snap/pacat-simple/common/<audio-file>
+```
+
+The same appplies to the rest of the commands.