Sound Engine

0x80 edited this page Nov 3, 2014 · 6 revisions

ZN Soundengine

Developed by Thijs Koerselman

The sound engine code can be found in client/js/soundengine.js. The WNU project didn't have a CommonJS or AMD module structure. The engine was developed using CommonJs modules and in order to integrate it easily this file is a compiled version together with its dependencies. The original source can easily be extracted from it since it's not minified.


The following options are used to configure the soundengine.

###pathToSoundset The path to the soundset on the filesystem. This is used by routes/sound.js to compile the configuration for the engine.

###baseUrl The base url used to prepend the filenames in the generated config. This could be a relative path, if the soundfiles are served from the same server, or an http url if the files are served by some external server. Note that CORS headers are required for the engine to be able to download the content from a different host.

###extension The file extension used for scanning the soundset filestructure. This is typically mp3. All other files are ignored.

###sceneLayersMixMode Can be 0/1. Mode 0 will keep the first scene layer playing when the mix value is set to 0. Mode 1 will fade out also the first layer.

###crossfadeSec The time used to crossfade from one scene to another when calling moveToScene(). It should correspond to the crossfade between project visualizations.

###mixBusVolume The master volume for all audio output of the engine, right before it is fed into the master bus compressor. This value is in db.


###init(config, callback) ####config A json configuration as returned by /sound/config. This data contains a list of all the scenes and their samples, together with the sound engine options. In development settings it is meant to be compiled by calling /sound/config which will read the specified soundset folder and compiles the json from its content. For more info see the 'Soundset Filestructure' section.

For production purposes use a precompiled json config.

####callback(err, progress, sceneId) The callback is called repeatedly before each of the loaded scenes and after the loading has been completed. The progress is a percentage value. When the loading is complete the progress will be 100. The sceneId of the currently loading scene is also returned. The callback is made once per scene. The previously loaded scene id could be used for enabling playback of that project when the others are still loading.

###start() / stop() Start stop the audio playback. The moveToScene call will also start the audio again.

###moveToScene(sceneId) Move focus to that scene. ####sceneId The id corresponds with the ids in the config file and correspond to the ZN project name. ####returns Info on the currently selected scene in the form of

{ "id": "scene_a", "layersMix": "0.64", "layers": { "count": 2 }, "smplr_a": { "count": 14 }, "smplr_b": { "count": 0 } }

###triggerSampler([index]) Randomly triggers a one shot sample from one of the two samplers. Samples are put in the pool and are randomly picked until the pool is empty and a new one is created. This to prevent repeating samples.

####index [optional] 0 or 1, corresponding to smplr_a and smplr_b folder in the soundset file structure.

####returns The filename of the triggered sample.

###setSceneLayersMix(value) The value should be between 0-1. All of the available layers of the current scene are spread over this range and gradually stacked by fading in. For example if you have 2 layers a value between 0-0.5 will fade in control the volume of the first layer, and 0.5-1 will control the volume of the seconds layer, while the first one keeps playing.

###setBaseLayersMix(value) Same as setSceneLayersMix but then for controlling the base layers which play continuously throughout all of the scenes.

Soundset Filestructure

Each soundset has a file structure to automatically map samples to scenes/projects. Folders in the soundset should have names that correspond to the project ids.

###__base The name __base is reserved. It is used to load special files which play underneath all of the scenes. The volume is controlled with the setBaseLayersMix API.

###Scene Folders Each scene has a specific content. All of the content is optional.

####volumes.json This optional file is used to make volume corrections to each of the files. It contains properties for settings the volumes of each of the layer files, the main output volumes for each of the samplers and the master volume of the whole scene mix.

All of the values are in db, where 0 corresponds to unity gain.

  "layers" : [-3, 0],
  "smplr_a" : -2,
  "master" : 0

###layers This folder can contain multiple files which are used for scene layers. They are stacked in alphabetical order using the API mix functions.

###smplr_a / smplr_b All of the files in these folders are added to sampler a and b. The samples are picked randomly so the alphabetical order has no influence.

###Example Soundset Structure

└── exampleset
    ├── __base
    │   ├── layers
    │   │   └── static_noisy_delay.mp3
    │   └── volumes.json
    ├── scene_a
    │   ├── layers
    │   │   ├── 1_drone_replow.mp3
    │   │   └── 2_drone_repmach.mp3
    │   ├── smplr_a
    │   │   ├── smp_tone_ring1.mp3
    │   │   ├── smp_tone_ring3.mp3
    │   │   ├── smp_tone_ring4.mp3
    │   │   ├── smp_tone_ring5.mp3
    │   │   ├── smp_tone_ring6.mp3
    │   │   ├── smp_tone_ring7.mp3
    │   │   ├── smp_tone_ring8.mp3
    │   │   └── smp_tone_ring9.mp3
    │   └── volumes.json
    └── scene_b
        ├── layers
        │   └── 1_wavey_delay.mp3
        ├── smplr_a
        │   ├── smp_tone_ring15.mp3
        │   ├── smp_tone_ring25.mp3
        │   ├── smp_tone_ring26.mp3
        │   ├── smp_tone_ring27.mp3
        │   ├── smp_tone_ring28.mp3
        │   └── smp_tone_ring29.mp3
        ├── smplr_b
        │   ├── smp_tone_ring1.mp3
        │   ├── smp_tone_ring5.mp3
        │   ├── smp_tone_ring6.mp3
        │   ├── smp_tone_ring7.mp3
        │   ├── smp_tone_ring8.mp3
        │   └── smp_tone_ring9.mp3
        └── volumes.json


A page is available to test the engine and its API as a standalone component. It is served on /sound/test.

  • [About this project](About this project)
  • [Adding a new project](Adding a new project)
  • API
  • [Colour Palette](colour palette)
  • Compositions
  • [Data Mapping](Data mapping)
  • [Handover from KS](Handover from KS)
  • Home
  • Inspiration
  • [Interim install](Interim install)
  • License
  • [Links for website](Links for website)
  • Load testing
  • Patina
  • [Project Rules](Project Rules)
  • Popularity
  • [Risk register](Risk register)
  • [S3 notes](S3 notes)
  • [Sound Engine](Sound Engine)
  • [Tech docs](Tech docs)
  • [Technical requirements](Technical requirements)
  • Testing & Monitoring
  • Website
  • [Zoon Data characteristics](Zoon Data characteristics)
  • [Zoon links resources](Zoon links resources)
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.