Beta Reader Lab Guide & .brl Format

1. 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?

Your work is organised into Projects. Each project keeps its own manuscript, chapters and comments.

1. Click Import .md/.txt in the header to load a manuscript file.
2. The app will auto-detect chapters and display them in the left sidebar.
3. Click any chapter to start reading.
4. Select (highlight) any text in the reader to add a tagged comment.
5. Enter your name in the Reader field so comments are attributed.

2. Working with Projects

Beta Reader Lab can keep multiple books in separate projects. The current project name is shown in the header, next to the ＋ New and Projects buttons.

Creating a new project

Click ＋ New in the header. Enter a title and a fresh, empty project is created. Your previous project is safely saved and can be opened again at any time.

Switching between projects

Click Projects in the header to open the project manager. Select a project and click Open. The app loads the selected project and saves your recent project list automatically.

Renaming a project

In the project manager, click Rename next to a project, type a new title, and confirm. The new name is saved immediately and shown in the header when that project is open.

Deleting a project

In the project manager, click Delete next to a project. You will be asked to confirm. The currently open project cannot be removed while it is open; switch to another project first.

Importing into a project

When you Import .brl, a prompt asks whether to create a new project from the file or replace the currently open project. Choose OK to create a new project, or Cancel to overwrite the current one.

3. 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).
• Markdown formatting (**bold**, *italic*, ~~strike~~) is converted to real styling — see Preparing Your Manuscript.
• 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.

4. 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.

5. Preparing Your Manuscript for Import

Follow these recommendations to get the cleanest import — correct chapter detection and preserved formatting.

Chapter headings

• Put each chapter heading on its own line. The most reliable format is Chapter 1, Chapter 12: Title, or Chapter 12 - Title.
• These also work: Part 1 / Book 2, Prologue / Epilogue, numbered lines (1. Title), Roman numerals (IV. Title), ALL-CAPS titles (2+ words), and Markdown headings (# Title).
• Use one style consistently — mixing "Chapter 1" with "3 - Title" can confuse detection.
• Keep headings short; a long line of prose in ALL CAPS may be detected as a heading.

Paragraphs

• Separate paragraphs with a blank line. Paragraphs are split on blank lines, so text that is only single-spaced may merge into one block.
• The first non-empty line before the first chapter becomes the story title — remove title-page clutter (author name, word count, copyright) if you don't want it picked up.

Inline formatting (Markdown)

You write	It becomes
**bold** or __bold__	bold
*italic* or _italic_	italic
***bold italic***	bold italic
~~strikethrough~~	strikethrough
`code`	inline code

Scene breaks

A line containing only ***, ---, ===, ~~~, or spaced symbols (* * *) becomes a visual ———— separator inside the chapter.

What to avoid

• Escaped punctuation from other editors (e.g. run\!) — stray backslashes are cleaned up automatically, but plain text is tidiest.
• Running headers, page numbers, or blank space at the top of the file — the first line becomes the title.
• Word-wrapped lines inside paragraphs — they import fine, but reflowing looks best with one paragraph per block.

6. Adding Comments

To add a comment on a specific passage:

1. Click the chapter you want to review in the left sidebar.
2. Select (highlight) the text you want to comment on in the reader pane.
3. A popup will appear showing your selected text, a tag dropdown, and a comment textarea.
4. Choose a tag from the dropdown (see Comment Tags).
5. Type your comment in the textarea.
6. 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.

7. Comment Tags

Tags help categorize your feedback. The app has two tag modes:

Editorial Mode (default)

♥ Loved this ⏱ Confusing timeline ✎ Typo ⏱ Pacing 💬 Unnatural dialogue ◎ Character issue ↓ Slow section ✦ Powerful moment ? Confusing + Praise 💭 Dialogue issue

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.

8. Filtering & Comment Actions

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

• 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).

9. 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).

10. 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.

11. 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) → any Microsoft voice → any English voice → the first available voice.

Reading global feedback

The 🔊 Read button next to the Global Feedback textarea reads your global feedback aloud using the same voice and speed settings.

12. The .brl File Format

A .brl file is a portable beta-reading session in JSON format. It carries the manuscript, every highlight and comment, and the reader's big-picture feedback in a single file that moves between reader and author.

Exporting a session

Click Export .brl in the header to download your entire beta reading session. The filename is automatically generated as storytitle_readername.brl.

What a .brl file contains

Field	Contents
Story title & reader name	Attribution for the feedback session
Chapters	Full chapter text, word counts, and reviewed status
Comments	Tag, comment text, the selected passage text, and resolved status
Global feedback	Big-picture notes applying to the whole manuscript
Tag library & mode	The active tag set (Editorial or Minimal) used in the session

Loading a .brl session

Click Import .brl in the header to load a previously exported session. This restores all chapters and their text, all comments with highlights, global feedback, reader name and story title, and the tag library and mode.

The app supports multiple file format versions (v1.0 through v2.0) with backward compatibility. Older format files are automatically converted.

13. Auto-Save & Storage

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.
• 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

14. 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.

15. 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.

16. Deleting Comments

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.

17. 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.

18. Troubleshooting / FAQ

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:

1. Re-import your original .md or .txt manuscript file.
2. 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.

Still stuck?

Reach us at info@theparsecpages.com.