1 /* 2 * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.sound.sampled.spi; 27 28 import java.io.InputStream; 29 30 import javax.sound.sampled.AudioFormat; 31 import javax.sound.sampled.AudioInputStream; 32 33 /** 34 * A format conversion provider provides format conversion services 35 * from one or more input formats to one or more output formats. 36 * Converters include codecs, which encode and/or decode audio data, 37 * as well as transcoders, etc. Format converters provide methods for 38 * determining what conversions are supported and for obtaining an audio 39 * stream from which converted data can be read. 40 * <p> 41 * The source format represents the format of the incoming 42 * audio data, which will be converted. 43 * <p> 44 * The target format represents the format of the processed, converted 45 * audio data. This is the format of the data that can be read from 46 * the stream returned by one of the <code>getAudioInputStream</code> methods. 47 * 48 * @author Kara Kytle 49 * @since 1.3 50 */ 51 public abstract class FormatConversionProvider { 52 53 54 // NEW METHODS 55 56 /** 57 * Obtains the set of source format encodings from which format 58 * conversion services are provided by this provider. 59 * @return array of source format encodings. If for some reason provider 60 * does not provide any conversion services, an array of length 0 is 61 * returned. 62 */ 63 public abstract AudioFormat.Encoding[] getSourceEncodings(); 64 65 66 /** 67 * Obtains the set of target format encodings to which format 68 * conversion services are provided by this provider. 69 * @return array of target format encodings. If for some reason provider 70 * does not provide any conversion services, an array of length 0 is 71 * returned. 72 */ 73 public abstract AudioFormat.Encoding[] getTargetEncodings(); 74 75 76 /** 77 * Indicates whether the format converter supports conversion from the 78 * specified source format encoding. 79 * @param sourceEncoding the source format encoding for which support is queried 80 * @return <code>true</code> if the encoding is supported, otherwise <code>false</code> 81 */ 82 public boolean isSourceEncodingSupported(AudioFormat.Encoding sourceEncoding){ 83 84 AudioFormat.Encoding sourceEncodings[] = getSourceEncodings(); 85 86 for(int i=0; i<sourceEncodings.length; i++) { 87 if( sourceEncoding.equals( sourceEncodings[i]) ) { 88 return true; 89 } 90 } 91 return false; 92 } 93 94 95 /** 96 * Indicates whether the format converter supports conversion to the 97 * specified target format encoding. 98 * @param targetEncoding the target format encoding for which support is queried 99 * @return <code>true</code> if the encoding is supported, otherwise <code>false</code> 100 */ 101 public boolean isTargetEncodingSupported(AudioFormat.Encoding targetEncoding){ 102 103 AudioFormat.Encoding targetEncodings[] = getTargetEncodings(); 104 105 for(int i=0; i<targetEncodings.length; i++) { 106 if( targetEncoding.equals( targetEncodings[i]) ) { 107 return true; 108 } 109 } 110 return false; 111 } 112 113 114 /** 115 * Obtains the set of target format encodings supported by the format converter 116 * given a particular source format. 117 * If no target format encodings are supported for this source format, 118 * an array of length 0 is returned. 119 * @param sourceFormat format of the incoming data 120 * @return array of supported target format encodings. 121 */ 122 public abstract AudioFormat.Encoding[] getTargetEncodings(AudioFormat sourceFormat); 123 124 125 /** 126 * Indicates whether the format converter supports conversion to a particular encoding 127 * from a particular format. 128 * @param targetEncoding desired encoding of the outgoing data 129 * @param sourceFormat format of the incoming data 130 * @return <code>true</code> if the conversion is supported, otherwise <code>false</code> 131 */ 132 public boolean isConversionSupported(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat){ 133 134 AudioFormat.Encoding targetEncodings[] = getTargetEncodings(sourceFormat); 135 136 for(int i=0; i<targetEncodings.length; i++) { 137 if( targetEncoding.equals( targetEncodings[i]) ) { 138 return true; 139 } 140 } 141 return false; 142 } 143 144 145 /** 146 * Obtains the set of target formats with the encoding specified 147 * supported by the format converter 148 * If no target formats with the specified encoding are supported 149 * for this source format, an array of length 0 is returned. 150 * @param targetEncoding desired encoding of the stream after processing 151 * @param sourceFormat format of the incoming data 152 * @return array of supported target formats. 153 */ 154 public abstract AudioFormat[] getTargetFormats(AudioFormat.Encoding targetEncoding, AudioFormat sourceFormat); 155 156 157 /** 158 * Indicates whether the format converter supports conversion to one 159 * particular format from another. 160 * @param targetFormat desired format of outgoing data 161 * @param sourceFormat format of the incoming data 162 * @return <code>true</code> if the conversion is supported, otherwise <code>false</code> 163 */ 164 public boolean isConversionSupported(AudioFormat targetFormat, AudioFormat sourceFormat){ 165 166 AudioFormat targetFormats[] = getTargetFormats( targetFormat.getEncoding(), sourceFormat ); 167 168 for(int i=0; i<targetFormats.length; i++) { 169 if( targetFormat.matches( targetFormats[i] ) ) { 170 return true; 171 } 172 } 173 return false; 174 } 175 176 177 /** 178 * Obtains an audio input stream with the specified encoding from the given audio 179 * input stream. 180 * @param targetEncoding desired encoding of the stream after processing 181 * @param sourceStream stream from which data to be processed should be read 182 * @return stream from which processed data with the specified target encoding may be read 183 * @throws IllegalArgumentException if the format combination supplied is 184 * not supported. 185 */ 186 public abstract AudioInputStream getAudioInputStream(AudioFormat.Encoding targetEncoding, AudioInputStream sourceStream); 187 188 189 /** 190 * Obtains an audio input stream with the specified format from the given audio 191 * input stream. 192 * @param targetFormat desired data format of the stream after processing 193 * @param sourceStream stream from which data to be processed should be read 194 * @return stream from which processed data with the specified format may be read 195 * @throws IllegalArgumentException if the format combination supplied is 196 * not supported. 197 */ 198 public abstract AudioInputStream getAudioInputStream(AudioFormat targetFormat, AudioInputStream sourceStream); 199 200 } | 1 /* 2 * Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package javax.sound.sampled.spi; 27 28 import javax.sound.sampled.AudioFormat; 29 import javax.sound.sampled.AudioInputStream; 30 31 import static javax.sound.sampled.AudioFormat.Encoding; 32 33 /** 34 * A format conversion provider provides format conversion services from one or 35 * more input formats to one or more output formats. Converters include codecs, 36 * which encode and/or decode audio data, as well as transcoders, etc. Format 37 * converters provide methods for determining what conversions are supported and 38 * for obtaining an audio stream from which converted data can be read. 39 * <p> 40 * The source format represents the format of the incoming audio data, which 41 * will be converted. 42 * <p> 43 * The target format represents the format of the processed, converted audio 44 * data. This is the format of the data that can be read from the stream 45 * returned by one of the {@code getAudioInputStream} methods. 46 * 47 * @author Kara Kytle 48 * @since 1.3 49 */ 50 public abstract class FormatConversionProvider { 51 52 /** 53 * Obtains the set of source format encodings from which format conversion 54 * services are provided by this provider. 55 * 56 * @return array of source format encodings. If for some reason provider 57 * does not provide any conversion services, an array of length 0 is 58 * returned. 59 */ 60 public abstract Encoding[] getSourceEncodings(); 61 62 /** 63 * Obtains the set of target format encodings to which format conversion 64 * services are provided by this provider. 65 * 66 * @return array of target format encodings. If for some reason provider 67 * does not provide any conversion services, an array of length 0 is 68 * returned. 69 */ 70 public abstract Encoding[] getTargetEncodings(); 71 72 /** 73 * Indicates whether the format converter supports conversion from the 74 * specified source format encoding. 75 * 76 * @param sourceEncoding the source format encoding for which support is 77 * queried 78 * @return {@code true} if the encoding is supported, otherwise 79 * {@code false} 80 */ 81 public boolean isSourceEncodingSupported(Encoding sourceEncoding) { 82 83 Encoding sourceEncodings[] = getSourceEncodings(); 84 85 for(int i=0; i<sourceEncodings.length; i++) { 86 if( sourceEncoding.equals( sourceEncodings[i]) ) { 87 return true; 88 } 89 } 90 return false; 91 } 92 93 /** 94 * Indicates whether the format converter supports conversion to the 95 * specified target format encoding. 96 * 97 * @param targetEncoding the target format encoding for which support is 98 * queried 99 * @return {@code true} if the encoding is supported, otherwise 100 * {@code false} 101 */ 102 public boolean isTargetEncodingSupported(Encoding targetEncoding) { 103 104 Encoding targetEncodings[] = getTargetEncodings(); 105 106 for(int i=0; i<targetEncodings.length; i++) { 107 if( targetEncoding.equals( targetEncodings[i]) ) { 108 return true; 109 } 110 } 111 return false; 112 } 113 114 /** 115 * Obtains the set of target format encodings supported by the format 116 * converter given a particular source format. If no target format encodings 117 * are supported for this source format, an array of length 0 is returned. 118 * 119 * @param sourceFormat format of the incoming data 120 * @return array of supported target format encodings. 121 */ 122 public abstract Encoding[] getTargetEncodings(AudioFormat sourceFormat); 123 124 /** 125 * Indicates whether the format converter supports conversion to a 126 * particular encoding from a particular format. 127 * 128 * @param targetEncoding desired encoding of the outgoing data 129 * @param sourceFormat format of the incoming data 130 * @return {@code true} if the conversion is supported, otherwise 131 * {@code false} 132 */ 133 public boolean isConversionSupported(Encoding targetEncoding, 134 AudioFormat sourceFormat) { 135 136 Encoding targetEncodings[] = getTargetEncodings(sourceFormat); 137 138 for(int i=0; i<targetEncodings.length; i++) { 139 if( targetEncoding.equals( targetEncodings[i]) ) { 140 return true; 141 } 142 } 143 return false; 144 } 145 146 /** 147 * Obtains the set of target formats with the encoding specified supported 148 * by the format converter If no target formats with the specified encoding 149 * are supported for this source format, an array of length 0 is returned. 150 * 151 * @param targetEncoding desired encoding of the stream after processing 152 * @param sourceFormat format of the incoming data 153 * @return array of supported target formats. 154 */ 155 public abstract AudioFormat[] getTargetFormats(Encoding targetEncoding, 156 AudioFormat sourceFormat); 157 158 /** 159 * Indicates whether the format converter supports conversion to one 160 * particular format from another. 161 * 162 * @param targetFormat desired format of outgoing data 163 * @param sourceFormat format of the incoming data 164 * @return {@code true} if the conversion is supported, otherwise 165 * {@code false} 166 */ 167 public boolean isConversionSupported(AudioFormat targetFormat, 168 AudioFormat sourceFormat) { 169 170 AudioFormat targetFormats[] = getTargetFormats( targetFormat.getEncoding(), sourceFormat ); 171 172 for(int i=0; i<targetFormats.length; i++) { 173 if( targetFormat.matches( targetFormats[i] ) ) { 174 return true; 175 } 176 } 177 return false; 178 } 179 180 /** 181 * Obtains an audio input stream with the specified encoding from the given 182 * audio input stream. 183 * 184 * @param targetEncoding desired encoding of the stream after processing 185 * @param sourceStream stream from which data to be processed should be 186 * read 187 * @return stream from which processed data with the specified target 188 * encoding may be read 189 * @throws IllegalArgumentException if the format combination supplied is 190 * not supported. 191 */ 192 public abstract AudioInputStream getAudioInputStream( 193 Encoding targetEncoding, AudioInputStream sourceStream); 194 195 /** 196 * Obtains an audio input stream with the specified format from the given 197 * audio input stream. 198 * 199 * @param targetFormat desired data format of the stream after processing 200 * @param sourceStream stream from which data to be processed should be 201 * read 202 * @return stream from which processed data with the specified format may be 203 * read 204 * @throws IllegalArgumentException if the format combination supplied is 205 * not supported. 206 */ 207 public abstract AudioInputStream getAudioInputStream( 208 AudioFormat targetFormat, AudioInputStream sourceStream); 209 } |