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; 18 19 import com.badlogic.gdx.audio.AudioDevice; 20 import com.badlogic.gdx.audio.AudioRecorder; 21 import com.badlogic.gdx.audio.Music; 22 import com.badlogic.gdx.audio.Sound; 23 import com.badlogic.gdx.files.FileHandle; 24 import com.badlogic.gdx.utils.GdxRuntimeException; 25 26 /** This interface encapsulates the creation and management of audio resources. It allows you to get direct access to the audio 27 * hardware via the {@link AudioDevice} and {@link AudioRecorder} interfaces, create sound effects via the {@link Sound} interface 28 * and play music streams via the {@link Music} interface. 29 * 30 * <p> 31 * All resources created via this interface have to be disposed as soon as they are no longer used. 32 * </p> 33 * 34 * <p> 35 * Note that all {@link Music} instances will be automatically paused when the {@link ApplicationListener#pause()} method is 36 * called, and automatically resumed when the {@link ApplicationListener#resume()} method is called. 37 * </p> 38 * 39 * @author mzechner */ 40 public interface Audio { 41 /** Creates a new {@link AudioDevice} either in mono or stereo mode. The AudioDevice has to be disposed via its 42 * {@link AudioDevice#dispose()} method when it is no longer used. 43 * 44 * @param samplingRate the sampling rate. 45 * @param isMono whether the AudioDevice should be in mono or stereo mode 46 * @return the AudioDevice 47 * 48 * @throws GdxRuntimeException in case the device could not be created */ newAudioDevice(int samplingRate, boolean isMono)49 public AudioDevice newAudioDevice (int samplingRate, boolean isMono); 50 51 /** Creates a new {@link AudioRecorder}. The AudioRecorder has to be disposed after it is no longer used. 52 * 53 * @param samplingRate the sampling rate in Hertz 54 * @param isMono whether the recorder records in mono or stereo 55 * @return the AudioRecorder 56 * 57 * @throws GdxRuntimeException in case the recorder could not be created */ newAudioRecorder(int samplingRate, boolean isMono)58 public AudioRecorder newAudioRecorder (int samplingRate, boolean isMono); 59 60 /** <p> 61 * Creates a new {@link Sound} which is used to play back audio effects such as gun shots or explosions. The Sound's audio data 62 * is retrieved from the file specified via the {@link FileHandle}. Note that the complete audio data is loaded into RAM. You 63 * should therefore not load big audio files with this methods. The current upper limit for decoded audio is 1 MB. 64 * </p> 65 * 66 * <p> 67 * Currently supported formats are WAV, MP3 and OGG. 68 * </p> 69 * 70 * <p> 71 * The Sound has to be disposed if it is no longer used via the {@link Sound#dispose()} method. 72 * </p> 73 * 74 * @return the new Sound 75 * @throws GdxRuntimeException in case the sound could not be loaded */ newSound(FileHandle fileHandle)76 public Sound newSound (FileHandle fileHandle); 77 78 /** Creates a new {@link Music} instance which is used to play back a music stream from a file. Currently supported formats are 79 * WAV, MP3 and OGG. The Music instance has to be disposed if it is no longer used via the {@link Music#dispose()} method. 80 * Music instances are automatically paused when {@link ApplicationListener#pause()} is called and resumed when 81 * {@link ApplicationListener#resume()} is called. 82 * 83 * @param file the FileHandle 84 * @return the new Music or null if the Music could not be loaded 85 * @throws GdxRuntimeException in case the music could not be loaded */ newMusic(FileHandle file)86 public Music newMusic (FileHandle file); 87 } 88