Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/algolia/voice-overlay-android
🗣 An overlay that gets your user’s voice permission and input as text in a customizable UI
https://github.com/algolia/voice-overlay-android
android chatbots conversation conversational-bots conversational-interface conversational-ui input instant-search instantsearch overlay permission permissions permissions-android search speech-recognition speech-to-text stt voice voice-assistant voice-recognition
Last synced: about 1 month ago
JSON representation
🗣 An overlay that gets your user’s voice permission and input as text in a customizable UI
- Host: GitHub
- URL: https://github.com/algolia/voice-overlay-android
- Owner: algolia
- License: mit
- Created: 2018-07-06T08:46:17.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2022-04-05T15:16:01.000Z (about 2 years ago)
- Last Synced: 2024-01-31T14:38:39.965Z (4 months ago)
- Topics: android, chatbots, conversation, conversational-bots, conversational-interface, conversational-ui, input, instant-search, instantsearch, overlay, permission, permissions, permissions-android, search, speech-recognition, speech-to-text, stt, voice, voice-assistant, voice-recognition
- Language: Kotlin
- Homepage: https://alg.li/voice
- Size: 38.5 MB
- Stars: 242
- Watchers: 12
- Forks: 37
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Lists
- awesome-android - VoiceOverlay - An overlay that gets your user’s voice permission and input as text in a customizable UI. (Libraries / GUI)
- awesome-android-ui - Voice Overlay
- awesome-android-ui - Voice Overlay
- -list-of-awesome-Android-packages-and-resources. - VoiceOverlay - An overlay that gets your user’s voice permission and input as text in a customizable UI. (Libraries / GUI)
README
# Overview
**Voice overlay** helps you turn your user's **voice** into **text**, providing a **polished UX** while handling for you the **necessary permission**.
Â
Â
Â
Â
# Demo
You can clone this repo, then run the Demo project by doing `./gradlew app:installDebug` and launching the application:
# Installation
The Voice overlay is available as a gradle dependency via [JCenter](https://bintray.com/bintray/jcenter). To install
it, add the following line to your app's `build.gradle`:
```groovy
dependencies {
// [...]
implementation 'com.algolia.instantsearch:voice:1.0.0-beta02'
// [...]
}
```
# Usage
## Basic usage
1. In your Activity, check if you have the permission and show the appropriate `Dialog`:
```kotlin
if (!isRecordAudioPermissionGranted()) {
VoicePermissionDialogFragment().show(supportFragmentManager, "DIALOG_PERMISSION")
} else {
VoiceInputDialogFragment().show(supportFragmentManager, "DIALOG_INPUT")
}
```
_See [it implemented in the demo app](app/src/main/kotlin/com/algolia/instantsearch/voice/demo/MainActivity.kt#L26-L30)._
This will display the permission dialog if the `RECORD_AUDIO` permission was not yet granted, then the voice input dialog once the permission is granted.
Once the user speaks, you will get their input back by implementing `VoiceSpeechRecognizer.ResultsListener`:
```kotlin
override fun onResults(possibleTexts: Array) {
// Do something with the results, for example:
resultView.text = possibleTexts.firstOrNull()?.capitalize()
}
```
_See [it implemented in the demo app](app/src/main/kotlin/com/algolia/instantsearch/voice/demo/MainActivity.kt#L41-L43)._
## When the permission is not granted
If the user didn't accept the permission, you [should explain](https://developer.android.com/training/permissions/requesting#explain) the permission's rationale. If they deny the permission, you need to guide them into manually enabling it if they want to use the voice-input feature.
Voice overlay makes it easy to handle all these cases:
```groovy
override fun onRequestPermissionsResult(requestCode: Int, permissions: Array, grantResults: IntArray) {
super.onRequestPermissionsResult(requestCode, permissions, grantResults)
if (Voice.isRecordPermissionWithResults(requestCode, grantResults)) {
when {
Voice.isPermissionGranted(grantResults) -> showVoiceDialog()
shouldExplainPermission() -> showPermissionRationale(getPermissionView())
else -> Voice.showPermissionManualInstructions(getPermissionView())
}
}
// [...] eventual handling of other permissions requested by your app
}
```
_See [it implemented in the demo app](app/src/main/kotlin/com/algolia/instantsearch/voice/demo/MainActivity.kt#L42-L51)._
This will display the permission rationale when the user doesn't allow it, and the manual instructions in case they denied it.
## Customization
You can customize your voice overlay in the following ways:
### Behavior
Several options let you adapt the voice overlay\'s behavior to your needs.
#### Suggestions
You can provide suggestions of what the user could say, to give them some examples.
```kotlin
voiceInputDialogFragment.setSuggestions(
"64GB Smartphone",
"Red running shoes",
"Cheap TV screen"
)
```
#### AutoStart
You can prevent the overlay from automatically listening to user input.
```kotlin
/// Requires the user to click the mic to start listening.
voiceInputDialogFragment.autoStart = false
// [...]
// you can also start listening programmatically with
voiceInputDialogFragment.start()
```
### Copy text
You can change any text displayed in the overlay by overriding its resource in your `strings.xml`:
```xml
Listening…
Say something like:
Sorry, we didn\'t quite get that.
Try repeating your request.
Try again
You can use voice search to find products.
May we access your device’s microphone to enable voice search?
Allow microphone access
No
Voice search requires this permission.
Request again?
Permission denied, allow it to use voice search.
Allow recording
On the next screen, tap Permissions then Microphone.
```
### Layouts
You can replace the voice overlay's layouts by your own, as long as they respect the following structure:
#### Permission
Create a layout called `voice_input.xml` with
- A `ViewGroup` container with id `@+id/voicePermission`
- A `View` with id `@+id/close` for closing the overlay when clicked
- A `TextView` with id `@+id/title`
- A `TextView` with id `@+id/subtitle`
#### Input
Create a layout called `voice_permission.xml` with
- A `ViewGroup` container with id `@+id/voiceInput`
- A `VoiceMicrophone` with id `@+id/microphone` to handle the voice input
- A `TextView` with id `@+id/suggestions` to display eventual suggestions
- A `View` with id `@+id/close` for closing the overlay when clicked
- A `TextView` with id `@+id/title`
- A `TextView` with id `@+id/subtitle`
- An eventual `TextView` with id `@+id/hint` to display a hint on error
- An eventual `RippleView` with id `@+id/ripple` if you want to keep the animation
## Getting Help
- **Need help**? Ask a question to the [Algolia Community](https://discourse.algolia.com/) or on [Stack Overflow](http://stackoverflow.com/questions/tagged/algolia).
- **Found a bug?** You can open a [GitHub issue](https://github.com/algolia/voice-overlay-android/issues/new).
- **Questions about Algolia?** You can search our [FAQ in our website](https://www.algolia.com/doc/faq/).
## Getting involved
* If you **want to contribute** please feel free to [**submit pull requests**](https://github.com/algolia/voice-overlay-android/pull/new).
* If you **have a feature request** please [**open an issue**](https://github.com/algolia/voice-overlay-android/issues/new).
* If you use the **Voice Overlay** in your app, we would love to hear about it! Drop us a line on [discourse](https://discourse.algolia.com/) or [twitter](https://twitter.com/algolia).
## License
The VoiceOverlay is available under the MIT license. See the [LICENSE file](./LICENSE) for more info.