Add docs (#1)

Author: kristianhentschelbbc

.github/workflows/docs.yml

@@ -0,0 +1,35 @@
+name: ci 
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - docs/**
+      - mkdocs.yml
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - run: pip install mkdocs-material 
+
+      - run: mkdocs gh-deploy --force

docs/allocation-algorithm.md

@@ -0,0 +1,33 @@
+# The allocation algorithm
+
+[Audio device orchestration](index.md#what-is-orchestration) is the concept of using multiple connected devices to play back an audio experience. It is capable of flexible, adaptable sound reproduction that takes into account the available loudspeaker devices.
+
+In our orchestration system, audio objects are allocated to devices by an *allocation algorithm*. The allocations depend on:
+
+* the [behaviours](audio.md#behaviours) that you've attached to each object;
+* the properties of the available devices; and
+* [control](controls.md) values that the listener has set.
+
+Every time that some of this information changes, the objects are processed one at a time, in the order in which they appear in the [audio object table](audio.md#audio-object-table).
+
+For each object, each available device is categorised as *preferred*, *allowed*, or *prohibited*. Devices can be given more than one of these labels, but in the final stage, any devices with a *prohibited* label cannot be used for the object.
+
+In the final device selections:
+
+* an object with the *All applicable devices* fixed behaviour setting will be allocated to all remaining *preferred* and *allowed* devices;
+
+* an object with the *One device only* fixed behaviour setting will be assigned to a single device selected at random from any *preferred* devices, or from any *allowed* devices if there are no *preferred* devices;
+
+* if there are no *preferred* or *allowed* devices, an object will not be allocated during that particular run of the allocation algorithm.
+
+This gives a great degree of flexibility in how objects are assigned to devices, and means that the reproduction can adapt to any number of devices whilst still being controlled by you as the content producer.
+
+## Change management
+
+As noted above, the allocation algorithm runs every time there is a change in some of the information it uses (for example, if a new device is added, a device drops out, or the listener uses a control). This means that the experience is flexible and adaptable.
+
+In some circumstances, there is an element of randomness to audio object allocations. If more than one device is *allowed* or *preferred*, but the object is only allowed into one device, then a random device will be selected. And this might change each time the allocation algorithm runs. Objects might even drop in and out as the available devices change.
+
+In certain situations, that's the desired behaviour. But if you want to encourage consistency in allocations (for example, keeping an object in the same device wherever possible), a [*Change management behaviour*](custom-behaviours.md#change-management) can be added. This gives the producer much greater control of exactly what happens to the objects when there is some change.
+
+If no *Change management behaviour* is applied to an object, it will be able to stop and start freely and will be allocated to any suitable devices as described above. See the [*Change management behaviour*](custom-behaviours.md#change-management) documentation for more information on how this can be customised.

docs/appearance.md

@@ -0,0 +1,82 @@
+# Appearance page
+
+On the Appearance page, you can make settings to customise the appearance of your prototype application (see the [prototype application](prototype.md) documentation for more information about the different components).
+
+## Text
+
+In the top row of text fields, you can give your application a **title**, **subtitle**, and an **introduction** paragraph. The title and subtitle will be visible on every page of the prototype application. The introduction text will only be visible on the home page.
+
+In the second row, you can set labels for the **start** and **join buttons**. The defaults are *Start new session* and *Join existing session* respectively.
+
+## Accent colour
+
+The **accent colour** is used for various components of the prototype application, including buttons and the play bar. You can specify the colour with a [hex triplet](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet), or use one of the preset colours.
+
+<a name="cover-image"></a>
+## Cover image
+
+The **cover image** is shown on the prototype application home page and all playing pages. Click "Add cover image", select an image file, then click "Open".
+
+* You should use a square image, ideally at least 600 x 600 pixels. Images that aren't squares will be cropped to square.
+* Images should use the JPEG (`.jpg` or `.jpeg`) or PNG (`.png`) formats.
+
+The prototype application will use the default image if you don't add one here.
+
+!!! Tip
+
+    * The prototype application is designed to work with a square image, but will display rectangular images too.
+
+    * The width of the displayed image will be 600 pixels. Smaller images will lack resolution, and larger images will be scaled.
+
+
+When you've imported a cover image, you'll see a text box labelled *Image alt text*. Use this to add **alternative text** to the image. Alternative (or alt) text is important for accessible design; among other benefits, it enables those using screen readers to better understand the page.
+
+!!! Tip
+    Good alt text provides a concise but complete description of the image. See, for example, the [BBC mobile accessibility guidelines](https://www.bbc.co.uk/guidelines/futuremedia/accessibility/mobile/text-equivalents/alternatives-for-non-text-content) for more details.
+
+<a name="interface-options"></a>
+## Interface options
+
+There are three customisable aspects of the prototype application in the *Interface options* section.
+
+* **Display list of active audio objects.** The prototype application can display the filenames of the audio objects that are currently being played on each device. This is helpful for checking that your [behaviours](audio.md#behaviours) are acting how you expect without necessarily needing to listen to the full piece. This is turned on by default.
+
+* **Enable calibration**. The prototype application can include a calibration mode that enables the listener to adjust for a time offset between the main and aux devices. Calibration mode is accessed through the instructions page; see the [prototype application](prototype.md#calibration-mode) documentation for a description of how it works. Calibration is turned off by default.
+
+!!! Tip
+    The orchestrated audio system underlying the prototype application uses a cloud-based synchronisation server to keep devices in sync, but this can't account for delay introduced by the software and hardware on individual devices. On some devices, this can be negligible, but on others, it's large enough (~200 ms) to make orchestration unsuitable for some types of sound that require very accurate synchronisation (such as rhythmic music). The manual calibration mode can help to correct for this, potentially making orchestration suitable for more experiences.
+
+* **Show Play and Pause buttons on aux devices**. When this option is checked, the aux devices will have a play/pause button allowing them to control the session playback. By default (i.e. when this option is unchecked), playback can only be controlled from the main device.
+
+## Audio compression
+
+Audio compression can be applied to the output of aux devices. This might be useful if the main device has significantly better or louder loudspeakers than the aux devices (for example, if the aux devices are all mobile phones), and it's consequently beneficial to increase the playback volume of quiet audio that's sent to aux devices.
+
+The compressor works by reducing the level of the loud parts of the sound (those above the *threshold*) and not affecting the quiet parts. Then, the level of the whole signal is increased—so there's less dynamic range in the signal, but the quiet parts are relatively louder.
+
+The compressor has two customisable parameters.
+
+* **Compressor ratio** is the amount of level reduction applied to the audio above the *threshold* level. A ratio of 2 means that a 2 dB increase in input level produces a 1 dB increase in output level.
+
+* **Compressor threshold** is a decibel value above which the compression will start taking effect.
+
+To disable compression, set the *Compressor threshold* to 0. This is the default value.
+
+!!! Tip
+    * Audio compression is implemented by a Web Audio API [DynamicsCompressorNode](https://developer.mozilla.org/en-US/docs/Web/API/DynamicsCompressorNode).
+
+    * The compressor has auto make-up gain based on the threshold, ratio, and knee.
+
+    * The compressor uses the following settings.
+
+        * Attack time: 0.01 s.
+        * Release time: 0.25 s.
+        * Knee: 30 dB.
+
+<a name="object-fade-out"></a>
+## Object fade out
+
+This value sets the length (in seconds) of the linear fade out that is applied to an object when a change means that it is no longer allocated to a device by the [allocation algorithm](allocation-algorithm.md). By default, it is set to 0 seconds (i.e. the object will immediately stop playing).
+
+!!! Tip
+    After a change in object allocations, there can sometimes be a short delay before an object starts playing in a new device. Setting a fade out can help to mitigate the effects of this in some circumstances.

docs/audio.md

@@ -0,0 +1,94 @@
+# Audio page
+
+On the audio page, you can import audio files (prepared according to the [guidelines](preparing-audio.md)) and set up [behaviours](#behaviours) that define how each object should be allocated to devices. There are also some shortcuts to features from the [Monitoring page](monitoring.md).
+
+Each sequence has its own set of audio files and behaviours. Switch between sequences by clicking the tabs (which are labelled with your sequence names).
+
+<a name="adding-files"></a>
+## Adding and replacing audio files
+
+To **add an initial set of audio files**, just click the "Add audio files" button. Find the files you want to add, select them, then press "Open". You'll see the audio files appear as rows in a table, with various options which are explained below.
+
+You can **delete** single or multiple files by selecting the checkboxes for the files you'd like to delete, then pressing the delete button at the top right of the table.
+
+You can also **replace** the full set of audio files by clicking "Replace all audio files".
+
+!!! Tip
+    When replacing audio files, if you select fewer new files than are already loaded, then any missing files will show errors (*"No audio file matches the object number"*). You'll need to manually delete these objects. It is only possible to import full sets of files.
+
+!!! Error
+    If you have any sequences with no audio files, you will not be able to preview or export the experience. There will be an error message on the [Export page](export.md) (*"No audio files have been added"*).
+
+<a name="audio-object-table"></a>
+## The audio object table
+
+Once you've imported your files, they'll appear as rows of the audio object table. In each row, you'll see a checkbox, the filename, a [panning](#panning) setting, two [fixed behaviours](fixed-behaviours.md), and an ["Add behaviour" button](#add-behaviour). These are detailed below. Any [behaviours](#behaviours) that you've added will also be shown in the table row.
+
+<a name="panning"></a>
+## Panning
+
+The current panning value for each object is shown in the object table row.
+
+To change the panning, just click the current value, which will reveal a slider. You can either adjust the panning using the slider, or click the "L", "R", or "C" buttons for 100% left, 100% right, or centre panning respectively.
+
+The panning cannot be changed for stereo objects.
+
+!!! Tip
+    See the [Preparing audio assets](preparing-audio.md#prepare-panning) page for information on automatic panning based on the filename.
+
+!!! Info
+    Panning is implemented by a Web Audio API [StereoPannerNode](https://developer.mozilla.org/en-US/docs/Web/API/StereoPannerNode) for browsers in which this is supported, and by other Web Audio API components that mimic the behaviour where the StereoPannerNode is not supported.
+
+<a name="behaviours"></a>
+## Behaviours
+
+Behaviours determine how each object should be allocated to devices. This lets you customise the listener experience, ensuring that it is flexible and can adapt to the number of connected devices and to settings that listeners make using [controls](controls.md).
+
+There are four types of behaviour.
+
+* [**Fixed behaviours**](fixed-behaviours.md) are always included for every object. They define the device roles and number of devices that objects can be allocated to. Fixed behaviours are shown as dropdown lists in the audio object table.
+* [**Control-linked behaviours**](control-linked-behaviours.md) are linked to any [controls](controls.md) that you've set up.
+* [**Custom behaviours**](custom-behaviours.md) give you more flexibility in deciding how the objects should be allocated.
+* The [**Image and effects behaviour**](image-behaviour.md) allows you to add timed images and effects, attached to audio objects, to the experience.
+
+The four behaviour types are described in more detail in the linked documentation pages.
+
+<a name="add-behaviour"></a>
+### Add behaviour button
+
+The "Add behaviour" button is used to add behaviours to the objects. Clicking the button will reveal a dropdown list containing the behaviour options. Click the option you need to apply it to the object.
+
+* The **control-linked behaviours** (which relate to any [controls](controls.md) that you have set up) appear at the top of the list with orange dots. You can only add one instance of each control-linked behaviour to each object. See [Control-linked behaviours](control-linked-behaviours.md) for more details.
+
+* The **custom behaviours** appear after the control-linked behaviours. There are six custom behaviour types (*Preferred if*, *Allowed if*, *Prohibited if*, *Exclusive*, *Change management*, and *Mute if*), each with a different colour dot. See [Custom behaviours](custom-behaviours.md) for more details.
+
+* The ***Images and effects*** behaviour appears after the custom behaviours. See [*Images and effects* behaviour](image-behaviour.md) for more details.
+
+When you add a behaviour to an object, it will appear as a coloured box in the object's row of the audio object table.
+
+### Editing and deleting behaviours
+
+Behaviours that have editable parameters (all [control-linked behaviours](control-linked-behaviours.md), most [custom behaviours](custom-behaviours.md), and the [image and effects behaviour](image-behaviour.md)) will show an "editable" icon. Clicking on the behaviour will open its settings.
+
+All [control-linked behaviours](control-linked-behaviours.md), [custom behaviours](custom-behaviours.md), and the [image and effects behaviour](image-behaviour.md) have a delete button ("X" icon) on the right hand side (you'll be asked to confirm that you want to delete the behaviour).
+
+### Adding the same behaviour to multiple objects
+
+The same behaviour can be added to multiple objects in one go. Select all of the objects to which you want to add the behaviour (using the checkboxes on the left hand side of the object table), then click the "Add behaviour" button (either above the audio object table, or on any of the selected objects).
+
+<a name="audio-page-monitoring"></a>
+## Monitoring
+
+*Audio Orchestrator* has a monitoring system that can be used to see and hear the effect that your behaviours have on your mix. Detailed control of the monitoring system is found on the [Monitoring page](monitoring.md), but there are shortcuts to some of the features on the Audio page.
+
+* The **Connect to DAW** button will connect *Audio Orchestrator* to your digital audio workstation (DAW). The first time this option is used, a settings dialogue box will be shown. The settings can be opened again by clicking the cog icon next to the "Connect to DAW" button. See the [Monitoring page](monitoring.md#daw-connect) documentation for more details on connecting to a DAW.
+* The **Play/pause** button will control audio playback when *Audio Orchestrator* is connected to the REAPER DAW.
+* The **Rerun allocation algorithm** button causes the [allocation algorithm](allocation-algorithm.md) to be rerun without needing any of the changes that would normally cause that to happen (a device being added or dropping out, or a control value changing). This can be useful for testing different possible random allocations.
+
+!!! Tip
+    On the Audio page, you won't be able to see any effect of clicking "Rerun allocation algorithm". You will be able to see changes on the [Monitoring page](monitoring.md) as well as hearing the changes if you've connected to a DAW.
+
+* The **Monitoring** button is a shortcut to opening the Monitoring page.
+
+![Screenshot of the monitoring settings buttons on the Audio page](images/monitoring/audio-page-monitoring-buttons.png)
+*Monitoring system shortcuts from the Audio page*