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}