StoryScore - Audio-Enhanced Ebook Reader

An immersive reading experience that combines background audio with storytelling. Built with React, TypeScript, Howler.js, and Framer Motion.

Features

• Audio-Enhanced Reading: Background audio tracks that sync with story progression
• Scroll-Based Audio Control: Audio tracks automatically start/stop based on scroll position
• Beautiful Typography: Serif fonts and paper-like background for optimal reading experience
• Browser Audio Compatibility: Handles browser audio policies with user interaction unlock
• Debug Mode: Press 'D' to toggle debug mode and see audio markers

How It Works

Story Format

The app uses a custom markdown format with special syntax:

@[meta:id:my-story]
@[meta:title:My Story]
@[meta:author:Author Name]
@[meta:cover:/cover/image.jpg]
@[meta:description:Story description]

@[config:audio:trackmapping:track1=/sounds/jungle-ambience.mp3]
@[config:audio:trackmapping:track2=/sounds/tension.mp3]

# Chapter Title

@[spacing:viewport]

@[audio:start:section-1:track1:volume:0.2:fadeIn:2:fadeOut:1]

Story text here...

@[audio:end:section-1]

@[audio:start:section-2:track2:volume:0.3:fadeIn:1:fadeOut:2]

More story text...

@[audio:end:section-2]

Syntax Reference

• @[meta:key:value] - Story metadata (id, title, author, cover, description)
• @[config:audio:trackmapping:trackName=filePath] - Maps track names to audio files
• @[spacing:viewport|large] - Adds vertical spacing (viewport height or large)
• @[audio:start:segmentId:trackName:volume:0.5:fadeIn:2:fadeOut:1] - Start audio segment
  • segmentId - Unique identifier to pair start/end markers
  • trackName - The track to play (as defined in trackmapping)
  • volume - Volume level 0.0 to 1.0 (optional, default 1.0)
  • fadeIn - Fade in duration in seconds (optional, default 0)
  • fadeOut - Fade out duration in seconds (optional, default 0)
• @[audio:end:segmentId] - End audio segment (references the start marker's segmentId)

Audio Tracks

Place your audio files in the public/sounds/ directory. Supported formats: MP3, WAV, OGG.

Development

# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

Technical Details

• React 19 with TypeScript for the UI
• Howler.js for audio management and browser compatibility
• Framer Motion for smooth animations
• Tailwind CSS for styling
• Intersection Observer API for scroll-based audio triggering
• Custom Markdown Parser for story format

Browser Compatibility

The app handles browser audio policies by requiring a user interaction before playing audio. An overlay appears on first load to unlock audio playback.

Debug Mode

Press 'D' to toggle debug mode and see audio markers in the story. This helps with positioning audio triggers during development.