Storyteller UI

Introduction

Welcome to the Storyteller Book UI! This tool helps you manage and trigger sound effects ('Pages') based on spoken words or phrases, organized into different 'Chapters'. Your book data is automatically saved in your browser's local storage.

Note: Google Chrome is recommended for the most reliable speech recognition performance. Other browsers may have limited or experimental support.

Sample Book

Download a sample book JSON file to get started. You can load this file using the 'Load Book File' option under 'Manage Book'. Remember, you'll need to provide your own audio files matching the filenames in the sample and use the 'Relink Files' button after loading.

Download Sample Book (.json)

Core Concepts

Book

The entire collection of your chapters and pages. It's automatically saved to your browser. You can also Save and Load the entire Book as a file using the "Manage Book" dropdown menu.

Chapter

A way to organize your Pages. Only pages within the currently active chapter (or Starred pages) can be triggered by keywords/phrases. Chapters appear as tabs above the page list. You can add, delete (except Index), and edit chapters.

Index Chapter

A special, undeletable chapter that always shows *all* pages in your book. It acts like a master list. It's also the default destination when using an "End Phrase".

Page

Represents a sound effect or audio clip. Each page has a title, one or more sound sources (variations), trigger keywords/phrases, volume, looping options, etc.

Starred Page

A page marked with a star. Starred pages can be triggered by their keywords/phrases regardless of which chapter is currently active.

Listening & Triggering

Starting/Stopping

Use the main buttons or the Spacebar (Toggle or Push-to-Talk mode) to start and stop listening for trigger words.

Primary Key(s) (Optional)

Each page can optionally have one or more Primary Keys (comma-separated words/phrases). If Primary Keys are set:

• The system must hear at least one of those exact Primary Keys in the spoken text first.
• If a Primary Key is heard, the system then checks for the page's regular Keywords (Smart Filtering) or Phrases (Phrase Matching) within the same spoken text to confirm the trigger.
• If none of the Primary Keys are heard, the page will not be triggered, even if its other keywords/phrases are present.

If a page does not have any Primary Keys, it behaves normally, triggering directly based on its Keywords or Phrases.

Smart Filtering (Keywords)

When enabled (checkbox above buttons), the system uses fuzzy matching on the 'Trigger Keywords' field. Pronouns (like 'you', 'he', 'she', 'they', etc.) are given lower priority when determining the best match.

• It generally requires at least two keywords from a page to match words in your speech to trigger the sound (unless a page only has one keyword).
• This check happens *after* a Primary Key (if any) is matched.
• If multiple pages match:
  • The page matching the most keywords is chosen first.
  • If keyword counts are tied, the page matching fewer (or zero) pronouns is preferred.
  • If still tied, the page with the fewest total keywords (more specific match) is preferred.
  • If still tied, the page whose matched keywords appear earliest in the phrase is chosen.
  • Fuzzy match score is used as a final tie-breaker.

Phrase Matching

When Smart Filtering is disabled, the system looks for exact matches of the lines entered in the 'Trigger Phrases' field. This check happens *after* a Primary Key (if any) is matched. It ignores punctuation and case.

Master Stop Keywords

Enter keywords (comma-separated) in the settings area. If the system hears one of these keywords, it will immediately stop *all* playing sounds, similar to clicking the "Stop All Sounds" button (Ctrl+Q).

Chapter Transitions & Endings

Transitioning Chapters (Entering)

You can automatically switch chapters by speaking a built-in cue phrase followed by a 'Transition Target Keyword' defined for the destination chapter.

• Built-in Cues: enter, go into, going into, wandering into, arrive at, move to, walk into, run into, head to, etc.
• Custom Cues: Add your own comma-separated cues in the settings area.
• Target Keywords: Defined in the "Edit Chapter" modal (pencil icon on a chapter tab). These identify the destination chapter (e.g., "forest", "tavern").

Example: If the "Forest" chapter has "forest" as a target keyword, saying "enter the forest" will switch the active chapter to "Forest".

