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
17package com.badlogic.gdx;
18
19import com.badlogic.gdx.audio.AudioDevice;
20import com.badlogic.gdx.audio.AudioRecorder;
21import com.badlogic.gdx.audio.Music;
22import com.badlogic.gdx.audio.Sound;
23import com.badlogic.gdx.files.FileHandle;
24import 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 */
40public 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 */
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 */
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 */
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 */
86	public Music newMusic (FileHandle file);
87}
88