1 /******************************************************************************* 2 * Copyright 2011 See AUTHORS file. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 ******************************************************************************/ 16 17 package com.badlogic.gdx.audio; 18 19 import com.badlogic.gdx.Audio; 20 import com.badlogic.gdx.files.FileHandle; 21 import com.badlogic.gdx.utils.Disposable; 22 23 /** <p> 24 * A Sound is a short audio clip that can be played numerous times in parallel. It's completely loaded into memory so only load 25 * small audio files. Call the {@link #dispose()} method when you're done using the Sound. 26 * </p> 27 * 28 * <p> 29 * Sound instances are created via a call to {@link Audio#newSound(FileHandle)}. 30 * </p> 31 * 32 * <p> 33 * Calling the {@link #play()} or {@link #play(float)} method will return a long which is an id to that instance of the sound. You 34 * can use this id to modify the playback of that sound instance. 35 * </p> 36 * 37 * <p> 38 * <b>Note</b>: any values provided will not be clamped, it is the developer's responsibility to do so 39 * </p> 40 * 41 * @author badlogicgames@gmail.com */ 42 public interface Sound extends Disposable { 43 /** Plays the sound. If the sound is already playing, it will be played again, concurrently. 44 * @return the id of the sound instance if successful, or -1 on failure. */ play()45 public long play (); 46 47 /** Plays the sound. If the sound is already playing, it will be played again, concurrently. 48 * @param volume the volume in the range [0,1] 49 * @return the id of the sound instance if successful, or -1 on failure. */ play(float volume)50 public long play (float volume); 51 52 /** Plays the sound. If the sound is already playing, it will be played again, concurrently. 53 * @param volume the volume in the range [0,1] 54 * @param pitch the pitch multiplier, 1 == default, >1 == faster, <1 == slower, the value has to be between 0.5 and 2.0 55 * @param pan panning in the range -1 (full left) to 1 (full right). 0 is center position. 56 * @return the id of the sound instance if successful, or -1 on failure. */ play(float volume, float pitch, float pan)57 public long play (float volume, float pitch, float pan); 58 59 /** Plays the sound, looping. If the sound is already playing, it will be played again, concurrently. 60 * @return the id of the sound instance if successful, or -1 on failure. */ loop()61 public long loop (); 62 63 /** Plays the sound, looping. If the sound is already playing, it will be played again, concurrently. You need to stop the sound 64 * via a call to {@link #stop(long)} using the returned id. 65 * @param volume the volume in the range [0, 1] 66 * @return the id of the sound instance if successful, or -1 on failure. */ loop(float volume)67 public long loop (float volume); 68 69 /** Plays the sound, looping. If the sound is already playing, it will be played again, concurrently. You need to stop the sound 70 * via a call to {@link #stop(long)} using the returned id. 71 * @param volume the volume in the range [0,1] 72 * @param pitch the pitch multiplier, 1 == default, >1 == faster, <1 == slower, the value has to be between 0.5 and 2.0 73 * @param pan panning in the range -1 (full left) to 1 (full right). 0 is center position. 74 * @return the id of the sound instance if successful, or -1 on failure. */ loop(float volume, float pitch, float pan)75 public long loop (float volume, float pitch, float pan); 76 77 /** Stops playing all instances of this sound. */ stop()78 public void stop (); 79 80 /** Pauses all instances of this sound. */ pause()81 public void pause (); 82 83 /** Resumes all paused instances of this sound. */ resume()84 public void resume (); 85 86 /** Releases all the resources. */ dispose()87 public void dispose (); 88 89 /** Stops the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If the sound is no longer 90 * playing, this has no effect. 91 * @param soundId the sound id */ stop(long soundId)92 public void stop (long soundId); 93 94 /** Pauses the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If the sound is no 95 * longer playing, this has no effect. 96 * @param soundId the sound id */ pause(long soundId)97 public void pause (long soundId); 98 99 /** Resumes the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If the sound is not 100 * paused, this has no effect. 101 * @param soundId the sound id */ resume(long soundId)102 public void resume (long soundId); 103 104 /** Sets the sound instance with the given id to be looping. If the sound is no longer playing this has no effect.s 105 * @param soundId the sound id 106 * @param looping whether to loop or not. */ setLooping(long soundId, boolean looping)107 public void setLooping (long soundId, boolean looping); 108 109 /** Changes the pitch multiplier of the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. 110 * If the sound is no longer playing, this has no effect. 111 * @param soundId the sound id 112 * @param pitch the pitch multiplier, 1 == default, >1 == faster, <1 == slower, the value has to be between 0.5 and 2.0 */ setPitch(long soundId, float pitch)113 public void setPitch (long soundId, float pitch); 114 115 /** Changes the volume of the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If the 116 * sound is no longer playing, this has no effect. 117 * @param soundId the sound id 118 * @param volume the volume in the range 0 (silent) to 1 (max volume). */ setVolume(long soundId, float volume)119 public void setVolume (long soundId, float volume); 120 121 /** Sets the panning and volume of the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. 122 * If the sound is no longer playing, this has no effect. 123 * @param soundId the sound id 124 * @param pan panning in the range -1 (full left) to 1 (full right). 0 is center position. 125 * @param volume the volume in the range [0,1]. */ setPan(long soundId, float pan, float volume)126 public void setPan (long soundId, float pan, float volume); 127 } 128