Package ptolemy.actor.lib.jjs.modules.audio

Class AudioHelper

  • public class AudioHelper
extends VertxHelperBase
    Helper for the audio.js JavaScript module. See the module for documentation. This class is based on the LiveSoundJavaSE class in Ptolemy II, written by Brian K. Vogel, Neil E. Turner, Steve Neuendorffer, and Edward A. Lee, with contributions from Dennis Geurts, Ishwinder Singh.
    Since:
    Ptolemy II 11.0
    Version:
    $Id$
    Author:
    Edward A. Lee
    Pt.AcceptedRating:
    Red (cxh)
    Pt.ProposedRating:
    Yellow (eal)

    • Constructor Detail

      • AudioHelper

        public AudioHelper​(java.lang.Object actor,
                   jdk.nashorn.api.scripting.ScriptObjectMirror currentObj)
        Create an audio helper.
        Parameters:
        actor - The actor associated with this helper.
        currentObj - The JavaScript object that this is helping.

    • Method Detail

      • byteFormats

        public static java.lang.String[] byteFormats()
        Return an array of supported byte formats for audio.
        Returns:
        An array of strings.

      • putSamples

        public void putSamples​(double[][] samplesArray,
                       java.lang.Runnable callback)
                throws java.lang.IllegalStateException,
                       java.io.IOException
        Play an array of audio samples. This method returns immediately and invokes the specified callback function when the samples have been successfully queued into the audio system. This method should not be called again before the callback has been invoked.

        The samples should be in the range (-1, 1). Samples that are outside this range will be hard-clipped so that they fall within this range.

        The first index of the specified array represents the channel number (0 for first channel, 1 for second channel, etc.). The number of channels is set by the setChannels() method. The second index represents the sample index within a channel. For example, putSamplesArray[n][m] contains the (m+1)th sample of the (n+1)th channel.

        Parameters:
        samplesArray - A two dimensional array containing the samples to play.
        callback - A callback function to invoke when the samples have been queued into the audio system.
        Throws:
        java.io.IOException - If the calling program does not have permission to access the audio playback resources.
        java.lang.IllegalStateException - If audio playback is currently inactive. That is, If startPlayback() has not yet been called or if stopPlayback() has already been called.

      • putBytes

        public void putBytes​(byte[] audioData,
                     java.lang.Runnable callback)
              throws java.lang.IllegalStateException,
                     java.io.IOException,
                     javax.sound.sampled.UnsupportedAudioFileException
        Play an array of audio samples given as a byte array. This method returns immediately and invokes the specified callback function when the samples have been successfully queued into the audio system. This method should not be called again before the callback has been invoked.
        Parameters:
        audioData - Byte array to play.
        callback - A callback function to invoke when the samples have been queued into the audio system.
        Throws:
        java.io.IOException - If the calling program does not have permission to access the audio playback resources.
        java.lang.IllegalStateException - If audio playback is currently inactive. That is, If startPlayback() has not yet been called or if stopPlayback() has already been called.
        javax.sound.sampled.UnsupportedAudioFileException - If the audioData provided is not in a supported format.

      • setCaptureParameters

        public void setCaptureParameters​(java.util.Map<java.lang.String,​java.lang.Integer> captureOptions,
                                 int captureTime,
                                 java.lang.String outputFormat)
                          throws java.io.IOException,
                                 javax.sound.sampled.LineUnavailableException
        Set the capture parameters for audio. This will stop any active capture and restart it. The captureOptions argument contains the following entries:
        1. bigEndian: 1 if big endian, 0 if little endian. The default is big endian.
        2. bitsPerSample: The number of bits per sample.
        3. channels: The number of channels.
        4. sampleRate: Sample rate in Hz.
        Allowable values for sampleRate are (most likely) 8000, 11025, 22050, 44100, and 48000 Hz. If this method is not invoked, then the default value of 8000 Hz is used. WAVE (aka .wav) is 16 bits, 1 channel, little endian, 44100 Hz.
        Parameters:
        captureOptions - The parameters for capture.
        captureTime - The amount of time (in ms) per capture.
        outputFormat - The requested output format.
        Throws:
        java.io.IOException - If the specified sample rate is not supported by the audio hardware or by Java.
        javax.sound.sampled.LineUnavailableException - If the audio line is not available.

      • setPlaybackParameters

        public void setPlaybackParameters​(java.util.Map<java.lang.String,​java.lang.Integer> playbackOptions,
                                  java.lang.String playbackFormat)
                           throws java.io.IOException,
                                  javax.sound.sampled.LineUnavailableException
        Set the playback parameters for audio. This will stop any active playback and restart it. The playbackOptions argument contains the following entries:
        1. bigEndian: 1 if big endian, 0 if little endian. The default is big endian.
        2. bitsPerSample: The number of bits per sample.
        3. channels: The number of channels.
        4. sampleRate: Sample rate in Hz.
        Allowable values for sampleRate are (most likely) 8000, 11025, 22050, 44100, and 48000 Hz. If this method is not invoked, then the default value of 8000 Hz is used. WAVE (aka .wav) is 16 bits, 1 channel, little endian, 44100 Hz.
        Parameters:
        playbackOptions - The parameters for playback.
        playbackFormat - The expected format of the input data.
        Throws:
        java.io.IOException - If the specified sample rate is not supported by the audio hardware or by Java.
        javax.sound.sampled.LineUnavailableException - If the audio line is not available.

      • startCapture

        public void startCapture()
                  throws java.io.IOException
        Start audio capture if it is not already active.
        Throws:
        java.io.IOException - If the audio target line cannot be acquired.

      • startPlayback

        public void startPlayback()
                   throws java.io.IOException
        Start audio playback if it is not already active.
        Throws:
        java.io.IOException - If the audio target line cannot be acquired.

      • stopCapture

        public void stopCapture()
        Stop audio capture if it is active.

      • stopPlayback

        public void stopPlayback()
        Stop audio playback if it is active.