Skip to content

Commit 05aa136

Browse files
FranRiadigosFranRiadigos
committed
Simplified README
1 parent 4a33f98 commit 05aa136

File tree

1 file changed

+50
-118
lines changed

1 file changed

+50
-118
lines changed

‎README.md‎

Lines changed: 50 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,29 @@
11
# Conversational Flow Component - Android
22

3-
| | TYPE | VERSION | STATUS | COVERAGE |
4-
|--------------------------- |:-------: |---------------------- |-------------------- |:----------------------:|
5-
| `conversational-flow-core` | _core_ | ![Latest version][i1] | ![Build Status][i4] | ![Coverage Status][i7] |
6-
| `addon-android-speech` | _addon_ | ![Latest version][i2] | ![Build Status][i5] | ![Coverage Status][i8] |
7-
| `addon-google-speech` | _addon_ | ![Latest version][i3] | ![Build Status][i6] | ![Coverage Status][i9] |
3+
| | TYPE | VERSION | STATUS | COVERAGE |
4+
|--------------------------- |:-------: |---------------------- |-------------------- |:-----------------------:|
5+
| `demo` | _demo_ | ![Latest demo][v0] | ![Build Status][s0] | ![Coverage Status][c0] |
6+
| `conversational-flow-core` | _core_ | ![Latest version][v1] | ![Build Status][s1] | ![Coverage Status][c1] |
7+
| `addon-android-speech` | _addon_ | ![Latest version][v2] | ![Build Status][s2] | ![Coverage Status][c2] |
8+
| `addon-google-speech` | _addon_ | ![Latest version][v3] | ![Build Status][s3] | ![Coverage Status][c3] |
89

910

1011
Part of the [Voice & User Interaction SDK]().
1112

12-
The library wraps and combines single platform resources and builds
13-
a _Software Component_ capable of create a communication flow between a device and a user with ease.
13+
This library combines both native built-in resources and cloud services from various providers into
14+
a Component capable to run reliably a Speech Synthesizer and a Voice Recognizer.
1415

