# wordshk

words.hk dictionary for Android and iOS

<img alt='wordshk app logo' src='assets/icon.png' style='width: 150px'>

# Download

<a href="https://apps.apple.com/us/app/words-hk-%E7%B2%B5%E5%85%B8/id1621976909?itsct=apps_box_badge&amp;itscg=30200" style="display: inline-block; overflow: hidden; border-radius: 13px; width: 180px"><img src="https://tools.applemediaservices.com/api/badges/download-on-the-app-store/black/en-us?size=250x83&amp;releaseDate=1657756800&h=1600d970c262d2b70ad557b308a2154b" alt="Download on the App Store" style="border-radius: 13px; width: 200px; height: 60px; padding-top: 10px padding-bottom: 10px"></a>
<a href='https://play.google.com/store/apps/details?id=hk.words.wordshk&pcampaignid=pcampaignidMKT-Other-global-all-co-prtnr-py-PartBadge-Mar2515-1'><img alt='Get it on Google Play' src='https://play.google.com/intl/en_us/badges/static/images/badges/en_badge_web_generic.png' height="80"/></a>
<a href='https://url.cloud.huawei.com/rBETYqkcU0?shareTo=qrcode'><img alt='Explore it on AppGallery' src='graphics/huawei_appgallery_badge.png' height="80"></a>
<a href="https://f-droid.org/repository/browse/?fdid=hk.words.wordshk"><img alt="Get it on F-Droid" height="80" src="https://f-droid.org/badge/get-it-on.png"/></a>

# Setup

1. Install Flutter by following the official doc: https://docs.flutter.dev/get-started/install

2. Download and install Android Studio to develop for Android: https://developer.android.com/studio

3. Start Android Studio, and go through the ‘Android Studio Setup Wizard’. This installs the latest Android SDK, Android SDK Command-line Tools, and Android SDK Build-Tools, which are required by Flutter when developing for Android.

4. Run `flutter doctor` to confirm your installation is working. You should see some output like below.
At a minimum you should have [✓] Flutter and [✓] Android toolchain to develop for Android, the other check marks are optional.
```
[✓] Flutter (Channel stable, 3.19.3, on Ubuntu 20.04.6 LTS 6.2.0-1019-azure, locale C.UTF-8)
[✓] Android toolchain - develop for Android devices (Android SDK version 34.0.0)
[✗] Chrome - develop for the web (Cannot find Chrome executable at google-chrome)
    ...
[✗] Linux toolchain - develop for Linux desktop
    ...
[!] Android Studio (not installed)
[✓] Connected device (1 available)
[✓] Network resources
```

If you want to build for iOS, you are required to use a Mac. You will need the latest version of Xcode as well.

3. Run the `setup.sh` at the root of this project to install the Rust backend.

4. Run `flutter run` to run the app, or
   * `flutter build appbundle` to create an Android app bundle
   * `flutter build apk` to build an Android APK
   * `flutter build ios` to build for iOS

Notes:
1. Build command for F-Droid (which forbids proprietary components like Google's MLKit):
   `flutter build appbundle --flavor foss`
2. Build command for Huawei AppGallery (which forbids sensitive content):
   `flutter build appbundle --flavor huawei`
3. Build command for Google Play Store (full version):
   `flutter build appbundle --flavor full`


# Release Checklist
1. Bump app version in `pubspec.yaml`
2. Open the wordshk-tools project and update the app version in `examples/export_sqlite_db/src/main.rs`:
   ```
   - api.export_dict_as_sqlite_db(&dict_path, "{old_version}")
   + api.export_dict_as_sqlite_db(&dict_path, "{new_version}")
   ```
3. Regenerate dictionary data with updated words.hk content
   a. Download the latest CSV from https://words.hk/faiman/request_data/
   b. Open the wordshk-tools project and replace the old wordshk.csv with the downloaded one
   c. Remove the first two autogenerated comments in the CSV
   d. Regenerate `dict.db.gz`:
      ```
      cd export_sqlite_db/
      cargo run --release
      gzip app_tmp/dict.db
      ```
      Copy the two files back to this project. Copy the `dict.db.gz` back to `assets/`.
4. Generate TTS recordings for new sentences
   a. Regenerate `dict.json` by going to `examples/export_json_dict` and run `cargo run --release`
   b. Copy the generated `app_tmp/dict.json` to project root
   c. Generate TTS by going to `tts/`, activate conda environment `conda activate wordshk`, and run `python tts.py`
   d. Upload newly generated audios to Alicloud OSS bucket by running `python upload_to_bucket.py`
5. Build iOS and Android binaries:
   ```
   flutter clean
   flutter pub get
   cd ios/
   pod install
   cd ..
   # Go to Xcode and Product -> Archive
   flutter build appbundle --flavor full
   ```
6. TAG the commit for F-droid.

# Normalize jyutping syllable audios

1. Open Adobe Audition, run the "Match Loudness" with these settings:
   
   * ITU-R BS.1770-3 Loudness
   * Target Loudness: -16 LUFS
   * Tolerance: 2 LU
   * Max True Peak Level: -2 dBTP
   * Look-ahead Time: 12ms
   * Release Time: 200ms

2. Export the files with matched loudness
   With export settings as follows:
   
   * Format MP3
   * Sample Type: Same as source
   * Format settings: MP3 24 Kbps CBR (Constant type)

3. Change directory into `assets/jyutping_female` or `assets/jyutping_male`.

4. Run `process_audios.sh`. This script does three things:
   
   1. Trim silence at the beginning and end of all mp3 files
   2. Pad the end of jap6sing1 syllables so they are not too short
   3. Peak normalize jap6sing1 syllables to make they as loud as other syllables

# Legal

Software: Copyright (C) 2022 Xiang Li, licensed under the MIT license.
Dictionary: Copyright (C) 2014-2022 Hong Kong Lexicography Limited.

"*words.hk*", "*wordshk*", "*粵典*" are trade names of Hong Kong Lexicography
Limited. Permission by Hong Kong Lexicography Limited must be obtained to
promote or distribute materials containing these names. In particular,
notwithstanding any permission (if applicable) to redistribute the source code
of this project and/or its derivative works by the copyright owner(s), unless
you obtain explicit permission from Hong Kong Lexicography Limited, you are
required to remove all mentions of "*words.hk*", "*wordshk*", "*粵典*" from
your redistributions.

The dictionary contents published by words.hk is copyrighted by Hong Kong
Lexicography Limited. You may be eligible to obtain a license from
https://words.hk/base/hoifong/