1.1 --- a/sound/src/main/java/org/apidesign/html/sound/spi/AudioEnvironment.java	Thu Feb 06 11:10:09 2014 +0100
     1.2 +++ b/sound/src/main/java/org/apidesign/html/sound/spi/AudioEnvironment.java	Thu Feb 06 14:25:31 2014 +0100
     1.3 @@ -42,19 +42,47 @@
     1.4   */
     1.5  package org.apidesign.html.sound.spi;
     1.6  
     1.7 -/** Basic interface for sound playback providers.
     1.8 +/** Basic interface for sound playback providers. Register your implementation
     1.9 + * in a way {@link java.util.ServiceLoader} can find it - e.g. use
    1.10 + * {@link org.openide.util.lookup.ServiceProvider} annotation.
    1.11   *
    1.12   * @author antonepple
    1.13 - * @param <Audio> the type representing an audio
    1.14 + * @param <Audio> custom type representing the internal audio state
    1.15   */
    1.16  public interface AudioEnvironment<Audio> {
    1.17 +    /** Checks if the provided URL can be a supported audio stream 
    1.18 +     * and if so, it create an object to represent it. The created object
    1.19 +     * will be used in future callbacks to other methods of this interface
    1.20 +     * (like {@link #play(java.lang.Object)}).
    1.21 +     * @param src the URL pointing to the media stream
    1.22 +     * @return an internal representation object or <code>null</code> if this
    1.23 +     *   environment does not know how to handle such stream
    1.24 +     */
    1.25      public Audio create(String src);
    1.26  
    1.27 +    /** Starts playback of the audio.
    1.28 +     * 
    1.29 +     * @param a the internal representation of the audio as created by {@link #create(java.lang.String)} method.
    1.30 +     */
    1.31      public void play(Audio a);
    1.32  
    1.33 +    /** Pauses playback of the audio.
    1.34 +     * 
    1.35 +     * @param a the internal representation of the audio as created by {@link #create(java.lang.String)} method.
    1.36 +     */
    1.37      public void pause(Audio a);
    1.38  
    1.39 +    /** Changes volume for the playback of the audio.
    1.40 +     * 
    1.41 +     * @param a the internal representation of the audio as created by {@link #create(java.lang.String)} method.
    1.42 +     * @param volume value between 0.0 and 1.0
    1.43 +     */
    1.44      public void setVolume(Audio a, double volume);
    1.45 -    
    1.46 +
    1.47 +    /** Checks whether given audio is supported
    1.48 +     * 
    1.49 +     * @param a
    1.50 +     * @return <code>true</code> or <code>false</code>
    1.51 +     */
    1.52      public boolean isSupported(Audio a);
    1.53  }