15-
Besides, it comes the following providers:
16+
Besides, it provides an [Interface](#create-a-conversation) based on a
17+
[Directed Graph](https://en.wikipedia.org/wiki/Directed_graph)
18+
implementation with [Directed Cycles](https://en.wikipedia.org/wiki/Cycle_(graph_theory))
19+
that allows a developer to create connected nodes and build a consistent conversation flow between
20+
a device and a user with ease.
21+
<br/>**Consistency** here stands for the needless to code the flow using conditional statements or
22+
any extra state complexity while ensuring the conversation will behave as expected.
1623

17-
- [Built-in Android](https://developers.google.com/voice-actions/interaction/voice-interactions) (default)
24+
It enables currently the following providers:
25+
26+
- [Built-in Android](https://developers.google.com/voice-actions/interaction/voice-interactions)
1827
- [TextToSpeech](https://developer.android.com/reference/android/speech/tts/TextToSpeech)
1928
- [SpeechRecognizer](https://developer.android.com/reference/android/speech/SpeechRecognizer)
2029
- [Google Cloud](https://cloud.google.com/)
@@ -28,12 +37,7 @@ Besides, it comes the following providers:
2837

2938
## Why choosing this library?
3039

31-
The **Conversational Flow Component** is based on a [Directed Graph](https://en.wikipedia.org/wiki/Directed_graph)
32-
which also allows [Directed Cycles](https://en.wikipedia.org/wiki/Cycle_(graph_theory))
33-
to create connected nodes that build a consistent conversation flow. **Consistent** here means that you won't need
34-
to code the flow using conditional statements or add any extra complexity if you don't want.
35-
36-
This library helps you when:
40+
Apart from the above mentioned, it also helps you when:
3741
- some devices don't have configured the resources you need to run a conversation in your app
3842
- a developer needs to learn and test quite a lot before even to start coding for voice capabilities
3943
- noise is impacting considerably the communication
@@ -45,9 +49,7 @@ This library helps you when:
4549
## Prerequisites
4650
The SDK works on Android version 5.0 (Lollipop) and above. _(for lower versions [contact us](mailto:[email protected]))_
4751

48-
## Setup
49-
Add the following code to your gradle file.
50-
52+
## Dependencies
5153

5254
repositories {
5355
maven { url "https://dl.bintray.com/chattylabs/maven" }
@@ -57,127 +59,57 @@ Add the following code to your gradle file.
5759
// Required
5860
implementation 'com.chattylabs.sdk.android:conversational-flow-core:x.y.z'
5961
60-
// You can either use only one or combine addon features
61-
// i.e. use the Synthesizer of Google but the Recognizer of Android
62+
// You can either use only one or combine addons
63+
// i.e. the Voice Recognizer of Google with the Synthesizer of Android
6264
implementation 'com.chattylabs.sdk.android:addon-android-speech:x.y.z'
6365
implementation 'com.chattylabs.sdk.android:addon-google-speech:x.y.z'
6466
}
6567

68+
### How to create a Conversation?
6669

67-
## Usage
68-
69-
If you use [Dagger 2](https://google.github.io/dagger/) in your project,
70-
you can provide the current `ConversationalFlowComponent` instance by applying the `ConversationalFlowModule.class`
71-
to your dagger component graph.
70+
You can use the component at any [Context]() level, both in an [Activity]() and a [Service]().
71+
<br/>You will create a set of `VoiceNode` objects and build a flow.
7272

7373
```java
74-
@dagger.Component( modules = { ConversationalFlowModule.class } )
75-
76-
//...
74+
// Retrieve the Component
75+
component = ConversationalFlowModule.provideComponent(...);
7776

78-
@Inject ConversationalFlowComponent component;
79-
```
80-
81-
If you don't user [Dagger 2](https://google.github.io/dagger/), then you can retrieve an instance using:
82-
83-
```java
84-
component = ConversationalFlowModule.provideComponent(new ILoggerImpl());
85-
```
86-
87-
Remember that you have to import at least one of the `addon` dependencies and configure
88-
which component you will be using.
89-
90-
```java
91-
component.updateConfiguration(builder ->
92-
builder.setRecognizerServiceType(() -> AndroidSpeechRecognizer.class)
93-
.setSynthesizerServiceType(() -> AndroidSpeechSynthesizer.class).build());
94-
95-
component.setup(context, status -> {
96-
if (status.isAvailable()) {
97-
// start using the functionality
98-
}
99-
});
100-
```
101-
102-
The configuration builder is based on a `LazyProvider` interface.
103-
<br/>This is helpful for instance with [SharedPreferences](), where the values can change anytime according
104-
to user preferences. By providing with the `LazyProvider` once, you don't need to run `updateConfiguration()`
105-
and `setup()` again.
106-
107-
[Learn more]() about the configurations you can set up.
108-
109-
### Create a Conversation
110-
111-
You can use the `ConversationalFlowComponent` at any context level, both in an Activity and a Service.
112-
113-
To create a conversation between the user and your app, you will create a set of `VoiceNode` objects
114-
and build a flow.
115-
116-
Retrieve a new instance of `Conversation`.
117-
118-
```java
77+
// Create a new instance of a Conversation
11978
Conversation conversation = component.create(context);
120-
```
121-
122-
Create the various message and action nodes you expect to use during the conversation.
123-
124-
```java
125-
// We create an initial message node.
126-
VoiceMessage question = VoiceMessage.newBuilder().setText("Do you need help?").build();
12779

128-
// We define what we expect from the user.
129-
String[] expected = new String[]{ "Yes", "I think so", "Sure" };
80+
// Create the various nodes you need
81+
VoiceMessage question = ...;
82+
VoiceMatch answers = ...;
13083

131-
// We create a node that handles what the user said
132-
VoiceMatch answers = VoiceMatch.newBuilder().setExpectedResults(expected)
133-
.setOnMatch(results -> conversation::next).build();
134-
135-
// We can create more nodes to check for not matched results and so on...
136-
// We also can automate the creation on a for loop from a Json File.
137-
// Check the sample demos!
138-
```
139-
140-
Now add these nodes into the current `Conversation` instance.
141-
142-
```java
84+
// Add the nodes into the current instance
14385
conversation.addNode(question);
14486
conversation.addNode(answers);
145-
```
146-
147-
Connect the nodes and start the conversation.
148-
149-
```java
150-
Flow flow = conversation.prepare();
87+
88+
// Connect the nodes each other
89+
ConversationFlow flow = conversation.prepare();
15190
flow.from(question).to(answers);
15291

153-
// Start the conversation out loud!
92+
// Start the conversation
15493
conversation.start(question);
15594
```
15695

157-
This is a simple example of the capabilities of the **Conversational Flow Component**.
158-
<br/>There are several configurations and listeners you can apply to each node, and different node types to use.
159-
160-
For instance, you could play a `VoiceMessage` and then collect a `VoiceCapture` from the user,
161-
or perhaps create multiple expected `VoiceAction`s and connect them to different `VoiceMessage`s.
162-
163-
<p align="center"><img src="assets/demo-sample.jpg" alt="demo-sample"/></p>
164-
165-
Take a look at the wiki page to [learn more]().
96+
There are different [Voice Nodes](), check the [wiki page]()
16697

167-
## Who uses this library?
168-
This is a list of Apps using the library:
98+
<p align="center"><img src="assets/flow-sample.jpg" alt="flow-sample"/></p>
16999

170-
<a href="https://play.google.com/store/apps/details?id=com.Chatty"><img src="https://lh3.googleusercontent.com/BwP_HPbu2G523jUQitRcfgADe5qKxZclxAbESmM4xaTNFS3ckz5uqkh12OimzqPC=s50-rw" alt="Chatty" title="Chatty"/> &nbsp;&nbsp;
171100
&nbsp;
172101

173-
[i1]: https://api.bintray.com/packages/chattylabs/maven/voice-interaction/images/download.svg?label=Latest%20version
174-
[i2]: https://api.bintray.com/packages/chattylabs/maven/voice-interaction/images/download.svg?label=Latest%20version
175-
[i3]: https://api.bintray.com/packages/chattylabs/maven/voice-interaction/images/download.svg?label=Latest%20version
102+
[v0]: https://img.shields.io/badge/demo-v0.6.3-blue.svg
103+
[v1]: https://api.bintray.com/packages/chattylabs/maven/conversational-flow-core/images/download.svg?label=Latest%20version
104+
[v2]: https://api.bintray.com/packages/chattylabs/maven/addon-android-speech/images/download.svg?label=Latest%20version
105+
[v3]: https://api.bintray.com/packages/chattylabs/maven/addon-google-speech/images/download.svg?label=Latest%20version
176106

177-
[i4]: https://app.bitrise.io/app/ad178a030b96de53/status.svg?token=Om0YDuYQ4vGPjsP0c_EbYQ&branch=master
178-
[i5]: https://app.bitrise.io/app/ad178a030b96de53/status.svg?token=Om0YDuYQ4vGPjsP0c_EbYQ&branch=master
179-
[i6]: https://app.bitrise.io/app/ad178a030b96de53/status.svg?token=Om0YDuYQ4vGPjsP0c_EbYQ&branch=master
107+
[s0]: https://app.bitrise.io/app/140e33e4fa4ab888/status.svg?token=QxUVT4wZRj6JGkZb4zSVAA&branch=master
108+
[s1]: https://app.bitrise.io/app/0967af538a0efcc5/status.svg?token=95j60AolkTmhbMvDK5zhFw&branch=master
109+
[s2]: https://app.bitrise.io/app/b555517d495ac587/status.svg?token=Fa2M4c_F5YHkhPddufLCNA&branch=master
110+
[s3]: https://app.bitrise.io/app/6a8c16b3b5c964a8/status.svg?token=Q6_u9joriJEzfzcWaLuVjg&branch=master
180111

181-
[i7]: https://coveralls.io/repos/chattylabs/conversational-flow-core/badge.svg?branch=master&service=github
182-
[i8]: https://coveralls.io/repos/chattylabs/addon-android-speech/badge.svg?branch=master&service=github
183-
[i9]: https://coveralls.io/repos/chattylabs/addon-google-speech/badge.svg?branch=master&service=github
112+
[c0]: https://coveralls.io/repos/chattylabs/unknown/badge.svg?branch=master&service=github
113+
[c1]: https://coveralls.io/repos/chattylabs/conversational-flow-core/badge.svg?branch=master&service=github
114+
[c2]: https://coveralls.io/repos/chattylabs/addon-android-speech/badge.svg?branch=master&service=github
115+
[c3]: https://coveralls.io/repos/chattylabs/addon-google-speech/badge.svg?branch=master&service=github

0 commit comments

Comments
 (0)