SMART: Uses fuzzy matching for Keywords (requires PK + 1 keyword, or 2+ keywords if no PK). DISABLED: Uses exact Phrase matching (after PK match, if any).
Allows multiple pages to trigger sequentially from a single phrase (split by "and", uses complex keyword exclusion).
Loose (0.5)Strict (1.0)0.80
Controls how closely spoken words must match keywords/PKs (higher value = stricter). Default: 0.80.
Audio Handling on Chapter Change:
Stops all currently playing sounds when changing chapters.
Only stops sounds started automatically by chapter enter/exit actions. Manually played sounds continue (may switch variation).
Stops sounds unless they are Starred OR exist in both chapters. Continuing sounds may switch variation.
Uses Smart Continue logic, but *never* stops sounds when transitioning *to* Index. Sounds may switch variation.
Autoplay on Chapter Tab Click:
Controls if clicking a chapter tab triggers that chapter's 'Autoplay Pages on Enter'. Voice transitions always trigger autoplay.
Create New Page
Create a new page with its first sound source. Add triggers based on the Smart Filtering setting. Primary Key is optional but must be matched first if provided.
First Sound Source Type:
80
Restricts when this page can be activated by voice or transitions (manual play always works).
If set, at least ONE of these words/phrases MUST be spoken to activate the page.
Used when Smart Filtering is ON (after Primary Key match, if set).
Used when Smart Filtering is OFF (after Primary Key match, if set).
Edit Page
Restricts when this page can be activated by voice or transitions.
If set, at least ONE of these words/phrases MUST be spoken first.
Used when Smart Filtering is ON (after Primary Key match, if set).
Used when Smart Filtering is OFF (after Primary Key match, if set).
80
Volume can be overridden per source variation.
Sound Source Variations
No sources found.
Edit variations () or mark for removal () upon saving.
Add Source Variation
Source Type:
Loading chapters...
If none selected, variation is general. If chapters selected, only plays when one of those is active.
Restricts when this specific variation plays.
80
Leave at 80 to use the Page's default volume, or set a specific volume for this variation.
Edit Chapter
Keywords identifying this chapter, used after Enter Phrases like "enter", "go to".
Select pages (from this chapter) to play automatically ONLY when entering via voice command. Use Ctrl/Cmd to select multiple.
Chapter Exit Actions (via Exit Phrase)
Select pages (from anywhere) to play sequentially when leaving this chapter via an Exit Phrase. Use Ctrl/Cmd to select multiple.
Select the chapter to transition to after leaving this one via an Exit Phrase. Defaults to Index.
Guidebook
Tips are never expected, but always appreciated. I hope you enjoy this little project of mine!
Welcome to the Storyteller! 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.
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 "Exit Phrase". When transitioning to the Index chapter, any currently playing sounds will continue to play (unless the 'Stop All Audio' setting is active).
Page
Represents a sound effect or audio clip. Each page has a title, trigger keywords/phrases, volume, looping options, etc., and one or more sound sources (variations).
Sound Source Variation
A specific audio file or YouTube clip associated with a Page. Each variation can have its own name, volume override, and optionally be assigned to specific Chapters and/or a specific Time of Day (Day/Night/Always).
Chapter Variation
A sound source variation assigned to one or more specific chapters. When its page is triggered and the active chapter is one of the assigned chapters, only variations assigned to that chapter (and matching the current time of day, if set) will be considered for playback. If multiple matching chapter variations exist, one is chosen randomly.
General Variation
A sound source variation *not* assigned to any specific chapter (its `chapterIds` is empty or `null`). These are played if a page is triggered and there are no playable variations specifically assigned to the currently active chapter (that also match the time of day).
Time of Day Variation
A sound source variation assigned to 'Day Only' or 'Night Only'. When its page is triggered, this variation is only considered if the current Time of Day matches its setting. Variations set to 'Always' are considered regardless of the time.
Page Time of Day Setting
Each page can be set to 'Day Only', 'Night Only', or 'Always'. This restricts when the page can be activated by voice commands or chapter transitions. Pages set to 'Day Only' or 'Night Only' will appear grayed out when the current time of day doesn't match. Manual playback via the play button ignores this restriction.
Starred Page
A page marked with a star. Starred pages can be triggered by their keywords/phrases regardless of which chapter is currently active, but still respect the Page's Time of Day Setting. Chapter/Time Variations still apply based on the active chapter and current time.
Starred Chapter
A chapter marked with a star. All pages within a starred chapter behave like starred pages: they can be triggered globally, but still respect their individual Time of Day Settings. Chapter/Time Variations still apply. If a page in the *current non-starred* chapter matches the spoken phrase *better* than a page in a starred chapter, the current chapter's page takes priority.
Listening & Triggering
Starting/Stopping
Use the main toggle button 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 Primary Keys with a confidence meeting the Minimum Confidence Threshold (see Settings).
If a Primary Key is heard with sufficient confidence, 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 meet the required confidence, 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.
Page Activation & Time of Day
A page will only be activated by voice or chapter transitions if its 'Time of Day Restriction' setting matches the current time ('Day Only' pages during the day, 'Night Only' pages at night, 'Always' pages anytime). Pages that don't match the current time will appear grayed out in the list.
Variation Selection
When a page is triggered, the system selects a variation to play:
It first looks for playable variations assigned to the currently active chapter AND matching the current time of day (or set to 'Always' time).
If none are found, it looks for playable general variations (not assigned to any chapter) that match the current time of day (or 'Always' time).
If multiple suitable variations are found at either step, one is chosen randomly.
If no variation matches the chapter and time criteria, the page will not play automatically.
Smart Filtering (Keywords)
When enabled (checkbox in Settings ), the system uses fuzzy matching on the 'Trigger Keywords' field.
Minimum Trigger Requirements: (Applies only if Page Time of Day matches)
If Primary Key(s) exist: Requires at least one PK match meeting the Minimum Confidence Threshold AND at least one regular keyword match meeting the Minimum Confidence Threshold.
If no Primary Key exists: Requires at least two regular keyword matches meeting the Minimum Confidence Threshold (or one match if the page only has one keyword defined).
Stage 1: High Confidence Count: Counts the number of non-pronoun keywords/PKs matched with confidence >= 0.9. The page(s) with the highest count win this stage.
Stage 2: Fuzzy Score Sum: If Stage 1 results in a tie or no pages meet the 0.9 threshold, calculates a Total Confidence Score for each page by summing the raw confidence scores (0.0-1.0) of all its validly matched non-pronoun unique keywords and PKs. The page with the highest Total Confidence Score is chosen.
Tie-breaking (if Stage 2 scores are tied or within 0.2):
Checks if the phrase contains an exact match (confidence 1.0) for a Primary Key. If only one of the tied pages has an exact PK match, it wins. If multiple or none have an exact PK match, proceed.
Compares pages based on the count of exact regular keyword matches (confidence 1.0). The page with more wins. If still tied, proceed.
The page with the most pronouns adjacent to non-pronoun keywords/PKs wins.
The page with the fewest total non-pronoun keywords defined wins.
The page whose first matched keyword appears earliest in the phrase wins.
The page whose second matched keyword appears earliest wins.
Phrase Matching
When Smart Filtering is disabled (checkbox in Settings ), the system looks for exact matches of the lines entered in the 'Trigger Phrases' field (if Page Time of Day matches). This check happens *after* a Primary Key (if any) is matched with sufficient confidence. It ignores punctuation and case.
Compound Phrasing
When enabled (checkbox in Settings ), allows multiple pages (that match the current time of day) to trigger sequentially from a single phrase.
If the phrase contains the word "and" (or "&"), the first page match only considers the text *before* the "and".
After the first page is matched, the system re-searches the *entire* phrase for another matching page, excluding the page already matched and the specific non-PK keywords that were used to match the previous page.
This process repeats until no more pages can be matched. A page requires at least one Primary Key match (if applicable) AND at least one *non-excluded* regular keyword match AND match the current time of day to be considered in subsequent iterations.
The matched pages play sequentially with a 300ms delay between them. If the *first* page matched had a "Play Next Page" set, that page will play *after* the entire compound sequence finishes.
Stop Phrases
Enter phrases (comma-separated) in the Settings area. If the system hears one of these phrases, it will immediately stop *all* playing sounds, similar to clicking the "Stop All Sounds" button (Ctrl+Q).
Chapter & Time Transitions
Changing Time of Day
Button: Click the Sun / Moon button next to the main controls to cycle between Day and Night.
Phrases: Define 'Daytime Transition Phrases' and 'Nighttime Transition Phrases' in Settings . Speaking one of these will switch the time accordingly (e.g., "the sun sets" switches to Night).
Effects of Time Change
Page Activation: Pages whose 'Time of Day Restriction' no longer matches the new time will become inactive (grayed out) and cannot be triggered by voice/transitions.
Playing Sounds (Page Restriction): If a sound is playing and its Page's 'Time of Day Restriction' ('Day Only' or 'Night Only') does not match the *new* time of day, the sound will stop.
Playing Sounds (Variation Switching): If a sound is playing and its Page's restriction *does* match the new time (or is 'Always'), the system checks its *Variation's* time setting. If the current variation is 'Day Only' and time changes to Night (or vice-versa), it attempts to find and switch to a playable 'Night Only' (or 'Day Only') variation for the current chapter (or a general 'Night Only'/'Day Only' variation). If none exists, it looks for an 'Always' variation. If no suitable variation is found, the sound stops. If the playing variation is already appropriate ('Always', or matches the new time), it continues playing.
Autoplay: Autoplay pages associated with the active chapter will stop if their Time of Day Restriction no longer matches the new time. Conversely, autoplay pages that *now* match the new time will start playing.
Entering Chapters (via Enter Phrase)
You can automatically switch chapters by speaking a built-in or custom "Enter Phrase" followed by a 'Chapter Keyword' defined for the destination chapter.
Built-in Enter Phrases:enter, go into, going into, wandering into, arrive at, move to, walk into, run into, head to, etc.
Custom Enter Phrases: Add your own comma-separated phrases in the Settings area.
Chapter 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 chapter keyword, saying "enter the forest" will switch the active chapter to "Forest".
Autoplay on Enter: In the "Edit Chapter" modal, you can select pages within that chapter to automatically play *only* when the chapter is activated via a spoken Enter Phrase. These pages will only play if their Time of Day Restriction matches the current time.
Audio Handling on Chapter Change: This setting (in Settings ) controls which sounds stop when you change chapters (by voice or clicking a tab). It interacts with Chapter/Time Variations:
Stop All Audio: Stops everything.
Stop Only Autoplay/Leave Sounds: Only stops sounds started automatically. Manually triggered sounds continue, potentially switching variation based on the new chapter/time.
Smart Continue: Stops sounds unless they are Starred OR exist in both chapters. Continuing sounds may switch variation based on the new chapter/time.
Smart Continue + Keep All for Index: Uses "Smart Continue" logic, but *never* stops sounds when transitioning *to* Index. Sounds may still switch variation based on the new chapter/time (usually to a General/Always variation if coming from a specific chapter/time variation).
Variation Switching on Chapter Change: If a sound is allowed to continue playing based on the 'Audio Handling' setting, the system checks if the currently playing variation is appropriate for the *new* chapter and current time. If a different variation is more appropriate, the current sound stops, and the new variation starts. If the current variation is still the best fit, it continues playing.
Exiting Chapters (via Exit Phrase)
You can stop certain sounds currently playing from the active chapter and transition to a designated chapter (defaulting to Index) by speaking an "Exit Phrase" followed by one of the *active* chapter's keywords.
Custom Exit Phrases: Add your own comma-separated phrases in the Settings area (e.g., "run from", "escape the").
Chapter Keywords: Uses the same chapter keywords defined for entering. The keyword mentioned confirms the intent to leave the chapter associated with that keyword.
Sounds on Exit: In the "Edit Chapter" modal, you can select specific pages (from anywhere) that will play sequentially *after* the active chapter's sounds are stopped/switched (based on Audio Handling/Variation logic) and *before* transitioning. These sounds only play if their Page Time of Day setting allows.
Transition Target on Exit: In the "Edit Chapter" modal, you can specify which chapter (including Index) to transition to after leaving this one via an Exit Phrase. Defaults to Index.
Example: You are in the "Tavern" chapter (Day time). Tavern sounds are playing (using a Day or Always variation). You say "leave the tavern". The system stops/switches sounds based on the "Audio Handling" setting and Variation Switching logic for the destination chapter and current time, plays any allowed "Sounds on Exit", and then transitions to the target chapter.
Managing Content
Creating Pages
Use the "Add New Page" button () to open the creation modal. Add a title, sound source, triggers, and set the 'Time of Day Restriction' for the page. Keywords/phrases are optional if you only intend to trigger the page via chaining or autoplay.
Editing Pages
Click the pencil icon on a page item. You can change all settings, including the 'Time of Day Restriction', add/remove variations, and star/unstar the page.
Managing Source Variations
In the "Edit Page" modal, click "+ Add Variation" or the pencil icon next to an existing variation.
Add/Edit: In the variation modal, you can upload/change the source, set a name, volume override, assign it to one or more specific Chapters using the checkboxes, and set its Time of Day ('Always', 'Day Only', 'Night Only').
Remove: Click the X icon next to a variation in the Edit Page modal list to mark it for removal upon saving.
Adding Pages to Chapters
Drag a page item 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).
From Book: Click the trash can icon . This permanently deletes the page.
Managing Chapters
Add: Click the "+ Add Chapter" button ().
Edit: Click the pencil icon on a chapter tab.
Delete: Click the X icon on a chapter tab. Deleting a chapter will reset any variations assigned *only* to that chapter back to being 'General' variations.
Import / Export / Save
Use the "Manage Book" dropdown menu ().
Autosave: Your book is automatically saved locally.
Save/Load Book File: Saves or loads the entire book, including all page/variation/chapter/time settings.
Export/Import Chapter: Saves or loads a single chapter and its associated pages/settings.
Relink Missing Files: Appears if missing audio files are detected.