Extensions | Audio Extension

Audio Extension

Add and control sounds

What You Need

  • Custom HTML code snippet
  • One or more audio files (e.g. .mp3, .opus, .ogg, .wav, .aac, .mp4, .webm)
  • A server to host your audio on (e.g. s3, FTP, Dropbox, Sharefile, Box, etc)
  • A Ceros experience

We thought it would be fun, and in some cases, pretty useful, if you could integrate sounds and music into your Ceros experience. Not only does this plugin let you do that, it also allows you to control the audio clips with play/pause buttons, toggles, loops, resets, mute and several different event triggers. You can also use this plugin to integrate a live stream right into your Ceros experience. Upload the demo experience to your studio to explore a finished audio piece, or follow the steps below to set up audio controls on your own.

How we did it

The first thing we did was to devise a naming convention for SDK Tags that would allow us to expose as much functionality from the Howler.js Web Audio library as possible. We then used the Ceros SDK to track interactions with objects whose tags followed the naming convention and to trigger the appropriate audio effects.

Import Demo Experience

How to implement

Add the Custom HTML


In the Settings panel, paste the script below in the Custom HTML field:

<script id="ceros-audio-plugin" src="//labs.ceros.com/sdk-plugins/audio/main-0.9.0.js" soundTag="playsound"></script>

Choosing a file type


    Not all audio codecs have full browser support. For a complete list of which do, click here. We recommend mp3 for the best balance of small file size and high quality, however, you can use any of the following:

    • Mp3
    • Opus
    • Ogg
    • Wav
    • Aac
    • M4a
    • Mp4
    • Webm


Hosting sound files


    In order for a sound file to be played, it must be hosted on an external server. We've attached a demo sound file here if you would like something to test.

    In you have your own server that can host files (e.g. s3 or FTP), make sure that it has Cross Origin Requests (CORS) enabled. If this is not an option, it is also possible to host the files on Dropbox, a third party file hosting service.

    Steps for hosting in Dropbox

    1. Login to Dropbox
    2. Upload the mp3 file to Dropbox. Once uploaded, the file will appear in My Files
    3. There will be a "Share" buttom at the very right side of the file (on the same line). Click this button.
    4. In the popup, click "Create a link", located on the right side of the file (on the same line). Click this button. The link to your mp3 file will appear and is now copied to your clipboard. This link will be used later, so save it! (Don't worry, you can always repeat steps 3 and 4 if you lose the link).

    Note: Dropbox will disable links that exceed 20GB worth of downloads per day. For experiences that are expected to receive traffic that exceeds 1,000 visitors per day, the sound files should be hosted on a CORS enabled server that won't limit bandwidth.


Adding sounds to your experience


    To add a sound file to your experience, you must attach the audio URL to the payload section of an icon, image, or text box in the Ceros Studio.

    Steps to add an audio file:

    1. Find the object you would like to attach the sound file to. We recommend placing a sound icon outside the canvas to make it easy to locate.
    2. With the object selected, open the SDK panel and, under current selection, add the tag playsound
    3. Add an additional tag of name:unique-name and substitute "unique-name" with a name of your choosing.
    4. Paste the URL to the sound file in the payload section. Ensure there are no extra spaces before or after the URL.


Adding click events to trigger a sound


    Sound events are the drivers of the extension, and are what give users control over the sounds in an experience. In order for users to interact with your sounds, events must be added to a triggering object.

    Steps to add a click event:

    1. Create or find the object you would like to add a click event to. We recommend using Hotspots to make it easier to locate in your layers panel.
    2. With the Hotspot or object selected, open the SDK panel and in the current selection section, add a sound-click tag. This tells the experience to listen for click events on this object.
    3. Add an addition tag for the event you would like to fire when the Hotspot or object is clicked, such as event:play. We've listed all of the possible events below.
    4. Finally, identify the name of the sound file you would like to trigger using the target:unique-name tag created in a previous step.

    Note: To let your user know they can interact with the hotspot, ensure "Activate cursor on hover" is checked.

    Events:

    TAG DESCRIPTION
    event:loop Plays the sound(s) and sets it to loop indefinitely.
    event:looptoggle Plays the sound(s) and sets it to loop indefinitely. Subsequent clicks will play/pause the sound.
    event:mute Toggles the volume on a sound(s).
    event:play Plays the sound(s).
    event:pause Pauses the sound(s).
    event:reset Resets and plays the sound(s).
    event:toggle Plays the sound(s). Subsequent clicks will pause/play the sound(s).
    event:fastforward Fast forwards the sound by 1 second, whether it's playing or paused. Does not play/unpause sounds.
    event:rewind Rewinds the sound by 1 second, whether it's playing or paused. Does not play/unpause sounds.
    event:fadein Fades the volume from 0 to the set volume (default: 2 second).
    event:fadeout Fades the volume from the set volume to 0 (default: 1 second)

    Global events: all events can be applied globally to every sound in the experience. In order to do so, change the event in the event tag to eventall


Optional: adding background sounds to your experience


    Background sounds will play as soon as the sound file has finished loading. Ensure your Ceros object, with the sound payload URL attached to it, is on the first page of your experience otherwise it will not play automatically.

    Two options for background sound configuration:

    1. Play: the sound file is played once on load. Tag = playsound and background:play.
    2. Loop: the sound file is played upon load, and set to loop. Tag = playsound and background:loop.


Optional: adding streams to your experience


    1. Follow the above steps for adding a typical audio file, making sure to add the URL of the source of the stream to the payload.
    2. Add the tag stream:true to the tags of the object.
    3. Make sure an event is attached, event:toggle is recommended for streams.

Sound settings


If you would like to really fine tune your sound and/or event settings, much can be done using tags alone. This section will tell you which settings you can change through tags and what those changes do.

WARNING: changing these may cause unexpected behavior.

Settings can be changed using the format: setting:value.

SETTING CHANGE DEFAULT
start:3000 Default = 0. To change the start time of your sound you may enter "start:your-start-time", i.e. "start:2000". The second part must be a number, and in milliseconds NOT seconds.
fastforwardtime:3500 Default = 1000
rewindtime:2000 Default = 1000
volume:83 Default = 100
rate:200 Pauses the sound(s).
event:reset Default = 100