Skip to content

Cloudy Reader 0.0.2

Choose a tag to compare

View all tags
@islanderman islanderman released this 06 Nov 08:23
· 95 commits to main since this release
v0.0.2
6a1302f

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

This release adds two voice engines, a disk image installer, and pronunciation fixes.

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.2-macos-arm64.dmg (about 431 MB) from Assets below.

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

    echo "1d0c56d65b631bfa681e4644a35ee43aed84187897763e618d93a4e6537b7de9  Cloudy-Reader-0.0.2-macos-arm64.dmg" | shasum -a 256 -c

    The output must read Cloudy-Reader-0.0.2-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.2-macos-arm64.zip (about 460 MB) from Assets below.

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

    echo "b36a1a8e5e38417569cb72f0c824e275b820ada164722ea92f35465ad62072fd  Cloudy-Reader-0.0.2-macos-arm64.zip" | shasum -a 256 -c

    The output must read Cloudy-Reader-0.0.2-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 voices and no engines. The app downloads them in the background at the first launch.

  • 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… 20% (412 of 1,974 MB), 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 and Speak stays off. 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

  • Disk image. The release adds a disk image beside the zip. Open it and drag Cloudy Reader onto the Applications link.
  • Checksum files. Each installer has a .sha256 file in Assets with the same value as the Checksum section below.
  • Two voice engines. Chatterbox Turbo adds one built-in voice. Qwen3-TTS adds two voices, Aiden (male) and Ryan (male).
  • Engine behavior. Both engines run on your Mac, and neither clones a voice. The same text with the same voice sounds the same each time.
  • Voice order. The menu lists Kokoro, Chatterbox Turbo, Qwen3-TTS, then Piper. Chatterbox Turbo and Qwen3-TTS have no grade, so their voices sort by name.
  • Window look. The question sits in a card, and the spoken script sits in its own panel. Only one progress bar shows at a time, and VoiceOver announces warnings and Voices downloaded. as well as errors.
  • Dimmed voices. A voice that cannot run yet shows dimmed, with its reason in the row, such as not downloaded yet or offline: not downloaded.
  • Skipped engines. A skipped engine shows <engine> not downloaded: <reason> in an empty status bar, such as not enough disk space: needs 3.3 GB, 1.1 GB free.
  • First use. The first reading with an engine shows Preparing… loading Chatterbox Turbo (first use only).
  • Saved voice. A saved voice that is not ready at start gives way to another voice. A note in the status bar says so.
  • Rotation. Chatterbox Turbo has no gender label and never rotates. US only adds Aiden, and Men only adds Aiden and Ryan.
  • Offline guard. An engine loads only files on your Mac and never contacts the network itself.
  • Pinned engine files. Each engine file has a commit-pinned address and a SHA-256 value. The app checks the SHA-256 again before the first load and refuses pickle files.
  • No IPA. Chatterbox Turbo and Qwen3-TTS take no IPA. They say a respelled word from its respelling, and a lexicon word or a checked chemical name as printed. The warning counts both as hard words.
  • Ranges. A tight en dash between two ascending numbers reads as "to": 5–10 grams is "5 to 10 grams". A hyphen or a spaced dash reads as "to" only before a unit, a percent sign, or a noun such as pages.
  • Comparisons. x<3 reads as "x is less than 3", and x>=3 reads as "x is greater than or equal to 3".
  • Function names. sin θ reads as "sine theta", and 40sin(30°) reads as "40 sine(30 degrees)". The word table also covers cos, tan, ln, and more.
  • Logarithms. log3 10 reads as "log base 3 of 10". A number glued to log with no argument stays whole, so log100 = 2 reads as "log 100 equals 2".
  • Units after "a" or "an". The unit is singular: a 2 kg cart reads as "a 2 kilogram cart".
  • Say-as guides. A say-as guide after an expression that starts with a function name covers the whole expression.
  • 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 fresh install, a failed first download shows no warning, because the status bar already holds "No voice is installed." 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 choice letter. The status bar then reads <engine> could not say '<part>'; try another voice.

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.
  • 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.2-macos-arm64.dmg:

SHA256  1d0c56d65b631bfa681e4644a35ee43aed84187897763e618d93a4e6537b7de9

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

SHA256  b36a1a8e5e38417569cb72f0c824e275b820ada164722ea92f35465ad62072fd
Assets 6
Loading