001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.io.audio;
003
004import java.io.IOException;
005import java.net.URL;
006
007import org.openstreetmap.josm.io.audio.AudioPlayer.Execute;
008import org.openstreetmap.josm.io.audio.AudioPlayer.State;
009
010/**
011 * Sound player interface. Implementations can be backed up by Java Sound API or Java FX Media API.
012 * @since 12328
013 */
014interface SoundPlayer {
015
016    /**
017     * Ask player to play a new media.
018     * @param command Command containing media information
019     * @param stateChange the previous state
020     * @param playingUrl the currently playing URL, if any
021     * @throws AudioException if an audio error occurs
022     * @throws IOException if an I/O error occurs
023     */
024    void play(Execute command, State stateChange, URL playingUrl) throws AudioException, IOException;
025
026    /**
027     * Ask player to pause the current playing media.
028     * @param command Command containing media information
029     * @param stateChange the previous state
030     * @param playingUrl the currently playing URL, if any
031     * @throws AudioException if an audio error occurs
032     * @throws IOException if an I/O error occurs
033     */
034    void pause(Execute command, State stateChange, URL playingUrl) throws AudioException, IOException;
035
036    /**
037     * Method called when a media is being played.
038     * @param command Command containing media information
039     * @return {@code true} if the playing call was blocking, and the playback is finished when this method returns
040     * @throws AudioException if an audio error occurs
041     * @throws IOException if an I/O error occurs
042     * @throws InterruptedException if the play is interrupted
043     */
044    boolean playing(Execute command) throws AudioException, IOException, InterruptedException;
045
046    /**
047     * Returns the media playback position, in seconds.
048     * @return the media playback position, in seconds
049     */
050    double position();
051
052    /**
053     * Returns the media playback speed ratio.
054     * @return the media playback speed ratio
055     */
056    double speed();
057
058    /**
059     * Adds a listener that will be notified of audio playback events.
060     * @param listener audio listener
061     */
062    void addAudioListener(AudioListener listener);
063}