snappy-hwe-snaps

Merge ~morphis/snappy-hwe-snaps/+git/alsa-utils:f/record-play-api into ~snappy-hwe-team/snappy-hwe-snaps/+git/alsa-utils:master

  1. Git
  2. lp:~morphis/snappy-hwe-snaps/+git/alsa-utils
  3. f/record-play-api
  4. Merge into master
Proposed by Simon Fels
Status: Needs review
Proposed branch: ~morphis/snappy-hwe-snaps/+git/alsa-utils:f/record-play-api
Merge into: ~snappy-hwe-team/snappy-hwe-snaps/+git/alsa-utils:master
Diff against target: 156 lines (+120/-2)
5 files modified
docs/content-mixer-state.md (+0/-0)
docs/metadata.yaml (+10/-2)
docs/playing-audio.md (+46/-0)
docs/recording-audio.md (+43/-0)
docs/reference/library-api.md (+21/-0)
Reviewer Review Type Date Requested Status
Tony Espy Needs Fixing
System Enablement Bot continuous-integration Needs Fixing
Alfonso Sanchez-Beato Needs Fixing
Konrad Zapałowicz (community) Needs Fixing
Alberto Milone (community) Approve
Review via email: mp+330900@code.launchpad.net

Description of the change

Document playback/recording and available library API

To post a comment you must log in.
Revision history for this message
Alberto Milone (albertomilone) wrote :

The documentation looks good to me.

review: Approve
Reply
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

PASSED: Successfully build documentation, rev: 71d81ec941f47dea830ac68e53fe656a57f46a4a

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/550/

Reply
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

FAILED: Continuous integration, rev:71d81ec941f47dea830ac68e53fe656a57f46a4a
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/499/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-worker/549
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/550
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-test/548/console
    None: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-update-mp/516/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/499/rebuild

review: Needs Fixing (continuous-integration)
Reply
Revision history for this message
Konrad Zapałowicz (kzapalowicz) wrote :

comments inline

review: Needs Fixing
Reply
Revision history for this message
Alfonso Sanchez-Beato (alfonsosanchezbeato) wrote :

Some comments, see below.

review: Needs Fixing
Reply
~morphis/snappy-hwe-snaps/+git/alsa-utils:f/record-play-api updated
adaa0ab... by Simon Fels

Respect review comments

Revision history for this message
Simon Fels (morphis) :
Reply
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

PASSED: Successfully build documentation, rev: adaa0ab8b45fa6637263ed3ecd314c495f138cad

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/552/

Reply
Revision history for this message
System Enablement Bot (system-enablement-ci-bot) wrote :

FAILED: Continuous integration, rev:adaa0ab8b45fa6637263ed3ecd314c495f138cad
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/501/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-worker/551
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/552
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-test/550/console
    None: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-update-mp/518/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/501/rebuild

review: Needs Fixing (continuous-integration)
Reply
Revision history for this message
Tony Espy (awe) wrote :

Looks good, but a couple of minor comments need addressing.

review: Needs Fixing
Reply

Unmerged commits

adaa0ab... by Simon Fels

Respect review comments

71d81ec... by Simon Fels

