🎭 StoryTeller - AI Audio Drama Generator

StoryTeller is a Python application that transforms text scripts into immersive audio dramas using AI-powered text-to-speech technology. Create professional-quality audio content with different character voices, perfect for podcasts, audiobooks, or interactive storytelling.

✨ Features

• 🎙️ Multi-Character Voice Generation: Assign unique AI voices to different characters
• 🎵 Automatic Audio Combination: Programmatically combines individual audio segments
• 🔧 Easy Configuration: Simple character-to-voice mapping
• 📝 Script Processing: Automatically cleans emotional cues and stage directions
• 🎯 Professional Output: Generates high-quality WAV audio files
• 🛠️ Standalone Tools: Includes utility scripts for audio processing
• 🤖 AI Story Conversion: Convert any story text into drama script format using Google Gemini

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• Deepgram API key (Get one here)
• Google API key (Get one here) - for story conversion feature

Installation

1. Clone the repository

   git clone https://github.com/yourusername/storyteller.git
   cd storyteller

2. Create a virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Set up environment variables

   cp env.example .env
   # Edit .env and add your Deepgram API key

5. Run the audio drama generator

   python src/storyteller/example.py

📖 Usage

Basic Usage

1. Configure your script in src/storyteller/example.py:

   DRAMA_SCRIPT = [
       {"character": "NARRATOR", "line": "Once upon a time..."},
       {"character": "HERO", "line": "I will save the day!"},
       {"character": "VILLAIN", "line": "Not if I can help it!"},
   ]

2. Map characters to voices:

   VOICE_MAP = {
       "NARRATOR": "aura-asteria-en",
       "HERO": "aura-luna-en",
       "VILLAIN": "aura-asteria-en",
   }

3. Run the generator:

   python src/storyteller/example.py

Available Voice Models

StoryTeller supports Deepgram's Aura voice models:

• aura-asteria-en - Clear, professional narrator voice
• aura-luna-en - Warm, engaging character voice
• aura-stella-en - Energetic, dynamic voice
• aura-athena-en - Authoritative, commanding voice
• aura-hera-en - Sophisticated, elegant voice
• aura-orion-en - Deep, resonant voice
• aura-arcas-en - Friendly, approachable voice
• aura-perseus-en - Strong, heroic voice
• aura-angus-en - Warm, fatherly voice
• aura-orpheus-en - Melodic, artistic voice
• aura-helios-en - Bright, optimistic voice
• aura-zeus-en - Powerful, authoritative voice

Note: Voice availability depends on your Deepgram plan.

Advanced Usage

Using the Standalone Audio Combiner

# Combine specific audio files
python scripts/combine_audio.py output.wav file1.wav file2.wav file3.wav

# Combine all files in a directory
python scripts/combine_audio.py final_drama.wav audio_segments/*.wav

Custom Script Processing

The clean_text() function automatically removes stage directions:

# Input: "(Sad voice) I guess I'll just go home."
# Output: "I guess I'll just go home."

AI Story Conversion

The new story conversion feature allows you to convert any story text into a drama script format using Google Gemini.

Using the Story Converter

from storyteller.example import convert_story_to_drama_script

# Your story text
story = """
Sarah was walking through the forest when she heard a strange noise behind her.
She turned around quickly, but there was nothing there. The wind rustled the leaves
above her head. "Hello?" she called out nervously. A voice replied from somewhere
in the trees: "Don't be afraid, Sarah. I've been waiting for you."
"""

# Convert to drama script
drama_script = convert_story_to_drama_script(story)

# The result will be a list of dictionaries like:
# [
#     {"character": "NARRATOR", "line": "Sarah was walking through the forest..."},
#     {"character": "SARAH", "line": "(nervously) Hello?"},
#     {"character": "MYSTERIOUS VOICE", "line": "Don't be afraid, Sarah..."}
# ]

Testing the Story Converter

Run the test script to try the conversion feature:

python test_story_conversion.py

This will:

1. Test the conversion with a sample story
2. Allow you to input your own story for conversion
3. Display the generated drama script

Integration with Audio Generation

Once you have a converted drama script, you can use it with the audio generation:

# Convert your story
drama_script = convert_story_to_drama_script(your_story)

# Replace the DRAMA_SCRIPT in example.py with your converted script
# Then run the audio generation
build_audio_drama()

🏗️ Project Structure

StoryTeller/
├── src/
│   ├── storyteller/           # Main package
│   │   ├── __init__.py
│   │   ├── main.py           # Application entry point
│   │   ├── config.py         # Configuration management
│   │   ├── example.py        # Audio drama generator
│   │   ├── models/           # Data models
│   │   ├── services/         # Business logic
│   │   ├── api/              # API endpoints
│   │   └── utils/            # Utility functions
│   └── tests/                # Test files
├── scripts/                  # Utility scripts
│   ├── dev_server.py        # Development server
│   └── combine_audio.py      # Audio file combiner
├── docs/                     # Documentation
├── requirements.txt          # Production dependencies
├── requirements-dev.txt      # Development dependencies
├── env.example              # Environment variables template
└── README.md                # This file

🔧 Configuration

Environment Variables

Create a .env file with the following variables:

# Required
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# Optional
DEBUG=True
LOG_LEVEL=INFO
LOG_FILE=logs/app.log

Voice Configuration

Customize character voices by modifying the VOICE_MAP:

VOICE_MAP = {
    "NARRATOR": "aura-asteria-en",
    "CHARACTER1": "aura-luna-en",
    "CHARACTER2": "aura-orion-en",
    # Add more characters as needed
}

🧪 Development

Setting up Development Environment

# Install development dependencies
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Run linting
black src/
isort src/
flake8 src/

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src/storyteller

# Run specific test file
pytest src/tests/test_main.py

📚 API Reference

Core Functions

build_audio_drama()

Main function that generates audio for all script lines and combines them.

combine_audio_files(input_files, output_file)

Combines multiple WAV files into a single audio file.

clean_text(text)

Removes stage directions and emotional cues from dialogue.

convert_story_to_drama_script(story_text)

Converts any story text into a drama script format using Google Gemini.

Parameters:

• story_text (str): The input story text to convert

Returns:

• List[Dict[str, str]]: A list of dictionaries with 'character' and 'line' keys

Example:

story = "Once upon a time, Alice found a magical book..."
script = convert_story_to_drama_script(story)
# Returns: [{"character": "NARRATOR", "line": "Once upon a time..."}, ...]

Configuration Functions

load_config()

Loads configuration from environment variables and .env file.

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Deepgram for providing excellent text-to-speech API
• The Python community for amazing audio processing libraries
• Contributors and users who help improve StoryTeller

📞 Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions
• 📧 Contact

🌟 Star History

---

Made with ❤️ for storytellers everywhere