001package jmri.jmrit.audio;
002
003import java.io.InputStream;
004import java.nio.ByteBuffer;
005import jmri.Audio;
006
007/**
008 * Represent an AudioBuffer, a place to store or control sound information.
009 * <p>
010 * The AbstractAudio class contains a basic implementation of the state and
011 * messaging code, and forms a useful start for a system-specific
012 * implementation. Specific implementations in the jmrix package, e.g. for
013 * LocoNet and NCE, will convert to and from the layout commands.
014 * <p>
015 * The states and names are Java Bean parameters, so that listeners can be
016 * registered to be notified of any changes.
017 * <p>
018 * Each AudioBuffer object has a two names. The "user" name is entirely free
019 * form, and can be used for any purpose. The "system" name is provided by the
020 * system-specific implementations, and provides a unique mapping to the layout
021 * control system (for example LocoNet or NCE) and address within that system.
022 * <br>
023 * <hr>
024 * This file is part of JMRI.
025 * <p>
026 * JMRI is free software; you can redistribute it and/or modify it under the
027 * terms of version 2 of the GNU General Public License as published by the Free
028 * Software Foundation. See the "COPYING" file for a copy of this license.
029 * <p>
030 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
031 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
032 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
033 *
034 * @author Matthew Harris copyright (c) 2009, 2011
035 */
036public interface AudioBuffer extends Audio {
037
038    /**
039     * Definition of unknown audio format
040     */
041    int FORMAT_UNKNOWN = 0x00;
042    /**
043     * Definition of 8-bit mono audio format
044     */
045    int FORMAT_8BIT_MONO = 0x11;
046    /**
047     * Definition of 16-bit mono audio format
048     */
049    int FORMAT_16BIT_MONO = 0x12;
050    /**
051     * Definition of 8-bit stereo audio format
052     */
053    int FORMAT_8BIT_STEREO = 0x21;
054    /**
055     * Definition of 16-bit stereo audio format
056     */
057    int FORMAT_16BIT_STEREO = 0x22;
058
059    /**
060     * Definition of 8-bit quad multi-channel audio format.
061     * <p>
062     * These formats are only supported by certain OpenAL implementations and
063     * support is determined at runtime.
064     * <p>
065     * JavaSound and Null implementations do not support these formats.
066     */
067    int FORMAT_8BIT_QUAD = 0x41;
068    /**
069     * Definition of 16-bit quad multi-channel audio format.
070     * <p>
071     * These formats are only supported by certain OpenAL implementations and
072     * support is determined at runtime.
073     * <p>
074     * JavaSound and Null implementations do not support these formats.
075     */
076    int FORMAT_16BIT_QUAD = 0x42;
077    /**
078     * Definition of 8-bit 5.1 multi-channel audio format.
079     * <p>
080     * These formats are only supported by certain OpenAL implementations and
081     * support is determined at runtime.
082     * <p>
083     * JavaSound and Null implementations do not support these formats.
084     */
085    int FORMAT_8BIT_5DOT1 = 0x61;
086    /**
087     * Definition of 16-bit 5.1 multi-channel audio format.
088     * <p>
089     * These formats are only supported by certain OpenAL implementations and
090     * support is determined at runtime.
091     * <p>
092     * JavaSound and Null implementations do not support these formats.
093     */
094    int FORMAT_16BIT_5DOT1 = 0x62;
095    /**
096     * Definition of 8-bit 6.1 multi-channel audio format.
097     * <p>
098     * These formats are only supported by certain OpenAL implementations and
099     * support is determined at runtime.
100     * <p>
101     * JavaSound and Null implementations do not support these formats.
102     */
103    int FORMAT_8BIT_6DOT1 = 0x71;
104    /**
105     * Definition of 16-bit 6.1 multi-channel audio format.
106     * <p>
107     * These formats are only supported by certain OpenAL implementations and
108     * support is determined at runtime.
109     * <p>
110     * JavaSound and Null implementations do not support these formats.
111     */
112    int FORMAT_16BIT_6DOT1 = 0x72;
113    /**
114     * Definition of 8-bit 7.1 multi-channel audio format.
115     * <p>
116     * These formats are only supported by certain OpenAL implementations and
117     * support is determined at runtime.
118     * <p>
119     * JavaSound and Null implementations do not support these formats.
120     */
121    int FORMAT_8BIT_7DOT1 = 0x81;
122    /**
123     * Definition of 16-bit 7.1 multi-channel audio format.
124     * <p>
125     * These formats are only supported by certain OpenAL implementations and
126     * support is determined at runtime.
127     * <p>
128     * JavaSound and Null implementations do not support these formats.
129     */
130    int FORMAT_16BIT_7DOT1 = 0x82;
131
132    /**
133     * Return the url of the sound sample
134     * <p>
135     * Applies only to sub-types:
136     * <ul>
137     * <li>Buffer
138     * </ul>
139     *
140     * @return url
141     */
142    String getURL();
143
144    /**
145     * Sets the url of the sound sample
146     * <p>
147     * Applies only to sub-types:
148     * <ul>
149     * <li>Buffer
150     * </ul>
151     *
152     * @param pUrl URL for location containing sound sample data
153     */
154    void setURL(String pUrl);
155
156    /**
157     * Sets the input stream of the sound sample
158     * <p>
159     * Applies only to sub-types:
160     * <ul>
161     * <li>Buffer
162     * </ul>
163     *
164     * @param stream InputStream containing sound sample data
165     */
166    void setInputStream(InputStream stream);
167
168    /**
169     * Retrieves the format of the sound sample stored in this buffer
170     * <p>
171     * Applies only to sub-types:
172     * <ul>
173     * <li>Buffer
174     * </ul>
175     *
176     * @return constant representing format
177     */
178    int getFormat();
179
180    /**
181     * Retrieves the length of the sound sample stored in this buffer
182     * <p>
183     * Applies only to sub-types:
184     * <ul>
185     * <li>Buffer
186     * </ul>
187     *
188     * @return length of sound sample in frames
189     * @see #getFrameSize()
190     */
191    long getLength();
192
193    /**
194     * Retrieves the frequency of the sound sample stored in this buffer
195     * <p>
196     * Applies only to sub-types:
197     * <ul>
198     * <li>Buffer
199     * </ul>
200     *
201     * @return frequency of sound sample in Hz
202     */
203    int getFrequency();
204
205    /**
206     * Retrieves the length of a sound sample frame stored in this buffer
207     * <p>
208     * Applies only to sub-types:
209     * <ul>
210     * <li>Buffer
211     * </ul>
212     *
213     * @return length of sound sample frame in bytes
214     */
215    int getFrameSize();
216
217    /**
218     * Sets the start loop point of the sound sample stored in this buffer
219     * <p>
220     * Applies only to sub-types:
221     * <ul>
222     * <li>Buffer
223     * </ul>
224     *
225     * @param startLoopPoint position of start loop point in samples
226     */
227    void setStartLoopPoint(long startLoopPoint);
228
229    /**
230     * Retrieves the start loop point of the sound sample stored in this buffer
231     * <p>
232     * Applies only to sub-types:
233     * <ul>
234     * <li>Buffer
235     * </ul>
236     *
237     * @return position of start loop point in samples
238     */
239    long getStartLoopPoint();
240
241    /**
242     * Sets the end loop point of the sound sample stored in this buffer
243     * <p>
244     * Applies only to sub-types:
245     * <ul>
246     * <li>Buffer
247     * </ul>
248     *
249     * @param endLoopPoint position of end loop point in samples
250     */
251    void setEndLoopPoint(long endLoopPoint);
252
253    /**
254     * Retrieves the end loop point of the sound sample stored in this buffer
255     * <p>
256     * Applies only to sub-types:
257     * <ul>
258     * <li>Buffer
259     * </ul>
260     *
261     * @return position of end loop point in samples
262     */
263    long getEndLoopPoint();
264
265    /**
266     * Sets that this buffer is to be streamed as opposed to loaded in full. Can
267     * only be turned off when {@link #isStreamedForced() isStreamedForced} is
268     * not set.
269     * <p>
270     * Applies only to sub-types:
271     * <ul>
272     * <li>Buffer
273     * </ul>
274     *
275     * @param streamed buffer is streamed from file or loaded in full
276     * @see #isStreamedForced()
277     */
278    void setStreamed(boolean streamed);
279
280    /**
281     * Retrieves the current streaming setting of this buffer
282     * <p>
283     * Applies only to sub-types:
284     * <ul>
285     * <li>Buffer
286     * </ul>
287     *
288     * @return current streaming setting
289     */
290    boolean isStreamed();
291
292    /**
293     * Determines if this buffer can be loaded in full or if it must be streamed
294     * from the file. Forced streaming is usually restricted to larger sound
295     * samples that are otherwise too large to fit directly into memory.
296     * <p>
297     * Applies only to sub-types:
298     * <ul>
299     * <li>Buffer
300     * </ul>
301     *
302     * @return True if buffer must be streamed; False it can be loaded in full
303     */
304    boolean isStreamedForced();
305
306    boolean loadBuffer(ByteBuffer b, int format, int frequency);
307}