Dorothy 🎵✨

Create audio-reactive visuals in Python with just a few lines of code

Now with OpenGL

Dorothy is a creative computing library that makes it incredibly easy to build interactive visual art that responds to music, beats, and audio in real-time. Think Processing meets Python, with superpowers for audio visualisation.

Dorothy in action

✨ Why Dorothy?

🎵 Audio-First: Built specifically for music visualisation with FFT, beat detection, and amplitude analysis
🎨 Artist-Friendly: Implementing existing best practices for an API that feels natural for creative coders
⚡ Real-Time: Smooth visuals with efficient OpenGL rendering
🤖 AI-Ready: Seamless integration with RAVE, MAGNet, and other ML audio models
🐍 Pure Python: Use NumPy, PyTorch, TensorFlow, or any Python library alongside Dorothy

🚀 Quick Start

Installation

pip install dorothy-cci

Your First Audio-Reactive Visual

from dorothy import Dorothy

dot = Dorothy()

class MySketch:
    def __init__(self):
        dot.start_loop(self.setup, self.draw)
    
    def setup(self):
        # Load your favorite song
        dot.music.start_file_stream("your_song.wav")
        dot.music.play()
    
    def draw(self):
        dot.background((0, 0, 0))  # Black background
        
        # Circle that pulses with the music
        size = 50 + dot.music.amplitude() * 200
        dot.fill((255, 100, 150))  # Pink
        dot.circle((dot.width//2, dot.height//2), size)

MySketch()

That's it! You now have a pink circle that pulses to your music. Press q to quit.

🎯 What Can You Build?

<details> <summary><strong>🎵 Audio Visualisers</strong> - Spectrum analysers, waveform displays, beat-reactive patterns</summary>

def draw(self):
    dot.background((0, 0, 0))
    
    # Draw FFT bars
    for i, freq in enumerate(dot.music.fft_vals()[:50]):
        height = freq * 300
        x = i * (dot.width / 50)
        dot.fill((100, 200, 255))
        dot.rectangle((x, dot.height - height), (x + 10, dot.height))

</details> <details> <summary><strong>🎨 Interactive Art</strong> - Mouse-controlled visuals, webcam integration, generative patterns</summary>

def draw(self):
    # Mouse-controlled brush with audio-reactive size
    brush_size = 10 + dot.music.amplitude() * 50
    dot.fill((255, dot.mouse_x % 255, dot.mouse_y % 255))
    dot.circle((dot.mouse_x, dot.mouse_y), brush_size)

</details> <details> <summary><strong>🤖 AI-Powered Visuals</strong> - RAVE model integration, neural audio synthesis, ML-driven art</summary>

# Generate audio with AI and visualise it
rave_id = dot.music.start_rave_stream("vintage.ts")
dot.music.play()

def draw(self):
    # Visualise AI-generated audio spectrum
    for i, val in enumerate(dot.music.fft_vals):
        # Your visualization code here

</details>

📚 Learning Path

All Examples

🌟 Level 1: Your First Steps

🎵 Pulse Rectangle - Circle that grows with music
🌈 Color Beats - Colors that change on beats
📊 Simple Spectrum - Your first FFT visualiser

🔥 Level 2: Getting Creative

🎭 Mouse Magic - Interactive drawing with audio
📹 Webcam Reaktor - Video effects with music
✨ Body Tracking - Hand tracking from tensorflow

🚀 Level 3: Advanced Wizardry

🤖 AI Audio Generation - RAVE and MAGNet integration
🎪 Live Coding - Update visuals without restarting
🎨 Complex Compositions - Multi-layer masterpieces

🎛️ Core Features

Audio Analysis

dot.music.amplitude()      # Current volume level (0-1)
dot.music.fft_vals()       # Frequency spectrum array
dot.music.is_beat()      # True if beat detected this frame

Drawing Tools

dot.fill((r, g, b))                  # Set fill color
dot.stroke((r, g, b))                # Set outline color
dot.circle((x, y), radius)           # Draw circles
dot.rectangle((x1, y1), (x2, y2))    # Draw rectangles
dot.line((x1, y1), (x2, y2))         # Draw lines

Interaction

dot.mouse_x, dot.mouse_y             # Mouse position
dot.width, dot.height                # Canvas dimensions
dot.millis, dot.frames               # Time and frame count

🎵 Audio Sources

🎧 Play Audio Files

dot.music.start_file_stream("song.wav")
dot.music.play()

🎤 Live Audio Input

# Use your microphone or system audio
dot.music.start_device_stream(device_id)

🤖 AI Audio Generation

# Generate with RAVE models
dot.music.start_rave_stream("model.ts")

# Generate with MAGNet models  
dot.music.start_magnet_stream("model.pth", "source.wav")

💡 Pro Tips

Start Simple: Begin with basic shapes and gradually add complexity
Use Live Coding: Enable hot-reloading for faster iteration (see example)
Layer Effects: Use dot.get_layer() for transparency and complex compositions
Optimise for Performance: Complex drawings may need optimisation
Debug Visually: Use annotate=True on shapes to see coordinates

🛠️ Installation & Setup

Requirements

Python 3.10, 3.11, 3.12, 3.13
Windows, macOS, or Linux
Audio device (speakers/headphones recommended)

For Audio Routing (macOS)

We recommend BlackHole for routing system audio to Dorothy.

Troubleshooting

<details> <summary>Common issues and solutions</summary>

No audio detected: Check your audio device with print(sd.query_devices())

Window won't close: Use Ctrl+C in terminal or q key with window focused

Installation issues: Try pip3 install dorothy-cci or create a virtual environment

Performance issues: Reduce canvas size or simplify drawing operations

</details>

🎨 Gallery

Coming Soon: Amazing projects built with Dorothy by the community!

Want to showcase your Dorothy creation? Open an issue with your project!

🤝 Community & Support

📖 Documentation: Full API Reference
💬 Discussions: GitHub Discussions
🐛 Issues: Report Bugs
📧 Contact: [Your contact info]

🚀 Contributing

Dorothy is open source and we love contributions! Whether it's:

🐛 Bug fixes
✨ New features
📖 Documentation improvements
🎨 Example projects
💡 Feature ideas

Check out our Contributing Guide to get started.

📄 License

Dorothy is MIT licensed. Create amazing things!

🙏 Acknowledgments

Built with love using:

ModernGl for fast graphics
sounddevice for audio I/O
librosa for audio analysis
NumPy for efficient computing

Ready to make some visual music? 🎵✨

Get Started • Examples • Documentation • Community

Made with ❤️ for creative coders, digital artists, and music lovers

</div>

Dorothy

Install / Use

README