@locativemedia/locative-audio-service

The sole purpose of this library is to provide an API that supports building auditory locative media experiences using 3d spatial audio without having to face the implementation challenges. This library has no UI components and is highly configurable. It takes into account and mitigates limitations and cross browser compatibility challenges. In addition it handles CPU-challenges and throttles certain API usages to better accommodate the limited resources available on a mobile device. Finally the library can play multiple spatial audio sources at the same time taking into account the geolocation and device orientation of the listener.

Overview

This library provides a service that makes it easy to build locative media experiences in the browser.

Installation

Installing the library is as easy as npm installing it:

npm install @locativemedia/locative-audio-service

Usage

Start by constructing the LocativeAudioService.

const locativeAudioService = new LocativeAudioService(config)

The config given to the constructor can include the following properties:

export interface ILocativeAudioServiceConfig {
	maxFindDistanceInM: number;

	// If given, environmental sounds will play
	// based on the geographical location of the target
	environmentAudio?: {
		// A token that is compatible with Google's Maps API.
		googleAuthToken: string;

		// An array of Google Maps metadata tags to play.
		files: {
			kind: MapsMetadataKind;
			path: string;
		}[];
		// A number between 0 and 1, indicating the amplitude. May be undefined
		volume?: number;
	};

	// If given, an ambient sound will play at all times during a session,
	// unaffected by any change to geolocation data.
	ambientAudio?: {
		path: string;
		volume?: number;
	};

	// An empty sound to place when the library is initialized.
	// This is done in order to conquer the AudioContext
	emptyAudio: {
		path: string;
	};

	// If given, audio won't abruptly start and stop,
	// but rather fade in/out depending on the given settings
	fadeOptions?: {
		fade: boolean;
		duration: number;
	};
}

Now, the library has to be initialized in direct response to a user gesture due to auto-play policies in modern browsers:

// Invoke 'initialize()' as direct response to a
// user gesture such as a 'click' event.
locativeAudioService.initialize();

To become familiar with some of the things this library can do, a few examples will be presented.

Example 1

An augmented environment represents the distance and angle between two entities such as a user and his or her target. We can visualize this by observing all changes to the augmented environment and rendering them to the DOM:

const element = document.querySelector("#something");
// Visualize the current angle difference by rotating some visual element by as many degrees
locativeAudioService.onAugmentedEnvironmentChanged (environment => element.style.transform = "rotate(" + environment.angleDiff + "deg)");

API reference

• dispose (): Promise<void>: Will clear all listeners for sensor data and reset the state.
• setTarget (position: IPosition|null): void: Will use the given position data to update the augmented environment, including audio panning and amplitude.
• startSession (): void: Will start audio playback. A target must be given before invoking this method.
• stopSession (): void: Will stop audio playback.
• onAugmentedEnvironmentChanged (subscriber: AugmentedEnvironmentSubscriber): ISubscription: The given callback will be invoked when the augmented environment changes
• onDeviceOrientationChanged (subscriber: DeviceOrientationSubscriber): ISubscription: The given callback will be invoked when the orientation of the device changes
• onCalibratedChanged (subscriber: CalibrationSubscriber): ISubscription: The given callback will be invoked when the calibration status of the device changes
• onStatusChanged (subscriber: StatusSubscriber): ISubscription: The given callback will be invoked when the status of the LocativeAudioService changes.
• onGeolocationChanged (subscriber: GeolocationSubscriber): ISubscription: The given callback will be invoked when the geolocation of the device changes.
• onSessionStarted (subscriber: SessionSubscriber): ISubscription: The given callback will be invoked when the a new session starts.
• onSessionStopped (subscriber: SessionSubscriber): ISubscription: The given callback will be invoked when an on-going session stops.