Skip to content

Clarify Coli first-run model download#36

Open
tens1x wants to merge 1 commit intomarswaveai:mainfrom
tens1x:clarify-coli-first-run-model-download
Open

Clarify Coli first-run model download#36
tens1x wants to merge 1 commit intomarswaveai:mainfrom
tens1x:clarify-coli-first-run-model-download

Conversation

@tens1x
Copy link
Copy Markdown

@tens1x tens1x commented Mar 28, 2026

I opened this PR because I ran into a confusing real-world setup flow that made it hard to tell whether the problem was installation, environment, or model download.

What happened

This was my actual setup path:

  1. I installed @marswave/coli successfully with: npm install -g @marswave/coli
  2. coli was available in PATH and coli --help worked as expected.
  3. However, ~/.coli was still empty, so it looked like nothing had been downloaded yet.
  4. TypeNo then reported: Coli model download looks incomplete:balabala......
  5. The error message was also hard to read in practice: there was additional text after that message, but the overlay UI extended beyond my screen truncated the content, so I could not see the full actionable instruction.
  6. At that point, it was not obvious whether:
    • coli had failed to install
    • TypeNo had failed to find coli
    • the speech model was supposed to be downloaded during install
    • or the failure was actually happening later during first transcription

What made this especially confusing is that npm install -g @marswave/coli succeeded, so the natural assumption was that the speech engine setup was already complete.

Only after digging further did it become clear that:

  • installing @marswave/coli only installs the CLI
  • the speech model is downloaded separately on the first actual transcription
  • if that GitHub download fails or is interrupted, users can end up seeing an incomplete-download error that feels disconnected from the install step

Why this PR

The current docs and UI already contain the necessary pieces, but they do notconnect them clearly enough for a first-time user.

In particular:

  • the README does not emphasize early enough that CLI install and model download are separate stages
  • the troubleshooting section suggests retrying npm install, even though the failing step may actually be the first model download
  • after auto-install succeeds, the app does not clearly tell the user that the first transcription will still need to download a model
  • the overlay error can truncate actionable diagnostics or render them beyond the visible area

This combination makes a successful npm install feel inconsistent with the later runtime error.

Changes

  • Clarify in README.md and README_CN.md that npm install -g @marswave/coli installs the CLI only.
  • Document that the speech model is downloaded on the first actual transcription into ~/.coli/models/.
  • Update model-download troubleshooting to recommend retrying transcription and clearing ~/.coli/models/ leftovers instead of re-running npm install.
  • Show a brief post-install hint in the app that the first transcription wil still download the speech model.
  • Improve timeout/incomplete-download error messages so they point users to ~/.coli/models/ and suggest proxy/TUN mode where relevant.
  • Allow error text in the overlay to wrap instead of truncating critical diagnostics into a single line.

Scope

This PR only changes documentation and user-facing setup/error messaging.
It does not change the transcription pipeline itself.


Note

Low Risk
Low risk: changes are limited to documentation and user-facing status/error messaging plus minor overlay layout tweaks, with no changes to transcription logic or data handling.

Overview
Clarifies in README.md and README_CN.md that npm install -g @marswave/coli installs only the CLI, and that the speech model is downloaded on the first transcription into ~/.coli/models/ (including updated troubleshooting guidance to retry transcription and clear partial model files).

Updates the app’s user messaging to match this flow: shows a brief post-install hint after auto-install, improves incomplete-model/timeout diagnostics to point at ~/.coli/models/ and proxy/TUN mode, and adjusts the overlay to wrap and display longer error messages (smaller font, multi-line, wider panel).

Written by Cursor Bugbot for commit a5ffa3e. This will update automatically on new commits. Configure here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant