Skip to content

Latest commit

 

History

History
174 lines (150 loc) · 16.6 KB

README.md

File metadata and controls

174 lines (150 loc) · 16.6 KB
Raw

Oscar AI Keyboard

Based out of HeliBoard is a privacy-conscious and customizable open-source keyboard, based on AOSP / OpenBoard. Does not use internet permission, and thus is 100% offline.

Get it on F-Droid Get APK from GitHub Get it on IzzyOnDroid

Table of Contents

Features

  • Add dictionaries for suggestions and spell check
    • build your own, or get them here, or in the experimental section (quality may vary)
    • additional dictionaries for emojis or scientific symbols can be used to provide suggestions (similar to "emoji search")
    • note that for Korean layouts, suggestions only work using this dictionary, the tools in the dictionary repository are not able to create working dictionaries
  • Customize keyboard themes (style, colors and background image)
    • can follow the system's day/night setting on Android 10+ (and on some versions of Android 9)
    • can follow dynamic colors for Android 12+
  • Customize keyboard layouts (only available when disabling use system languages)
  • Customize special layouts, like symbols, number, or functional key layout
  • Multilingual typing
  • Glide typing (only with closed source library ☹️)
    • library not included in the app, as there is no compatible open source library available
    • can be extracted from GApps packages ("swypelibs"), or downloaded here (click on the file and then "raw" or the tiny download button)
  • Clipboard history
  • One-handed mode
  • Split keyboard (only available if the screen is large enough)
  • Number pad
  • Backup and restore your settings and learned word / history data

FAQ / Common Issues

  • Add a dictionary: First download the dictionary file, e.g. from here. Then go to language settings, click on the language, then on + next to dictionary the add and select the file. Alternatively you can open a .dict file in a file explorer with HeliBoard and then select the language. Note that the latter method does not work with all file explorers.

  • Emoji search: You can get addon dictionaries for emoji suggestions in the dictionaries repo. An actual search function does not exist yet.

  • Cannot switch choose layout: This is only possible when use system languages is disabled. You can select the layout when tapping on the language.

    • How to customize layout: Go to layout selection and use the + button, then you can add a custom layout, either from a file or you can copy and edit an existing layout.

  • No suggestions for some language: Check dictionaries repo whether a dictionary is available. If there is one, download it and add it in the language settings for this language.

  • No suggestions in some app / text field: This app respects the no suggestions flag set by some input fields, i.e. the developer does not want you to see suggestions here. Best do in issue report for that app if you think this behavior is wrong. Alternatively you can enable the always show suggestions setting that overrides the no suggestions flag.

  • Multilingual typing (type in multiple languages without switching manually): Enable in Languages & Layouts, select the main language and tap the + button next to multilingual typing to add a language. Note that the selection is limited to languages with the same script as the main language, and to languages that have a dictionary (see above for how to add).

  • How to enable glide typing: There is no glide typing built into this app, but you can load compatible libraries: Go to advanced settings -> load gesture typing library and point to a file (setting not available in nouserlib version). You can extract the file from GApps packages ("swypelibs"), or download one here. Make sure to use the correct version (app will tell you in the dialog to load the library).

    • Glide typing is not working after loading a library: Possibly the download was corrupted, or you downloaded the wrong file. If you get a "unknown file" confirmation popup, it is likely you are not using the correct file (or you might be using a different version of the library). In rare cases, there might be crashes when the file is not in internal storage, or some Samsung-specific problems.

  • German layout with / without umlauts: German (Germany) layout has umlauts, German layout doesn't

  • Spell checker is not checking all languages in multilingual typing: Make sure you actually enabled HeliBoard spell checker. Usually it can be found in System Settings -> System -> Languages -> Advanced -> Spell Checker, but this may depend on Android version.

  • Words added to Gboard dictionary are not suggested: Gboard uses its own dictionary instead of the system's personal dictionary. See here for how to export the words.

  • What is the nouserlib version?: The normal version (release) allows the user to provide a library for glide typing, while the nouserlib version does not. Running code that isn't supplied with the app is dynamic code loading, which is a security risk. Android Studio warns about this:

    Dynamically loading code from locations other than the application's library directory or the Android platform's built-in library directories is dangerous, as there is an increased risk that the code could have been tampered with. Applications should use loadLibrary when possible, which provides increased assurance that libraries are loaded from one of these safer locations. Application developers should use the features of their development environment to place application native libraries into the lib directory of their compiled APKs.

    The app checks the SHA256 checksum of the library and warns the user if it doesn't match with known library versions. A mismatch indicates the library was modified, but may also occur if the user intentionally provides a different library than expected (e.g. a self-built variant). Note that if the the app is installed as a system app, both versions have access to the system glide typing library (if it is installed).

  • App crashing when using as system app: This happens if you do not install the app, but just copy the APK. Then the app's own library is not extracted from the APK, and not accessible to the app. You will need tp either install the app over itself, or provide a library.

Hidden Functionality

