Plugin Structure

Plugins are Python files that define classes inheriting from the PluginBase class. Each plugin must implement a standard interface to work with the Plugin Manager.

Basic Plugin Structure

# plugins/my_custom_generator.py
import random
import pretty_midi
from plugin_api import PluginBase

class MyCustomGenerator(PluginBase):
    """
    My custom MIDI generator plugin
    """
    
    def __init__(self):
        super().__init__()
        self.name = "My Custom Generator"
        self.description = "Generates MIDI notes using my algorithm"
        self.author = "Your Name"
        self.version = "1.0"
        
        # Define parameters
        self.parameters = {
            "param_name": {
                "type": "int",  # Can be "int", "float", "bool", "list", or "str"
                "min": 0,       # For numeric types
                "max": 100,     # For numeric types
                "default": 50,  # Default value
                "description": "Description of the parameter"
                # For "list" type, add "options": ["Option1", "Option2", ...]
            },
            # More parameters...
        }
    
    def generate(self, existing_notes=None, **kwargs):
        """
        Generate MIDI notes
        
        Args:
            existing_notes: Optional list of existing notes
            **kwargs: Parameters passed from the UI
            
        Returns:
            List of generated pretty_midi.Note objects
        """
        # Extract parameters with defaults
        param_value = kwargs.get("param_name", self.parameters["param_name"]["default"])
        
        # Your generation algorithm here...
        result = []
        
        # Example: Create a simple note
        note = pretty_midi.Note(
            velocity=100,
            pitch=60,  # Middle C
            start=0.0,
            end=1.0
        )
        result.append(note)
        
        return result

Installing Your Plugin

1. Save your plugin file in the plugins directory.
2. Restart the application, or click "Refresh" in the Plugin Manager if available.
3. Your plugin will be automatically discovered and added to the list.

Working with MIDI Notes

The Piano Roll uses the pretty_midi library for MIDI note representation. Each note is a pretty_midi.Note object with the following properties:

• pitch: The MIDI note number (0-127)
• velocity: The velocity of the note (0-127)
• start: The start time in seconds
• end: The end time in seconds

Parameter Types

The following parameter types are supported:

• int: Integer value with min/max range
• float: Floating-point value with min/max range
• bool: Boolean value (true/false)
• list: Selection from a list of options
• str: Text value (can be combined with options for a dropdown)

Example Parameter Definitions

# Integer parameter
"tempo": {
    "type": "int",
    "min": 60,
    "max": 240,
    "default": 120,
    "description": "Tempo in BPM"
}

# Float parameter
"probability": {
    "type": "float",
    "min": 0.0,
    "max": 1.0,
    "default": 0.5,
    "description": "Probability of note generation"
}

# Boolean parameter
"use_existing": {
    "type": "bool",
    "default": True,
    "description": "Use existing notes as input"
}

# List parameter
"scale": {
    "type": "list",
    "options": ["Major", "Minor", "Pentatonic", "Blues"],
    "default": "Major",
    "description": "Musical scale to use"
}

Example Plugins

The application comes with several example plugins:

1. motif_generator.py: Creates melodies based on motifs and variations
2. markov_generator.py: Uses Markov chains to generate melodies
3. melody_generator.py: Emotional melody generator inspired by FL Studio
4. godzilla_piano_transformer.py: AI-powered generation using Godzilla Piano Transformer model

AI-Powered Plugins

The godzilla_piano_transformer.py plugin demonstrates integration with external AI models:

• Uses Gradio API to communicate with Hugging Face Spaces
• Supports existing notes as input primers
• Includes fallback generation if API is unavailable
• Demonstrates proper error handling and retry logic
• Uses helper utilities from api_helpers.py for common operations

Study these examples to understand how to create more complex generation algorithms.

Tips for Plugin Development

1. Test incrementally: Start with a simple generator and gradually add complexity.
2. Use random seeds: Allow users to specify a random seed for reproducible results.
3. Handle existing notes: Consider how your plugin will interact with existing notes.
4. Provide clear descriptions: Make sure your parameters have clear descriptions.
5. Validate parameters: Use the validate_parameters method to ensure valid input.

Advanced Plugin Features

For advanced plugins, you can:

1. Create custom helper methods within your plugin class.
2. Use advanced music theory concepts (scales, chords, progressions).
3. Incorporate machine learning algorithms if applicable.
4. Process existing notes to create variations or accompaniments.
5. Integrate external APIs for AI-powered generation.

Working with External APIs

For plugins that integrate with external APIs (like AI models), use the helper utilities in api_helpers.py:

from .api_helpers import (
    ApiConnectionManager,
    MidiFileHandler, 
    TempFileManager,
    validate_api_parameters,
    create_fallback_melody
)

class MyAIPlugin(PluginBase):
    def __init__(self):
        super().__init__()
        self.connection_manager = ApiConnectionManager(max_retries=3, timeout=60)
    
    def generate(self, existing_notes=None, **kwargs):
        with TempFileManager() as temp_manager:
            # Create input MIDI file
            input_path = MidiFileHandler.create_temp_midi_from_notes(existing_notes)
            temp_manager.add_temp_file(input_path)
            
            # Make API call with retry logic
            result = self.connection_manager.call_with_retry(self._api_call, input_path, **kwargs)
            
            # Parse result or fallback
            if result:
                return MidiFileHandler.parse_midi_file(result)
            else:
                return create_fallback_melody()

API Helper Utilities

The api_helpers.py module provides:

• ApiConnectionManager: Retry logic and timeout handling
• MidiFileHandler: MIDI file creation and parsing
• TempFileManager: Automatic cleanup of temporary files
• validate_api_parameters: Parameter validation and normalization
• create_fallback_melody: Simple fallback when APIs fail

Plugin Showcase

Share your plugins with the community! If you've created an interesting plugin, consider submitting it to our 🌟 Showcase Wiki or open a pull request to include it in the main repository.

Use the hashtag #MIDIGen on social media to share your creations!