Sawdust

A powerful, extensible music visualization application built with Python and PySide6. Create stunning visual effects synchronized to your audio tracks with an intuitive plugin-based architecture.

Features

🎵 Audio-Reactive Visualizations

• Waveform Effects: Dynamic audio waveforms with customizable styles and colors
• Point Sphere: 3D particle systems that react to audio frequencies
• Real-time Audio Analysis: Advanced frequency analysis and envelope detection

🎨 Visual Effects

• Text Overlays: Customizable text with fonts, colors, and positioning
• Image Effects: Import and manipulate images with transformations
• Plugin Architecture: Extensible system for creating custom effects

🎬 Video Production

• High-Quality Rendering: Export your visualizations as MP4 videos
• Real-time Preview: See your effects in action before rendering
• Project Management: Save and load projects with .sdust files

🔧 Technical Features

• Modern UI: Clean, intuitive interface built with PySide6
• Cross-Platform: Works on macOS, Windows, and Linux
• GPU Acceleration: Optional OpenGL support for enhanced performance
• Modular Design: Clean separation between UI and business logic

Installation

Prerequisites

• Python 3.11 or higher
• PySide6
• NumPy
• Additional dependencies listed in requirements.txt

Setup

1. Clone the repository:

   git clone https://github.com/askscience/Sawdust.git
   cd Sawdust

2. Create a virtual environment:

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

3. Install dependencies:

   pip install -r requirements.txt

4. Run the application:

   python3 app.py

Usage

Basic Workflow

1. Load Audio: Click "Select Audio" to choose your music file
2. Add Effects: Use the "Add Effect" menu to add visualizations
3. Customize: Adjust effect properties in the right panel
4. Preview: Use the play controls to preview your visualization
5. Render: Click "Render Video" to export your creation

Effect Types

Waveform Effects

• Style: Choose from various waveform representations
• Colors: Customize primary and accent colors
• Parameters: Adjust bar count, thickness, and height

Text Overlays

• Content: Add custom text messages
• Typography: Choose fonts, sizes, and colors
• Positioning: Place text anywhere on the canvas

Image Effects

• Import: Load images from your computer
• Transform: Scale, rotate, and position images
• Blend: Control opacity and blending modes

Point Sphere

• 3D Visualization: Complex particle systems
• Audio Reactivity: Particles respond to frequency data
• Customization: Extensive parameter control

Project Management

• Save Projects: File → Save Project (.sdust format)
• Load Projects: File → Open Project
• New Projects: File → New Project

Plugin Development

Sawdust uses a modular plugin architecture. Each effect is a separate plugin located in src/plugins/:

src/plugins/
├── text/           # Text overlay effects
├── image/          # Image manipulation effects
├── waveform/       # Audio waveform visualizations
└── point_sphere/   # 3D particle systems

Creating Custom Effects

1. Create a new directory in src/plugins/
2. Implement the Effect base class
3. Define your effect's properties and rendering logic
4. The plugin system will automatically discover and load your effect

Architecture

Core Components

• MainWindow: Primary UI and application logic
• ProjectManager: Handles save/load functionality and serialization
• Effect System: Base classes and plugin architecture
• Audio Utils: Frequency analysis and audio processing
• Render Engine: Video export and frame generation

Key Files

• src/main_window.py: Main application window and UI logic
• src/project_manager.py: Project serialization and data management
• src/effect_base.py: Base effect class and interfaces
• src/plugin_loader.py: Dynamic plugin discovery and loading
• src/render.py: Video rendering and export functionality

Contributing

We welcome contributions! Please feel free to:

• Report bugs and issues
• Suggest new features
• Submit pull requests
• Create new effect plugins

Development Setup

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Acknowledgments

• Built with PySide6 for the user interface
• Audio processing powered by NumPy
• Video rendering capabilities provided by various multimedia libraries

---

Sawdust - Transform your music into visual art 🎵✨

A powerful Python application for creating music videos with visual effects, built using PySide6 and OpenGL.

Features

• Visual Effects: Add various effects including images, text, waveforms, and 3D shapes
• Real-time Preview: Live preview with both CPU and OpenGL rendering modes
• Audio Integration: Support for audio files with waveform visualization
• Video Export: Render your creations to MP4 format
• Plugin System: Extensible architecture with custom effect plugins

Requirements

• Python 3.11 or higher
• PySide6
• OpenGL support

Installation

1. Clone the repository:

git clone <repository-url>
cd Sawdust

2. Create a virtual environment:

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

3. Install dependencies:

pip install -r requirements.txt

Usage

1. Start the application:

python3 app.py

2. Adding Effects:

   • Click the "+" button to add effects
   • Choose from Image, Text, Waveform, or Point Sphere effects
   • Configure effect properties in the right panel

3. Audio Integration:

   • Load an audio file to sync your visuals
   • Use waveform effects to visualize the audio

4. Preview:

   • Use the preview window to see your creation in real-time
   • Toggle between CPU and OpenGL rendering modes

5. Export:

   • Click "Render" to export your video as MP4
   • Choose output resolution and quality settings

Project Structure

Sawdust/
├── app.py                 # Main application entry point
├── src/
│   ├── main_window.py     # Main application window
│   ├── preview_widget.py  # CPU-based preview widget
│   ├── gl_preview_widget.py # OpenGL preview widget
│   ├── render.py          # Video rendering engine
│   ├── effect_base.py     # Base effect class
│   ├── audio_utils.py     # Audio processing utilities
│   ├── plugin_loader.py   # Plugin system loader
│   ├── plugins/           # Effect plugins
│   │   ├── image/         # Image effect plugin
│   │   ├── text/          # Text effect plugin
│   │   ├── waveform/      # Audio waveform plugin
│   │   └── point_sphere/  # 3D sphere effect plugin
│   └── icons/             # UI icons
└── requirements.txt       # Python dependencies

Available Effects

Image Effect

• Load and display images
• Position, scale, and rotate images
• Opacity control

Text Effect

• Add custom text overlays
• Font selection and styling
• Color and positioning options

Waveform Effect

• Visualize audio waveforms
• Multiple visualization styles
• Color and amplitude customization

Point Sphere Effect

• 3D animated sphere with particles
• Customizable colors and animation speed
• OpenGL-accelerated rendering

Development

Adding New Effects

1. Create a new plugin directory in src/plugins/
2. Implement the effect class inheriting from EffectBase
3. Create a UI file for effect properties
4. The plugin will be automatically loaded by the plugin system

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Troubleshooting

• OpenGL Issues: If you experience rendering problems, try switching to CPU preview mode
• Audio Problems: Ensure your audio files are in supported formats (WAV, MP3, etc.)
• Performance: For better performance, use OpenGL mode and ensure your graphics drivers are up to date

License

This project is open source. Please check the license file for details.