Skip to content

Cloudy Reader 0.0.3

Latest

Choose a tag to compare

@islanderman islanderman released this 07 Nov 04:16
· 37 commits to main since this release

Cloudy Reader reads National Science Bowl questions aloud on a Mac, using local text-to-speech voices.

This release adds the macOS voices and a new look, removes the Paste and Speak Clipboard buttons, and fixes how the choice letters W, X, Y, and Z are spoken.

Requirements

  • An Apple Silicon Mac (arm64).
  • macOS 26.2 or later. The bundled libraries set this floor.
  • About 4.2 GB of free disk space: about 1.1 GB for the app and the rest for the voices and the engines.
  • A network connection for the first launch. Daily use works offline.

Install

Use the disk image unless you prefer the zip. Both files hold the same app.

Install from the disk image (recommended)

  1. Download Cloudy-Reader-0.0.3-macos-arm64.dmg (about 432 MB) from Assets below.

  2. Check the SHA-256 in Terminal, from the folder that holds the file:

    echo "568ca7bfff458814c180c575c5454e30e187d37a09dc9a638c5abebb5c0a1341  Cloudy-Reader-0.0.3-macos-arm64.dmg" | shasum -a 256 -c

    The output must read Cloudy-Reader-0.0.3-macos-arm64.dmg: OK. Any other output means a damaged download: download the file again.

  3. Open the disk image: double-click it in Finder.

  4. Drag Cloudy Reader onto the Applications link beside it.

  5. Eject the disk image.

  6. Open the app for the first time as described below.

Install from the zip

  1. Download Cloudy-Reader-0.0.3-macos-arm64.zip (about 460 MB) from Assets below.

  2. Check the SHA-256 in Terminal, from the folder that holds the file:

    echo "98f2b79d2875aa1eb46042c099b3d57bca33c95be1c433955ae43f4ed2a2321b  Cloudy-Reader-0.0.3-macos-arm64.zip" | shasum -a 256 -c

    The output must read Cloudy-Reader-0.0.3-macos-arm64.zip: OK. Any other output means a damaged download: download the file again.

  3. Unzip the file: double-click it in Finder.

  4. Move Cloudy Reader.app to /Applications before you open it.

  5. Open the app for the first time as described below.

Open the app for the first time

The app is ad-hoc signed. An ad-hoc signature uses no Apple Developer ID, and the app is not notarized.

macOS flags a downloaded copy as quarantined. Gatekeeper blocks the first launch and says it cannot verify the app. The dialog wording differs between macOS versions.

To approve the blocked app:

  1. Open the app once, then close the warning dialog.
  2. Open System Settings > Privacy & Security.
  3. Scroll to Security. Find the message about Cloudy Reader.
  4. Click Open Anyway. Confirm with your password or Touch ID.
  5. Open the app again and click Open.

Approve only an app that you built or that comes from a source you trust.

You can remove the quarantine flag in Terminal instead. This skips the Gatekeeper prompt, so use it only for an app you trust:

xattr -dr com.apple.quarantine "/Applications/Cloudy Reader.app"

First launch

The disk image and the zip hold no voice files and no engine files. The app downloads them in the background at the first launch. The macOS voices need no download.

  • Order: the Piper voices, then the Kokoro voices, then Chatterbox Turbo, then Qwen3-TTS.
  • Disk check: before each engine, the app checks the free disk space and skips an engine that does not fit.
  • Source: Hugging Face over HTTPS. The app checks every file against a pinned SHA-256 value.
  • Progress: the status bar shows a label for each group, such as Downloading Qwen3-TTS… 42% (829 MB of 2.0 GB), and a progress bar.
  • A group's voices appear in the menu when that group ends. Speak works as soon as a voice appears.
  • A failed file is tried again at the next start. A retry in the same run resumes a partial file.
  • With no network at the first launch, nothing downloads. Speak still works with a macOS voice, and the other voices download when you start the app again with a network.
  • --offline skips the download and the name lookups: open -a "Cloudy Reader" --args --offline. Quit the app first.
  • CLOUDYREADER_OFFLINE=1 has the same effect.

What is in this release

Added

  • macOS voices. The Voice menu has a new macOS section with the English voices installed on your Mac, without the novelty voices. They need no download.
  • Start voice. The app picks a macOS voice by itself only when no other voice is installed.
  • Letters on macOS voices. The macOS voices say the choice letters W, X, Y, and Z by name. Enhanced and Premium voices were not checked.

