Skip to content

STUDIO.md

Latest commit

 

History

History
118 lines (89 loc) · 6.42 KB

STUDIO.md

File metadata and controls

118 lines (89 loc) · 6.42 KB
Raw

Desktop Studio Guide

The Interactive Reader Desktop Studio provides a visual environment for narration design, dialogue attribution review, character voice assignment, and pronunciation customization.

The Studio is embedded directly in the desktop reader window (ireader document.md --window).

1. Opening the Studio

Launch your document in window mode:

uv run ireader chapter.md --window

Click the Studio & Settings button in the reader toolbar to open the Studio drawer. The Studio interface contains three primary tabs:

  1. Characters & Voice — Manage narrator voice, active book characters, and the global character roster.
  2. Dialogue — Review detected dialogue, correct speaker attributions, and mark non-dialogue text.
  3. Pronunciation — Add phonetic overrides for terms, names, and technical vocabulary.

2. Characters & Voice

Narrator Voice

Set the default voice used for non-dialogue prose and unassigned dialogue.

  • Choose any voice from the Kokoro voice catalog (e.g., am_fenrir, af_bella, bf_emma).
  • Click 🔊 Preview to hear a sample of the voice.

This Book (Active Characters)

Lists character profiles currently active for this specific document.

  • Click + New Book Character to create a profile.
  • Character ID: Unique, immutable identifier (e.g., alice, dr_watson).
  • Display Name: Primary character name (e.g., Alice, Dr. John Watson).
  • Voice: The Kokoro voice assigned to this character.
  • Aliases: Comma-separated alternative names or titles used in the text (e.g., Watson, the doctor).
  • Click 🔊 Preview Voice within the modal to test the character voice before saving.

Global Character Roster (Reusable)

The Global Roster is a cross-book library of character voices persisted in ~/.interactive_reader/characters.json.

  • Dormant by Default: Characters in the global roster do not automatically participate in dialogue attribution for open books until activated.
  • "Use in This Book": Click the Use in This Book button on any global character to copy a detached snapshot into the current book's configuration.
  • No Live Coupling: Modifying a character in the global roster later will not mutate existing books or cause unexpected audio staleness.
  • Add to Global Roster: Click Add to Global on any local character profile to save it to your reusable library.

3. Dialogue Review Workflow

Interactive Reader uses deterministic dialogue parsing to automatically detect quotes and infer speakers. The Dialogue tab allows you to inspect and correct these attributions.

┌────────────────────────────────────────────────────────────┐
│ ITEM 4 OF 18                                      DIRECT   │
│ "I didn't expect you so early," she said.                  │
│                                                            │
│ Speaker: Sarah      Attribution: Direct (speaker after)    │
│ [ Previous ]  [ ✕ Not Dialogue ]      [ Save & Next ]      │
└────────────────────────────────────────────────────────────┘

Review Queue & Filter Buckets

Filter quotes by confidence category:

  • All: All detected quotes in the document.
  • Unknown: Quotes where no reliable speaker was identified.
  • Contextual: Quotes inferred from conversational context or proximity.
  • Direct: Quotes with explicit speaker attribution verbs (e.g., said Alice).
  • Overrides: Quotes with manual user corrections.
  • Not Dialogue: Quotes marked as non-dialogue prose.

Review Card & Actions

  • Click Excerpt: Clicking the excerpt jumps the reader to that exact quote in the document.
  • Speaker Selection: Choose an active character from the dropdown. You can also select a character from the Global Roster section of the dropdown, which automatically activates the character in this book.
  • Save & Next (Alt+N / Enter): Save the speaker override and advance to the next item.
  • Previous (Alt+P): Return to the previous quote.
  • [ ✕ Not Dialogue ]: Mark the text as non-dialogue prose (e.g., technical quotes, scare quotes, or title citations).
  • Clear Override: Remove a manual override and return to automatic attribution.

4. Pronunciation Lexicon

The Pronunciation tab allows you to override default grapheme-to-phoneme (G2P) pronunciation for uncommon names, fantasy terms, acronyms, or mispronounced words.

Adding & Editing Rules

Click + Add Rule to open the pronunciation editor:

  • Scope:
    • This Book: Applies only to the current document (chapter.ireader.json).
    • Global (All Books): Applies across all documents (~/.interactive_reader/lexicon.json).
  • Word / Term: The word or root term to match (e.g., Enma).
  • Normal G2P: Shows the baseline Misaki G2P phoneme breakdown.
  • Phoneme Override: Kokoro/Misaki phonetic notation (e.g., ˈɛnmə).
  • Case Sensitive: Restrict matching to exact casing.
  • Possessive Handling: Rules automatically derive standard possessive inflections (e.g., Enma's -> ˈɛnməz).

Live Previews

  • Phoneme Preview: Instant in-memory phonetic resolution as you type.
  • 🔊 Preview Audio: Synthesizes an ephemeral audio snippet using the inference engine.

Rule Hierarchy & Masking

  • Rules are tagged as [Book] or [Global].
  • If a book rule matches the same term as a global rule, it displays as [Book Override] with (Masking Global: /.../).
  • Deleting the book override restores and unmasks the global rule.

5. Save vs. Apply & Audio Regeneration

Immediate Persistence

Every change made in the Studio (character edit, speaker override, pronunciation rule) is saved immediately to disk in the document's sidecar (chapter.ireader.json) or global storage.

On-Demand Regeneration

Configuration changes do not interrupt current playback. When audio-affecting changes are saved:

  1. The Studio displays a pending notice (e.g., Audio changes pending: 3 of 12 units require regeneration).
  2. Click ⚡ Regenerate Audio to start background synthesis.
  3. Prefix Preservation: Only modified units and subsequent dependent audio units are regenerated. Unchanged preceding audio remains fully intact and instantly playable.