{"id":44850407,"url":"https://github.com/fsecada01/midi-drums","last_synced_at":"2026-02-17T06:18:59.323Z","repository":{"id":316977177,"uuid":"1065377580","full_name":"fsecada01/midi-drums","owner":"fsecada01","description":"🥁 Comprehensive MIDI drum generation system with 4 genres (Metal, Rock, Jazz, Funk), 28 styles, and 7 authentic drummer personalities. Plugin-based architecture for professional EZDrummer-compatible output.","archived":false,"fork":false,"pushed_at":"2026-02-08T16:42:53.000Z","size":507,"stargazers_count":5,"open_issues_count":7,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-08T21:48:52.129Z","etag":null,"topics":["audio-generation","drummer-styles","drums","ezdrummer","midi","multi-genre","music-generation","music-production","plugin-architecture","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fsecada01.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-27T15:50:28.000Z","updated_at":"2026-02-08T16:42:56.000Z","dependencies_parsed_at":"2025-09-28T01:14:31.979Z","dependency_job_id":"9fa71ed6-3034-4d17-a46b-e300a202fbb4","html_url":"https://github.com/fsecada01/midi-drums","commit_stats":null,"previous_names":["fsecada01/midi-drums"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fsecada01/midi-drums","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsecada01%2Fmidi-drums","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsecada01%2Fmidi-drums/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsecada01%2Fmidi-drums/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsecada01%2Fmidi-drums/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fsecada01","download_url":"https://codeload.github.com/fsecada01/midi-drums/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsecada01%2Fmidi-drums/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29535934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T05:00:25.817Z","status":"ssl_error","status_checked_at":"2026-02-17T04:57:16.126Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio-generation","drummer-styles","drums","ezdrummer","midi","multi-genre","music-generation","music-production","plugin-architecture","python"],"created_at":"2026-02-17T06:18:57.204Z","updated_at":"2026-02-17T06:18:59.299Z","avatar_url":"https://github.com/fsecada01.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🥁 MIDI Drums Generator\n\n\u003cdiv align=\"center\"\u003e\n\n[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/)\n[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![MIDI](https://img.shields.io/badge/Output-MIDI-purple.svg)](https://en.wikipedia.org/wiki/MIDI)\n[![EZDrummer](https://img.shields.io/badge/Compatible-EZDrummer_3-orange.svg)](https://www.toontrack.com/product/ezdrummer-3/)\n[![Code Reduction](https://img.shields.io/badge/Code_Reduction-62%25-brightgreen.svg)](claudedocs/REFACTORING_PROGRESS.md)\n[![Test Coverage](https://img.shields.io/badge/Tests-39_passing-success.svg)](tests/)\n[![Type Safety](https://img.shields.io/badge/Type_Safety-100%25-blue.svg)](midi_drums/)\n\n*A comprehensive, plugin-based MIDI drum track generation system*\n\n[🚀 Quick Start](#-quick-start) • [📖 Documentation](#-documentation) • [🎵 Examples](#-examples) • [🔌 Plugins](#-plugin-system) • [🤝 Contributing](#-contributing)\n\n\u003c/div\u003e\n\n---\n\n## 🎯 Overview\n\nMIDI Drums Generator is a powerful Python system that creates professional-quality drum tracks in MIDI format. Built with a modular, plugin-based architecture, it supports multiple musical genres, drummer styles, and song structures with realistic humanization and variations.\n\n### ✨ Key Features\n\n🎪 **Multi-Genre Support**\n- **Metal**: Heavy, Death, Power, Progressive, Doom, Thrash, Breakdown\n- **Rock**: Classic, Blues, Alternative, Progressive, Punk, Hard, Pop\n- **Jazz**: Swing, Bebop, Fusion, Latin, Ballad, Hard Bop, Contemporary\n- **Funk**: Classic, P-Funk, Shuffle, New Orleans, Fusion, Minimal, Heavy\n- **Expandable**: Plugin architecture for Electronic and more\n\n🥁 **Drummer Imitation**\n- **7 Famous Drummers**: Bonham, Porcaro, Weckl, Chambers, Roeder, Dee, Hoglan\n- Signature fills and playing techniques based on research\n- Compatible across multiple genres with authentic styles\n\n🏗️ **Flexible Song Structure**\n- Configurable sections (verse, chorus, bridge, breakdown)\n- Pattern variations and dynamic fills\n- Custom song arrangements\n\n🎛️ **Professional Features**\n- Realistic velocity variations and humanization\n- EZDrummer 3 compatible MIDI mapping\n- Multiple complexity and dynamics levels\n\n🔧 **Multiple Interfaces**\n- Python API for integration\n- Command-line interface (CLI tool installable with `uv tool install`)\n- Direct module usage for custom applications\n- Reaper DAW integration for professional workflows\n\n🤖 **AI-Powered Generation** (NEW!)\n- Natural language pattern generation with Pydantic AI\n- Intelligent composition with Langchain agents\n- Provider-agnostic backend (Anthropic, OpenAI, Groq, Cohere)\n- Environment-driven configuration for production use\n\n## ⚡ Code Quality \u0026 Architecture\n\nThe MIDI Drums Generator underwent comprehensive refactoring achieving **extraordinary code reduction** while maintaining 100% functional equivalence:\n\n### Refactoring Achievements\n\n| Achievement | Metric |\n|-------------|--------|\n| **Total Code Reduction** | 62% (2,898 lines eliminated) |\n| **Genre Plugins** | 37% reduction (757 lines saved) |\n| **Drummer Plugins** | 83% reduction (2,141 lines saved!) |\n| **Test Coverage** | 39 comprehensive tests, 100% passing |\n| **Type Safety** | Full type hints throughout |\n\n### Modern Architecture\n\nThe refactored architecture uses three foundational systems:\n\n**1. Configuration Constants** - Type-safe constants eliminating magic numbers\n```python\nfrom midi_drums.config import VELOCITY, TIMING, DEFAULTS\nbuilder.kick(0.0, VELOCITY.KICK_MEDIUM)  # Self-documenting!\n```\n\n**2. Pattern Templates** - 8 reusable templates for declarative composition\n```python\nfrom midi_drums.patterns import TemplateComposer, DoubleBassPedal, BlastBeat\npattern = TemplateComposer(\"death_metal\").add(DoubleBassPedal()).build()\n```\n\n**3. Drummer Modifications** - 12 composable modifications for authentic techniques\n```python\nfrom midi_drums.modifications import BehindBeatTiming, TripletVocabulary\npattern = behind_beat.apply(triplets.apply(pattern))\n```\n\n### Benefits\n\n✅ **Zero Code Duplication** - Reusable templates and modifications\n✅ **Professional Quality** - Full type hints, comprehensive testing\n✅ **Maintainable** - Clear separation of concerns, easy to extend\n✅ **Tested** - 100% functional equivalence validated\n✅ **Documented** - See [REFACTORING_PROGRESS.md](claudedocs/REFACTORING_PROGRESS.md) for details\n\n## 🚀 Quick Start\n\n### Installation\n\n**Option 1: Install as CLI tool (Recommended)**\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/midi-drums.git\ncd midi-drums\n\n# Install as a global CLI tool\nuv tool install .\n\n# Now use 'midi-drums' command anywhere\nmidi-drums --help\n```\n\n**Option 2: Development installation**\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/midi-drums.git\ncd midi-drums\n\n# Set up virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # Linux/macOS\n# or\n.venv\\Scripts\\activate     # Windows\n\n# Install dependencies\npip install -r core_requirements.txt\n```\n\n### Generate Your First Drum Track\n\n```python\nfrom midi_drums.api.python_api import DrumGeneratorAPI\n\n# Initialize the generator\napi = DrumGeneratorAPI()\n\n# Create a death metal song\nsong = api.create_song(\"metal\", \"death\", tempo=180)\napi.save_as_midi(song, \"death_metal_track.mid\")\n\n# Create a jazz swing pattern with Dave Weckl style\njazz_song = api.create_song(\"jazz\", \"swing\", tempo=120, drummer=\"weckl\")\napi.save_as_midi(jazz_song, \"jazz_swing_weckl.mid\")\n\nprint(\"🎵 Generated: death_metal_track.mid \u0026 jazz_swing_weckl.mid\")\n```\n\n### Command Line Usage\n\n**If installed with `uv tool install`:**\n```bash\n# Generate songs across different genres\nmidi-drums generate --genre metal --style heavy --tempo 155 --output metal_song.mid\nmidi-drums generate --genre rock --style classic --tempo 140 --output rock_song.mid\nmidi-drums generate --genre jazz --style swing --tempo 120 --output jazz_song.mid\nmidi-drums generate --genre funk --style classic --tempo 110 --output funk_song.mid\n\n# Generate patterns with drummer styles\nmidi-drums pattern --genre rock --section verse --drummer bonham --output bonham_verse.mid\n\n# Reaper DAW integration\nmidi-drums reaper export --genre metal --style doom --tempo 120 --output doom.rpp --midi\n\n# List available options\nmidi-drums list genres\nmidi-drums list drummers\n```\n\n**Or use the module directly:**\n```bash\npython -m midi_drums.api.cli generate --genre metal --style heavy --output metal.mid\npython -m midi_drums.api.cli reaper export --genre metal --style doom --output doom.rpp\n```\n\n## 🤖 AI-Powered Generation\n\nGenerate drum patterns from natural language using AI! The system supports multiple AI providers with environment-driven configuration.\n\n### Setup\n\n```bash\n# Install AI dependencies\npip install -r ai_requirements.txt\n\n# Configure your preferred AI provider\nexport AI_PROVIDER=\"anthropic\"  # or openai, groq, cohere\nexport ANTHROPIC_API_KEY=\"your-api-key\"\nexport AI_MODEL=\"claude-sonnet-4-20250514\"  # optional, has smart defaults\n```\n\n### Natural Language Pattern Generation\n\n```python\nfrom midi_drums.ai import DrumGeneratorAI\n\n# Initialize AI generator (uses environment variables)\nai = DrumGeneratorAI()\n\n# Generate from natural language descriptions\npattern, response = await ai.generate_pattern_from_text(\n    \"aggressive metal breakdown with double bass and blast beats\",\n    section=\"breakdown\",\n    tempo=180,\n    bars=4\n)\n\n# AI analyzes and infers characteristics\nprint(f\"Genre: {response.characteristics.genre}\")\nprint(f\"Style: {response.characteristics.style}\")\nprint(f\"Intensity: {response.characteristics.intensity}\")\nprint(f\"Double bass: {response.characteristics.use_double_bass}\")\n\n# Export to MIDI\nai.export_pattern(pattern, \"ai_breakdown.mid\", tempo=180)\n```\n\n### Agent-Based Composition\n\n```python\n# Use Langchain agent for multi-step reasoning\nresult = ai.compose_with_agent(\n    \"Create a progressive metal song with verse and chorus patterns, \"\n    \"then apply the Bonham drummer style to make it more dynamic\"\n)\n\nprint(result['output'])  # Agent's creative response\n```\n\n### Multi-Provider Support\n\n```python\nfrom midi_drums.ai import AIBackendConfig, AIProvider\n\n# Switch providers programmatically\nopenai_config = AIBackendConfig(\n    provider=AIProvider.OPENAI,\n    model=\"gpt-4o\",\n    api_key=\"sk-...\",\n    temperature=0.7\n)\n\nai_openai = DrumGeneratorAI(backend_config=openai_config)\n\n# Or use Groq for fast, cost-effective generation\ngroq_config = AIBackendConfig(\n    provider=AIProvider.GROQ,\n    model=\"llama-3.3-70b-versatile\",\n    api_key=\"gsk-...\"\n)\n\nai_groq = DrumGeneratorAI(backend_config=groq_config)\n```\n\n### Supported AI Providers\n\n| Provider | Models | Best For |\n|----------|--------|----------|\n| **Anthropic** | Claude Sonnet 4 | High-quality, nuanced generation |\n| **OpenAI** | GPT-4o, GPT-4 Turbo | Versatile, well-tested |\n| **Groq** | Llama 3.3 70B | Fast inference, cost-effective |\n| **Cohere** | Command R+ | Enterprise use cases |\n\n**Environment Variables:**\n- `AI_PROVIDER` - Provider selection (default: anthropic)\n- `AI_MODEL` - Model identifier (provider-specific defaults)\n- `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GROQ_API_KEY`, `COHERE_API_KEY`\n- `AI_TEMPERATURE` - Generation temperature (0.0-2.0, default: 0.7)\n- `AI_MAX_TOKENS` - Maximum output tokens (default: 4096)\n\nSee [claudedocs/AI_BACKEND_MIGRATION.md](claudedocs/AI_BACKEND_MIGRATION.md) for complete documentation.\n\n## 🎛️ Reaper DAW Integration\n\nExport drum tracks directly to Reaper projects with automatic section markers!\n\n### Python API\n\n```python\nfrom midi_drums.api.python_api import DrumGeneratorAPI\nfrom midi_drums.exporters import ReaperExporter\n\n# Generate drums\napi = DrumGeneratorAPI()\nsong = api.create_song(\"metal\", \"doom\", tempo=120)\n\n# Export to Reaper with markers\nexporter = ReaperExporter()\nexporter.export_with_markers(\n    song=song,\n    output_rpp=\"doom_metal.rpp\",\n    marker_color=\"#FF5733\"\n)\n\n# Also export MIDI separately\nexporter.export_with_midi(\n    song=song,\n    output_rpp=\"doom_metal.rpp\",\n    output_midi=\"doom_metal.mid\"\n)\n```\n\n### CLI Usage\n\n```bash\n# Generate drums and create Reaper project with markers\nmidi-drums reaper export \\\n    --genre metal \\\n    --style doom \\\n    --tempo 120 \\\n    --output doom_metal.rpp \\\n    --midi\n\n# With all options\nmidi-drums reaper export \\\n    --genre metal \\\n    --style death \\\n    --tempo 180 \\\n    --output death.rpp \\\n    --midi death_drums.mid \\\n    --complexity 0.8 \\\n    --humanization 0.4 \\\n    --drummer hoglan \\\n    --marker-color \"#FF0000\" \\\n    --template my_template.rpp\n\n# Add markers from existing metadata (recommended)\nmidi-drums reaper add-markers \\\n    --metadata output/my_song/metadata.json \\\n    --output project.rpp\n\n# Auto-detect metadata from MIDI directory\nmidi-drums reaper add-markers \\\n    --song output/my_song/complete.mid \\\n    --output project.rpp \\\n    --marker-color \"#00FF00\"\n\n# Manual structure specification\nmidi-drums reaper add-markers \\\n    --structure \"intro:4,verse:8,chorus:8,outro:4\" \\\n    --tempo 120 \\\n    --output project.rpp\n```\n\n### Features\n\n- ✅ **Automatic section markers** - Intro, verse, chorus, bridge, etc.\n- ✅ **Time-accurate positioning** - Markers at exact bar positions\n- ✅ **Metadata-based workflow** - Use existing metadata.json files or auto-detect\n- ✅ **Template support** - Use existing Reaper projects as base\n- ✅ **Custom marker colors** - Hex color codes supported\n- ✅ **Immutable operations** - Original files never modified\n- ✅ **MIDI export** - Optionally export MIDI alongside Reaper project\n- ✅ **Flexible workflows** - Metadata file, auto-detection, or manual specification\n\nSee [docs/REAPER_INTEGRATION.md](docs/REAPER_INTEGRATION.md) for complete documentation.\n\n## 📖 Documentation\n\n### Architecture\n\nThe system follows a layered, plugin-based architecture:\n\n```\n┌─────────────────────────────────────────┐\n│           API Layer                     │\n│  CLI │ Python API │ Direct Usage       │\n├─────────────────────────────────────────┤\n│        Application Layer                │\n│  DrumGenerator │ Pattern Manager        │\n├─────────────────────────────────────────┤\n│         Plugin System                   │\n│  Genre Plugins │ Drummer Plugins        │\n├─────────────────────────────────────────┤\n│         Core Models                     │\n│  Pattern │ Song │ Beat │ Kit            │\n├─────────────────────────────────────────┤\n│         Processing Engines              │\n│  MIDI Engine │ Humanization             │\n└─────────────────────────────────────────┘\n```\n\n### Available Genres \u0026 Styles\n\n#### 🤘 Metal Genre\n- **Heavy**: Classic heavy metal (Sabbath, Iron Maiden style)\n- **Death**: Blast beats, double bass, intense patterns\n- **Power**: Anthemic, driving patterns with melodic elements\n- **Progressive**: Complex time signatures and syncopation\n- **Thrash**: Fast, aggressive patterns with precision\n- **Doom**: Slow, heavy, powerful patterns\n- **Breakdown**: Syncopated patterns for breakdown sections\n\n#### 🎸 Rock Genre\n- **Classic**: 70s classic rock (Led Zeppelin, Deep Purple)\n- **Blues**: Blues rock with shuffles and triplets\n- **Alternative**: 90s alternative rock syncopation\n- **Progressive**: Complex progressive rock patterns\n- **Punk**: Fast, aggressive punk rock\n- **Hard**: Hard rock with heavy emphasis\n- **Pop**: Pop rock with clean patterns\n\n#### 🎷 Jazz Genre\n- **Swing**: Traditional swing with ride patterns\n- **Bebop**: Fast, complex bebop rhythms\n- **Fusion**: Jazz fusion with electric energy\n- **Latin**: Latin jazz with clave patterns\n- **Ballad**: Soft, brushed ballad patterns\n- **Hard Bop**: Aggressive hard bop rhythms\n- **Contemporary**: Modern contemporary jazz\n\n#### 🕺 Funk Genre\n- **Classic**: James Brown \"the one\" emphasis\n- **P-Funk**: Parliament-Funkadelic grooves\n- **Shuffle**: Bernard Purdie shuffle patterns\n- **New Orleans**: Second line funk patterns\n- **Fusion**: Jazz-funk fusion styles\n- **Minimal**: Stripped-down pocket grooves\n- **Heavy**: Heavy funk with rock influence\n\n#### 🥁 Available Drummers\n- **John Bonham**: Triplet vocabulary, behind-the-beat timing\n- **Jeff Porcaro**: Half-time shuffle, studio precision\n- **Dave Weckl**: Linear playing, fusion mastery\n- **Dennis Chambers**: Funk mastery, incredible chops\n- **Jason Roeder**: Atmospheric sludge, minimal creativity\n- **Mikkey Dee**: Speed/precision, versatile power\n- **Gene Hoglan**: Mechanical precision, blast beats\n\n#### 🔮 Future Expansions\n- **Electronic**: House, Techno, Drum'n'Bass, Dubstep\n- **World**: Latin, Reggae, Afrobeat\n- **More Drummers**: Neil Peart, Buddy Rich, Stewart Copeland\n\n## 🎵 Examples\n\n### Python API Examples\n\n```python\nfrom midi_drums.api.python_api import DrumGeneratorAPI\n\napi = DrumGeneratorAPI()\n\n# Multi-genre songs with custom parameters\nmetal_song = api.create_song(\"metal\", \"progressive\", tempo=140, complexity=0.9)\nrock_song = api.create_song(\"rock\", \"classic\", tempo=130, drummer=\"bonham\")\njazz_song = api.create_song(\"jazz\", \"swing\", tempo=120, drummer=\"weckl\")\nfunk_song = api.create_song(\"funk\", \"classic\", tempo=110, drummer=\"chambers\")\n\n# Batch generation across genres\nspecs = [\n    {'genre': 'metal', 'style': 'death', 'tempo': 180},\n    {'genre': 'rock', 'style': 'blues', 'tempo': 95, 'drummer': 'porcaro'},\n    {'genre': 'jazz', 'style': 'fusion', 'tempo': 135, 'drummer': 'weckl'},\n    {'genre': 'funk', 'style': 'pfunk', 'tempo': 105, 'drummer': 'chambers'}\n]\nfiles = api.batch_generate(specs, \"output/\")\n\n# Individual patterns with drummer styles\nverse = api.generate_pattern(\"rock\", \"verse\", \"classic\")\nbonham_verse = api.apply_drummer_style(verse, \"bonham\")\njazz_swing = api.generate_pattern(\"jazz\", \"verse\", \"swing\")\nfunk_breakdown = api.generate_pattern(\"funk\", \"breakdown\", \"heavy\")\n```\n\n### Direct Module Usage\n\n```python\nfrom midi_drums import DrumGenerator\n\ngenerator = DrumGenerator()\n\n# Custom song structure\nsong = generator.create_song(\n    genre=\"metal\",\n    style=\"heavy\",\n    tempo=155,\n    structure=[\n        (\"intro\", 4), (\"verse\", 8), (\"chorus\", 8),\n        (\"verse\", 8), (\"chorus\", 8), (\"bridge\", 4),\n        (\"chorus\", 8), (\"outro\", 4)\n    ],\n    complexity=0.7,\n    humanization=0.3\n)\n\ngenerator.export_midi(song, \"custom_song.mid\")\n```\n\n### CLI Examples\n\n**Using `midi-drums` command (after `uv tool install`):**\n\n```bash\n# Generate songs across all genres\nmidi-drums generate --genre metal --style death --tempo 180 --complexity 0.8 --output death.mid\nmidi-drums generate --genre rock --style classic --tempo 140 --drummer bonham --output rock_bonham.mid\nmidi-drums generate --genre jazz --style swing --tempo 120 --drummer weckl --output jazz_weckl.mid\nmidi-drums generate --genre funk --style classic --tempo 110 --drummer chambers --output funk_chambers.mid\n\n# Generate patterns with drummer styles\nmidi-drums pattern --genre rock --section verse --style blues --drummer porcaro --output porcaro_verse.mid\nmidi-drums pattern --genre jazz --section bridge --style fusion --drummer weckl --output weckl_bridge.mid\n\n# Reaper integration\nmidi-drums reaper export --genre metal --style doom --tempo 120 --output doom.rpp --midi\nmidi-drums reaper export --genre jazz --style swing --tempo 110 --output jazz.rpp --template my_template.rpp\n\n# System information\nmidi-drums info\nmidi-drums list genres\nmidi-drums list styles --genre jazz\nmidi-drums list drummers\n```\n\n**Or use module directly:**\n```bash\npython -m midi_drums.api.cli generate --genre metal --style death --output death.mid\npython -m midi_drums.api.cli reaper export --genre metal --output metal.rpp\n```\n\n## 🔌 Plugin System\n\nThe plugin architecture makes it easy to extend the system with new genres and drummer styles. The refactored architecture provides reusable templates and modifications for rapid development.\n\n### Creating a Genre Plugin (Refactored Approach)\n\n**Modern approach** using pattern templates for declarative composition:\n\n```python\nfrom midi_drums.plugins.base import GenrePlugin\nfrom midi_drums.patterns import TemplateComposer, BasicGroove, DoubleBassPedal\nfrom midi_drums.config import VELOCITY, TIMING\n\nclass MetalGenrePluginRefactored(GenrePlugin):\n    @property\n    def genre_name(self) -\u003e str:\n        return \"metal\"\n\n    @property\n    def supported_styles(self) -\u003e List[str]:\n        return [\"heavy\", \"death\", \"power\", \"progressive\", \"thrash\", \"doom\"]\n\n    def generate_pattern(self, section: str, parameters: GenerationParameters) -\u003e Pattern:\n        if parameters.style == \"death\":\n            # Declarative composition - just 5 lines!\n            return (\n                TemplateComposer(f\"death_metal_{section}\")\n                .add(DoubleBassPedal(pattern=\"continuous\", speed=16))\n                .add(BlastBeat(style=\"traditional\", intensity=0.9))\n                .build(bars=2, complexity=parameters.complexity)\n            )\n        # ... other styles using templates\n```\n\n**Traditional approach** still available for custom patterns:\n\n```python\nfrom midi_drums.plugins.base import GenrePlugin\nfrom midi_drums.models.pattern import PatternBuilder\n\nclass RockGenrePlugin(GenrePlugin):\n    def generate_pattern(self, section: str, parameters: GenerationParameters) -\u003e Pattern:\n        builder = PatternBuilder(f\"rock_{parameters.style}_{section}\")\n\n        if parameters.style == \"classic\":\n            builder.kick(0.0, 105).kick(2.0, 105)\n            builder.snare(1.0, 110).snare(3.0, 110)\n            for i in range(8):\n                builder.hihat(i * 0.5, 80)\n\n        return builder.build()\n```\n\n### Creating a Drummer Plugin (Refactored Approach)\n\n**Modern approach** using composable modifications (reduced from ~380 to ~66 lines!):\n\n```python\nfrom midi_drums.plugins.base import DrummerPlugin\nfrom midi_drums.modifications import BehindBeatTiming, TripletVocabulary, HeavyAccents\n\nclass BonhamPluginRefactored(DrummerPlugin):\n    def __init__(self):\n        self.behind_beat = BehindBeatTiming(max_delay_ms=25.0)\n        self.triplets = TripletVocabulary(triplet_probability=0.4)\n        self.accents = HeavyAccents(accent_boost=15)\n\n    @property\n    def drummer_name(self) -\u003e str:\n        return \"bonham\"\n\n    def apply_style(self, pattern: Pattern) -\u003e Pattern:\n        # Composable modifications - authentic Bonham techniques!\n        styled_pattern = pattern.copy()\n        styled_pattern = self.behind_beat.apply(styled_pattern, intensity=0.7)\n        styled_pattern = self.triplets.apply(styled_pattern, intensity=0.8)\n        styled_pattern = self.accents.apply(styled_pattern, intensity=0.9)\n        return styled_pattern\n```\n\n**Available Modifications**: BehindBeatTiming, TripletVocabulary, GhostNoteLayer, LinearCoordination, HeavyAccents, ShuffleFeelApplication, FastChopsTriplets, PocketStretching, MinimalCreativity, SpeedPrecision, TwistedAccents, MechanicalPrecision\n\n**Available Templates**: BasicGroove, DoubleBassPedal, BlastBeat, JazzRidePattern, FunkGhostNotes, CrashAccents, TomFill, TemplateComposer\n\n## 🛠️ Development\n\n### Setup Development Environment\n\n```bash\n# Install development dependencies\nbin/py_update.sh  # Linux/macOS\nbin/py_update.bat # Windows\n\n# Or using uv (recommended)\nuv sync --all-groups  # Syncs dev, ai, and core dependencies\n\n# Run linting\nbin/linting.sh  # Linux/macOS\nbin/linting.bat # Windows\n```\n\n### Continuous Integration\n\nThe project uses **GitHub Actions** for automated testing:\n\n- ✅ Automated linting (ruff, black, isort)\n- ✅ Multi-version testing (Python 3.12, 3.13)\n- ✅ Coverage reporting\n- 🚧 Currently debugging dependency installation issues\n\nSee [docs/CI_CD.md](docs/CI_CD.md) for CI/CD documentation.\n\n### Testing\n\nThe project uses **pytest** with comprehensive test coverage:\n\n```bash\n# Run all tests\npytest\n\n# Run specific test categories\npytest -m unit          # Unit tests (no API key needed)\npytest -m integration   # Integration tests\npytest -m ai           # AI tests (requires API key)\n\n# Run tests in parallel\npytest -n auto\n\n# Run with coverage\npytest --cov=midi_drums --cov-report=html\n\n# Skip AI tests if no API key\npytest -m \"not requires_api\"\n```\n\n**Test Organization:**\n- `tests/unit/` - Unit tests for individual components (8 files)\n- `tests/integration/` - End-to-end integration tests (6 files)\n- `tests/ai/` - AI-powered generation tests (4 files)\n- `tests/conftest.py` - Shared fixtures and configuration\n\n**Test Markers:**\n- `@pytest.mark.unit` - Fast unit tests, no external dependencies\n- `@pytest.mark.integration` - Integration tests\n- `@pytest.mark.ai` - AI functionality tests\n- `@pytest.mark.requires_api` - Tests requiring API keys (auto-skipped if unavailable)\n- `@pytest.mark.slow` - Long-running tests\n\n```python\n# Example test run output\n============================= test session starts =============================\n8 passed in 10.69s ==============================\n✅ Backend abstraction tests\n✅ Configuration validation\n✅ Environment variable loading\n✅ Provider fallback handling\n```\n\n### Project Structure\n\n```\nmidi_drums/\n├── __init__.py              # Main exports\n├── config/\n│   └── constants.py        # VELOCITY, TIMING, DEFAULTS (283 lines)\n├── patterns/\n│   └── templates.py        # 8 reusable pattern templates (585 lines)\n├── modifications/\n│   └── drummer_mods.py     # 12 drummer modifications (732 lines)\n├── core/\n│   └── engine.py           # DrumGenerator - main engine\n├── models/\n│   ├── pattern.py          # Pattern, Beat, PatternBuilder\n│   ├── song.py             # Song, Section, GenerationParameters\n│   └── kit.py              # DrumKit configurations\n├── plugins/\n│   ├── base.py             # Plugin system foundation\n│   ├── genres/\n│   │   ├── metal_refactored.py    # 290 lines (was 373)\n│   │   ├── rock_refactored.py     # 332 lines (was 513)\n│   │   ├── jazz_refactored.py     # 337 lines (was 599)\n│   │   └── funk_refactored.py     # 330 lines (was 561)\n│   └── drummers/\n│       ├── bonham_refactored.py   # 66 lines (was 339)\n│       ├── porcaro_refactored.py  # 63 lines (was 369)\n│       ├── weckl_refactored.py    # 63 lines (was 383)\n│       ├── chambers_refactored.py # 70 lines (was 381)\n│       ├── roeder_refactored.py   # 63 lines (was 371)\n│       ├── dee_refactored.py      # 63 lines (was 360)\n│       └── hoglan_refactored.py   # 63 lines (was 389)\n├── engines/\n│   └── midi_engine.py      # MIDI file generation\n├── api/\n│   ├── python_api.py       # High-level Python API\n│   └── cli.py              # Command-line interface\n└── claudedocs/\n    └── REFACTORING_PROGRESS.md  # Complete refactoring docs\n```\n\n### Running Examples\n\n```bash\n# Test the system\npython test_new_architecture.py\n\n# Try the examples\npython examples/basic_usage.py\n\n# Compare with original implementation\npython migrate_from_original.py\n```\n\n## 🎼 MIDI Output\n\nThe system generates professional MIDI files compatible with:\n\n- **EZDrummer 3** (primary target)\n- **Superior Drummer 3**\n- **BFD3**\n- **Any GM-compatible drum sampler**\n- **DAWs** (Logic Pro, Pro Tools, Cubase, Reaper, etc.)\n\n### MIDI Features\n\n- ✅ Standard GM drum mapping\n- ✅ Realistic velocity variations (60-127)\n- ✅ Humanized timing (configurable)\n- ✅ Ghost notes and accents\n- ✅ Dynamic fills and variations\n- ✅ Multi-bar pattern support\n\n## 📊 Migration from Original\n\nThis system evolved from a simple single-file generator (`generate_metal_drum_track.py`) into a comprehensive platform:\n\n### Before → After\n\n| Original | New Architecture |\n|----------|------------------|\n| Single file | Modular plugin system |\n| One metal style | 7+ metal styles, expandable |\n| Fixed song structure | Configurable structures |\n| Hardcoded patterns | Dynamic pattern generation |\n| No API | Multiple interfaces |\n| No variations | Humanization \u0026 variations |\n\nThe original script is preserved for compatibility, and `migrate_from_original.py` demonstrates equivalent functionality.\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how you can help:\n\n### 🎵 Add New Genres\n1. Create a new plugin in `midi_drums/plugins/genres/`\n2. Implement the `GenrePlugin` interface\n3. Add comprehensive patterns for different sections and styles\n4. Include characteristic fills and variations\n5. Examples: Rock, Jazz, and Funk genres with 7 styles each\n\n### 🥁 Add Drummer Styles\n1. Create a drummer plugin in `midi_drums/plugins/drummers/`\n2. Implement the `DrummerPlugin` interface\n3. Add signature playing techniques and fills based on research\n4. Make it compatible with multiple genres\n5. Examples: 7 drummers already implemented with authentic styles\n\n### 🐛 Report Issues\n- Found a bug? Open an issue on GitHub\n- Include MIDI output samples if possible\n- Provide steps to reproduce\n\n### 💡 Suggest Features\n- New musical genres or styles\n- Advanced humanization techniques\n- Integration with specific DAWs or samplers\n\n## 📜 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **Original Inspiration**: Single-file metal drum generator\n- **MIDI Generation**: [midiutil](https://github.com/MarkCWirt/MIDIUtil) library\n- **Target Platform**: [EZDrummer 3](https://www.toontrack.com/product/ezdrummer-3/) compatibility\n- **Architecture**: Plugin-based design inspired by modern audio software\n\n## 📈 Roadmap\n\n### Phase 1: Core Expansion ✅\n- [x] Rock genre plugin with 7 styles\n- [x] Jazz genre plugin with 7 styles (swing, bebop, fusion, latin, etc.)\n- [x] Funk genre plugin with 7 styles\n- [x] 7 drummer plugins (Bonham, Porcaro, Weckl, Chambers, Roeder, Dee, Hoglan)\n- [x] Comprehensive testing and validation system\n- [x] Reaper DAW integration with automatic markers\n- [x] CLI tool installation (`uv tool install`)\n- [x] GitHub Actions CI/CD pipeline\n\n### Phase 2: Advanced Features 🚧\n- [ ] Electronic genre plugin (House, Techno, Drum'n'Bass)\n- [ ] More drummer plugins (Neil Peart, Buddy Rich, Stewart Copeland)\n- [ ] Reaper marker import (generate drums from existing markers)\n- [ ] Real-time audio synthesis\n- [ ] AI-driven pattern variations\n- [ ] Advanced humanization algorithms\n- [ ] Groove template system\n\n### Phase 3: Integration 🔮\n- [ ] REST API for web services\n- [ ] DAW integration (VST/AU plugins)\n- [ ] Pattern marketplace\n- [ ] Visual pattern editor\n- [ ] World music genres (Latin, Reggae, Afrobeat)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ for drummers, producers, and music creators**\n\n[⭐ Star this project](https://github.com/yourusername/midi-drums) • [🐛 Report Bug](https://github.com/yourusername/midi-drums/issues) • [💡 Request Feature](https://github.com/yourusername/midi-drums/issues)\n\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffsecada01%2Fmidi-drums","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffsecada01%2Fmidi-drums","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffsecada01%2Fmidi-drums/lists"}