Autoplay on Transition: In the "Edit Chapter" modal, you can select pages within that chapter to automatically play *only* when the chapter is activated via a spoken keyword transition (using transition cues, not end phrases). Sounds started this way will automatically stop if you transition to another chapter.

Ending Chapter Sounds (Leaving)

You can stop all sounds currently playing from the active chapter and transition to a designated chapter (defaulting to Index) by speaking an end phrase followed by any chapter's target keyword.

• Built-in End Phrases: leave, exit, depart from, leaving, exiting.
• Custom End Phrases: Add your own comma-separated phrases in the settings area (e.g., "run from", "escape the").
• Target Keywords: Uses the same target keywords defined for chapter transitions. The keyword mentioned confirms the intent to leave, but the action affects the *currently active* chapter.
• Sounds on Leave (NEW!): In the "Edit Chapter" modal, you can select specific pages (from anywhere in the book) that will play sequentially *after* the active chapter's sounds are stopped and *before* transitioning.
• Transition Target on Leave (NEW!): In the "Edit Chapter" modal, you can specify which chapter (including Index) to transition to after leaving. Defaults to Index.

Example: You are in the "Tavern" chapter (which has "tavern" as a target keyword). Tavern sounds are playing. You say "leave the tavern". The system stops all sounds belonging to the Tavern chapter, plays any "Sounds on Leave" configured for the Tavern chapter, and then transitions to the "Transition Target on Leave" chapter configured for the Tavern (which defaults to Index if not set).

Managing Content

Creating Pages

Use the "Create New Page" section. Add a title, sound source (file or YouTube URL with optional start/end times), and trigger keywords/phrases. Optionally add Primary Key(s) for stricter activation. Keywords/phrases are optional if you only intend to trigger the page via chaining or autoplay. It's also important to note that you should include verbs and adjectives in your keywords as they will help with page selection accuracy.

Editing Pages

Click the pencil icon on a page item in the list. You can change all settings, including the Primary Key(s), add/remove sound source variations, and star/unstar the page.

Adding Pages to Chapters

Drag a page item from the list and drop it onto the desired (non-Index) chapter tab.

Removing Pages

• From Chapter: Click the icon on a page item (only visible in non-Index chapters). The page remains in the Book (and Index).
• From Book: Click the trash can icon on a page item. This permanently deletes the page from the book and all chapters.

Managing Chapters

• Add: Click the "+ Add Chapter" button.
• Edit: Click the pencil icon on a chapter tab (not available for Index). Edit name, transition targets, autoplay pages, sounds on leave, and transition target on leave.
• Delete: Click the X icon on a chapter tab (not available for Index). Deleting a chapter does *not* delete its pages from the book.

Import / Export / Save

Use the "Manage Book" dropdown menu.

• Autosave: Your book is automatically saved to your browser's local storage whenever you make changes.
• Save/Load Book File: Saves or loads the entire collection of chapters and pages as a file, including Primary Keys and all custom chapter settings. This is useful for backups or transferring between computers.
• Export Active Chapter: Saves the currently selected chapter and all its associated page data (including leave settings) into a chapter-specific file. (Cannot export Index).
• Import Chapter: Loads a previously exported chapter file. It will prompt you if the chapter name conflicts. If imported pages have titles that already exist in your book, it will link the chapter to your existing pages instead of creating duplicates. Chapter leave settings will be imported.
• Burn Book: Permanently deletes all book data from your browser's memory and local storage. Use with caution!

Keyboard Shortcuts

• Spacebar: Start/Stop Listening (depends on Toggle/Push mode)
• Ctrl+S / Cmd+S: Save Book to File
• Ctrl+O / Cmd+O: Load Book from File (opens file dialog)
• Ctrl+Q / Cmd+Q: Stop All Sounds
• Ctrl+Enter / Cmd+Enter: Create Page (in main form) or Save Changes (in modals)
• Escape: Close active Edit Page or Edit Chapter modal