sound/SoundPlayer.js

/**
 * Sound player interface
 *
 * @author Alain Pitiot
 * @version 2022.2.3
 * @copyright (c) 2017-2020 Ilixa Ltd. (http://ilixa.com) (c) 2020-2022 Open Science Tools Ltd. (https://opensciencetools.org)
 * @license Distributed under the terms of the MIT License
 */

import { PsychObject } from "../util/PsychObject.js";

/**
 * <p>SoundPlayer is an interface for the sound players, who are responsible for actually playing the sounds, i.e. the tracks or the tones.</p>
 *
 * @interface
 * @extends PsychObject
 */
export class SoundPlayer extends PsychObject
{
	/**
	 * @memberOf module:sound
	 * @param {module:core.PsychoJS} psychoJS - the PsychoJS instance
	 */
	constructor(psychoJS)
	{
		super(psychoJS);
	}

	/**
	 * Determine whether this player can play the given sound.
	 *
	 * @abstract
	 * @param {module:sound.Sound} - the sound
	 * @return {Object|undefined} an instance of the SoundPlayer that can play the sound, or undefined if none could be found
	 */
	static accept(sound)
	{
		throw {
			origin: "SoundPlayer.accept",
			context: "when evaluating whether this player can play a given sound",
			error: "this method is abstract and should not be called.",
		};
	}

	/**
	 * Start playing the sound.
	 *
	 * @abstract
	 * @param {number} [loops] - how many times to repeat the sound after it has played once. If loops == -1, the sound will repeat indefinitely until stopped.
	 */
	play(loops)
	{
		throw {
			origin: "SoundPlayer.play",
			context: "when starting the playback of a sound",
			error: "this method is abstract and should not be called.",
		};
	}

	/**
	 * Stop playing the sound immediately.
	 *
	 * @abstract
	 */
	stop()
	{
		throw {
			origin: "SoundPlayer.stop",
			context: "when stopping the playback of a sound",
			error: "this method is abstract and should not be called.",
		};
	}

	/**
	 * Get the duration of the sound, in seconds.
	 *
	 * @abstract
	 */
	getDuration()
	{
		throw {
			origin: "SoundPlayer.getDuration",
			context: "when getting the duration of the sound",
			error: "this method is abstract and should not be called.",
		};
	}

	/**
	 * Set the duration of the sound, in seconds.
	 *
	 * @abstract
	 */
	setDuration(duration_s)
	{
		throw {
			origin: "SoundPlayer.setDuration",
			context: "when setting the duration of the sound",
			error: "this method is abstract and should not be called.",
		};
	}

	/**
	 * Set the number of loops.
	 *
	 * @abstract
	 * @param {number} loops - how many times to repeat the sound after it has played once. If loops == -1, the sound will repeat indefinitely until stopped.
	 */
	setLoops(loops)
	{
		throw {
			origin: "SoundPlayer.setLoops",
			context: "when setting the number of loops",
			error: "this method is abstract and should not be called.",
		};
	}

	/**
	 * Set the volume of the tone.
	 *
	 * @abstract
	 * @param {Integer} volume - the volume of the tone
	 * @param {boolean} [mute= false] - whether or not to mute the tone
	 */
	setVolume(volume, mute = false)
	{
		throw {
			origin: "SoundPlayer.setVolume",
			context: "when setting the volume of the sound",
			error: "this method is abstract and should not be called.",
		};
	}
}