Changed

  • New look. The window has a new look: more space around the controls, Voice and Rotation at the same width, and the buttons Repeat, Stop and Speak, with Speak as the default.
  • Spoken script. The Spoken script sits under the question and is open by default. It fills as you add text, a moment after each change, and it needs no network.
  • Voice menu. Every voice shows its name, accent and gender where known, its engine, and its quality, such as 8-bit or Enhanced. A Kokoro voice shows its published grade, such as Grade A.
  • About panel. A new About panel opens from the app menu. It has no buttons; Escape or Command-W closes it.
  • Status bar. The status bar draws its warning and error icons as lines. While the voices download, "No voice is installed." is information, not a warning.
  • Build check. A release build now stops when the app would carry the home folder, user name, or build folder of the machine that built it.

Removed

  • Paste and Speak Clipboard. The Paste and Speak Clipboard buttons are gone, with the Speak Clipboard command (Shift-Command-V). Command-V in the question box still pastes.
  • Clipboard. The app no longer reads the clipboard by itself.

Fixed

  • Choice letters. The choice letters W, X, Y, and Z are now said by name on Qwen3-TTS (Ryan, Aiden) and Chatterbox Turbo, not read as words like "way" or "see". Each letter plays a checked recording made with the same voice.
  • Voices. Qwen3-TTS: Ryan and Aiden. Chatterbox Turbo: its built-in voice. The Piper and Kokoro voices said the letters correctly before and are unchanged.

Same as 0.0.2

  • Downloads. The first launch downloads the same files as in 0.0.2: the Piper and Kokoro voice files and the Chatterbox Turbo and Qwen3-TTS engine files, about 3.05 GB in all.
  • Manual. Read it at https://cloudyreader.com.

Known limits

  • Apple Silicon only. There is no Intel build.
  • The app is ad-hoc signed and not notarized. The disk image is not signed or notarized either. The first launch needs a one-time approval.
  • The first launch downloads the voices and both engines.
  • On a Mac with no English macOS voice, a failed first download leaves no voice, and Speak stays off.
  • The next start tries the missing files again. See No voice is installed.
  • Piper voice genders are a guess: nobody has checked the 5 voices by ear. Men only and Women only rotation uses them.
  • A Kokoro voice wraps each line in about 0.4 s of near silence. Its pauses, except the one after a choice letter, run about 0.8 s longer than the inserted silence.
  • On a Mac with less than 24 GiB of memory, one of Chatterbox Turbo and Qwen3-TTS stays loaded. Switching between them reloads the engine.
  • One reading holds at most 8,000 characters with Chatterbox Turbo or Qwen3-TTS.
  • An engine can fail to say a short part, such as a single hard word. The status bar then reads <engine> could not say '<part>'; try another voice.
  • With Read answer line on, the answer letter can be mispronounced on Qwen3-TTS and Chatterbox Turbo, and Ryan can fail to read an answer that starts with a lone letter. The choice letters themselves are fine.

License

  • Cloudy Reader is licensed under the Apache License 2.0.
  • The app also bundles GPL components, such as piper-tts and jdk4py, plus phonemizer-fork in a build with Kokoro.
  • The original Chatterbox Turbo model by Resemble AI is MIT licensed, and the card of its mlx-community MLX conversion lists Apache-2.0. Qwen3-TTS is Apache-2.0, in an MLX build by mlx-community.
  • The macOS voices come with macOS. Cloudy Reader neither downloads nor redistributes them.
  • Distributing the app is subject to those licenses. This is not legal advice.
  • Details: the License section of the README.

Cloudy Reader is an independent project. It is not affiliated with, endorsed by, or sponsored by the U.S. Department of Energy or the National Science Bowl.

Checksum

SHA-256 of Cloudy-Reader-0.0.3-macos-arm64.dmg:

SHA256  568ca7bfff458814c180c575c5454e30e187d37a09dc9a638c5abebb5c0a1341

SHA-256 of Cloudy-Reader-0.0.3-macos-arm64.zip:

SHA256  98f2b79d2875aa1eb46042c099b3d57bca33c95be1c433955ae43f4ed2a2321b