2 * Copyright 2001 Sun Microsystems, Inc.
4 * See the file "license.terms" for information on usage and
5 * redistribution of this file, and for a DISCLAIMER OF ALL
8 package com.sun.speech.freetts.audio;
10 import javax.sound.sampled.AudioFormat;
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.
21 * interface provides a set of potential synchronization points to
22 * allow a specific AudioPlayer to batch output in various ways.
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
30 * The methods: <code> begin, end</code> are used to bracket smaller amounts of
31 * audio data (typically associated with a single utterance).
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.
39 public interface AudioPlayer {
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.
48 * @param format the audio format
50 void setAudioFormat(AudioFormat format) ;
53 * Retrieves the audio format for this player
55 * @return the current audio format
58 AudioFormat getAudioFormat();
61 * Pauses all audio output on this player. Play can be resumed
62 * with a call to resume
67 * Resumes audio output on this player
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.
79 * Waits for all queued audio to be played
81 * @return <code>true</code> if the audio played to completion;
82 * otherwise <code> false </code> if the audio was stopped
88 * Starts the output of a set of data. Audio data for a single
89 * utterance should be grouped between begin/end pairs.
91 * @param size the size of data in bytes to be output before
92 * <code>end</code> is called.
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.
100 * @return <code>true</code> if the audio was output properly,
101 * <code> false</code> if the output was canceled
109 * Cancels all queued output. All 'write' calls until the next
110 * reset will return false.
117 * Waits for all audio playback to stop, and closes this AudioPlayer.
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.
127 * @return the current volume (between 0 and 1)
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.
136 * @param volume the new volume (between 0 and 1)
138 void setVolume(float volume);
142 * Gets the amount of audio played since the last resetTime
144 * @return the amount of audio in milliseconds
150 * Resets the audio clock
156 * Starts the first sample timer
158 void startFirstSampleTimer();
161 * Writes the given bytes to the audio stream
163 * @param audioData audio data to write to the device
165 * @return <code>true</code> of the write completed successfully,
166 * <code> false </code>if the write was cancelled.
168 boolean write(byte[] audioData);
171 * Writes the given bytes to the audio stream
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.
177 * @return <code>true</code> of the write completed successfully,
178 * <code> false </code>if the write was cancelled.
180 boolean write(byte[] audioData, int offset, int size);
183 * Shows metrics for this audio player