From 34f18f9766862acd29b8e231313b82d47095891f Mon Sep 17 00:00:00 2001 From: Kelly Davis Date: Thu, 17 Mar 2016 10:42:25 +0100 Subject: [PATCH] Issue #1162: Implementation of Keyword Spotting API Signed-off-by: Kelly Davis --- .../eclipse/smarthome/io/voice/KSEvent.java | 16 +++++ .../smarthome/io/voice/KSException.java | 53 ++++++++++++++++ .../smarthome/io/voice/KSListener.java | 27 ++++++++ .../eclipse/smarthome/io/voice/KSService.java | 61 +++++++++++++++++++ .../smarthome/io/voice/KSServiceHandle.java | 20 ++++++ .../io/voice/KeywordSpottingErrorEvent.java | 38 ++++++++++++ .../io/voice/KeywordSpottingEvent.java | 44 +++++++++++++ 7 files changed, 259 insertions(+) create mode 100644 bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSEvent.java create mode 100644 bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSException.java create mode 100644 bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSListener.java create mode 100644 bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSService.java create mode 100644 bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSServiceHandle.java create mode 100644 bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KeywordSpottingErrorEvent.java create mode 100644 bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KeywordSpottingEvent.java diff --git a/bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSEvent.java b/bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSEvent.java new file mode 100644 index 00000000000..d3e009a86a2 --- /dev/null +++ b/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 { +} diff --git a/bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSException.java b/bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSException.java new file mode 100644 index 00000000000..41a8ee0934e --- /dev/null +++ b/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); + } +} diff --git a/bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSListener.java b/bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSListener.java new file mode 100644 index 00000000000..455cdb64523 --- /dev/null +++ b/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); +} diff --git a/bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSService.java b/bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSService.java new file mode 100644 index 00000000000..4206e0384c7 --- /dev/null +++ b/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 getSupportedLocales(); + + /** + * Obtain the audio formats supported by this KSService + * + * @return The audio formats supported by this service + */ + public Set 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; +} diff --git a/bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSServiceHandle.java b/bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KSServiceHandle.java new file mode 100644 index 00000000000..0b5f384e307 --- /dev/null +++ b/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(); +} diff --git a/bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KeywordSpottingErrorEvent.java b/bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KeywordSpottingErrorEvent.java new file mode 100644 index 00000000000..62c00763173 --- /dev/null +++ b/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; + } +} diff --git a/bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KeywordSpottingEvent.java b/bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/KeywordSpottingEvent.java new file mode 100644 index 00000000000..4479b65cae3 --- /dev/null +++ b/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; + } +}