Storyteller

Introduction

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.

Download Sample Book (.json)

Video Tutorial

Watch this video for a visual walkthrough on how to get started with Storyteller, add your sounds, and use the core features:

Watch Tutorial Video

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, YouTube clip, or Syrinscape Element 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.

Audio Controls & Settings

Master Volume

A global volume control affecting all sounds (file-based, YouTube, and Syrinscape). It acts as a percentage multiplier (0-100%) on top of individual Page/Variation volumes. Find it below the main control buttons on the main page. The 'Stop All Sounds' button () still mutes everything instantly and is independent of this slider.

Autoplay on Chapter Tab Click (Setting)

This setting (in the main Settings modal ) determines if clicking a chapter tab triggers that chapter's 'Autoplay Pages on Enter'.

• 'On': Clicking a tab always attempts to play autoplay pages (respecting page time restrictions).
• 'Only While Listening': Autoplay via tab click only occurs if speech recognition is active.
• 'Off': Clicking a tab never triggers autoplay pages.

Note: Voice-initiated chapter transitions (Enter/Exit phrases, Plotter threads) *always* attempt to trigger autoplay pages for the destination chapter, regardless of this setting (respecting page time restrictions).

Syrinscape Integration

To use Syrinscape sounds:

1. Go to Settings ().
2. Enter your Syrinscape Auth Token (found on your Syrinscape account page).
3. Click "Initialize Syrinscape Player". You should see a success message. This only needs to be done once per session, or if the token changes.
4. When adding or editing a Page/Source Variation, select "Syrinscape" as the type.
5. Use the "Search Syrinscape" input and button. A modal will appear with search results.
6. Click on a sound from the search results to select it. Its Element ID, Name, and Kind will be stored.
7. Optionally, set a "Play Duration (seconds)" for the Syrinscape sound if you want it to stop automatically. If a duration is set, Storyteller's loop controls for this source will be disabled/unchecked.

Syrinscape sounds will then be playable like other sound types. The main "Stop All Sounds" button will also attempt to stop all Syrinscape sounds via syrinscape.player.controlSystem.stopAll(). Individual Syrinscape sounds are stopped using their Element ID and Kind. If a duration is set, the sound will stop after that time.

Syrinscape Preview in Search

In the "Search Syrinscape Sounds" modal, each result will have a single Play/Stop toggle button ( / ). This allows you to preview sounds before adding them to your page. Only one preview can play at a time from the modal. Previews stop if the modal is closed or if "Stop All Sounds" is used.

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:

1. It first looks for playable variations assigned to the currently active chapter AND matching the current time of day (or set to 'Always' time).
2. 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).
3. If multiple suitable variations are found at either step, one is chosen randomly.
4. If no variation matches the chapter and time criteria, the page will not play automatically.

Exception for Plot Threads: When sounds are triggered via a Story Plotter thread, the system will typically select variations based on the destination chapter of the thread and the current time of day (after any time change specified by the thread). This ensures sounds play in the context of the new scene.

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/Plotter Sounds: Only stops sounds started automatically by chapter enter/exit actions or plot threads. Manually played 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.

• Built-in Exit Phrases: leave, exit, depart from, leaving, exiting.
• 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'). For Syrinscape, use the search to find and select an element, and optionally set a play duration.
• 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.

Story Plotter

The Story Plotter provides a visual way to map out transitions between chapters using "threads". Open it using the button.

• Chapter Nodes: All existing chapters in your book, including the 'Index' chapter, are automatically added as nodes to the plot board when you open the plotter. Nodes for newly created chapters (or if Index wasn't there) will appear when you next open the plotter.
• Moving Nodes: Click and drag the header of a chapter node to reposition it. Threads connected to the node will update dynamically as you drag.
• Creating Threads: Click the blue output connector (right side) of a node, then click the input connector (left side) of the target node. This creates a visual thread representing a potential transition. You can create multiple distinct threads between the same two chapters if needed.
• Overlapping Threads: If multiple threads exist between the same two chapters, they will be automatically drawn with a slight offset to prevent complete overlap, making them easier to distinguish and click.
• Configuring Threads: Click directly on a thread line to open its configuration menu. Here you can set:
  • Title (Optional): A name for the thread, shown when hovering over the line.
  • Transition Phrases/Keywords: Specific phrases or keywords that will activate this thread when spoken while in the 'from' chapter.
  • Sounds on Transition: Pages to play **simultaneously** when this thread is activated. Use the search bar to filter pages.
  • Time Condition: Restrict thread activation to 'Day Only' or 'Night Only'.
  • Time Change: Optionally change the global time of day to 'Day' or 'Night' when the thread activates.
• Thread Appearance: Threads are automatically colored differently. Hovering over a thread highlights it and shows its title (if set).
• Deleting Threads: Open the thread's configuration menu and click "Delete Thread".
• Navigation: Use the mouse wheel to zoom in/out. Click and drag the background to pan the view. Use the control buttons to zoom or reset the view.

Activation Logic: When you speak, the system first checks if any configured plot threads originating from the current chapter match your phrase (based on the thread's phrases/keywords and time condition). If a matching thread is found:

1. The time of day may change if specified by the thread.
2. The active chapter switches to the thread's destination.
3. The configured sounds for the thread then play **simultaneously**. These sounds will respect the Page's overall 'Time of Day Restriction' and their individual 'Source Variation' settings (including chapter and time-of-day assignments for variations, based on the new chapter and time).

This process takes priority over standard Enter/Exit phrase chapter transitions.

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 and story plot data.
• Export/Import Chapter: Saves or loads a single chapter and its associated pages/settings.
• Relink Missing Files: Appears if missing audio files are detected.
• Burn Book: Permanently deletes all data.

Keyboard Shortcuts

• Spacebar: Start/Stop Listening (Toggle/Push mode)
• Ctrl+S / Cmd+S: Save Book to File
• Ctrl+O / Cmd+O: Load Book from File
• Ctrl+Q / Cmd+Q: Stop All Sounds
• Ctrl+Enter / Cmd+Enter: Confirm in Modals
• Escape: Close Modals