{"id":29829241,"url":"https://github.com/scribbletune/pydrums","last_synced_at":"2025-07-29T08:33:35.854Z","repository":{"id":305973365,"uuid":"1021740374","full_name":"scribbletune/pydrums","owner":"scribbletune","description":"AI-powered drum pattern generation and MIDI conversion","archived":false,"fork":false,"pushed_at":"2025-07-22T23:10:19.000Z","size":85,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-23T01:09:49.390Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scribbletune.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-07-17T21:52:44.000Z","updated_at":"2025-07-22T23:10:23.000Z","dependencies_parsed_at":"2025-07-23T01:09:55.960Z","dependency_job_id":"56a2a931-3df9-404c-8c1b-e8838a6c6b32","html_url":"https://github.com/scribbletune/pydrums","commit_stats":null,"previous_names":["scribbletune/pydrums"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/scribbletune/pydrums","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scribbletune%2Fpydrums","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scribbletune%2Fpydrums/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scribbletune%2Fpydrums/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scribbletune%2Fpydrums/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scribbletune","download_url":"https://codeload.github.com/scribbletune/pydrums/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scribbletune%2Fpydrums/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267653353,"owners_count":24122188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-07-29T08:33:33.187Z","updated_at":"2025-07-29T08:33:35.844Z","avatar_url":"https://github.com/scribbletune.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PyDrums 🥁\n\n**AI-powered drum pattern generation and MIDI conversion**\n\nPyDrums is a comprehensive Python toolkit that uses AI (via Ollama) to generate professional drum patterns from text descriptions and convert them to MIDI files. Perfect for musicians, producers, and developers working with rhythm and percussion.\n\n## ✨ Features\n\n- 🤖 **AI Pattern Generation**: Uses few-shot learning with Ollama to generate drum patterns from natural language\n- 🎼 **MIDI Conversion**: Convert patterns to standard MIDI files compatible with any DAW\n- 📚 **Professional Training Data**: Built on 200+ professional drum patterns across 15+ musical styles\n- 🔄 **Multiple Data Sources**: Load patterns from GitHub repositories and custom JSON sources\n- 🎮 **Interactive Mode**: Real-time pattern generation with immediate feedback\n- 🛠️ **CLI Tool**: Command-line interface for batch processing and automation\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/pydrums.git\ncd pydrums\n\n# Create virtual environment\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\\\Scripts\\\\activate\n\n# Install dependencies\npip install -e .\n```\n\n### Prerequisites\n\n1. **Install Ollama**: Download from [ollama.ai](https://ollama.ai)\n2. **Pull a model**: `ollama pull llama3.1:latest`\n\n### Basic Usage\n\n```bash\n# 1. Setup training data (downloads 268 professional patterns with speed variations)\npydrums setup-data --skip-primary\n\n# 2. Generate a pattern from 17 available styles with speed control\npydrums generate -d \"Create a funky afro-cuban beat\" --to-midi\n\n# 3. Interactive mode - try any of the 17 styles with speed variations!\npydrums generate --interactive\n\n# 4. Convert pattern string to MIDI\npydrums convert -p \"ch: x-x-x-x-; sd: ----x---; bd: x-----x-\"\n\n# 5. Regenerate training data with enhanced speed variations\npydrums regenerate-training\n\n# 6. Check your expanded dataset\npydrums info\n```\n\n## 📖 Documentation\n\n### Pattern Notation\n\nPyDrums uses a 6-token notation system:\n\n- `x` = Hit/strike the drum\n- `-` = Rest/silence\n- `R` = Roll (extended sound)\n- `_` = Ghost note (quiet hit)\n- `[` = Flam start (grace note)\n- `]` = Flam end\n\n### Drum Abbreviations\n\n- `ch` = Closed Hi-Hat\n- `oh` = Open Hi-Hat\n- `sd` = Snare Drum\n- `bd` = Bass Drum\n- `hh` = Hi-Hat Pedal\n- `cc` = Crash Cymbal\n- `rc` = Ride Cymbal\n- `ht` = High Tom\n- `mt` = Mid Tom\n- `lt` = Low Tom\n\n### Additional Documentation\n\n- 📊 **[DATASET.md](DATASET.md)**: Comprehensive dataset documentation with detailed style breakdowns and statistics\n- 🎵 **[examples/](examples/)**: Usage examples and tutorials\n- 🛠️ **[.github/copilot-instructions.md](.github/copilot-instructions.md)**: Development guidelines\n\n### Python API\n\n```python\nfrom pydrums import PatternGenerator, MidiConverter, DataLoader\n\n# Generate patterns\ngenerator = PatternGenerator()\npattern = generator.generate_pattern(\"Create a jazz shuffle\")\n\n# Convert to MIDI\nconverter = MidiConverter()\nmidi_file = converter.pattern_to_midi(pattern, tempo_bpm=140)\n\n# Load additional data\nloader = DataLoader()\npatterns = loader.load_github_json_patterns()\n```\n\n## 🎯 Use Cases\n\n- **Music Production**: Generate drum patterns for songs and beats\n- **Practice**: Create backing tracks for musicians\n- **Game Development**: Generate dynamic music for games\n- **Music Education**: Learn about rhythm and pattern construction\n- **AI Research**: Experiment with music generation and few-shot learning\n\n## 🔧 Configuration\n\n### Data Source Management\n\n```bash\n# Setup with all available sources\npydrums setup-data\n\n# Use only DrumMachinePatterns260 (recommended)\npydrums setup-data --skip-primary\n\n# Force re-download of all data\npydrums setup-data --force-reload\n\n# Add your own JSON pattern source\npydrums setup-data --additional-url \"https://raw.githubusercontent.com/user/repo/patterns.json\" --additional-name \"my_patterns\"\n```\n\n### Available Style Examples\n\n```bash\n# Generate patterns from different styles in your dataset\npydrums generate -d \"Create a funk groove with ghost notes\" --to-midi\npydrums generate -d \"Make an afro-cuban pattern\" --to-midi\npydrums generate -d \"Generate a reggae one drop beat\" --to-midi\npydrums generate -d \"Create a jazz shuffle pattern\" --to-midi\npydrums generate -d \"Make a disco four-on-the-floor beat\" --to-midi\npydrums generate -d \"Generate a bossa nova rhythm\" --to-midi\npydrums generate -d \"Create a rock ballad pattern\" --to-midi\n\n# NEW: Speed variation examples\npydrums generate -d \"Create a half-time funk groove\" --to-midi\npydrums generate -d \"Generate a double-time rock beat\" --to-midi\npydrums generate -d \"Make a simple quarter note disco pattern\" --to-midi\npydrums generate -d \"Create a laid-back jazz groove\" --to-midi\n```\n\n### Model Selection\n\n```bash\n# Use different Ollama model\npydrums generate -d \"rock beat\" -m \"mistral:latest\"\n```\n\n### Advanced Options\n\n```python\n# Custom generation parameters\npattern = generator.generate_pattern(\n    \"Create a complex progressive pattern\",\n    num_examples=5,        # More examples for better context\n    temperature=0.8,       # Higher creativity\n    style_hint=\"funk\"      # Guide style selection from 17 available styles\n)\n\n# MIDI with custom settings\nmidi_file = converter.pattern_to_midi(\n    pattern,\n    tempo_bpm=140,\n    loop_count=8,          # 8 repetitions\n    ticks_per_beat=960     # Higher resolution\n)\n```\n\n## 📊 Training Data\n\nPyDrums includes professionally curated drum patterns from multiple sources:\n\n### Current Dataset Statistics\n\n- **268 Professional Patterns**: High-quality drum machine patterns\n- **1,331+ AI Training Examples**: Generated from professional patterns with speed variations\n- **17 Musical Styles**: Comprehensive coverage of musical genres\n- **4 Speed Variations**: Normal, half-time, double-time, and quarter-note patterns\n- **Multiple Time Signatures**: 4/4, 12/8, 3/4, and more\n- **JSON Format**: Structured data for reliable AI training\n\n### Speed Variations Available\n\n- **Normal Speed** (16th notes): Standard drum patterns with 16-character resolution\n- **Half-Time** (32nd notes): Slower, laid-back grooves with extended spacing\n- **Double-Time** (8th notes): Fast, energetic patterns with rapid hits\n- **Quarter Notes**: Simple, minimal patterns emphasizing strong beats\n\n### Pattern Length Examples\n\n```\nNormal (16 chars):    ch: x-x-x-x-x-x-x-x-; bd: x---x---x---x---\nHalf-time (32 chars): ch: x---x---x---x---x---x---x---x---; bd: x-------x-------x-------x-------\nDouble-time (8 chars): ch: xxxxxxxx; bd: x-x-x-x-\nQuarter notes (4 chars): ch: xxxx; bd: xxxx\n```\n\n### Available Musical Styles\n\n1. **Funk** (150 examples) - Syncopated grooves and ghost notes\n2. **Rock** (135 examples) - Classic and modern rock beats\n3. **General** (122 examples) - Versatile patterns for any genre\n4. **Disco** (110 examples) - Four-on-the-floor dance patterns\n5. **Reggae** (105 examples) - One drop and rockers patterns\n6. **Jazz** (90 examples) - Swing and shuffle patterns\n7. **Ballad** (90 examples) - Slow, emotional patterns\n8. **Pop** (90 examples) - Commercial and radio-friendly beats\n9. **R\u0026B** (90 examples) - Soul and rhythm \u0026 blues grooves\n10. **Latin** (85 examples) - Salsa, mambo, and cha-cha patterns\n11. **Afro-Cuban** (75 examples) - Traditional African-Cuban rhythms\n12. **Shuffle** (45 examples) - Swung eighth note patterns\n13. **Bossa Nova** (45 examples) - Brazilian jazz patterns\n14. **Blues** (45 examples) - Traditional blues rhythms\n15. **Waltz** (24 examples) - 3/4 time signature patterns\n16. **March** (20 examples) - Military and ceremonial beats\n17. **Tango** (10 examples) - Argentinian tango rhythms\n\n### Data Sources\n\n1. **Primary**: [DrumMachinePatterns260](https://github.com/stephenhandley/DrumMachinePatterns/blob/master/Sources/DrumMachinePatterns260/Patterns.json) - 268 patterns in perfect JSON format\n2. **Legacy**: [stephenhandley/DrumMachinePatterns](https://github.com/stephenhandley/DrumMachinePatterns) - Individual pattern files\n3. **Reference**: [montoyamoraga/drum-machine-patterns](https://github.com/montoyamoraga/drum-machine-patterns) - Additional patterns in markdown format\n\n## 🧠 How It Works\n\nPyDrums uses **few-shot learning** rather than traditional model training:\n\n1. **Context Loading**: Selects relevant example patterns based on your description\n2. **Prompt Engineering**: Creates structured prompts with notation guides and examples\n3. **AI Generation**: Uses Ollama to generate new patterns following the established format\n4. **Validation**: Checks output format and provides fallbacks if needed\n5. **MIDI Conversion**: Converts text patterns to standard MIDI using General MIDI mapping\n\nThis approach is:\n\n- ⚡ **Fast**: No training time required\n- 🎯 **Accurate**: Uses proven professional patterns as examples\n- 🔄 **Adaptable**: Easy to add new styles and patterns\n- 💻 **Local**: Runs entirely on your machine with Ollama\n\n## 🛠️ Development\n\n### Project Structure\n\n```\npydrums/\n├── src/pydrums/           # Main package\n│   ├── __init__.py\n│   ├── pattern_generator.py    # AI pattern generation\n│   ├── midi_converter.py       # MIDI file creation\n│   ├── data_loader.py          # Data loading and processing\n│   └── cli.py                  # Command-line interface\n├── data/                       # Training data\n├── midi_output/               # Generated MIDI files\n├── examples/                  # Usage examples\n├── tests/                     # Unit tests\n└── requirements.txt           # Dependencies\n```\n\n### Running Tests\n\n```bash\npip install -e \".[dev]\"\npytest tests/\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack src/ tests/\n\n# Lint code\nflake8 src/ tests/\n\n# Type checking\nmypy src/\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\n### Adding New Pattern Sources\n\nTo add a new pattern data source:\n\n1. Implement loading logic in `DataLoader.load_additional_json_source()`\n2. Add conversion logic for the specific format\n3. Update the CLI to accept the new source\n4. Add tests for the new functionality\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Ollama](https://ollama.ai) for local AI capabilities\n- [stephenhandley/DrumMachinePatterns](https://github.com/stephenhandley/DrumMachinePatterns) for excellent training data\n- [montoyamoraga/drum-machine-patterns](https://github.com/montoyamoraga/drum-machine-patterns) for additional pattern resources\n- The music production community for feedback and inspiration\n\n## 📞 Support\n\n- 🐛 [Report bugs](https://github.com/yourusername/pydrums/issues)\n- 💡 [Request features](https://github.com/yourusername/pydrums/issues)\n- 📧 [Email support](mailto:your.email@example.com)\n- 💬 [Community discussions](https://github.com/yourusername/pydrums/discussions)\n\n---\n\n**Happy drumming! 🥁🎵**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscribbletune%2Fpydrums","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscribbletune%2Fpydrums","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscribbletune%2Fpydrums/lists"}