Add additional endpoints and fields for Audio Clips

Author: nightowlengineer

src/main/java/engineer/nightowl/sonos/api/domain/SonosAudioClip.java

@@ -1,7 +1,11 @@
 package engineer.nightowl.sonos.api.domain;
 
+import engineer.nightowl.sonos.api.enums.SonosAudioClipErrorCode;
+import engineer.nightowl.sonos.api.enums.SonosClipState;
 import engineer.nightowl.sonos.api.enums.SonosClipType;
 import engineer.nightowl.sonos.api.enums.SonosPriority;
+import org.apache.commons.lang3.builder.EqualsBuilder;
+import org.apache.commons.lang3.builder.HashCodeBuilder;
 
 import java.net.URI;
 
@@ -16,7 +20,11 @@ public class SonosAudioClip {
     private String appId;
     private SonosPriority priority;
     private SonosClipType clipType;
+    private SonosClipState status;
+    private SonosAudioClipErrorCode errorCode;
+    private String httpAuthorization;
     private URI streamUrl;
+    private Integer volume;
 
     /**
      * Default constructor
@@ -26,22 +34,31 @@ public SonosAudioClip() {
 
     /**
      * Full args constructor
-     *
-     * @param id        Sonos generates this unique identifier and assigned to the audio clip.
-     * @param name      User identifiable string.
-     * @param appId     This string identifies the app that created the audioClip. Companies should use their reversed Internet domain name as the identifier, similar to com.acme.app.
-     * @param priority  (Optional) Clip priority. Clips are low priority by default (not yet implemented).
-     * @param clipType  (Optional) Sonos plays a built-in sound when this option is provided. The default value is CHIME.
-     * @param streamUrl (Optional) Sonos will play this URL when you provide one. The caller does not need to specify a CUSTOM clipType in addition to providing the streamUrl. Sonos supports only MP3 or WAV files as audio clips.
+     * @param id                Sonos generates this unique identifier and assigned to the audio clip.
+     * @param name              User identifiable string.
+     * @param appId             This string identifies the app that created the audioClip. Companies should use their reversed Internet domain name as the identifier, similar to com.acme.app.
+     * @param priority          (Optional) Clip priority. Clips are low priority by default (not yet implemented).
+     * @param clipType          (Optional) Sonos plays a built-in sound when this option is provided. The default value is CHIME.
+     * @param status            This field indicates the state of the audio clip, for example, if it’s active, it’s currently playing. Audio clips transition from pending (on load) to active to done. Sonos returns the state only in events.
+     * @param errorCode         (Optional) Custom error code for audio clips.
+     * @param streamUrl         (Optional) Sonos will play this URL when you provide one. The caller does not need to specify a CUSTOM clipType in addition to providing the streamUrl. Sonos supports only MP3 or WAV files as audio clips.
+     * @param httpAuthorization (Optional) Set a string to pass in the Authorization header when fetching the streamUrl. Omit this parameter to omit the Authorization header. Sonos includes the Authorization header when the streamUrl is secure (HTTPS). Sonos supports an httpAuthorization value up to 512 bytes.
+     * @param volume            (Optional) Audio Clip playback volume, between 0 and 100. There are internal upper and lower limits for the audio clip volume level in order to prevent the audio clip from being too loud or inaudible.
+     *                  If the parameter is beyond those limits, Sonos automatically adjusts the audio clip volume to the lower or upper limit. The default behavior is to playback at the current player volume.
      */
     public SonosAudioClip(final String id, final String name, final String appId, final SonosPriority priority,
-                          final SonosClipType clipType, final URI streamUrl) {
+                          final SonosClipType clipType, final SonosClipState status, final SonosAudioClipErrorCode errorCode,
+                          final URI streamUrl, final String httpAuthorization, final Integer volume) {
         this.id = id;
         this.name = name;
         this.appId = appId;
         this.priority = priority;
         this.clipType = clipType;
+        this.status = status;
+        this.errorCode = errorCode;
         this.streamUrl = streamUrl;
+        this.httpAuthorization = httpAuthorization;
+        this.volume = volume;
     }
 
     public String getId() {
@@ -76,6 +93,16 @@ public void setPriority(final SonosPriority priority) {
         this.priority = priority;
     }
 
+    public SonosAudioClipErrorCode getErrorCode()
+    {
+        return errorCode;
+    }
+
+    public void setErrorCode(SonosAudioClipErrorCode errorCode)
+    {
+        this.errorCode = errorCode;
+    }
+
     public SonosClipType getClipType() {
         return clipType;
     }
@@ -92,15 +119,90 @@ public void setStreamUrl(final URI streamUrl) {
         this.streamUrl = streamUrl;
     }
 
+    public SonosClipState getStatus()
+    {
+        return status;
+    }
+
+    public void setStatus(SonosClipState status)
+    {
+        this.status = status;
+    }
+
+    public String getHttpAuthorization()
+    {
+        return httpAuthorization;
+    }
+
+    public void setHttpAuthorization(String httpAuthorization)
+    {
+        this.httpAuthorization = httpAuthorization;
+    }
+
+    public Integer getVolume()
+    {
+        return volume;
+    }
+
+    public void setVolume(Integer volume)
+    {
+        this.volume = volume;
+    }
+
     @Override
-    public String toString() {
+    public String toString()
+    {
         return "SonosAudioClip{" +
                 "id='" + id + '\'' +
                 ", name='" + name + '\'' +
                 ", appId='" + appId + '\'' +
                 ", priority=" + priority +
                 ", clipType=" + clipType +
+                ", status=" + status +
+                ", errorCode=" + errorCode +
+                ", httpAuthorization='" + httpAuthorization + '\'' +
                 ", streamUrl=" + streamUrl +
+                ", volume=" + volume +
                 '}';
     }
+
+    @Override
+    public boolean equals(Object o)
+    {
+        if (this == o) return true;
+
+        if (o == null || getClass() != o.getClass()) return false;
+
+        SonosAudioClip that = (SonosAudioClip) o;
+
+        return new EqualsBuilder()
+                .append(id, that.id)
+                .append(name, that.name)
+                .append(appId, that.appId)
+                .append(priority, that.priority)
+                .append(clipType, that.clipType)
+                .append(status, that.status)
+                .append(errorCode, that.errorCode)
+                .append(httpAuthorization, that.httpAuthorization)
+                .append(streamUrl, that.streamUrl)
+                .append(volume, that.volume)
+                .isEquals();
+    }
+
+    @Override
+    public int hashCode()
+    {
+        return new HashCodeBuilder(17, 37)
+                .append(id)
+                .append(name)
+                .append(appId)
+                .append(priority)
+                .append(clipType)
+                .append(status)
+                .append(errorCode)
+                .append(httpAuthorization)
+                .append(streamUrl)
+                .append(volume)
+                .toHashCode();
+    }
 }

src/main/java/engineer/nightowl/sonos/api/enums/SonosAudioClipErrorCode.java

@@ -0,0 +1,25 @@
+package engineer.nightowl.sonos.api.enums;
+
+/**
+ * <p>SonosSessionErrorCode class.</p>
+ */
+public enum SonosAudioClipErrorCode implements SonosErrorBase
+{
+    ERROR_AUDIO_CLIP_DO_NOT_DISTURB("The user has enabled “do not disturb” mode, which temporarily disables audio clips (not yet implemented)."),
+    ERROR_AUDIO_CLIP_ID_NOT_FOUND("The specified audio clip id was not recognized by the player. This may be because the player purged it from memory. Players purge audio clips from memory after playing them."),
+    ERROR_AUDIO_CLIP_MEDIA_ERROR("The media type is not supported by Sonos."),
+    ERROR_AUDIO_CLIP_CANCEL("The clip was canceled before activation. When canceled, the status of the clip moves from pending to dismissed."),
+    ERROR_AUDIO_CLIP_EXPIRE("The clip expired prior to activation.");
+
+    private String errorMessage;
+
+    SonosAudioClipErrorCode(final String errorMessage)
+    {
+        this.errorMessage = errorMessage;
+    }
+
+    public String getErrorMessage()
+    {
+        return errorMessage;
+    }
+}

src/main/java/engineer/nightowl/sonos/api/enums/SonosClipState.java

@@ -0,0 +1,22 @@
+package engineer.nightowl.sonos.api.enums;
+
+public enum SonosClipState
+{
+    ACTIVE("Currently playing"),
+    DISMISSED("Dismissed"),
+    DONE("Playback complete"),
+    INTERRUPTED("Playback interrupted, for example, by a high priority audio clip"),
+    PENDING("Scheduled for playback, but not active");
+
+    private String extraInfo;
+
+    SonosClipState(final String extraInfo)
+    {
+        this.extraInfo = extraInfo;
+    }
+
+    public String getExtraInfo()
+    {
+        return extraInfo;
+    }
+}

src/main/java/engineer/nightowl/sonos/api/resource/AudioClipResource.java

@@ -2,6 +2,7 @@
 
 import engineer.nightowl.sonos.api.SonosApiClient;
 import engineer.nightowl.sonos.api.domain.SonosAudioClip;
+import engineer.nightowl.sonos.api.domain.SonosSuccess;
 import engineer.nightowl.sonos.api.exception.SonosApiClientException;
 import engineer.nightowl.sonos.api.exception.SonosApiError;
 
@@ -21,7 +22,7 @@ public AudioClipResource(final SonosApiClient apiClient) {
     }
 
     /**
-     * Schedule a provided audioClip for playback. Only supported by Sonos One and Beam
+     * Schedule a provided audioClip for playback
      *
      * @param clientToken for the user
      * @param playerId    to play the audioClip on
@@ -36,4 +37,20 @@ public SonosAudioClip loadAudioClip(final String clientToken, final String playe
         return postToApi(SonosAudioClip.class, clientToken, String.format("/v1/players/%s/audioClip", playerId), audioClip);
     }
 
+    /**
+     * Cancel a specified audioClip via its ID.
+     *
+     * @param clientToken for the user
+     * @param playerId    the audioClip is scheduled to play on
+     * @param clipId      of the audioClip
+     * @return whether the clip was cancelled
+     * @throws engineer.nightowl.sonos.api.exception.SonosApiClientException if an error occurs during the call
+     * @throws engineer.nightowl.sonos.api.exception.SonosApiError           if there is an error from the API
+     * @see <a href="https://developer.sonos.com/reference/control-api/audioclip/loadaudioclip/">Sonos docs</a>
+     */
+    public SonosSuccess cancelAudioClip(final String clientToken, final String playerId, final String clipId)
+            throws SonosApiClientException, SonosApiError {
+        return deleteFromApi(SonosSuccess.class, clientToken, String.format("/v1/players/%s/audioClip/%s", playerId, clipId));
+    }
+
 }