net.java.html.sound.AudioClip Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of net.java.html.sound Show documentation
The newest version!
/**
 * HTML via Java(tm) Language Bindings
 * Copyright (C) 2013 Jaroslav Tulach 
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, version 2 of the License.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details. apidesign.org
 * designates this particular file as subject to the
 * "Classpath" exception as provided by apidesign.org
 * in the License file that accompanied this code.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. Look for COPYING file in the top folder.
 * If not, see http://wiki.apidesign.org/wiki/GPLwithClassPathException
 */
package net.java.html.sound;

import java.util.ServiceLoader;
import org.apidesign.html.sound.spi.AudioEnvironment;

/** Handle to an audio clip which can be {@link #play() played}, {@link #pause() paused}
 * and etc. Obtain new instance via {@link #create(java.lang.String) create} factory 
 * method and then use it when necessary.
 *
 * @author antonepple
 */
public abstract class AudioClip {
    private AudioClip() {
    }

    /** Creates new instance of an audio clip based on the provided URL.
     * If no suitable audio environment provider is found, the method 
     * returns a dummy instance that does nothing and only returns
     * false from its {@link #isSupported()} method.
     * 
     * @param src the URL where to find the audio clip
     * @return the audio clip handle
     * @throws NullPointerException if src is null
     */
    public static AudioClip create(String src) {
        src.getClass();
        for (AudioEnvironment ae : ServiceLoader.load(AudioEnvironment.class)) {
            Impl handle = create(ae, src);
            if (handle != null) {
                return handle;
            }
        }
        return DummyClip.INSTANCE;
    }
    
    /** Plays the clip from begining to the end.
     */
    public abstract void play();

    /** Pauses playback of the clip
     */
    public abstract void pause();

    /**
     * Specifies the volume of the audio. Must be a number between 0.0 and 1.0:
     * 
     *   1.0 - highest volume
     *   0.5 - 50% volume
     *   0.0 - silent
     * 
     * 
     * @param volume for the playback
     */
    public abstract void setVolume(double volume);
    
    /** Check whether the audio clip is supported and can be played.
     * @return true if it is likely that after calling {@link #play()} 
     *   a sound will be produced
     */
    public abstract boolean isSupported();

//    public abstract void playFrom(int seconds);

    //
    // Implementation
    //
    
    private static