Issue eclipse-archived#1162: Implementation of Keyword Spotting API

Signed-off-by: Kelly Davis <kdavis@mozilla.com>

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSEvent.java

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2014-2016 openHAB UG (haftungsbeschraenkt) and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.eclipse.smarthome.io.voice;
+
+/**
+ * A tagging interface for keyword spotting events.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public interface KSEvent {
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSException.java

@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) 2014-2016 openHAB UG (haftungsbeschraenkt) and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.eclipse.smarthome.io.voice;
+
+/**
+ * General purpose keyword spotting exception
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public class KSException extends Exception {
+
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * Constructs a new exception with null as its detail message.
+ */
+ public KSException() {
+ super();
+ }
+
+ /**
+ * Constructs a new exception with the specified detail message and cause.
+ *
+ * @param message Detail message
+ * @param cause The cause
+ */
+ public KSException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new exception with the specified detail message.
+ *
+ * @param message Detail message
+ */
+ public KSException(String message) {
+ super(message);
+ }
+
+ /**
+ * Constructs a new exception with the specified cause.
+ *
+ * @param cause The cause
+ */
+ public KSException(Throwable cause) {
+ super(cause);
+ }
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSListener.java

@@ -0,0 +1,27 @@
+/**
+ * Copyright (c) 2014-2016 openHAB UG (haftungsbeschraenkt) and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.eclipse.smarthome.io.voice;
+
+/**
+ * The listener interface for receiving {@link KSEvent} events.
+ *
+ * A class interested in processing {@link KSEvent} events implements this interface,
+ * and its instances are passed to the {@code KSService}'s {@code spot()} method.
+ * Such instances are then targeted for various {@link KSEvent} events corresponding
+ * to the keyword spotting process.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public interface KSListener {
+ /**
+ * Invoked wwhen a {@link KSEvent} event occurs during keyword spotting.
+ *
+ * @param ksEvent The {@link KSEvent} fired by the {@link KSService}
+ */
+ public void ksEventReceived(KSEvent ksEvent);
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSService.java

@@ -0,0 +1,61 @@
+/**
+ * Copyright (c) 2014-2016 openHAB UG (haftungsbeschraenkt) and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.eclipse.smarthome.io.voice;
+
+import java.util.Locale;
+import java.util.Set;
+
+import org.eclipse.smarthome.io.audio.AudioFormat;
+import org.eclipse.smarthome.io.audio.AudioSource;
+
+/**
+ * This is the interface that a keyword spotting service has to implement.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public interface KSService {
+ /**
+ * Obtain the Locales available from this KSService
+ *
+ * @return The Locales available from this service
+ */
+ public Set<Locale> getSupportedLocales();
+
+ /**
+ * Obtain the audio formats supported by this KSService
+ *
+ * @return The audio formats supported by this service
+ */
+ public Set<AudioFormat> getSupportedFormats();
+
+ /**
+ * This method starts the process of keyword spotting
+ *
+ * The audio data of the passed {@link AudioSource} is passed to the keyword
+ * spotting engine. The keyword spotting attempts to spot {@code keyword} as
+ * being spoken in the passed {@code Locale}. Spotted keyword is indicated by
+ * fired {@link KSEvent} events targeting the passed {@link KSListener}.
+ *
+ * The passed {@link AudioSource} must be of a supported {@link AudioFormat}.
+ * In other words a {@link AudioFormat} compatable with one returned from
+ * the {@code getSupportedFormats()} method.
+ *
+ * The passed {@code Locale} must be supported. That is to say it must be
+ * a {@code Locale} returned from the {@code getSupportedLocales()} method.
+ *
+ * The passed {@code keyword} is the keyword which should be spotted.
+ *
+ * @param ksListener Non-null {@link KSListener} that {@link KSEvent} events target
+ * @param audioSource The {@link AudioSource} from which keywords are spotted
+ * @param locale The {@code Locale} in which the target keywords are spoken
+ * @param keyword The keyword which to spot
+ * @return A {@link KSServiceHandle} used to abort keyword spotting
+ * @throws A {@link KSException} if any paramater is invalid or a problem occurs
+ */
+ public KSServiceHandle spot(KSListener ksListener, AudioSource audioSource, Locale locale, String keyword) throws KSException;
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSServiceHandle.java

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) 2014-2016 openHAB UG (haftungsbeschraenkt) and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.eclipse.smarthome.io.voice;
+
+/**
+ * An handle to a {@link KSService}
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public interface KSServiceHandle {
+ /**
+ * Aborts keyword spotting in the associated {@link KSService}
+ */
+ public void abort();
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KeywordSpottingErrorEvent.java

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) 2014-2016 openHAB UG (haftungsbeschraenkt) and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.eclipse.smarthome.io.voice;
+
+/**
+ * A {@link KSEvent} fired when the {@link KSService} encounters an error.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public class KeywordSpottingErrorEvent implements KSEvent {
+ /**
+ * The message describing the error
+ */
+ private final String message;
+
+ /**
+ * Constructs an instance with the passed {@code message}.
+ *
+ * @param message The message describing the error
+ */
+ public KeywordSpottingErrorEvent(String message) {
+ this.message = message;
+ }
+
+ /**
+ * Gets the message describing this error
+ *
+ * @return The message describing this error
+ */
+ public String getMessage() {
+ return this.message;
+ }
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KeywordSpottingEvent.java

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) 2014-2016 openHAB UG (haftungsbeschraenkt) and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ */
+package org.eclipse.smarthome.io.voice;
+
+import org.eclipse.smarthome.io.audio.AudioSource;
+
+/**
+ * A {@link KSEvent} fired when the {@link KSService} spots a keyword.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public class KeywordSpottingEvent implements KSEvent {
+ /**
+ * AudioSource from which the keyword was spotted 
+ */
+ private final AudioSource audioSource;
+
+ /**
+ * Constructs an instance with the passed {@code audioSource}
+ *
+ * @param audioSource The AudioSource of the spotted keyword 
+ */
+ public KeywordSpottingEvent(AudioSource audioSource) {
+ if (null == audioSource) {
+ throw new IllegalArgumentException("The passed audioSource is null");
+ }
+
+ this.audioSource = audioSource;
+ }
+
+ /**
+ * Returns the audioSource of the spotted keyword
+ *
+ * @return The audioSource of the spotted keyword
+ */
+ public AudioSource getAudioSource() {
+ return this.audioSource;
+ }
+}