Applied some documentation within the code.

Author: FranRiadigos

app/src/main/java/com/chattylabs/demo/voice/CustomConversationActivity.java

@@ -158,14 +158,14 @@ private void listen(int index) {
                     }
                 }
             }
-            synthesizer.releaseCurrentQueue();
+            synthesizer.freeCurrentQueue();
             if (synthesizer.isEmpty()) {
                 component.shutdown();
             } else synthesizer.resume();
         }, (RecognizerListener.OnError) (i, i1) -> {
             Log.e(TAG, "Error " + i);
 
-            synthesizer.releaseCurrentQueue();
+            synthesizer.freeCurrentQueue();
             if (synthesizer.isEmpty()) {
                 component.shutdown();
             } else synthesizer.resume();

sdk-addon-android-speech/src/main/java/com/chattylabs/sdk/android/voice/AndroidSpeechRecognizer.java

@@ -42,10 +42,8 @@ public final class AndroidSpeechRecognizer extends BaseSpeechRecognizer {
                             ComponentConfig configuration,
                             AndroidAudioManager audioManager,
                             BluetoothSco bluetoothSco,
-                            Creator<SpeechRecognizer>
-                                    recognizerCreator,
                             ILogger logger) {
-        super(configuration, bluetoothSco, audioManager, logger);
+        super(configuration, audioManager, bluetoothSco, logger);
         this.application = application;
         this.release();
         this.mainHandler = new AndroidHandlerImpl(Looper.getMainLooper());
@@ -54,7 +52,7 @@ public final class AndroidSpeechRecognizer extends BaseSpeechRecognizer {
         this.speechRecognizerIntent.putExtra(RecognizerIntent.EXTRA_CALLING_PACKAGE, application.getPackageName());
         this.speechRecognizerIntent.putExtra(RecognizerIntent.EXTRA_PARTIAL_RESULTS, true);
         this.speechRecognizerIntent.putExtra(RecognizerIntent.EXTRA_SPEECH_INPUT_POSSIBLY_COMPLETE_SILENCE_LENGTH_MILLIS, 5000L);
-        this.recognizerCreator = recognizerCreator;
+        this.recognizerCreator = () -> SpeechRecognizer.createSpeechRecognizer(application);
     }
 
     private final AndroidSpeechRecognitionAdapter listener = new AndroidSpeechRecognitionAdapter() {

sdk-addon-google-speech/src/main/java/com/chattylabs/sdk/android/voice/GoogleSpeechRecognizer.java

@@ -59,7 +59,7 @@ public final class GoogleSpeechRecognizer extends BaseSpeechRecognizer {
                            AndroidAudioManager audioManager,
                            BluetoothSco bluetoothSco,
                            ILogger logger) {
-        super(configuration, bluetoothSco, audioManager, logger);
+        super(configuration, audioManager, bluetoothSco, logger);
         this.application = application;
         this.release();
         this.serialThread = ThreadUtils.newSerialThread();

sdk-addon-google-speech/src/main/java/com/chattylabs/sdk/android/voice/GoogleSpeechSynthesizerAdapter.java

@@ -1,6 +1,5 @@
 package com.chattylabs.sdk.android.voice;
 
-import static com.chattylabs.sdk.android.voice.ConversationalFlowComponent.*;
 
 abstract class GoogleSpeechSynthesizerAdapter implements SynthesizerUtteranceListener {
     private SynthesizerListener.OnStart onStartedListener;

sdk-conversational-flow-core/src/main/java/com/chattylabs/sdk/android/voice/AndroidAudioManager.java

@@ -12,10 +12,10 @@ public class AndroidAudioManager {
     private static final String TAG = Tag.make("AndroidAudioHandler");
 
     // States
-    private boolean requestAudioFocusMayDuck; // released
-    private boolean requestAudioFocusExclusive; // released
-    private boolean requestAudioExclusive; // released
-    private int audioMode = AudioManager.MODE_CURRENT; // released
+    private boolean requestAudioFocusMayDuck;
+    private boolean requestAudioFocusExclusive;
+    private boolean requestAudioExclusive;
+    private int audioMode = AudioManager.MODE_CURRENT;
 
     private int dtmfVolume;
     private int systemVolume;
@@ -138,9 +138,9 @@ public void setAudioMode() {
                 AudioManager.MODE_IN_CALL :
                 AudioManager.MODE_NORMAL);
 
-        // Enabling this option, the audio is not rooted to the speakers if the sco is activated
-        // Meaning that we can force bluetooth sco even with speakers connected
-        // Nice to have feature!
+        // By enabling this option, the audio is not rooted to the speakers if the sco is activated
+        // meaning that we can force bluetooth sco even with speakers connected
+        // TODO: Nice to have feature!
         //speakerphoneOn = audioManager.isSpeakerphoneOn();
         //boolean isHeadsetConnected = peripheral.get(Peripheral.Type.HEADSET).isConnected();
         //if (!isHeadsetConnected) { audioManager.setSpeakerphoneOn(!isBluetoothScoRequired()); }
@@ -150,13 +150,13 @@ public void setAudioMode() {
     public void unsetAudioMode() {
         audioManager.setMode(audioMode);
 
-        // Enabling this option, the audio is not rooted to the speakers if the sco is activated
-        // Meaning that we can force bluetooth sco even with speakers connected
-        // Nice to have feature!
+        // By enabling this option, the audio is not rooted to the speakers if the sco is activated
+        // meaning that we can force bluetooth sco even with speakers connected
+        // TODO: Nice to have feature!
         //audioManager.setSpeakerphoneOn(speakerphoneOn);
     }
 
-    private void adjustVolumeForBeep() {
+    private void setStreamToMaxVolume() {
         // Volume
         dtmfVolume = audioManager.getStreamVolume(AudioManager.STREAM_DTMF);
         audioManager.setStreamVolume(AudioManager.STREAM_DTMF, audioManager.getStreamMaxVolume(AudioManager.STREAM_DTMF), 0);
@@ -174,7 +174,7 @@ private void adjustVolumeForBeep() {
         audioManager.setStreamVolume(AudioManager.STREAM_VOICE_CALL, audioManager.getStreamMaxVolume(AudioManager.STREAM_VOICE_CALL), 0);
     }
 
-    private void resetVolumeForBeep() {
+    private void resetVolumeToDefaultValues() {
         // Volume
         audioManager.setStreamVolume(AudioManager.STREAM_DTMF, dtmfVolume, 0);
         audioManager.setStreamVolume(AudioManager.STREAM_SYSTEM, systemVolume, 0);

sdk-conversational-flow-core/src/main/java/com/chattylabs/sdk/android/voice/AndroidAudioRecorder.java

@@ -43,7 +43,7 @@ public class AndroidAudioRecorder {
     private static final int NO_SPEECH_TIMEOUT_MILLIS = 4000;
     private static final int MAX_SPEECH_LENGTH_MILLIS = 30 * 1000;
 
-    public static abstract class Callback {
+    public abstract static class Callback {
 
         /**
          * Called when the recorder starts hearing voice.
@@ -201,8 +201,14 @@ private AudioRecord createAudioRecord() {
     }
 
     /**
-     * Continuously processes the captured audio and notifies {@link #mCallback} of corresponding
+     * Continuously processes the captured audio and notifies {@link Callback} of corresponding
      * events.
+     * <p/>
+     * If no sound is recorder for more than the value of {@link #setNoSpeechTimeout(int)} it notifies
+     * {@link Callback#onVoiceError(int)} with {@link SpeechRecognizer#ERROR_SPEECH_TIMEOUT}.
+     * <p/>
+     * If sound is recorder for more than the value of {@link #setMaxSpeechLength(int)} it notifies
+     * {@link Callback#onVoiceEnd()}.
      */
     private class ProcessVoice implements Runnable {
 

sdk-conversational-flow-core/src/main/java/com/chattylabs/sdk/android/voice/BaseSpeechRecognizer.java

@@ -4,6 +4,25 @@
 
 import com.chattylabs.sdk.android.common.internal.ILogger;
 
+/**
+ * When implementing from this class you must create a constructor that receives the following parameters
+ * in the same order:
+ * <p/>
+ * <pre>{@code
+ * public Constructor(Application, ComponentConfig, AndroidAudioManager, BluetoothSco, ILogger) {
+ *     super(ComponentConfig, AndroidAudioManager, BluetoothSco, ILogger);
+ *     //...
+ * }
+ * }</pre>
+ * Otherwise the addon initialization will throw and Exception on runtime.
+ *
+ * @see SpeechRecognizerComponent
+ * @see android.app.Application
+ * @see ComponentConfig
+ * @see AndroidAudioManager
+ * @see BluetoothSco
+ * @see ILogger
+ */
 abstract class BaseSpeechRecognizer implements SpeechRecognizerComponent {
     // Minimum constants
     int MIN_VOICE_RECOGNITION_TIME_LISTENING = 2000;
@@ -17,9 +36,9 @@ abstract class BaseSpeechRecognizer implements SpeechRecognizerComponent {
     protected final ILogger logger;
 
     BaseSpeechRecognizer(ComponentConfig configuration,
-                                BluetoothSco bluetoothSco,
-                                AndroidAudioManager audioManager,
-                                ILogger logger) {
+                         AndroidAudioManager audioManager,
+                         BluetoothSco bluetoothSco,
+                         ILogger logger) {
         this.configuration = configuration;
         this.bluetoothSco = bluetoothSco;
         this.audioManager = audioManager;
@@ -47,6 +66,10 @@ void abandonAudioFocus() {
         audioManager.abandonAudioFocus();
     }
 
+    /**
+     * Setting this option will forward a flag onto the {@link RecognizerUtteranceListener} implementation.
+     * <br/>The developer can then opt to record again the user voice as a second chance if there is no match.
+     */
     public void setTryAgain(boolean tryAgain) {
         getRecognitionListener().setTryAgain(tryAgain);
     }
@@ -83,7 +106,7 @@ public void shutdown() {
     @CallSuper
     @Override
     public void release() {
-
+        // No resources to release at this level
     }
 
     private void handleListeners(RecognizerListener... listeners) {

sdk-conversational-flow-core/src/main/java/com/chattylabs/sdk/android/voice/BaseSpeechSynthesizer.java

@@ -18,11 +18,29 @@
 
 import static com.chattylabs.sdk.android.voice.ConversationalFlowComponent.TAG;
 
+/**
+ * When implementing from this class you must create a constructor that receives the following parameters
+ * in the same order:
+ * <p/>
+ * <pre>{@code
+ * public Constructor(Application, ComponentConfig, AndroidAudioManager, BluetoothSco, ILogger) {
+ *     super(ComponentConfig, AndroidAudioManager, BluetoothSco, ILogger);
+ *     //...
+ * }
+ * }</pre>
+ * Otherwise the addon initialization will throw and Exception on runtime.
+ *
+ * @see SpeechSynthesizerComponent
+ * @see android.app.Application
+ * @see ComponentConfig
+ * @see AndroidAudioManager
+ * @see BluetoothSco
+ * @see ILogger
+ */
 abstract class BaseSpeechSynthesizer implements SpeechSynthesizerComponent {
 
-    String DEFAULT_QUEUE_ID = "default_queue_id";
-
     // Constants
+    static final String DEFAULT_QUEUE_ID = "com.chattylabs.sdk.android.voice:default_queue_id";
     private static final String DEFAULT_UTTERANCE_ID = "u:";
     private static final String MAP_UTTERANCE_ID = "utteranceId";
     private static final String MAP_SILENCE = "silence";
@@ -37,13 +55,13 @@ abstract class BaseSpeechSynthesizer implements SpeechSynthesizerComponent {
     private final Object lock = new Object();
 
     // States
-    private boolean isReady; // released
-    private boolean isOnHold; // released
-    private boolean isSpeaking; // released
+    private boolean isReady;
+    private boolean isOnHold;
+    private boolean isSpeaking;
 
     // Resources
-    private String queueId = DEFAULT_QUEUE_ID; // released
-    private SynthesizerUtteranceListener synthesizerUtteranceListener; // released
+    private String queueId = DEFAULT_QUEUE_ID;
+    private SynthesizerUtteranceListener synthesizerUtteranceListener;
     private String lastQueueId;
     private final AndroidAudioManager audioManager;
     private final BluetoothSco bluetoothSco;
@@ -282,7 +300,7 @@ public  <T extends SynthesizerListener> void playSilence(long durationInMillis,
     }
 
     @Override
-    public void releaseCurrentQueue() {
+    public void freeCurrentQueue() {
         logger.w(TAG, "TTS - isOnHold set to false");
         isOnHold = false;
     }
@@ -303,7 +321,7 @@ public void stop() {
         // Audio focus
         audioManager.abandonAudioFocus();
         setSpeaking(false);
-        releaseCurrentQueue();
+        freeCurrentQueue();
     }
 
     @CallSuper
@@ -315,7 +333,7 @@ public void release() {
             queue.put(DEFAULT_QUEUE_ID, new ConcurrentLinkedQueue<>());
         }
         queueId = DEFAULT_QUEUE_ID;
-        releaseCurrentQueue();
+        freeCurrentQueue();
         setReady(false);
         setSpeaking(false);
         logger.v(TAG, "TTS - states and resources released");
@@ -346,7 +364,6 @@ public void resume() {
     }
 
     private void run() {
-        // This is useless because it is being called already in onDone and onError
         moveToNextQueueIfNeeded();
         if (!isEmpty()) {
             // Gets and plays the current message in the queue
@@ -387,7 +404,7 @@ private void playTheCurrentQueue(Map<String, Object> map) {
                 @Override
                 public void onConnected() {
                     logger.i(getTag(), "TTS - Sco onConnected");
-                    runMap(map);
+                    chooseItemToPlay(map);
                 }
 
                 @Override
@@ -405,11 +422,11 @@ public void onDisconnected() {
         }
         else {
             logger.v(getTag(), "TTS - bluetooth sco is: %s", (bluetoothSco.isBluetoothScoOn() ? "on" : "off"));
-            runMap(map);
+            chooseItemToPlay(map);
         }
     }
 
-    private void runMap(Map<String, Object> map) {
+    private void chooseItemToPlay(Map<String, Object> map) {
         audioManager.requestAudioFocus(configuration.isAudioExclusiveRequiredForSynthesizer());
         if (map.containsKey(MAP_MESSAGE)) {
             //noinspection unchecked
@@ -420,7 +437,8 @@ private void runMap(Map<String, Object> map) {
         else if (map.containsKey(MAP_SILENCE)) {
             //noinspection unchecked
             playSilence((String) map.get(MAP_UTTERANCE_ID), (long) map.get(MAP_SILENCE));
-        }
+        } else
+            throw new RuntimeException("No message or silence item to play");
     }
 
     @Override

sdk-conversational-flow-core/src/main/java/com/chattylabs/sdk/android/voice/BluetoothSco.java

@@ -20,13 +20,13 @@ public class BluetoothSco {
     private final Condition condition = lock.newCondition();
 
     // States
-    private boolean isScoReceiverRegistered; // released
+    private boolean isScoReceiverRegistered;
     private boolean isBluetoothScoOn;
 
     // Resources
     private Application application;
     private AndroidAudioManager audioManager;
-    private BluetoothScoReceiver bluetoothScoReceiver = new BluetoothScoReceiver();
+    private BluetoothScoReceiver bluetoothScoReceiver;
 
     // Log stuff
     private ILogger logger;
@@ -94,7 +94,7 @@ public void stopSco() {
             audioManager.stopBluetoothSco();
             lock.lock();
             try {
-                condition.await(5, TimeUnit.SECONDS);
+                condition.await(2, TimeUnit.SECONDS);
             } catch (InterruptedException e) {
                 logger.logException(e);
             } finally {

sdk-conversational-flow-core/src/main/java/com/chattylabs/sdk/android/voice/Conversation.java

@@ -1,24 +1,15 @@
 package com.chattylabs.sdk.android.voice;
 
-import android.support.annotation.IntDef;
 import android.support.annotation.NonNull;
 
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-
 public interface Conversation {
-
     int FLAG_ENABLE_ERROR_MESSAGE_ON_LOW_SOUND = 1;
 
-    @IntDef({FLAG_ENABLE_ERROR_MESSAGE_ON_LOW_SOUND})
-    @Retention(RetentionPolicy.SOURCE)
-    @interface Flag {}
-
-    void addFlag(@Flag int flag);
+    void addFlag(@ConversationFlag int flag);
 
-    void removeFlag(@Flag int flag);
+    void removeFlag(@ConversationFlag int flag);
 
-    boolean hasFlag(@Flag int flag);
+    boolean hasFlag(@ConversationFlag int flag);
 
     void addNode(@NonNull VoiceNode node);