Save This Page
Home » openjdk-7 » com.sun.media » sound » [javadoc | source]
    1   /*
    2    * Copyright (c) 2007, 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   package com.sun.media.sound;
   26   
   27   import java.util.Map;
   28   import javax.sound.midi.MidiUnavailableException;
   29   import javax.sound.midi.Synthesizer;
   30   import javax.sound.sampled.AudioFormat;
   31   import javax.sound.sampled.AudioInputStream;
   32   import javax.sound.sampled.SourceDataLine;
   33   
   34   /**
   35    * <code>AudioSynthesizer</code> is a <code>Synthesizer</code>
   36    * which renders it's output audio into <code>SourceDataLine</code>
   37    * or <code>AudioInputStream</code>.
   38    *
   39    * @see MidiSystem#getSynthesizer
   40    * @see Synthesizer
   41    *
   42    * @author Karl Helgason
   43    */
   44   public interface AudioSynthesizer extends Synthesizer {
   45   
   46       /**
   47        * Obtains the current format (encoding, sample rate, number of channels,
   48        * etc.) of the synthesizer audio data.
   49        *
   50        * <p>If the synthesizer is not open and has never been opened, it returns
   51        * the default format.
   52        *
   53        * @return current audio data format
   54        * @see AudioFormat
   55        */
   56       public AudioFormat getFormat();
   57   
   58       /**
   59        * Gets information about the possible properties for the synthesizer.
   60        *
   61        * @param info a proposed list of tag/value pairs that will be sent on open.
   62        * @return an array of <code>AudioSynthesizerPropertyInfo</code> objects
   63        * describing possible properties. This array may be an empty array if
   64        * no properties are required.
   65        */
   66       public AudioSynthesizerPropertyInfo[] getPropertyInfo(
   67               Map<String, Object> info);
   68   
   69       /**
   70        * Opens the synthesizer and starts rendering audio into
   71        * <code>SourceDataLine</code>.
   72        *
   73        * <p>An application opening a synthesizer explicitly with this call
   74        * has to close the synthesizer by calling {@link #close}. This is
   75        * necessary to release system resources and allow applications to
   76        * exit cleanly.
   77        *
   78        * <p>Note that some synthesizers, once closed, cannot be reopened.
   79        * Attempts to reopen such a synthesizer will always result in
   80        * a <code>MidiUnavailableException</code>.
   81        *
   82        * @param line which <code>AudioSynthesizer</code> writes output audio into.
   83        * If <code>line</code> is null, then line from system default mixer is used.
   84        * @param info a <code>Map<String,Object></code> object containing
   85        * properties for additional configuration supported by synthesizer.
   86        * If <code>info</code> is null then default settings are used.
   87        *
   88        * @throws MidiUnavailableException thrown if the synthesizer cannot be
   89        * opened due to resource restrictions.
   90        * @throws SecurityException thrown if the synthesizer cannot be
   91        * opened due to security restrictions.
   92        *
   93        * @see #close
   94        * @see #isOpen
   95        */
   96       public void open(SourceDataLine line, Map<String, Object> info)
   97               throws MidiUnavailableException;
   98   
   99       /**
  100        * Opens the synthesizer and renders audio into returned
  101        * <code>AudioInputStream</code>.
  102        *
  103        * <p>An application opening a synthesizer explicitly with this call
  104        * has to close the synthesizer by calling {@link #close}. This is
  105        * necessary to release system resources and allow applications to
  106        * exit cleanly.
  107        *
  108        * <p>Note that some synthesizers, once closed, cannot be reopened.
  109        * Attempts to reopen such a synthesizer will always result in
  110        * a <code>MidiUnavailableException<code>.
  111        *
  112        * @param targetFormat specifies the <code>AudioFormat</code>
  113        * used in returned <code>AudioInputStream</code>.
  114        * @param info a <code>Map<String,Object></code> object containing
  115        * properties for additional configuration supported by synthesizer.
  116        * If <code>info</code> is null then default settings are used.
  117        *
  118        * @throws MidiUnavailableException thrown if the synthesizer cannot be
  119        * opened due to resource restrictions.
  120        * @throws SecurityException thrown if the synthesizer cannot be
  121        * opened due to security restrictions.
  122        *
  123        * @see #close
  124        * @see #isOpen
  125        */
  126       public AudioInputStream openStream(AudioFormat targetFormat,
  127               Map<String, Object> info) throws MidiUnavailableException;
  128   }

Save This Page
Home » openjdk-7 » com.sun.media » sound » [javadoc | source]