Features that may go unnoticed, and further potentially useful information

  • Long-pressing toolbar keys results in additional functionality: clipboard -> paste, move left/right -> word left/right, move up/down -> page up/down, word left/right -> line start/end, page up/down -> page start/end, copy -> cut, select word <-> select all, undo <-> redo
  • Long-press the Comma-key to access Clipboard View, Emoji View, One-handed Mode, Settings, or Switch Language:
    • Emoji View and Language Switch will disappear if you have the corresponding key enabled;
    • For some layouts it's not the Comma-key, but the key at the same position (e.g. it's q for Dvorak layout).
  • When incognito mode is enabled, no words will be learned, and no emojis will be added to recents.
  • Sliding key input: Swipe from shift or symbol key to another key. This will enter a single uppercase key or symbol and return to the previous keyboard.
  • Hold shift or symbol key, press one or more keys, and then release shift or symbol key to return to the previous keyboard.
  • Long-press a suggestion in the suggestion strip to show more suggestions, and a delete button to remove this suggestion.
  • Swipe up from a suggestion to open more suggestions, and release on the suggestion to select it.
  • Long-press an entry in the clipboard history to pin it (keep it in clipboard until you unpin).
  • Swipe left in clipboard view to remove an entry (except when it's pinned)
  • Select text and press shift to switch between uppercase, lowercase and capitalize words
  • You can add dictionaries by opening the file
    • This only works with content-uris and not with file-uris, meaning that it may not work with some file explorers.
  • Not really a feature, but you can restart the keyboard by going to the settings and swiping it away from recents
  • Debug mode / debug APK
    • Long-press a suggestion in the suggestion strip twice to show the source dictionary.
    • When using debug APK, you can find Debug Settings within the Advanced Preferences, though the usefulness is limited except for dumping dictionaries into the log.
      • For a release APK, you need to tap the version in About several times, then you can find debug settings in Advanced Preferences.
      • When enabling Show suggestion infos, suggestions will have some tiny numbers on top showing some internal score and source dictionary.
    • In the event of an application crash, you will be prompted whether you want the crash logs when you open the Settings.
    • When using multilingual typing, space bar will show an confidence value used for determining the currently used language.
  • For users doing manual backups with root access: Starting at Android 7, some files and the main shared preferences file are not in the default location, because the app is using device protected storage. This is necessary so the settings and layout files can be read before the device is unlocked, e.g. at boot. The files are usually located in /data/user_de/0/<package_id>/, though the location may depend on the device and Android version.

Contributing ❤

Reporting Issues

Whether you encountered a bug, or want to see a new feature in HeliBoard, you can contribute to the project by opening a new issue here. Your help is always welcome!

Before opening a new issue, be sure to check the following:

  • Does the issue already exist? Make sure a similar issue has not been reported by browsing existing issues. Please search open and closed issues.
  • Is the issue still relevant? Make sure your issue is not already fixed in the latest version of HeliBoard.
  • Is it a single topic? If you want to suggest multiple things, open multiple issues.
  • Did you use the issue template? It is important to make life of our kind contributors easier by avoiding issues that miss key information to their resolution. Note that issues that that ignore part of the issue template will likely get treated with very low priority, as often they are needlessly hard to read or understand (e.g. huge screenshots, not providing a proper description, or addressing multiple topics).

If you're interested, you can read the following useful text about effective bug reporting (a bit longer read): https://www.chiark.greenend.org.uk/~sgtatham/bugs.html

Translations

Translations can be added using Weblate. You will need an account to update translations and add languages. Add the language you want to translate to in Languages -> Manage translated languages in the top menu bar. Updating translations in a PR will not be accepted, as it may cause conflicts with Weblate translations.

To Community

You can share your themes, layouts and dictionaries with other people:

  • Themes can be saved and loaded using the menu on top-right in the adjust colors screen
  • Custom keyboard layouts are text files whose content you can edit, copy and share
    • this applies to main keyboard layouts and to special layouts adjustable in advanced settings
    • see layouts.md for details
  • Creating dictionaries is a little more work
    • first you will need a wordlist, as described here and in the repository readme
    • the you need to compile the dictionary using external tools
    • the resulting file (and ideally the wordlist too) can be shared with other users
    • note that there will not be any further dictionaries added to this app, but you can add dictionaries to the dictionaries repository

Code Contribution

See Contribution Guidelines

To-do

Planned features and improvements:

  • Improve support for modifier keys (alt, ctrl, meta and fn), some ideas:
    • keep modifier keys on with long press
    • keep modifier keys on until the next key press
    • use sliding input
  • Less complicated addition of new keyboard languages (e.g. #519)
  • Additional and customizable key swipe functionality
    • Some functionality will not be possible when using glide typing
  • Ability to enter all emojis independent of Android version (optional, #297)
  • Add and enable emoji dictionaries by default (if available for language)
  • Clearer / more intuitive arrangement of settings
    • Maybe hide some less used settings by default (similar to color customization)
  • Make use of the .com key in URL fields (currently only available for tablets)
    • With language-dependent TLDs
  • Internal cleanup (a lot of over-complicated and convoluted code)
  • Bug fixes

What will not be added:

  • Material 3 (not worth adding 1.5 MB to app size)
  • Dictionaries for more languages (you can still download them)
  • Anything that requires additional permissions, unless there is a very good reason

License

HeliBoard (as a fork of OpenBoard) is licensed under GNU General Public License v3.0.

Permissions of this strong copyleft license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work, under the same license. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights.

See repo's LICENSE file.

Since the app is based on Apache 2.0 licensed AOSP Keyboard, an Apache 2.0 license file is provided.

The icon is licensed under Creative Commons BY-SA 4.0. A license file is also included.

Credits