This project is a user interface template built with the @bbc/audio-orchestration-core library library. It is a starting point for developing additional features.
This template is also used by Audio Orchestrator to preview and export a prototype application. The documentation explains how to use a custom build of this template.
Audio Orchestrator is used to combine this template with encoded audio and metadata files.
Make sure you have installed and built the dependencies by running npm install and npm run build -ws in the repository root (not this template folder).
Run the development server:
npm run devThe page will be available at http://localhost:8080 and automatically refresh on most changes to the source code. Note that you will need to restart the development server if you have changed and rebuilt e.g. the core library.
The template can be configured to use different synchronisation solutions. Edit the configuration in index.html to choose and customise one of the options (and reload the page to apply the changes).
- PeerJS: by default, a public PeerJS server is used. The integration is more experimental than the Cloud-Sync option, but does not require running your own server. The peerJS synchronisation adapter processes requests from all connected devices in the session within the browser on the main device.
- Cloud-Sync: this is the traditional option and still the default option in Audio Orchestrator. You will need to install the server software from the Cloud Sync repository and configure the server address in
index.html.
Audio sequences are added by copying their metadata and audio files to the audio/ directory (which is copied to dist/audio as part of the build process) and registering them in the configuration object in src/index.html. Both of those steps are usually done using Audio Orchestrator, but the example files included with this repository indicate the expected layout and syntax.
This section introduces the key components of the template application, intended for developers looking to customise it or add features beyond those that can be configured in Audio Orchestrator.
The following libraries are used in the template, and their documentation may be useful when looking to make changes.
When you build (npm run build) the template, a dist/ folder including all assets needed to publish the experience, including JavaScript and CSS bundles and a copy of all audio files and images, is created.
The template is a React application instantiated in the <script> tag in index.html, which calls the initOrchestrationTemplate function defined in index.js with the target DOM element and the experience configuration object. Available configuration keys are defined in config.js.
The React app's root component is in App.jsx, this imports all the available pages. Each page is a React component (in pages/).
Application state is managed using Redux and Redux-Saga. The sagas (sagas.js) define the flow through different application states (such as navigating between pages, waiting for a connection, validating user input). The reducer (template/reducer.js) receives actions dispatched by React components or the sagas to update the application state.
The orchestration client instance is created in template/orchestration.js, where we also register event handlers that can update the application state by dispatching actions. Note that there is a similar file, (template/calibrationOrchestration.js, which manages a second orchestration session for use with calibration mode.
All user interface components are defined with (at least) a .jsx (React component) file and an .scss (style) file in components/. For the most recently written components we prefer using React Redux hooks (useSelector) in the component itself to access the state; however some components still use mapStateToProps functions defined in a Connected<Component>.jsx instead. When adding a new component, take care to also import the .scss file in index.js.
@bbc/audio-orchestration-template Copyright (C) 2022 BBC R&D
See the LICENSE file for terms applicable to this package, and the top-level Readme file for further information.