Source: extern/sfx.js

  1. import register from "../util/register.js";
  3. import m_obj_util_fact from "../intern/obj_util.js";
  4. import m_scs_fact from "../intern/scenes.js";
  5. import m_sfx_fact from "../intern/sfx.js";
  6. import m_print_fact from "../intern/print.js";
  8. /** 
  9.  * Sound effects API.
  10.  * Uses Web Audio API for sound effects and HTML5 audio for background music.
  11.  * @see https://www.blend4web.com/doc/en/audio.html
  12.  * @module sfx
  13.  * @cc_externs AudioContext webkitAudioContext MediaElementAudioSourceNode
  14.  */
  15. function SFX(ns, exports) {
  17. var m_obj_util = m_obj_util_fact(ns);
  18. var m_scs      = m_scs_fact(ns);
  19. var m_sfx      = m_sfx_fact(ns);
  20. var m_print    = m_print_fact(ns);
  22. /**
  23.  * Play sound through the speaker.
  24.  * @method module:sfx.play
  25.  * @param {Object3D} obj Object 3D
  26.  * @param {number} [when=0] Delay after exec in seconds
  27.  * @param {number} [duration=0] Duration of the speaker's playback cycle (in
  28.  * seconds). duration=0 - assign default value according to sound playback length.
  29.  */
  30. exports.play = function(obj, when, duration) {
  31.     when = when || 0;
  32.     duration = duration || 0;
  33.     m_sfx.play(obj, when, duration);
  34. }
  35. /**
  36.  * Play sound through the speaker using the default delay and duration params.
  37.  * @method module:sfx.play_def
  38.  * @param {Object3D} obj Object 3D
  39.  */
  40. exports.play_def = function(obj) {
  41.     m_sfx.play_def(obj);
  42. }
  44. /**
  45.  * Check if sound is played through the speaker now.
  46.  * @method module:sfx.is_playing
  47.  * @param {Object3D} obj Object 3D
  48.  * @returns {boolean} Playing state
  49.  */
  50. exports.is_playing = function(obj) {
  51.     return m_sfx.is_playing(obj);
  52. }
  54. /**
  55.  * Stop the speaker.
  56.  * @method module:sfx.stop
  57.  * @param {Object3D} obj Object 3D
  58.  */
  59. exports.stop = function(obj) {
  60.     m_sfx.stop(obj);
  61. }
  64. /**
  65.  * Pause the speaker.
  66.  * @method module:sfx.pause
  67.  * @param {Object3D} obj Object 3D
  68.  */
  69. exports.pause = function(obj) {
  70.     m_sfx.speaker_pause(obj);
  71. }
  73. /**
  74.  * Resume the paused speaker.
  75.  * @method module:sfx.resume
  76.  * @param {Object3D} obj Object 3D
  77.  */
  78. exports.resume = function(obj) {
  79.     m_sfx.speaker_resume(obj);
  80. }
  82. /**
  83.  * Stop the speaker's looping playback.
  84.  * @method module:sfx.loop_stop
  85.  * @param {Object3D} obj Speaker object
  86.  * @param {number} [when=0] Delay after exec in seconds
  87.  * @param {boolean} [wait=false] Wait loop until currently played cycle is
  88.  * finished
  89.  */
  90. exports.loop_stop = function(obj, when, wait) {
  91.     when = when || 0;
  92.     wait = wait || false;
  93.     m_sfx.loop_stop(obj, when, wait);
  94. }
  97. /**
  98.  * Change the speaker playback rate value.
  99.  * @method module:sfx.playrate
  100.  * @param {Object3D} obj Object 3D
  101.  * @param {number} playrate Playback rate (1.0 - normal speed).
  102.  */
  103. exports.playrate = function(obj, playrate) {
  104.     m_sfx.playrate(obj, playrate);
  105. }
  107. /**
  108.  * Get the speaker playback rate value.
  109.  * @method module:sfx.playrate
  110.  * @param {Object3D} obj Object 3D
  111.  * @returns {number} Playback rate
  112.  */
  113. exports.get_playrate = function(obj) {
  114.     return m_sfx.get_playrate(obj);
  115. }
  117. /**
  118.  * Set cyclic flag.
  119.  * @method module:sfx.cyclic
  120.  * @param {Object3D} obj Speaker object.
  121.  * @param {boolean} cyclic New cyclic flag value.
  122.  */
  123. exports.cyclic = function(obj, cyclic) {
  124.     m_sfx.cyclic(obj, cyclic);
  125. }
  127. /**
  128.  * Check if the cyclic flag is set.
  129.  * @method module:sfx.is_cyclic
  130.  * @param {Object3D} obj Speaker object.
  131.  * @returns {boolean} Cyclic flag value.
  132.  */
  133. exports.is_cyclic = function(obj) {
  134.     return m_sfx.is_cyclic(obj);
  135. }
  137. /**
  138.  * Reset the listener speed.
  139.  * Use before rapid listener movements to neutralize undesirable doppler effect.
  140.  * @method module:sfx.listener_reset_speed
  141.  * @param {number} speed The listener new speed
  142.  * @param {?Float32Array} [dir=null] The listener new direction
  143.  * @deprecated Use {@link module:sfx.listener_stride|sfx.listener_stride} instead
  144.  */
  145. exports.listener_reset_speed = function(speed, dir) {
  146.     m_sfx.listener_stride();
  147. }
  149. /**
  150.  * Make a listener stride.
  151.  * Use before quick listener movements to neutralize undesirable doppler effect.
  152.  * @method module:sfx.listener_stride
  153.  */
  154. exports.listener_stride = function() {
  155.     m_sfx.listener_stride();
  156. }
  158. /**
  159.  * Reset the speaker speed.
  160.  * It's necessary to nullify speed before the speaker has moved quickly in order
  161.  * to neutralize the undesirable doppler effect.
  162.  * @method module:sfx.speaker_reset_speed
  163.  * @param {Object3D} obj Speaker object.
  164.  * @param {number} speed The speaker's new speed
  165.  * @param {?Float32Array} [dir=null] The speaker's new direction
  166.  * @deprecated Use {@link module:sfx.speaker_stride|sfx.speaker_stride} instead
  167.  */
  168. exports.speaker_reset_speed = function(obj, speed, dir) {
  169.     m_sfx.speaker_stride(obj);
  170. }
  172. /**
  173.  * Make a speaker stride.
  174.  * Use before rapid speaker movements to neutralize undesirable doppler effect.
  175.  * @method module:sfx.speaker_reset_speed
  176.  * @param {Object3D} obj Speaker object.
  177.  */
  178. exports.speaker_stride = function(obj) {
  179.     m_sfx.speaker_stride(obj);
  180. }
  182. /**
  183.  * Get volume level.
  184.  * @method module:sfx.get_volume
  185.  * @param {?Object3D} obj Object 3D or null for MASTER volume
  186.  * @returns {number} Volume (0..1)
  187.  */
  188. exports.get_volume = function(obj) {
  189.     if (obj && typeof obj === "object")
  190.         return m_sfx.get_volume(obj);
  191.     else
  192.         return m_sfx.get_master_volume();
  193. }
  194. /**
  195.  * Set volume level.
  196.  * @method module:sfx.set_volume
  197.  * @param {?Object3D} obj Object 3D or null for MASTER volume
  198.  * @param {number} volume Volume (0..1)
  199.  */
  200. exports.set_volume = function(obj, volume) {
  201.     if (obj && typeof obj === "object")
  202.         m_sfx.set_volume(obj, volume);
  203.     else
  204.         m_sfx.set_master_volume(volume);
  205. }
  207. /**
  208.  * Mute/unmute.
  209.  * @method module:sfx.mute
  210.  * @param {?Object3D} obj Speaker object or null to mute the whole scene.
  211.  * @param {boolean} muted New state
  212.  */
  213. exports.mute = function(obj, muted) {
  214.     if (obj && typeof obj === "object")
  215.         m_sfx.mute(obj, muted);
  216.     else
  217.         m_sfx.mute_master(muted);
  218. }
  220. /**
  221.  * Check if the speaker is muted.
  222.  * @method module:sfx.is_muted
  223.  * @param {?Object3D} obj Speaker object or null for the whole scene.
  224.  * @returns {boolean} Muted state.
  225.  */
  226. exports.is_muted = function(obj) {
  227.     if (obj && typeof obj === "object")
  228.         return m_sfx.is_muted(obj);
  229.     else
  230.         return m_sfx.is_master_muted();
  231. }
  233. /**
  234.  * Get the speaker objects which are used by the module.
  235.  * @returns {Array} Speaker object array
  236.  */
  237. exports.get_speaker_objects = function() {
  238.     return m_sfx.get_speaker_objects().slice(0);
  239. }
  241. /**
  242.  * Check if there are some active speakers in use or not.
  243.  * @method module:sfx.check_active_speakers
  244.  * @returns {boolean} Check result
  245.  */
  246. exports.check_active_speakers = m_sfx.check_active_speakers;
  248. /**
  249.  * Set compressor params.
  250.  * @method module:sfx.set_compressor_params
  251.  * @param {CompressorParams} params Params object
  252.  * @cc_externs threshold knee ratio attack release
  253.  */
  254. exports.set_compressor_params = function(params) {
  255.     m_sfx.set_compressor_params(m_scs.get_active(), params);
  256. }
  257. /**
  258.  * Get compressor params.
  259.  * @method module:sfx.get_compressor_params
  260.  * @returns {CompressorParams} Params object
  261.  */
  262. exports.get_compressor_params = function() {
  263.     return m_sfx.get_compressor_params(m_scs.get_active());
  264. }
  266. /**
  267.  * Duck (reduce the volume).
  268.  * works independently from the volume API and the volume randomization
  269.  * @method module:sfx.duck
  270.  * @param {?Object3D} obj Object 3D or null for MASTER
  271.  * @param {number} value Duck amount.
  272.  * @param {number} time Time to change volume.
  273.  */
  274. exports.duck = function(obj, value, time) {
  275.     if (obj && typeof obj === "object")
  276.         m_sfx.duck(obj, value, time);
  277.     else
  278.         m_sfx.duck_master(value, time);
  279. }
  281. /**
  282.  * Unduck (restore the volume).
  283.  * @method module:sfx.unduck
  284.  * @param {?Object3D} obj Object 3D or null for MASTER
  285.  */
  286. exports.unduck = function(obj) {
  287.     if (obj && typeof obj === "object")
  288.         m_sfx.unduck(obj);
  289.     else
  290.         m_sfx.unduck_master();
  291. }
  293. /**
  294.  * Apply the new playlist from the given set of speakers.
  295.  * The new playlist starts playing immediately.
  296.  * @method module:sfx.apply_playlist
  297.  * @param {Object3D[]} objs Array of objects.
  298.  * @param {number} delay Number of seconds between tracks
  299.  * @param {boolean} random Randomize playback sequence
  300.  */
  301. exports.apply_playlist = m_sfx.apply_playlist;
  302. /**
  303.  * Stop playback and clear the playlist.
  304.  * @method module:sfx.clear_playlist
  305.  */
  306. exports.clear_playlist = m_sfx.clear_playlist;
  308. /**
  309.  * Detect supported audio container.
  310.  * Containers have same meaning as file extension here, for each one possible
  311.  * fallback exists:
  312.  * <ul>
  313.  * <li>ogg -> mp4
  314.  * <li>mp3 -> ogg
  315.  * <li>mp4 -> ogg
  316.  * </ul>
  317.  * @method module:sfx.detect_audio_container
  318.  * @param {string} [hint="ogg"] Required container
  319.  * @returns {string} Supported container or ""
  320.  */
  321. exports.detect_audio_container = m_sfx.detect_audio_container;
  322. /**
  323.  * Detect supported video container.
  324.  * Containers have same meaning as file extension here, for each one possible
  325.  * fallback exists:
  326.  * <ul>
  327.  * <li>ogv -> m4v
  328.  * <li>m4v -> webm
  329.  * <li>webm -> m4v
  330.  * </ul>
  331.  * @method module:sfx.detect_video_container
  332.  * @param {string} [hint="webm"] Required container
  333.  * @returns {string} Supported container or ""
  334.  */
  335. exports.detect_video_container = m_sfx.detect_video_container;
  336. /**
  337.  * Set positional params.
  338.  * @method module:sfx.set_positional_params
  339.  * @param {Object3D} obj Object 3D
  340.  * @param {PositionalParams} params Params object
  341.  * @cc_externs dist_ref dist_max attenuation
  342.  */
  343. exports.set_positional_params = m_sfx.set_positional_params;
  344. /**
  345.  * Get positional params.
  346.  * @method module:sfx.get_positional_params
  347.  * @param {Object3D} obj Object 3D
  348.  * @returns {PositionalParams} Params object
  349.  */
  350. exports.get_positional_params = m_sfx.get_positional_params;
  352. /**
  353.  * Set filter params.
  354.  * @method module:sfx.set_filter_params
  355.  * @param {Object3D} obj Object 3D
  356.  * @param {FilterParams} params Params object
  357.  * @cc_externs freq Q gain
  358.  */
  359. exports.set_filter_params = m_sfx.set_filter_params;
  360. /**
  361.  * Get filter params.
  362.  * @method module:sfx.get_filter_params
  363.  * @param {Object3D} obj Object 3D
  364.  * @returns {FilterParams} Params object
  365.  */
  366. exports.get_filter_params = m_sfx.get_filter_params;
  368. /**
  369.  * Get filter frequency response.
  370.  * @method module:sfx.get_filter_freq_response
  371.  * @param {Object3D} obj Object 3D
  372.  * @param {Float32Array} freq_arr Input array with frequencies.
  373.  * @param {Float32Array} mag_arr Output array with filter response magnitudes.
  374.  * @param {Float32Array} phase_arr Output array with filter response phases.
  375.  */
  376. exports.get_filter_freq_response = m_sfx.get_filter_freq_response;
  378. /**
  379.  * Get duration of the speaker's playback cycle.
  380.  * Zero duration means looped or non-ready speaker
  381.  * @method module:sfx.get_duration
  382.  * @param {?Object3D} obj Speaker object.
  383.  * @returns {number} Duration
  384.  */
  385. exports.get_duration = function(obj) {
  386.     if (!obj || !m_obj_util.is_speaker(obj)) {
  387.         m_print.error("Object \"" + (obj ? obj.name : undefined) +
  388.                       "\" is not a valid speaker");
  389.         return 0;
  390.     }
  391.     return m_sfx.get_duration(obj);
  392. }
  394. }
  396. var sfx_factory = register("sfx", SFX);
  398. export default sfx_factory;