Interface AudioPlayer

  • All Known Implementing Classes:
    JavaClipAudioPlayer, JavaStreamingAudioPlayer, MultiFile8BitAudioPlayer, MultiFileAudioPlayer, NullAudioPlayer, RawFileAudioPlayer, SingleFileAudioPlayer

    public interface AudioPlayer
    Provides an interface to the audio system for use by freetts. Audio is presented to the AudioPlayer as byte arrays. Implementations of this AudioPlayer interface will format the data based upon the current audio format (as set by setAudioFormat) and output the data.

    The AudioPlayer interface provides a set of potential synchronization points to allow a specific AudioPlayer to batch output in various ways.

    These synchronization points are in pairs: reset, drain are used to bracket output of large amounts of audio data. Typically, an implementation will not return from drain until all queued audio has been played (or cancelled).

    The methods: begin, end are used to bracket smaller amounts of audio data (typically associated with a single utterance).

    Threading Issues

    Most of the methods in an AudioPlayer must be called from a single thread. The only exceptions to this rule are pause, resume, cancel, showMetrics, close, getTime, resetTime which can be called from other threads.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void begin​(int size)
      Starts the output of a set of data.
      void cancel()
      Cancels all queued output.
      void close()
      Waits for all audio playback to stop, and closes this AudioPlayer.
      boolean drain()
      Waits for all queued audio to be played
      boolean end()
      Signals the end of a set of data.
      javax.sound.sampled.AudioFormat getAudioFormat()
      Retrieves the audio format for this player
      long getTime()
      Gets the amount of audio played since the last resetTime
      float getVolume()
      Returns the current volume.
      void pause()
      Pauses all audio output on this player.
      void reset()
      Prepares for another batch of output.
      void resetTime()
      Resets the audio clock
      void resume()
      Resumes audio output on this player
      void setAudioFormat​(javax.sound.sampled.AudioFormat format)
      Sets the audio format to use for the next set of outputs.
      void setVolume​(float volume)
      Sets the current volume.
      void showMetrics()
      Shows metrics for this audio player
      void startFirstSampleTimer()
      Starts the first sample timer
      boolean write​(byte[] audioData)
      Writes the given bytes to the audio stream
      boolean write​(byte[] audioData, int offset, int size)
      Writes the given bytes to the audio stream
    • Method Detail

      • setAudioFormat

        void setAudioFormat​(javax.sound.sampled.AudioFormat format)
        Sets the audio format to use for the next set of outputs. Since an audio player can be shared by a number of voices, and since voices can have different AudioFormats (sample rates for example), it is necessary to allow clients to dynamically set the audio format for the player.
        Parameters:
        format - the audio format
      • getAudioFormat

        javax.sound.sampled.AudioFormat getAudioFormat()
        Retrieves the audio format for this player
        Returns:
        the current audio format
      • pause

        void pause()
        Pauses all audio output on this player. Play can be resumed with a call to resume
      • resume

        void resume()
        Resumes audio output on this player
      • reset

        void reset()
        Prepares for another batch of output. Larger groups of output (such as all output associated with a single FreeTTSSpeakable) should be grouped between a reset/drain pair.
      • drain

        boolean drain()
        Waits for all queued audio to be played
        Returns:
        true if the audio played to completion; otherwise false if the audio was stopped
      • begin

        void begin​(int size)
        Starts the output of a set of data. Audio data for a single utterance should be grouped between begin/end pairs.
        Parameters:
        size - the size of data in bytes to be output before end is called.
      • end

        boolean end()
        Signals the end of a set of data. Audio data for a single utterance should be groupd between begin/end pairs.
        Returns:
        true if the audio was output properly, false if the output was canceled or interrupted.
      • cancel

        void cancel()
        Cancels all queued output. All 'write' calls until the next reset will return false.
      • close

        void close()
        Waits for all audio playback to stop, and closes this AudioPlayer.
      • getVolume

        float getVolume()
        Returns the current volume. The volume is specified as a number between 0.0 and 1.0, where 1.0 is the maximum volume and 0.0 is the minimum volume.
        Returns:
        the current volume (between 0 and 1)
      • setVolume

        void setVolume​(float volume)
        Sets the current volume. The volume is specified as a number between 0.0 and 1.0, where 1.0 is the maximum volume and 0.0 is the minimum volume.
        Parameters:
        volume - the new volume (between 0 and 1)
      • getTime

        long getTime()
        Gets the amount of audio played since the last resetTime
        Returns:
        the amount of audio in milliseconds
      • resetTime

        void resetTime()
        Resets the audio clock
      • startFirstSampleTimer

        void startFirstSampleTimer()
        Starts the first sample timer
      • write

        boolean write​(byte[] audioData)
        Writes the given bytes to the audio stream
        Parameters:
        audioData - audio data to write to the device
        Returns:
        true of the write completed successfully, false if the write was cancelled.
      • write

        boolean write​(byte[] audioData,
                      int offset,
                      int size)
        Writes the given bytes to the audio stream
        Parameters:
        audioData - audio data to write to the device
        offset - the offset into the buffer
        size - the number of bytes to write.
        Returns:
        true of the write completed successfully, false if the write was cancelled.
      • showMetrics

        void showMetrics()
        Shows metrics for this audio player