Issue eclipse-archived#1021: Implementation of STT Interfaces

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

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/AudioStartEvent.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 {@link STTEvent} fired when the {@link STTService} starts hearing audio.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public class AudioStartEvent implements STTEvent {
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/AudioStopEvent.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 {@link STTEvent} fired when the {@link STTService} stops hearing audio.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public class AudioStopEvent implements STTEvent {
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/RecognitionStartEvent.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 {@link STTEvent} fired when the {@link STTService} starts recognition.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public class RecognitionStartEvent implements STTEvent {
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/RecognitionStopEvent.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 {@link STTEvent} fired when the {@link STTService} stops recognition.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public class RecognitionStopEvent implements STTEvent {
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/STTEvent.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 speech-to-text events.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public interface STTEvent {
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/STTException.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 STT exception
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public class STTException extends Exception {
+
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * Constructs a new exception with null as its detail message.
+ */
+ public STTException() {
+ super();
+ }
+
+ /**
+ * Constructs a new exception with the specified detail message and cause.
+ *
+ * @param message Detail message
+ * @param cause The cause
+ */
+ public STTException(String message, Throwable cause) {
+ super(message, cause);
+ }
+
+ /**
+ * Constructs a new exception with the specified detail message.
+ *
+ * @param message Detail message
+ */
+ public STTException(String message) {
+ super(message);
+ }
+
+ /**
+ * Constructs a new exception with the specified cause.
+ *
+ * @param cause The cause
+ */
+ public STTException(Throwable cause) {
+ super(cause);
+ }
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/STTListener.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 STTEvent} events.
+ *
+ * A class interested in processing {@link STTEvent} events implements this interface,
+ * and its instances are passed to the {@code STTService}'s {@code recognize()} method.
+ * Such instances are then targeted for various {@link STTEvent} events corresponding
+ * to the speech recognition process.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public interface STTListener {
+ /**
+ * Invoked wwhen a {@link STTEvent} event occurs during speech recognition.
+ *
+ * @param sttEvent The {@link STTEvent} fired by the {@link STTService}
+ */
+ public void sttEventReceived(STTEvent sttEvent);
+}

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

@@ -0,0 +1,65 @@
+/**
+ * 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 speech-to-text service has to implement.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public interface STTService {
+ /**
+ * Obtain the Locales available from this STTService
+ *
+ * @return The Locales available from this service
+ */
+ public Set<Locale> getSupportedLocales();
+
+ /**
+ * Obtain the audio formats supported by this STTService
+ *
+ * @return The audio formats supported by this service
+ */
+ public Set<AudioFormat> getSupportedFormats();
+
+ /**
+ * This method starts the process of speech recognition.
+ *
+ * The audio data of the passed {@link AudioSource} is passed to the speech
+ * recognition engine. The recognition engine attempts to recognize speech
+ * as being spoken in the passed {@code Locale} and containing statements
+ * specified in the passed {@code grammars}. Recognition is indicated by
+ * fired {@link STTEvent} events targeting the passed {@link STTListener}.
+ *
+ * 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 grammars} must consist of a syntatically valid grammar
+ * as specified by the JSpeech Grammar Format. If {@code grammars} is null
+ * or empty, large vocabulary continuous speech recognition is attempted.
+ *
+ * @see <a href="https://www.w3.org/TR/jsgf/">JSpeech Grammar Format.</a>
+ * @param sttListener Non-null {@link STTListener} that {@link STTEvent} events target
+ * @param audioSource The {@link AudioSource} from which speech is recognized
+ * @param locale The {@code Locale} in which the target speech is spoken
+ * @param grammars The JSpeech Grammar Format grammar specifying allowed statements
+ * @return A {@link STTServiceHandle} used to abort recognition
+ * @throws A {@link SSTException} if any paramater is invalid or a STT problem occurs
+ */
+ public STTServiceHandle recognize(STTListener sttListener, AudioSource audioSource, Locale locale, Set<String> grammars) throws STTException;
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/STTServiceHandle.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 STTService}
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public interface STTServiceHandle {
+ /**
+ * Aborts recognition in the associated {@link STTService}
+ */
+ public void abort();
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/SpeechRecognitionErrorEvent.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 STTEvent} fired when the {@link STTService} encounters an error.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public class SpeechRecognitionErrorEvent implements STTEvent {
+ /**
+ * 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 SpeechRecognitionErrorEvent(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/SpeechRecognitionEvent.java

@@ -0,0 +1,69 @@
+/**
+ * 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 STTEvent} fired when the {@link STTService} recognizes speech.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public class SpeechRecognitionEvent implements STTEvent {
+ /**
+ * Confidence of recognized speech
+ */
+ private final float confidence;
+
+ /**
+ * Transcript of recognized speech
+ */
+ private final String transcript;
+
+ /**
+ * Constructs an instance with the passed {@code transcript} and {@code confidence}.
+ *
+ * The confidence represents a numeric estimate between 0 and 1, inclusively, of how
+ * confident the recognition engine is of the transcript. A higher number means the
+ * system is more confident.
+ *
+ * @param transcript The transcript of the recognized speech
+ * @param confidence The confidence of the transcript
+ */
+ public SpeechRecognitionEvent(String transcript, float confidence) {
+ if ((null == transcript) || (transcript.isEmpty())) {
+ throw new IllegalArgumentException("The passed transcript is null or empty");
+ }
+ if ((confidence < 0.0) || (1.0 < confidence)) {
+ throw new IllegalArgumentException("The passed confidence is less than 0.0 or greater than 1.0");
+ }
+
+ this.transcript = transcript;
+ this.confidence = confidence;
+ }
+
+ /**
+ * Returns the transcript of the recognized speech.
+ *
+ * @return The transcript of the recognized speech.
+ */
+ public String getTranscript() {
+ return this.transcript;
+ }
+
+ /**
+ * Returns the confidence of the transcript.
+ *
+ * The confidence represents a numeric estimate between 0 and 1, inclusively, of how
+ * confident the recognition engine is of the transcript. A higher number means the
+ * system is more confident.
+ *
+ * @return The transcript of the recognized speech.
+ */
+ public float getConfidence() {
+ return this.confidence;
+ }
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/SpeechStartEvent.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 {@link STTEvent} fired when the {@link STTService} starts hearing speech.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public class SpeechStartEvent implements STTEvent {
+}

bundles/io/org.eclipse.smarthome.io.voice/src/main/java/org/eclipse/smarthome/io/voice/SpeechStopEvent.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 {@link STTEvent} fired when the {@link STTService} stops hearing speech.
+ *
+ * @author Kelly Davis - Initial contribution and API
+ */
+public class SpeechStopEvent implements STTEvent {
+}