git.gag.com Git - debian/freetts/blob - com/sun/speech/freetts/audio/AudioPlayer.java

   1 /**
   2  * Copyright 2001 Sun Microsystems, Inc.
   3  *
   4  * See the file "license.terms" for information on usage and
   5  * redistribution of this file, and for a DISCLAIMER OF ALL
   6  * WARRANTIES.
   7  */
   8 package com.sun.speech.freetts.audio;
   9
  10 import javax.sound.sampled.AudioFormat;
  11
  12 /**
  13  *  Provides an  interface to the audio system for use by freetts.
  14  *  Audio is presented to the AudioPlayer as byte arrays.
  15  *  Implementations of this AudioPlayer interface will format the data
  16  *  based upon the current audio format (as set by
  17  *  <code>setAudioFormat</code>) and output the data.
  18  *
  19  *  <p>
  20  *  The AudioPlayer
  21  *  interface provides a set of potential synchronization points to
  22  *  allow a specific AudioPlayer to batch output in various ways.
  23  *  <p>
  24  *  These synchronization points are in pairs: <code>reset,
  25  *  drain</code> are used to bracket output of large amounts of audio
  26  *  data. Typically, an implementation will not return from
  27  *  <code>drain</code> until all queued audio has been played (or
  28  *  cancelled).
  29  *  <p>
  30  *  The methods: <code> begin, end</code> are used to bracket smaller amounts of
  31  *  audio data (typically associated with a single utterance).
  32  *
  33  *  <h1>Threading Issues</h1>
  34  *  Most of the methods in an AudioPlayer must be called from a
  35  *  single thread. The only exceptions to this rule are <code> pause,
  36  *  resume, cancel, showMetrics, close, getTime, resetTime</code>
  37  *  which can be called from other threads.
  38  */
  39 public interface AudioPlayer {
  40
  41     /**
  42      * Sets the audio format to use for the next set of outputs. Since
  43      * an audio player can be shared by a number of voices, and since
  44      * voices can have different AudioFormats (sample rates for
  45      * example), it is necessary to allow clients to dynamically set
  46      * the audio format for the player.
  47      *
  48      * @param format the audio format
  49      */
  50     void setAudioFormat(AudioFormat format) ;
  51
  52     /**
  53      * Retrieves the audio format for this player
  54      *
  55      * @return the current audio format
  56      *
  57      */
  58     AudioFormat getAudioFormat();
  59
  60     /**
  61      * Pauses all audio output on this player. Play can be resumed
  62      * with a call to resume
  63      */
  64     void pause();
  65
  66     /**
  67      * Resumes audio output on this player
  68      */
  69     void resume();
  70
  71     /**
  72      * Prepares for another batch of output. Larger groups of output
  73      * (such as all output associated with a single FreeTTSSpeakable)
  74      * should be grouped between a reset/drain pair.
  75      */
  76     void reset();
  77
  78     /**
  79      * Waits for all queued audio to be played
  80      *
  81      * @return <code>true</code> if the audio played to completion;
  82      *     otherwise <code> false </code> if the audio was stopped
  83      */
  84     boolean drain();
  85
  86
  87     /**
  88      *  Starts the output of a set of data. Audio data for a single
  89      *  utterance should be grouped between begin/end pairs.
  90      *
  91      * @param size the size of data in bytes to be output before
  92      *    <code>end</code> is called.
  93      */
  94     void begin(int size);
  95
  96     /**
  97      *  Signals the end of a set of data. Audio data for a single
  98      *  utterance should be groupd between <code> begin/end </code> pairs.
  99      *
 100      *  @return <code>true</code> if the audio was output properly,
 101      *          <code> false</code> if the output was canceled
 102      *          or interrupted.
 103      *
 104      */
 105     boolean end();
 106
 107
 108     /**
 109      * Cancels all queued output. All 'write' calls until the next
 110      * reset will return false.
 111      *
 112      */
 113     void cancel();
 114
 115
 116     /**
 117      * Waits for all audio playback to stop, and closes this AudioPlayer.
 118      */
 119     void close();
 120
 121
 122     /**
 123      * Returns the current volume. The volume is specified as a number
 124      * between 0.0 and 1.0, where 1.0 is the maximum volume and 0.0 is
 125      * the minimum volume.
 126      *
 127      * @return the current volume (between 0 and 1)
 128      */
 129     float getVolume();
 130
 131     /**
 132      * Sets the current volume. The volume is specified as a number
 133      * between 0.0 and 1.0, where 1.0 is the maximum volume and 0.0 is
 134      * the minimum volume.
 135      *
 136      * @param volume the new volume (between 0 and 1)
 137      */
 138     void setVolume(float volume);
 139
 140
 141     /**
 142      * Gets the amount of audio played since the last resetTime
 143      *
 144      * @return the amount of audio in milliseconds
 145      */
 146     long getTime();
 147
 148
 149     /**
 150      * Resets the audio clock
 151      */
 152     void resetTime();
 153
 154
 155     /**
 156      * Starts the first sample timer
 157      */
 158     void startFirstSampleTimer();
 159
 160     /**
 161      * Writes the given bytes to the audio stream
 162      *
 163      * @param audioData audio data to write to the device
 164      *
 165      * @return <code>true</code> of the write completed successfully,
 166      *          <code> false </code>if the write was cancelled.
 167      */
 168     boolean write(byte[] audioData);
 169
 170     /**
 171      * Writes the given bytes to the audio stream
 172      *
 173      * @param audioData audio data to write to the device
 174      * @param offset the offset into the buffer
 175      * @param size the number of bytes to write.
 176      *
 177      * @return <code>true</code> of the write completed successfully,
 178      *          <code> false </code>if the write was cancelled.
 179      */
 180     boolean write(byte[] audioData, int offset, int size);
 181
 182     /**
 183      * Shows metrics for this audio player
 184      */
 185     void showMetrics();
 186 }
 187
 188