About

Offline-capable audio tour for museums / heritage locations.

We needed to deliver offline-capable audio tours for 100+ venues in rural Cornwall so just built our own library. It may be useful for your project as it handles the audio controls, and extras such as caching and touch gestures so you can focus on the content.

This is the audio tour software we are developing for https://celticquietplaces.com/ (see a live example).

Features

Whole page experience - full page portrait images (on mobiles and tablets) with audio controls. The max page width is set at 768px so it appears full width on mobiles and most tablets, but still looks OK on desktops.

JSON-Driven Content – Tours defined in a single .json file. Support for local media or remote URLs.

Additional detail at each stop - have an interesting object or extra detail at one of the stops? Add it to the tour within that stop.

Native Web Components – Works in React, Vue, Svelte, or a plain HTML file.

Storage interface – Supports the Cache API using a Service Worker. Your users can download tours and then explore with zero signal. The built-in default is for browsers so works great for websites but NOT for within apps such those using capacitor. For capacitor (like us) you need to inject a new storage function (see example below).

Lightweight – Tiny bundle footprint.

Native-Feel Interactions – Includes smooth touch gestures, swipe navigation, and high-performance SVG animations for a premium app feel.

NPM Package: Available as an npm module. See examples audio-tour-player-example, audio-tour-player-capacitor-example

Getting started

Installation

Via npm

npm install audio-tour-player

Then, import it into your main JavaScript or TypeScript file:

import 'audio-tour-player';

Add the Player to your HTML

Use the custom element to display the tour. Pass your specific tour URL (can be remote).

<audio-tour-player src="./tours/my-tour.json"></audio-tour-player>

You can optionally define other features:

offline-capable - true (default) / false

cache-name - any string

<audio-tour-player 
    src="./tours/my-tour.json"
    offline-capable="true"
    cache-name="cqp1"
    >
</audio-tour-player>

The default cache name is "audio-tour-player-cache-v1".

The default storage interface is for a browser environment and will use a service worker (see Offline support below) and the Cache API for offline storage.

Audio formats

MP3, OGG, WAV, M4A

Note, because of the way browsers handle audio media, the filename must end with .mp3, .ogg, .wav, or .m4a for it to be playable. It took us ages to work this out! Images can be named anything but playing audio files are fussy. If you want to serve the media files dynamically - as we do - then end your dynamic URL with something that looks like a filename. e.g. mymediaserver.php?id=123&name=file.mp3

Create your my-tour.json

The tour is controlled by a simple JSON file. An array of stops are shown in the order they appear in the file. Each one should have:

• title (this also appears on the button for this stop so keep it brief)
• desc (a one or two sentence description of where and what the stop is)
• image (the image shown behind the audio controls - use a portrait picture as we assume most people will view on mobile)
• audio (an audio file)

The very first 'stop' is the main menu screen so choose an image to represent the whole tour and text that invites visitors to start the tour.

Nested details. Audio tour (after version 1.1) handles details within each stop. The structure for detail is just like the other stops but posted as a "stops" array within the stop. See example below.

If you are going to work cross-origin (storing media and your json file is on different domain) then remember to set CORS on that server. Each "stop" supports a title, description, background image, and an audio track.

{
  "stops": [
    {
      "title": "Welcome to the Tour",
      "desc": "This is the main menu. From here you can download the tour for offline use or select a specific stop. Press start or choose a stop",
      "image": "assets/intro-bg.jpg"
    },
    {
      "title": "The Ancient Well",
      "desc": "You are standing before a site of significant local history...",
      "image": "assets/stop1.jpg",
      "audio": "assets/audio/stop1.mp3"
    },
    {
      "title": "The Interesting wall",
      "desc": "You are standing before a site of significant local history...",
      "image": "assets/stop2.jpg",
      "audio": "assets/audio/stop2.mp3"
      "stops": [
           {
            "title": "Additional detail",
            "desc": "This is an example nested detail stop. More information on this interesting wall",
            "image": "assets/stop2-detail1.jpg",
            "audio": "assets/audio/stop2-detail1.mp3"
      }
      ]
    }
  ]
}

Offline Support

To enable offline caching, ensure the service worker sw.js is in the root of your project (or in your public/ folder depending on your build tool). You can copy the sw.js file from node_modules/audio-tour-player/sw.js

The default offline support with a service worker only functions within a client's browser. They visit the audio tour and click the 'Download for offline use' button and then the files are available (as long as the service worker keeps running). Service workers may stop running if not used.

Injecting a new storage

For capacitor you won't need to worry about the service worker as it won't work inside a native app. However, you can inject new functionality for storage after initiating the player. We use our own functions based on @capacitor/filesytem

See audio-tour-player-capacitor-example for a working example.

e.g.

import 'audio-tour-player'
import { capacitorStorageDelegate, capacitorUrlRewriter } from './capacitor-bridge.js';


// Wait for the DOM to be ready and initiate the player
document.addEventListener('DOMContentLoaded', () => {
  const player = document.querySelector('audio-tour-player');

  if (player.attributes.src) {
    console.log('Audio Player present and src attribute is set.');
  }

  // Inject the Capacitor logic
  player.storage = capacitorStorageDelegate;
  player.urlRewriter = capacitorUrlRewriter;
});

License

• v1.1.0 (and later): Non-commercial License (see LICENSE).
• v1.0.x (and earlier): MIT License

Acknowledgements

Inspired by the full page background image and simple HTML5 audio of https://github.com/NP102456/audio-tour