Minor refactoring and document audio playback/recording + API

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1diff --git a/docs/reference/content-mixer-state.md b/docs/content-mixer-state.md
2index baaac89..baaac89 100644
3--- a/docs/reference/content-mixer-state.md
4+++ b/docs/content-mixer-state.md
5diff --git a/docs/metadata.yaml b/docs/metadata.yaml
6index bd330f4..ed8a6a4 100644
7--- a/docs/metadata.yaml
8+++ b/docs/metadata.yaml
9@@ -3,9 +3,17 @@ navigation:
10 children:
11 - title: About alsa-utils
12 location: index.md
13+ - title: Usage
14+ children:
15+ - title: Playing Audio
16+ location: playing-audio.md
17+ - title: Recording Audio
18+ location: recording-audio.md
19+ - title: Device-specific initial ALSA state configuration
20+ location: content-mixer-state.md
21 - title: Reference
22 children:
23+ - title: ALSA Library API
24+ location: reference/library-api.md
25 - title: Available tools
26 location: reference/available-utilities.md
27- - title: Device-specific initial ALSA state configuration
28- location: reference/content-mixer-state.md
29diff --git a/docs/playing-audio.md b/docs/playing-audio.md
30new file mode 100644
31index 0000000..e0ae262
32--- /dev/null
33+++ b/docs/playing-audio.md
34@@ -0,0 +1,46 @@
35+---
36+title: "Playing Audio"
37+table_of_contents: True
38+---
39+
40+# Playing Audio
41+
42+Playing audio with the commands offered by the alsa-utils snap is mostly
43+straightforward. The only tricky thing is where the audio data
44+comes from. Due to the fact that the alsa-utils snap is completely
45+confined access to audio data is only possible through certain file
46+system locations.
47+
48+The most common location the alsa-utils snap should have access to is
49+the home directory of the currently executing user. It is available for
50+the snap when the 'home' plug is connected.
51+
52+!!! positive "Pro-Tip"
53+ You can verify that the `home` plug is connected by calling:<br/>
54+ `$ snap interfaces alsa-utils`
55+
56+## On The Command Line
57+
58+Playback via the `aplay` command is only possible with raw PCM audio data
59+which is contained in a [WAV](https://en.wikipedia.org/wiki/WAV) file.
60+
61+Once the audio data is in an accessible place (e.g. `/home`) playback can
62+be started with the following command:
63+
64+```
65+$ alsa-utils.aplay -t wav $HOME/my-audio.wav
66+```
67+
68+Eventually, depending on your hardware and ALSA configuration, you may have
69+to select the target playback device with the `--device` argument. For
70+example:
71+
72+```
73+$ alsa-utils.aplay --device=mydevice -t wav $HOME/my-audio.wav
74+```
75+
76+Available audio devices on your system can be listed with:
77+
78+```
79+$ ls /sys/class/sound | grep hw
80+```
81diff --git a/docs/recording-audio.md b/docs/recording-audio.md
82new file mode 100644
83index 0000000..c4407aa
84--- /dev/null
85+++ b/docs/recording-audio.md
86@@ -0,0 +1,43 @@
87+---
88+title: "Recording Audio"
89+table_of_contents: True
90+---
91+
92+# Recording Audio
93+
94+Aside from [playing audio](playing-audio.md) the alsa-utils snap also allows
95+a user to record audio. For this the usual command is `arecord`. It records
96+raw PCM audio data from a input port of a selected audio card and stores it
97+optionally in a file.
98+
99+As the `arecord` command writes the recorded audio data by default into a file
100+we need an accessible place for the `alsa-utils` snap the file can be placed
101+
102+The `arecord` command writes the recorded audio data by default into a file.
103+We need an accessible place for the alsa-utils snap so that the file can be
104+saved. The best place for this is the home directory of the current user. To allow
105+the snap to access the home directory the `home` plug of the `alsa-utils` snap
106+needs to be connected.
107+
108+!!! positive "Pro-Tip"
109+ You can verify that the `home` plug is connected by calling:<br/>
110+ `$ snap interfaces alsa-utils`
111+
112+## On the command line
113+
114+Audio recorded can be started with the `arecord` command:
115+
116+```
117+$ arecord $HOME/recorded-audio.dat
118+```
119+
120+Additionally the output format and type can be specified with the `-f` and `-t`
121+command line arguments. For example we can select `wav` as output type
122+and `SE16_LE` as format with the following command:
123+
124+```
125+$ arecord -f SE16_LE -t wav $HOME/recorded-audio.wav
126+```
127+
128+For more available command line arguments please see the output of `arecord -h`
129+or the [corresponding documentation](reference/available-utilities.md).
130diff --git a/docs/reference/library-api.md b/docs/reference/library-api.md
131new file mode 100644
132index 0000000..3c6dbdf
133--- /dev/null
134+++ b/docs/reference/library-api.md
135@@ -0,0 +1,21 @@
136+---
137+title: "ALSA Library API"
138+table_of_contents: True
139+---
140+
141+# ALSA Library API
142+
143+The ALSA project provides a set of libraries which can be used to interact
144+with the Linux kernel side audio stack.
145+
146+Further details and the full API reference can be found
147+[here](http://www.alsa-project.org/alsa-doc/alsa-lib/).
148+
149+!!! positive "Pro-Tip"
150+ In order to use the ALSA development libraries you have to include a
151+ copy inside your snap. You can use the `build-packages` part of your
152+ `snapcraft.yaml` for this (see the [snapcraft documentation](https://snapcraft.io/docs/)
153+ for more details) and add `libasound2-dev`. This will build
154+ your software against the available ALSA libaries on your build system
155+ and will include relevant parts in your snap.
156+

Subscribers

People subscribed via source and target branches

to all changes: