Merge pull request #81 from timothyjward/alsa-contribution

Document the ALSA contribution model in Volumio 3.x

Author: volumio

docs/03_Plugin_System/03_Index.js.md

@@ -48,10 +48,18 @@ IMPORTANT TIPS:
 
 Then we add all the required functions for a generic plugin:
 
+### Plugin Lifecycle
+
+With the release of Volumio 3, the lifecycle of Volumio plugins has been better defined. Plugins are expected to complete `onVolumioStart` and `onStart` asynchronously by returning a Promise which completes when they have finished starting. Volumio will wait for all plugins to finish `onVolumioStart` before calling `onStart` on any plugin. Only once `onStart` has completed for all plugins will Volumio have finished starting.
+
+Note that plugin startup speed does affect the overall Volumio startup time. Try to avoid having long-running tasks that block startup. If a plugin appears to be *stuck*, and doesn't resolve the promise that it returns from `onVolumioStart` or `onStart` then Volumio will regard this plugin as having failed to start.
+
+One key difference between `onVolumioStart` and `onStart` is that it is *not safe* to play audio during `onVolumioStart`. While `onVolumioStart` is running plugins may still be making changes or creating resources that are needed by the audio stack. It is also considered good manners not to rely on functions (other than reading the configuration) from other plugins in `onVolumioStart`. This limits the likelihood that a plugin that you write will call into another plugin before it is fully initialised.
+
 
 #### On Volumio Start
 
-This is the code that gets executed when Volumio starts and triggers the plugin start. Typically, what you do is load the plugin configuration.
+This is the code that gets executed when Volumio starts and triggers the plugin start. Typically, what you do is load the plugin configuration, set up data structures, and create any necessary resources
 
 ```javascript
 ControllerSpop.prototype.onVolumioStart = function()
@@ -60,8 +68,14 @@ ControllerSpop.prototype.onVolumioStart = function()
 	this.config = new (require('v-conf'))();
 	this.config.loadFile(configFile);
 
+        var promise = libQ.nfcall(fs.writeFile, '/tmp/message', 'Hello World', 'utf8');
+        
+        return promise;
 }
 ```
+**IMPORTANT:**
+
+* You'll notice that we use promises here. That's why Volumio needs to know when the plugin has actually started, or if it failed. So what we're doing is returning the promise on successful start, and rejecting it if it doesn't start properly.
 
 #### On Start
 

docs/03_Plugin_System/09_Custom_ALSA_Contributions.md

@@ -0,0 +1,71 @@
+##  Custom ALSA Contributions
+
+Starting with Volumio 3 plugins are forbidden from directly changing the ALSA configuration in `/etc/asound.conf`. This is to resolve the many issues that occurred when multiple plugins wanted to make changes to the ALSA configuration, and to simplify the behaviour of sofware volume control. 
+
+Clearly some plugins will need to customise the Volumio ALSA configuration to provide their functionality. The way that this is achieved is through ALSA contribution snippets.  
+
+### What is an ALSA Contribution Snippet
+
+An ALSA contribution snippet is a piece of ALSA configuration provided by a plugin in a specially named file. It is designed to be easily assembled (along with other contribution snippets) into a complete ALSA configuration.
+
+The simplest valid ALSA contribution snippet would be a file named `in.out.conf` with the following content:
+
+```
+pcm.in {
+    type copy
+    slave.pcm "out"
+}
+```
+
+There are several important things to note about this snippet:
+* The file name has is of the form `<a>.<b>.conf`, where `<a>` and `<b>` are the "input" and "output" of the contribution snippet
+* The snippet does not attempt to directly address the audio hardware - it only deals with the behaviour of the plugin (in this case an no-op transform)
+* Snippets should expect that their input samples are linear, and should output linear samples.
+* The snippet must be prepared to handle a variety of input sample rates, bit depths, and channel counts. In most cases this will not need special handling, however if it does then an ALSA `plug` can be used.
+
+### Providing an ALSA Contribution Snippet
+
+Plugins must opt-in to providing ALSA contributions. This is done by setting the `has_alsa_contribution` property to `true` in the `volumio_info` of the plugin's `package.json`.
+
+```
+{
+  "name": "my_plugin",
+  "version": "1.0.0",
+  "description": "My super cool plugin",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "author": "Volumio",
+  "license": "ISC",
+  "volumio_info": {
+    "plugin_type": "audio_interface",
+    "boot_priority":4,
+    "has_alsa_contribution":true
+  }
+}
+```
+In addition to the `package.json` the plugin must place its ALSA contribution snippet(s) in a well defined location
+
+#### Static ALSA Contribution Snippets
+
+Static snippets are ones which do not rely on any configuration or runtime values, and so can be hardcoded as part of the plugin archive. Most plugins will be able to use static snippets.
+
+Static snippets live inside the plugin in a folder called `asound`.
+
+#### Dynamic ALSA Contribution Snippets
+
+In some cases it is necessary to customise an ALSA snippet based on configuration, or data which can be found only once the plugin is installed. This obviously prevents the snippet from being included as part of the plugin archive.
+
+Dynamic Contributions should be generated in `onVolumioStart` and written to the `asound` directory of plugin configuration folder. For example:
+
+```
+var folder = self.commandRouter.pluginManager.getConfigurationFile(self.context, 'asound');
+var promise  = libQ.nfcall(fs.writeFile, folder + '/in.out.conf', content, 'utf8');
+```
+
+### ALSA Contribution Snippet Ordering
+
+In general plugins should avoid trying to pick a particular order for snippets to run. There are, however, some cases where it is preferable to supply an ordering hint to Volumio. 
+
+In these scenarios the name of the ALSA contribution can be adjusted to include a third numeric segment `<a>.<b>.<priority>.conf`. The priority is an integer, and defaults to zero if not specified. Larger (more positive) values are put closer to the audio source. Lower (more negative) values are put closer to the hardware.