Project: [Creative Apps] - [Story Weaver]

[sakshisemalti]

Track

Creative Apps (GitHub Copilot)

Project Name

Story Weaver

GitHub Username

@sakshisemalti

Repository URL

https://github.com/sakshisemalti/Story-Weaver

Project Description

About Project

The Story Weaver is a full-stack web application that lets anyone create and experience a personalized, AI-generated interactive story — in real time, right in the browser.

You pick a genre, describe your characters, and paint the world you want to inhabit. The AI writes your opening scene. Then you drive the story forward by making choices at the end of each chapter. Every decision changes what happens next. When the tale concludes, you can download the entire story you co-created — as a text file or structured JSON.

It's part interactive fiction, part creative writing tool, part AI playground. No writing skills required. No account needed. Just imagination.

The Problem It Solves

Most AI writing tools are just blank text boxes — you prompt, it generates, and you're done. There's no interactivity, no personal investment, no sense that your decisions matter.

The Story Weaver flips this. It puts the reader in the driver's seat:

• Writers use it to explore story directions they haven't thought of
• Readers experience stories that feel personal because they shaped them
• Educators use it for creative writing exercises and narrative thinking
• Developers can see a working pattern for human-in-the-loop AI generation
• The core insight is simple: AI-generated text becomes far more engaging when the human has agency over where it goes.

Features

Story Generation

• Choose from 6 genres: Fantasy, Sci-Fi, Mystery, Horror, Romance, Adventure
• Describe your characters and setting in your own words — total creative freedom
• AI writes a unique opening scene every single time — no two stories are alike
• 3 branching choices per chapter let you steer the narrative
• 3 chapters + epilogue give every story a proper arc and satisfying conclusion
• Graceful mock fallback if the AI is unavailable — the app never crashes or breaks

Scene Illustrations

• Every chapter gets a mood-matched scene image from Picsum Photos CDN
• Images load instantly — no API key, no rate limits, no delays
• Seeds are deterministic: same genre + chapter always = same image, every time

Voice Narration

• Full text-to-speech narration using the browser's Web Speech API — no external service needed
• Voice picker with three categories:
  Female — Samantha, Zira, Karen and similar voices
  Male — Daniel, Alex, David and similar voices
• Browse and select any installed system voice by name from a dropdown
• Pitch auto-adjusts per category for the best dramatic effect
• Stops automatically on each new chapter; restart anytime

Reading Experience

• Typewriter animation reveals story text character by character for cinematic effect
• Skip button for readers who want to read at their own pace
• Chapter progress bar shows how far through the story you are
• Collapsible story history lets you review every past chapter and the choices you made

Export Your Story

• Download as .txt — clean, readable plain text with chapter headings
• Download as .json — structured data with metadata, all chapter text, choices made, and image URLs
• Keep, share, or print the story you created

Responsive Design

• Works beautifully on mobile, tablet, and desktop
• Dark gothic parchment aesthetic with warm amber candlelight accents
• Typography: Playfair Display (headings) + Crimson Text (body) + JetBrains Mono (UI labels)

Demo Video or Screenshots

Demo Video : https://youtu.be/heN7JVFrewU

Primary Programming Language

Python

Key Technologies Used

Frontend	React 18, React Router v6
Developer Tools	GitHub Copilot
Styling	TailwindCSS 3
Build Tool	Vite
Backend	Node.js, Express
Local AI	Ollama HTTP API
AI Model	gemma:2b (swappable via .env)
Voice	Web Speech API (browser-native, no cost)
Images	Picsum Photos CDN

Submission Type

Individual

Team Members

No response

Submission Requirements

• My project meets the track-specific challenge requirements
• My repository includes a comprehensive README.md with setup instructions
• My code does not contain hardcoded API keys or secrets
• I have included demo materials (video or screenshots)
• My project is my own work with proper attribution for any third-party code
• I agree to the Code of Conduct
• I have read and agree to the Disclaimer
• My submission does NOT contain any confidential, proprietary, or sensitive information
• I confirm I have the rights to submit this content and grant the necessary licenses

Quick Setup Summary

1.Clone the Repository

git clone https://github.com/your-username/your-repo.git
cd your-repo

2.Install Dependencies

# Install backend dependencies
cd backend
npm install

# Install frontend dependencies
cd ../frontend
npm install

3.Install & Start Ollama

Download and install Ollama: Ollama

• Pull a model

ollama pull gemma:2b
ollama serve
# Runs on http://localhost:11434

4. Start the backend

cd backend
npm install
# create a file .env in backend folder
npm start
# Runs on http://localhost:3001

5. Start Frontend

cd frontend
npm install
npm run dev
# Runs on http://localhost:3000

You're Ready!
Open in your browser:
http://localhost:3000
Start weaving your AI-generated story.

---

Environment Variables

backend/.env:

OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=gemma:2b
PORT=3001
OLLAMA_TIMEOUT_MS=30000

Technical Highlights

Technical Highlights

1. Human-in-the-Loop AI Design
   The story is generated chapter-by-chapter based on user choices instead of a single prompt. This preserves narrative continuity while giving users meaningful control over story progression.

2. Local-First AI (No Cloud Dependency)
   Runs entirely on Ollama with local LLMs:

• No API keys
• No usage costs
• Fully offline capable

3. Model-Agnostic Backend
   AI logic is isolated in the backend. Switching models (Gemma, LLaMA, Mistral, etc.) requires only a .env change — no frontend modifications.

4. Multi-Voice Narration System
   Implemented dynamic voice selection using the Web Speech API:

• Automatically loads system voices (onvoiceschanged handling)
• Categorizes voices into Female and Male
• Supports accent-based filtering (en-GB, en-AU, en-IE)
• Stops and resets narration cleanly on chapter change

5. Structured Prompt Engineering
   Prompts are designed to:

• Maintain prior chapter context
• Return structured JSON
• Reduce hallucinations
• Ensure predictable API responses

6. Resilient Fallback System
   If the AI model fails or times out, the backend switches to a mock generator so the app never crashes during a demo.

7. AI-Assisted Development
   GitHub Copilot was used as an AI pair programmer for scaffolding, debugging async logic, refactoring, and improving prompt design — accelerating development.

Challenges & Learnings

1. Maintaining Story Continuity

Challenge: Ensuring each AI-generated chapter stayed consistent with previous events and character behavior.
Learning: Context injection and structured prompt design are critical for maintaining narrative coherence in multi-step AI workflows.

2. Handling LLM Timeouts & Failures

Challenge: Ollama occasionally timed out or returned slow responses, especially with larger models.
Learning: Implementing configurable timeouts and a graceful fallback system is essential for building resilient AI applications with the help of github copilot

3. Web Speech API Voice Loading

Challenge: Voices load asynchronously in some browsers (especially Chrome), causing the voice picker to appear empty.
Learning: Proper event handling (onvoiceschanged) and state synchronization are necessary when working with browser-native APIs.

4. Structured AI Output Parsing

Challenge: Ensuring the AI consistently returned properly formatted JSON for frontend rendering.
Learning: Clear output constraints in prompts significantly reduce hallucinations and parsing errors.

Contact Information

https://www.linkedin.com/in/sakshi-semalti/

Country/Region

India