Getting Started
Beta Reader Lab is a browser-based tool for beta readers to read manuscripts, highlight text, and leave tagged comments — all without an internet connection. Everything runs locally in your browser; no data is sent to any server.
First time?
- Click Import .md/.txt in the header to load a manuscript file.
- The app will auto-detect chapters and display them in the left sidebar.
- Click any chapter to start reading.
- Select (highlight) any text in the reader to add a tagged comment.
- Enter your name in the Reader field so comments are attributed.
Privacy: All data stays in your browser. Sessions are saved to IndexedDB and localStorage on your device only.
Importing Manuscripts
Click Import .md/.txt in the header to load a Markdown or plain-text manuscript file.
- Supported formats:
.md (Markdown) and .txt (plain text).
- Asterisks (
*) are automatically stripped from the imported text.
- The first non-chapter line is used as the story title.
- Chapters are auto-detected and split (see Chapter Detection).
- Importing a new manuscript replaces the current one and clears all existing comments.
Tip: If your manuscript uses scene breaks (e.g. *** or ---), they are preserved as visual ———— separators within chapters.
Chapter Detection
When you import a manuscript, Beta Reader Lab automatically splits it into chapters using these heading patterns:
- "Chapter N" — e.g.
Chapter 1: The Beginning, Chapter 12 - Escape, Chap. 3
- "Part N" / "Book N" — e.g.
Part 1: The Journey
- Prologue / Epilogue — with optional subtitles
- Numbered headings — e.g.
1. Title or 1 - Title
- Roman numerals — e.g.
IV. Title, XII - Title
- ALL CAPS titles — lines in all uppercase with 2+ words
- Markdown headings — e.g.
# Title, ## Title
Scene breaks (***, ---, ===, ~~~) within chapters are converted to visual separators.
Each chapter shows its word count in the sidebar. Clicking a chapter marks it as reviewed and updates the progress badge.
To add a comment on a specific passage:
- Click the chapter you want to review in the left sidebar.
- Select (highlight) the text you want to comment on in the reader pane.
- A popup will appear showing your selected text, a tag dropdown, and a comment textarea.
- Choose a tag from the dropdown (see Comment Tags).
- Type your comment in the textarea.
- Click Add Comment to save.
The selected text will be highlighted in the reader with a color matching the tag. Clicking a highlight scrolls to the corresponding comment in the sidebar.
Note: The reader pane is read-only — you cannot edit the manuscript text directly. This ensures the original text is preserved for accurate comment references.
Tags help categorize your feedback. The app has two tag modes:
Editorial Mode (default)
Full set of tags:
- Loved this — Something you really enjoyed
- Confusing timeline — Timeline or sequence confusion
- Typo — Spelling, grammar, or formatting error
- Pacing — Too fast, too slow, or uneven pacing
- Unnatural dialogue — Unnatural or awkward dialogue
- Character issue — Character development or motivation issues
- Slow section — Section that drags or loses momentum
- Powerful moment — Particularly impactful or well-written moment
- Confusing — Hard to understand or follow
- Praise — Something well done
- Dialogue issue — General dialogue problems
Special Tags
- Comment — General comment or feedback (always available at the top of the dropdown)
- Other — Miscellaneous comment not fitting other categories
Minimal Mode
A reduced tag set with only the most essential tags: Loved this, Confusing timeline, Typo, Pacing, Unnatural dialogue, Character issue, Slow section, and Powerful moment.
Tag colors: Each tag has a distinct color that appears in both the highlight in the reader and the tag pill in the comments list, making it easy to scan feedback at a glance.
Filtering Comments
The Comments panel in the left sidebar has three filter dropdowns:
- Tag: Show only comments with a specific tag (e.g. only Typos).
- Chapter: Show only comments from a specific chapter.
- Status: Show only Open (unresolved) or Resolved comments.
Filters can be combined — e.g. show all "Pacing" comments in "Chapter 3" that are still "Open".
Comment Actions
Each comment in the list has three action buttons:
- Jump — Switches to the comment's chapter and scrolls the highlight into view.
- Resolve / Reopen — Toggles the resolved state. Resolved comments appear dimmed.
- Delete — Permanently removes the comment and its highlight (with confirmation).
Comment Density
The Comment Density panel (bottom of the left sidebar) shows a visual bar chart of how many comments each chapter has received.
- Each chapter gets a horizontal bar proportional to its comment count.
- The bar uses a gradient from light to accent color.
- The numeric comment count is shown beside each bar.
- This helps you quickly identify which chapters have the most feedback (and may need the most revision).
Global Feedback
The Global Feedback bar sits between the header and the main reading area. Use it for big-picture feedback that applies to the whole manuscript rather than a specific passage.
- Write overall impressions, character arc observations, pacing notes, worldbuilding thoughts, etc.
- Global feedback is saved with the session and included in
.brl exports.
- Click the 🔊 Read button to have the feedback read aloud using the selected voice.
Read Aloud
Beta Reader Lab includes a text-to-speech feature that reads manuscript text aloud using your browser's built-in speech synthesis.
Controls (in the header)
- Voice dropdown: Select from available system voices. By default, English voices (en-US, en-AU, en-GB) are shown. Check Show all voices to see every available voice.
- Speed slider: Adjust reading speed from 0.5x to 2.0x (default 1.0x).
- 🔊 Read button: Reads the current chapter aloud. If your cursor is positioned in the reader, it reads from that point to the end of the chapter. Click again (shows ⏸️ Stop) to stop.
Default Voice
The app automatically selects Andrew Online (Natural) — English (United States) as the default voice if it is available on your system. If not, it falls back to:
- Any English Microsoft voice
- Microsoft Neural voices (Edge browser)
- Any Microsoft voice
- Any English voice
- The first available voice
Edge browser: Microsoft Edge provides high-quality "Neural" voices (shown with a ✨ icon). Other Microsoft voices are shown with a 🔊 icon. For the best reading experience, use Edge.
Reading Global Feedback
The 🔊 Read button next to the Global Feedback textarea reads your global feedback aloud using the same voice and speed settings.
Exporting Sessions
Click Export .brl in the header to download your entire beta reading session as a .brl file (JSON format).
The exported file includes:
- Story title and reader name
- All chapters with text, word counts, and reviewed status
- All comments with tags, text, selection text, and resolved status
- Global feedback text
- The active tag library and mode
The filename is automatically generated as storytitle_readername.brl.
Best practice: Export a .brl file when you finish a reading session. This is your portable backup that can be loaded on any device or shared with an author.
Loading .brl Sessions
Click Import .brl in the header to load a previously exported .brl session file.
This restores:
- All chapters and their text
- All comments with highlights
- Global feedback
- Reader name and story title
- Tag library and mode from the session
The app supports multiple file format versions (v1.0 through v2.0) with backward compatibility. Older format files are automatically converted.
Note: If a session was auto-saved without chapter text (metadata-only format v1.7), you'll see a placeholder. Re-import the original manuscript file to restore full chapter content.
Auto-Save
Beta Reader Lab automatically saves your session so you never lose work.
How it works
- IndexedDB: Full session data (including chapter text) is saved to your browser's IndexedDB every 30 seconds and on key actions (adding comments, switching chapters, resolving comments, etc.).
- localStorage: Lightweight metadata is also saved to localStorage for quick session detection on startup.
- On page unload: A final save is triggered when you close or navigate away from the page.
What triggers a save?
- Adding, deleting, or resolving a comment
- Switching chapters
- Changing reader name or global feedback
- Changing voice or speed settings
- Toggling dark mode
- Scrolling (debounced, saves scroll position)
- Every 30 seconds automatically
Storage limits: If localStorage quota is exceeded, the app degrades gracefully — saving fewer comments and using compressed keys. IndexedDB has much larger capacity and is preferred.
Dark Mode
Toggle Dark mode in the header (right side) to switch between light and dark themes.
- Your preference is saved with the session and restored on next load.
- Dark mode uses a deep blue/slate color palette optimized for low-light reading.
- All UI elements adapt: reader pane, sidebar, popups, highlights, and comment cards.
Mobile & Tablet
Beta Reader Lab is fully responsive and works on phones and tablets.
Tablet (≤ 900px)
- The sidebar becomes a slide-in drawer accessed via the 𝌆 button in the header.
- Tap outside the drawer (on the overlay) to close it.
- Swipe right from the left edge to open; swipe left to close.
Mobile (≤ 599px)
- A bottom tab bar appears with three tabs: 📖 Reader, 🗂 Chapters, and 💬 Comments.
- The voice dropdown is hidden (use the Read button directly).
- Touch targets are enlarged for easier tapping.
- The comment popup takes full width.
Tiny phones (≤ 379px)
- The header title is hidden to save space.
- Header groups are more compact.
Delete a single comment
Click the Delete button on any comment in the Comments list. You'll be asked to confirm. The comment and its highlight are permanently removed.
Delete all comments
Click Delete All Comments in the header. You'll see a confirmation dialog showing the total count. All comments and highlights are removed. The manuscript text itself is not affected.
Warning: Deleting comments cannot be undone. Consider exporting a .brl file first as a backup.
Tips & Best Practices
- Read first, comment second: Do a full read-through of a chapter before adding comments to get the big picture.
- Use tags consistently: Pick the most specific tag for each comment (e.g. "Typo" rather than "Comment" for spelling errors).
- Resolve as you go: If you re-read and a concern no longer applies, mark it Resolved to keep your list clean.
- Use Global Feedback for big-picture notes: Save line-level issues for inline comments and arc/structure observations for global feedback.
- Export regularly: Use Export .brl after each session as a portable backup.
- Use Read Aloud for proof-listening: Hearing the text can reveal awkward phrasing and pacing issues you might miss when reading silently.
- Check Comment Density: Chapters with many comments may need the most revision — flag these in your global feedback.
- Enter your reader name: This personalizes the export filename and helps the author track who provided which feedback.
Troubleshooting
Voices not appearing in the dropdown
Browsers load voices asynchronously. If the dropdown shows "Loading voices...", wait a few seconds. If it persists:
- Try refreshing the page.
- Check Show all voices to see if any voices are available.
- Some browsers require interaction before loading voices — click anywhere on the page.
- In sandboxed environments (e.g. iframes), speech synthesis may be unavailable.
Chapter text shows "Content Not Available"
This happens when a session was saved in metadata-only format (v1.7) without chapter text. To fix:
- Re-import your original
.md or .txt manuscript file.
- Or load a
.brl export that includes full chapter text.
Session not restoring on reload
- Check that your browser allows IndexedDB and localStorage (not in private/incognito mode).
- Clearing browser data will erase saved sessions — always export a
.brl backup.
- If storage quota was exceeded, only minimal data may have been saved.
Read Aloud not working
- Ensure your browser supports the Web Speech API (most modern browsers do).
- Check that a voice is selected in the dropdown.
- Try clicking Read again — sometimes the first click initializes the speech engine.
- If using a mobile browser, speech may be interrupted when the screen turns off.
Highlights not showing on text
Highlights are applied by matching the saved selection text against paragraph text. If the manuscript was edited externally, the text may no longer match. Re-import the original file to restore highlights.