# beatstoch
**BPM-aware stochastic drum MIDI generator** - Create dynamic, probabilistic drum patterns that adapt to any song's BPM.
[](https://www.python.org/downloads/)
[](https://github.com/james-see/beatstoch/actions)
[](https://github.com/astral-sh/uv)
[](https://github.com/james-see/beatstoch)
## Features
- **BPM Database Integration**: Automatically looks up song BPM from [BPM Database](https://www.bpmdatabase.com/)
- **Psychoacoustic Algorithm**: Research-based rhythms using golden ratio, Fibonacci sequences, and fractal complexity
- **Multiple Styles**: House, breaks, and generic drum patterns with natural human feel
- **Stochastic Generation**: Creates varied, probabilistic drum patterns with optimal predictability vs surprise balance
- **Golden Ratio Microtiming**: Microtiming variations (20-30ms) for authentic groove perception
- **Natural Velocity Curves**: Sine wave-based dynamics for expressive, human-like drum hits
- **Fractal Pattern Complexity**: Multi-level fractal generation for organic rhythmic complexity
- **MIDI Export**: Generates standard MIDI files compatible with any DAW
- **CLI & Library**: Use as a command-line tool or Python library
## Installation
### Using uv (recommended)
```bash
git clone https://github.com/james-see/beatstoch.git
cd beatstoch
uv sync
```
### Using pip
```bash
pip install mido numpy requests beautifulsoup4
```
## Quick Start
### Command Line Interface
Generate drum patterns from song titles:
```bash
# Generate 8 bars of house-style drums for "1979" by Smashing Pumpkins
uv run beatstoch generate "1979" --artist "Smashing Pumpkins" --bars 8
# Generate breaks-style pattern at 127 BPM
uv run beatstoch generate-bpm 127 --bars 4 --style breaks
# Enable verbose logging to see BPM lookup process
uv run beatstoch generate "Billie Jean" --artist "Michael Jackson" --verbose
```
### Python Library
```python
from beatstoch import generate_from_song, generate_stochastic_pattern
# Generate from song lookup
mid, bpm = generate_from_song(
"1979",
artist="Smashing Pumpkins",
bars=8,
style="house",
swing=0.1,
intensity=0.9,
groove_intensity=0.8
)
mid.save(f"stoch_1979_{int(bpm)}bpm.mid")
print(f"Generated pattern at {bpm} BPM")
# Generate with explicit BPM
mid2 = generate_stochastic_pattern(
bpm=127,
bars=4,
style="breaks",
seed=123,
steps_per_beat=4,
swing=0.12,
groove_intensity=0.7
)
mid2.save("stoch_127_breaks.mid")
```
## Command Line Options
### `generate` command (song lookup)
- `title`: Song title (required)
- `--artist`: Artist name (optional, improves BPM lookup accuracy)
- `--bars`: Number of bars to generate (default: 8)
- `--style`: Drum style - `house`, `breaks`, or `generic` (default: house)
- `--steps-per-beat`: Resolution (default: 4)
- `--swing`: Swing amount 0.0-1.0 (default: 0.10)
- `--intensity`: Pattern density 0.0-1.0 (default: 0.9)
- `--groove-intensity`: Psychoacoustic groove strength 0.0-1.0 (default: 0.7)
- `--seed`: Random seed for reproducible patterns
- `--fallback-bpm`: BPM to use if lookup fails
- `--verbose`: Show BPM lookup details
### `generate-bpm` command (explicit BPM)
- `bpm`: Target BPM (required)
- `--bars`: Number of bars (default: 8)
- `--style`: Drum style - `house`, `breaks`, or `generic` (default: house)
- `--steps-per-beat`: Resolution (default: 4)
- `--swing`: Swing amount (default: 0.10)
- `--intensity`: Pattern density (default: 0.9)
- `--groove-intensity`: Psychoacoustic groove strength 0.0-1.0 (default: 0.7)
- `--seed`: Random seed
## Drum Styles
### House
Classic four-on-the-floor kick pattern enhanced with golden ratio timing and fractal hi-hat complexity. Features natural velocity curves and microtiming groove for authentic dance music feel.
### Breaks
Syncopated breakbeat patterns using fractal complexity and Fibonacci probability distributions. Golden ratio microtiming creates the authentic "human feel" groove prized by breakbeat producers.
### Generic
Balanced backbeat pattern with psychoacoustic optimization. Combines predictable structure (85% predictability) with controlled surprise elements for engaging, natural-sounding rhythms suitable for any genre.
## Output
Generated MIDI files are saved with descriptive names:
- `stoch_[artist]_[title]_[bpm]bpm.mid` (from song lookup)
- `stoch_[bpm]bpm.mid` (from explicit BPM)
Files are compatible with all major DAWs and MIDI software.
## Requirements
- Python 3.9+ (tested on 3.9-3.14)
- Internet connection (for BPM database lookup)
- MIDI-compatible software (for playback/editing)
## Dependencies
- [mido](https://github.com/mido/mido) - MIDI file handling
- [numpy](https://numpy.org/) - Numerical computations
- [requests](https://requests.readthedocs.io/) - HTTP requests
- [beautifulsoup4](https://www.crummy.com/software/BeautifulSoup/) - HTML parsing
## Release Instructions
### Automated Releases (Recommended)
The project includes GitHub Actions that automatically create releases when version tags are pushed.
**To create a new release:**
1. **Update version** in `pyproject.toml` and `src/beatstoch/__init__.py` (if exists)
2. **Update CHANGELOG.md** with new features and fixes
3. **Create and push a version tag:**
```bash
# Ensure you're on main branch and up to date
git checkout main
git pull origin main
# Create annotated tag
VERSION="1.0.0"
git tag -a "v${VERSION}" -m "Release version ${VERSION}"
# Push tag to trigger automated release
git push origin "v${VERSION}"
```
4. **Automated workflow will:**
- Run tests
- Build the package
- Create a GitHub release with distribution files
- Deploy documentation to GitHub Pages
- Publish to PyPI (if PYPI_API_TOKEN is configured)
### Manual PyPI Publishing
If automation isn't set up or fails:
1. **Build distributions:**
```bash
uv build
```
2. **Upload to PyPI:**
```bash
uv publish
```
3. **Verify installation:**
```bash
pip install beatstoch
beatstoch --help
```
### PyPI Setup
1. **Get PyPI API token** from [PyPI Account Settings](https://pypi.org/manage/account/)
2. **Add to GitHub Secrets:** Go to repository Settings > Secrets and variables > Actions
3. **Add `PYPI_API_TOKEN`** with your PyPI API token value
## Documentation
Documentation is automatically built and deployed to GitHub Pages using MkDocs.
- **Live Documentation:** [https://james-see.github.io/beatstoch/](https://james-see.github.io/beatstoch/)
- **Build locally:** `mkdocs serve` (requires MkDocs installation)
## Development
### Setup
```bash
git clone https://github.com/james-see/beatstoch.git
cd beatstoch
uv sync
```
### Testing
```bash
# Run all tests
uv run python -m pytest
# Test with coverage
uv run python -m pytest --cov=src/beatstoch
# Test CLI functionality
uv run beatstoch generate-bpm 120 --bars 2
```
### Building Documentation
```bash
# Install MkDocs
pip install mkdocs mkdocs-material
# Preview locally
mkdocs serve
# Deploy to GitHub Pages
mkdocs gh-deploy
```
## License
This project is released into the public domain under the [Unlicense](https://unlicense.org/).
[](http://unlicense.org/)
## Contributing
1. Fork the repository at [https://github.com/james-see/beatstoch](https://github.com/james-see/beatstoch)
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes and add tests
4. Run the test suite: `uv run python -m pytest`
5. Commit your changes: `git commit -m 'Add amazing feature'`
6. Push to the branch: `git push origin feature/amazing-feature`
7. Open a Pull Request
## Support
- 📖 [Documentation](https://james-see.github.io/beatstoch/)
- 🐛 [Issue Tracker](https://github.com/james-see/beatstoch/issues)
- 💬 [Discussions](https://github.com/james-see/beatstoch/discussions)
- 📧 [GitHub Repository](https://github.com/james-see/beatstoch)
---
*Generated drum patterns are for educational and creative purposes. Always respect music copyrights and licensing.*
Raw data
{
"_id": null,
"home_page": null,
"name": "beatstoch",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "midi, drums, music, bpm, stochastic, algorithmic, composition, audio, cli",
"author": "James Campbell",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/26/52/9ce90afbf6caaf54269813597701eab1aa295f3d5605cfbac0c7ca20fd28/beatstoch-1.2.0.tar.gz",
"platform": null,
"description": "# beatstoch\n\n**BPM-aware stochastic drum MIDI generator** - Create dynamic, probabilistic drum patterns that adapt to any song's BPM.\n\n[](https://www.python.org/downloads/)\n[](https://github.com/james-see/beatstoch/actions)\n[](https://github.com/astral-sh/uv)\n[](https://github.com/james-see/beatstoch)\n\n## Features\n\n- **BPM Database Integration**: Automatically looks up song BPM from [BPM Database](https://www.bpmdatabase.com/)\n- **Psychoacoustic Algorithm**: Research-based rhythms using golden ratio, Fibonacci sequences, and fractal complexity\n- **Multiple Styles**: House, breaks, and generic drum patterns with natural human feel\n- **Stochastic Generation**: Creates varied, probabilistic drum patterns with optimal predictability vs surprise balance\n- **Golden Ratio Microtiming**: Microtiming variations (20-30ms) for authentic groove perception\n- **Natural Velocity Curves**: Sine wave-based dynamics for expressive, human-like drum hits\n- **Fractal Pattern Complexity**: Multi-level fractal generation for organic rhythmic complexity\n- **MIDI Export**: Generates standard MIDI files compatible with any DAW\n- **CLI & Library**: Use as a command-line tool or Python library\n\n## Installation\n\n### Using uv (recommended)\n```bash\ngit clone https://github.com/james-see/beatstoch.git\ncd beatstoch\nuv sync\n```\n\n### Using pip\n```bash\npip install mido numpy requests beautifulsoup4\n```\n\n## Quick Start\n\n### Command Line Interface\n\nGenerate drum patterns from song titles:\n```bash\n# Generate 8 bars of house-style drums for \"1979\" by Smashing Pumpkins\nuv run beatstoch generate \"1979\" --artist \"Smashing Pumpkins\" --bars 8\n\n# Generate breaks-style pattern at 127 BPM\nuv run beatstoch generate-bpm 127 --bars 4 --style breaks\n\n# Enable verbose logging to see BPM lookup process\nuv run beatstoch generate \"Billie Jean\" --artist \"Michael Jackson\" --verbose\n```\n\n### Python Library\n\n```python\nfrom beatstoch import generate_from_song, generate_stochastic_pattern\n\n# Generate from song lookup\nmid, bpm = generate_from_song(\n \"1979\",\n artist=\"Smashing Pumpkins\",\n bars=8,\n style=\"house\",\n swing=0.1,\n intensity=0.9,\n groove_intensity=0.8\n)\nmid.save(f\"stoch_1979_{int(bpm)}bpm.mid\")\nprint(f\"Generated pattern at {bpm} BPM\")\n\n# Generate with explicit BPM\nmid2 = generate_stochastic_pattern(\n bpm=127,\n bars=4,\n style=\"breaks\",\n seed=123,\n steps_per_beat=4,\n swing=0.12,\n groove_intensity=0.7\n)\nmid2.save(\"stoch_127_breaks.mid\")\n```\n\n## Command Line Options\n\n### `generate` command (song lookup)\n- `title`: Song title (required)\n- `--artist`: Artist name (optional, improves BPM lookup accuracy)\n- `--bars`: Number of bars to generate (default: 8)\n- `--style`: Drum style - `house`, `breaks`, or `generic` (default: house)\n- `--steps-per-beat`: Resolution (default: 4)\n- `--swing`: Swing amount 0.0-1.0 (default: 0.10)\n- `--intensity`: Pattern density 0.0-1.0 (default: 0.9)\n- `--groove-intensity`: Psychoacoustic groove strength 0.0-1.0 (default: 0.7)\n- `--seed`: Random seed for reproducible patterns\n- `--fallback-bpm`: BPM to use if lookup fails\n- `--verbose`: Show BPM lookup details\n\n### `generate-bpm` command (explicit BPM)\n- `bpm`: Target BPM (required)\n- `--bars`: Number of bars (default: 8)\n- `--style`: Drum style - `house`, `breaks`, or `generic` (default: house)\n- `--steps-per-beat`: Resolution (default: 4)\n- `--swing`: Swing amount (default: 0.10)\n- `--intensity`: Pattern density (default: 0.9)\n- `--groove-intensity`: Psychoacoustic groove strength 0.0-1.0 (default: 0.7)\n- `--seed`: Random seed\n\n## Drum Styles\n\n### House\nClassic four-on-the-floor kick pattern enhanced with golden ratio timing and fractal hi-hat complexity. Features natural velocity curves and microtiming groove for authentic dance music feel.\n\n### Breaks\nSyncopated breakbeat patterns using fractal complexity and Fibonacci probability distributions. Golden ratio microtiming creates the authentic \"human feel\" groove prized by breakbeat producers.\n\n### Generic\nBalanced backbeat pattern with psychoacoustic optimization. Combines predictable structure (85% predictability) with controlled surprise elements for engaging, natural-sounding rhythms suitable for any genre.\n\n## Output\n\nGenerated MIDI files are saved with descriptive names:\n- `stoch_[artist]_[title]_[bpm]bpm.mid` (from song lookup)\n- `stoch_[bpm]bpm.mid` (from explicit BPM)\n\nFiles are compatible with all major DAWs and MIDI software.\n\n## Requirements\n\n- Python 3.9+ (tested on 3.9-3.14)\n- Internet connection (for BPM database lookup)\n- MIDI-compatible software (for playback/editing)\n\n## Dependencies\n\n- [mido](https://github.com/mido/mido) - MIDI file handling\n- [numpy](https://numpy.org/) - Numerical computations\n- [requests](https://requests.readthedocs.io/) - HTTP requests\n- [beautifulsoup4](https://www.crummy.com/software/BeautifulSoup/) - HTML parsing\n\n## Release Instructions\n\n### Automated Releases (Recommended)\n\nThe project includes GitHub Actions that automatically create releases when version tags are pushed.\n\n**To create a new release:**\n\n1. **Update version** in `pyproject.toml` and `src/beatstoch/__init__.py` (if exists)\n\n2. **Update CHANGELOG.md** with new features and fixes\n\n3. **Create and push a version tag:**\n ```bash\n # Ensure you're on main branch and up to date\n git checkout main\n git pull origin main\n\n # Create annotated tag\n VERSION=\"1.0.0\"\n git tag -a \"v${VERSION}\" -m \"Release version ${VERSION}\"\n\n # Push tag to trigger automated release\n git push origin \"v${VERSION}\"\n ```\n\n4. **Automated workflow will:**\n - Run tests\n - Build the package\n - Create a GitHub release with distribution files\n - Deploy documentation to GitHub Pages\n - Publish to PyPI (if PYPI_API_TOKEN is configured)\n\n### Manual PyPI Publishing\n\nIf automation isn't set up or fails:\n\n1. **Build distributions:**\n ```bash\n uv build\n ```\n\n2. **Upload to PyPI:**\n ```bash\n uv publish\n ```\n\n3. **Verify installation:**\n ```bash\n pip install beatstoch\n beatstoch --help\n ```\n\n### PyPI Setup\n\n1. **Get PyPI API token** from [PyPI Account Settings](https://pypi.org/manage/account/)\n2. **Add to GitHub Secrets:** Go to repository Settings > Secrets and variables > Actions\n3. **Add `PYPI_API_TOKEN`** with your PyPI API token value\n\n## Documentation\n\nDocumentation is automatically built and deployed to GitHub Pages using MkDocs.\n\n- **Live Documentation:** [https://james-see.github.io/beatstoch/](https://james-see.github.io/beatstoch/)\n- **Build locally:** `mkdocs serve` (requires MkDocs installation)\n\n## Development\n\n### Setup\n```bash\ngit clone https://github.com/james-see/beatstoch.git\ncd beatstoch\nuv sync\n```\n\n### Testing\n```bash\n# Run all tests\nuv run python -m pytest\n\n# Test with coverage\nuv run python -m pytest --cov=src/beatstoch\n\n# Test CLI functionality\nuv run beatstoch generate-bpm 120 --bars 2\n```\n\n### Building Documentation\n```bash\n# Install MkDocs\npip install mkdocs mkdocs-material\n\n# Preview locally\nmkdocs serve\n\n# Deploy to GitHub Pages\nmkdocs gh-deploy\n```\n\n## License\n\nThis project is released into the public domain under the [Unlicense](https://unlicense.org/).\n\n[](http://unlicense.org/)\n\n## Contributing\n\n1. Fork the repository at [https://github.com/james-see/beatstoch](https://github.com/james-see/beatstoch)\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes and add tests\n4. Run the test suite: `uv run python -m pytest`\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## Support\n\n- \ud83d\udcd6 [Documentation](https://james-see.github.io/beatstoch/)\n- \ud83d\udc1b [Issue Tracker](https://github.com/james-see/beatstoch/issues)\n- \ud83d\udcac [Discussions](https://github.com/james-see/beatstoch/discussions)\n- \ud83d\udce7 [GitHub Repository](https://github.com/james-see/beatstoch)\n\n---\n\n*Generated drum patterns are for educational and creative purposes. Always respect music copyrights and licensing.*\n",
"bugtrack_url": null,
"license": null,
"summary": "BPM-aware stochastic drum generator: library + CLI.",
"version": "1.2.0",
"project_urls": {
"Documentation": "https://james-see.github.io/beatstoch/",
"Homepage": "https://github.com/james-see/beatstoch",
"Repository": "https://github.com/james-see/beatstoch",
"Source": "https://github.com/james-see/beatstoch",
"Tracker": "https://github.com/james-see/beatstoch/issues"
},
"split_keywords": [
"midi",
" drums",
" music",
" bpm",
" stochastic",
" algorithmic",
" composition",
" audio",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2b874a77b2257b1a2279d1b6ce9fcdd6c53c01acf67897593605bccd4dacc4b1",
"md5": "d7a3c829c6b6cb17ff5c66a6456eaf83",
"sha256": "dba622ea562eab36c745035a88a3fcbf971544a42ec7fa222adff68bb0de6143"
},
"downloads": -1,
"filename": "beatstoch-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d7a3c829c6b6cb17ff5c66a6456eaf83",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13018,
"upload_time": "2025-10-17T17:42:33",
"upload_time_iso_8601": "2025-10-17T17:42:33.549045Z",
"url": "https://files.pythonhosted.org/packages/2b/87/4a77b2257b1a2279d1b6ce9fcdd6c53c01acf67897593605bccd4dacc4b1/beatstoch-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "26529ce90afbf6caaf54269813597701eab1aa295f3d5605cfbac0c7ca20fd28",
"md5": "937dd73acee9df1fb6d8288ea9b73e69",
"sha256": "a89f530d3466715806906bcc6e4fb6af627a37b3d7b23d3617e1cfadbc2dd8ef"
},
"downloads": -1,
"filename": "beatstoch-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "937dd73acee9df1fb6d8288ea9b73e69",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 15982,
"upload_time": "2025-10-17T17:42:35",
"upload_time_iso_8601": "2025-10-17T17:42:35.141830Z",
"url": "https://files.pythonhosted.org/packages/26/52/9ce90afbf6caaf54269813597701eab1aa295f3d5605cfbac0c7ca20fd28/beatstoch-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-17 17:42:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "james-see",
"github_project": "beatstoch",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "beatstoch"
}
JSON
